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]
). ForCurveAnalysis
, 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 usingset_series_data()
whereas supplementary data is added usingset_supplementary_data()
. Series and supplementary data are retrieved usingdata_for()
andsupplementary_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
andfigure_options
available to set parameters that define how to plot and what is plotted.BaseDrawer
is similar in that it also hasoptions
andfigure_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 anaxis
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 anxlabel
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 thefigure()
method is called. Any figure options that are defined in both the plottersfigure_options
attribute and the drawersfigure_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 thefigure()
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 ofBaseDrawer
may add additional figure options. To make validation easier and the code cleaner, thefigure()
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:
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)
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 (Union[Tuple[float, float], List[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. If there are multiple columns in the canvas, this could be a list of xlims.ylim (Union[Tuple[float, float], List[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. If there are multiple rows in the canvas, this could be a list of ylims.xval_unit (Union[str, List[str]])
Default value:None
Unit of x values. No scaling prefix is needed here as this is controlled byxval_unit_scale
. If there are multiple columns in the canvas, this could be a list of xval_units.yval_unit (Union[str, List[str]])
Default value:None
Unit of y values. No scaling prefix is needed here as this is controlled byyval_unit_scale
. If there are multiple rows in the canvas, this could be a list of yval_units.xval_unit_scale (Union[bool, List[bool]])
Default value:True
Whether to add an SI unit prefix toxval_unit
if needed. For example, when the x values represent time andxval_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 toTrue
. IfFalse
is provided, the axis numbers will be displayed in the scientific notation. If there are multiple columns in the canvas, this could be a list of xval_unit_scale.yval_unit_scale (Union[bool, List[bool]])
Default value:True
Whether to add an SI unit prefix toyval_unit
if needed. Seexval_unit_scale
for details. If there are multiple rows in the canvas, this could be a list of yval_unit_scale.xscale (str)
Default value:None
The scaling of the x-axis, such aslog
orlinear
.yscale (str)
Default value:None
The scaling of the y-axis, such aslog
orlinear
.figure_title (str)
Default value:None
Title of the figure. Defaults to None, i.e. nothing is shown.sharex (bool)
Default value:True
Set True to share x-axis ticks among sub-plots.sharey (bool)
Default value:True
Set True to share y-axis ticks among sub-plots.series_params (Dict[str, Dict[str, Any]])
Default value: {}A dictionary of parameters for each series. This is keyed on the name for each series. Sub-dictionary is expected to have the following three configurations, “canvas”, “color”, “symbol” and “label”; “canvas” is the integer index of axis (when multi-canvas plot is set), “color” is the color of the drawn graphics, “symbol” is the series marker style for scatter plots, and “label” is a user provided series label that appears in the legend.
Initialization
Create a new plotter instance.
- Parameters:
drawer (BaseDrawer) – The drawer to use when creating the figure.
Attributes
- figure_options¶
Figure options for the plotter and its drawer.
Figure options differ from normal options (
options
) in that the plotter passes figure options on to the drawer when creating a figure (whenfigure()
is called). This waydrawer
can draw an appropriate figure. An example of a figure option is the x-axis label.
- options¶
Options for the plotter.
Options for a plotter modify how the class generates a figure. This includes an optional axis object, being the drawer canvas. Make sure verify whether the option you want to set is in
options
orfigure_options
.
- series¶
Series names that have been added to this plotter.
- series_data¶
Data for series being plotted.
Series data includes data such as scatter points, interpolated fit values, and standard deviations. Series data is grouped by series name (
Union[str, int, float]
) and then by a data key (str
). Though series data can be accessed throughseries_data
, it is recommended to access them withdata_for()
anddata_exists_for()
as they allow for easier access to nested values and can handle multiple data keys in one query.- Returns:
A dictionary containing series data.
- supplementary_data¶
Additional data for the figure being plotted, that isn’t associated with a series.
Supplementary data includes text, fit reports, or other data that is associated with the figure but not an individual series. It is typically data additional to the direct results of an experiment.
Methods
- clear_series_data(series_name=None)[source]¶
Clear series data for this plotter.
- Parameters:
series_name (str | int | float | None) – The series name identifying which data should be cleared. If None, all series data is cleared. Defaults to None.
- data_exists_for(series_name, data_keys)[source]¶
Returns whether the given data keys exist for the given series.
- Parameters:
series_name (str | int | float) – The name of the given series.
data_keys (str | List[str]) – The data keys to be checked.
- Returns:
True if all data keys have values assigned for the given series. False if at least one does not have a value assigned.
- Return type:
bool
- data_for(series_name, data_keys)[source]¶
Returns data associated with the given series.
The returned tuple contains the data, associated with
data_keys
, in the same orders as they are provided. For example,plotter.set_series_data("seriesA", x=data.x, y=data.y, yerr=data.yerr) # The following calls are equivalent. x, y, yerr = plotter.data_for("seriesA", ["x", "y", "yerr"]) x, y, yerr = data.x, data.y, data.yerr # Retrieving a single data key returns a tuple. Note the comma after ``x``. x, = plotter.data_for("seriesA", "x")
data_for()
is intended to be used by sub-classes ofBasePlotter
when plotting in the_plot_figure()
method.- Parameters:
series_name (str | int | float) – The series name for the given series.
data_keys (str | List[str]) – List of data keys for the data to be returned. If a single data key is given as a string, it is wrapped in a list.
- Returns:
A tuple of data associated with the given series, identified by
data_keys
. If no data has been set for a data key, None is returned for the associated tuple entry.- Return type:
Tuple[Any | None]
- data_keys_for(series_name)[source]¶
Returns a list of data keys for the given series.
- Parameters:
series_name (str | int | float) – The series name for which to return the data keys, i.e., the types of data for each series.
- Returns:
The list of data keys for data in the plotter associated with the given series. If the series has not been added to the plotter, an empty list is returned.
- Return type:
List[str]
- abstract classmethod expected_series_data_keys()[source]¶
Returns the expected series data keys supported by this plotter.
- Return type:
List[str]
- abstract classmethod expected_supplementary_data_keys()[source]¶
Returns the expected supplementary data keys supported by this plotter.
- Return type:
List[str]
- figure()[source]¶
Generates and returns a figure for the already provided series and supplementary data.
figure()
calls_plot_figure()
, which is overridden by sub-classes. Before and after calling_plot_figure()
;_configure_drawer()
,initialize_canvas()
andformat_canvas()
are called on the drawer respectively.- Returns:
A figure generated by
drawer
, of the same type asdrawer.figure
.- Return type:
Any
- set_figure_options(**fields)[source]¶
Set the figure options.
- Parameters:
fields – The fields to update in figure options.
- set_options(**fields)[source]¶
Set the plotter options.
- Parameters:
fields – The fields to update in options.
- Raises:
AttributeError – If an unknown option is encountered.
- set_series_data(series_name, **data_kwargs)[source]¶
Sets data for the given series.
Note that if data has already been assigned for the given series and data key, it will be overwritten with the new values.
set_series_data
will warn if the data key is unexpected; i.e., not within those returned byexpected_series_data_keys()
.- Parameters:
series_name (str | int | float) – The name of the given series.
data_kwargs – The data to be added, where the keyword is the data key.
- set_supplementary_data(**data_kwargs)[source]¶
Sets supplementary data for the plotter.
Supplementary data differs from series data in that it is not associate with a series name. Fit reports are examples of supplementary data as they contain fit results from an analysis class, such as the “goodness” of a curve fit.
Note that if data has already been assigned for the given data key, it will be overwritten with the new values.
set_supplementary_data
will warn if the data key is unexpected; i.e., not within those returned byexpected_supplementary_data_keys()
.