Note

This is the documentation for the current state of the development branch of Qiskit Experiments. The documentation or APIs here can change prior to being released.

BasePlotter¶

class BasePlotter(drawer)[source]¶

An abstract class for the serializable figure plotters.

Overview

A plotter takes data from an experiment analysis class or experiment and plots a given figure using a drawing backend. Sub-classes define the kind of figure created and the expected data.

Data is split into series and supplementary data. Series data is grouped by series name (Union[str, int, float]). For CurveAnalysis, this is the model name for a curve fit. For series data associated with a single series name and supplementary data, data values are identified by a data key (str). Different data per series and figure must have a different data key to avoid overwriting values. Experiment and analysis results can be passed to the plotter so appropriate graphics can be drawn on the figure canvas. Series data is added to the plotter using set_series_data() whereas supplementary data is added using set_supplementary_data(). Series and supplementary data are retrieved using data_for() and supplementary_data respectively.

Series data contains values to be plotted on a canvas, such that the data can be grouped into subsets identified by their series name. Series names can be thought of as legend labels for the plotted data, and as curve names for a curve fit. Supplementary data is not associated with a series or curve and is instead only associated with the figure. Examples include analysis reports or other text that is drawn onto the figure canvas.

Options and Figure Options

Plotters have both options and figure_options available to set parameters that define how to plot and what is plotted. BaseDrawer is similar in that it also has options and figure_options. The former contains class-specific variables that define how an instance behaves. The latter contains figure-specific variables that typically contain values that are drawn on the canvas, such as text.

For example, BasePlotter has an axis option that can be set to the canvas on which the figure should be drawn. This changes how the plotter works in that it changes where the figure is drawn. BasePlotter has an xlabel figure option that can be set to change the text drawn next to the X-axis in the final figure. As the value of this option will be drawn on the figure, it is a figure option.

As plotters need a drawer to generate a figure, and the drawer needs to know what to draw, figure options are passed to drawer when the figure() method is called. Any figure options that are defined in both the plotters figure_options attribute and the drawers figure_options attribute are copied to the drawer: i.e., BaseDrawer.set_figure_options() is called for each common figure option, setting the value of the option to the value stored in the plotter.

Note

If a figure option called “foo” is not set in the drawer’s figure options (BaseDrawer.figure_options) but is set in the plotter’s figure options (figure_options), it will not be copied over to the drawer when the figure() method is called. This means that some figure options from the plotter may be unused by the drawer. BasePlotter and its subclasses filter these options before setting them in the drawer, as subclasses of BaseDrawer may add additional figure options. To make validation easier and the code cleaner, the figure() method conducts this check before setting figure options in the drawer.

Example

plotter = MyPlotter(MyDrawer())

# MyDrawer contains the following figure_options with default values.
plotter.drawer.figure_options.xlabel
plotter.drawer.figure_options.ylabel

# MyDrawer does NOT contain the following figure option
# plotter.drawer.figure_options.unknown_variable    # Raises an error as it
                                                    # does not exist in
                                                    # `drawer.figure_options`.

# If we set the following figure options, they will be set in the drawer as
# they are defined in `plotter.drawer.figure_options`.
plotter.set_figure_options(xlabel="Frequency", ylabel="Fidelity")

# During a call to `plotter.figure()`, the drawer's figure options are updated.
# The following values would then be returned from the drawer.
plotter.drawer.figure_options.xlabel                # returns "Frequency"
plotter.drawer.figure_options.ylabel                # returns "Fidelity"

# If we set the following option and figure option, they will NOT be set in the
# drawer as the drawer doesn't contain default values for these option names.
plotter.set_options(plot_fit=False)                 # Example plotter option
plotter.set_figure_options(unknown_variable=5e9)    # Example figure option

# As `plot_fit` is not a figure option, it is not set in the drawer.
plotter.drawer.options.plot_fit     # Would raise an error if no default
                                    # exists, or return a different value to
                                    # `plotter.options.plot_fit`.

# As `unknown_variable` is not set in the drawer's figure options, it is not set
# during a # call to the `figure()` method.
# plotter.drawer.figure_options.unknown_variable    # Raises an error as it
                                                    # does not exist in
                                                    # `drawer.figure_options`.

drawer¶

The drawer to use when plotting.

Type:: BaseDrawer

Options

The following can be set using set_options().

Options

Defined in the class BasePlotter:
- axis (Any)
  
  Default value: None
  
  Arbitrary object that can be used as a drawing canvas.
- subplots (Tuple[int, int])
  
  Default value: (1, 1)
  
  Number of rows and columns when the experimental result is drawn in the multiple windows.
- style (PlotStyle)
  
  Default value: {}
  
  The style definition to use when plotting. This overwrites figure option custom_style set in drawer. The default is an empty style object, and such the default drawer plotting style will be used.

Figure options

The following can be set using set_figure_options().

Options

Defined in the class BasePlotter:
- xlabel (Union[str, List[str]])
  
  Default value: None
  
  X-axis label string of the output figure. If there are multiple columns in the canvas, this could be a list of labels.
- ylabel (Union[str, List[str]])
  
  Default value: None
  
  Y-axis label string of the output figure. If there are multiple rows in the canvas, this could be a list of labels.
- xlim (Tuple[float, float])
  
  Default value: None
  
  Min and max value of the horizontal axis. If not provided, it is automatically scaled based on the input data points.
- ylim (Tuple[float, float])
  
  Default value: None
  
  Min and max value of the vertical axis. If not provided, it is automatically scaled based on the input data points.
- xval_unit (str)
  
  Default value: None
  
  Unit of x values. No scaling prefix is needed here as this is controlled by xval_unit_scale.
- yval_unit (str)
  
  Default value: None
  
  Unit of y values. See xval_unit for details.
- xval_unit_scale (bool)
  
  Default value: True
  
  Whether to add an SI unit prefix to xval_unit if needed. For example, when the x values represent time and xval_unit="s", xval_unit_scale=True adds an SI unit prefix to "s" based on X values of plotted data. In the output figure, the prefix is automatically selected based on the maximum value in this axis. If your x values are in [1e-3, 1e-4], they are displayed as [1 ms, 10 ms]. By default, this option is set to True. If False is provided, the axis numbers will be displayed in the scientific notation.
- yval_unit_scale (bool)
  
  Default value: True
  
  Whether to add an SI unit prefix to yval_unit if needed. See xval_unit_scale for details.
- figure_title (str)
  
  Default value: None
  
  Title of the figure. Defaults to None, i.e. nothing is shown.
- series_params (Dict[SeriesName, Dict[str, Any]])
  
  Default value: {}
  
  A dictionary of plot parameters for each series. This is keyed on the name for each series. Sub-dictionary is expected to have following three configurations, “canvas”, “color”, and “symbol”; “canvas” is the integer index of axis (when multi-canvas plot is set), “color” is the color of the curve, and “symbol” is the marker Style of the curve for scatter plots.

Initialization

Create a new plotter instance.

Parameters:: drawer (BaseDrawer) – The drawer to use when creating the figure.

Attributes

`BasePlotter.figure_options`	Figure options for the plotter and its drawer.
`BasePlotter.options`	Options for the plotter.
`BasePlotter.series`	Series names that have been added to this plotter.
`BasePlotter.series_data`	Data for series being plotted.
`BasePlotter.supplementary_data`	Additional data for the figure being plotted, that isn't associated with a series.

Methods

`BasePlotter.clear_series_data`([series_name])	Clear series data for this plotter.
`BasePlotter.clear_supplementary_data`()	Clears supplementary data.
`BasePlotter.config`()	Return the config dictionary for this drawing.
`BasePlotter.data_exists_for`(series_name, ...)	Returns whether the given data keys exist for the given series.
`BasePlotter.data_for`(series_name, data_keys)	Returns data associated with the given series.
`BasePlotter.data_keys_for`(series_name)	Returns a list of data keys for the given series.
`BasePlotter.expected_series_data_keys`()	Returns the expected series data keys supported by this plotter.
`BasePlotter.expected_supplementary_data_keys`()	Returns the expected supplementary data keys supported by this plotter.
`BasePlotter.figure`()	Generates and returns a figure for the already provided series and supplementary data.
`BasePlotter.set_figure_options`(**fields)	Set the figure options.
`BasePlotter.set_options`(**fields)	Set the plotter options.
`BasePlotter.set_series_data`(series_name, ...)	Sets data for the given series.
`BasePlotter.set_supplementary_data`(**data_kwargs)	Sets supplementary data for the plotter.