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.
BaseDrawer¶
- class BaseDrawer[source]¶
Abstract class for the serializable Qiskit Experiments figure drawer.
Overview
A drawer may be implemented by different drawer backends such as matplotlib or Plotly. Sub-classes that wrap these backends by subclassing
BaseDrawer
must implement the following abstract methods.- initialize_canvas
This method should implement a protocol to initialize a drawer canvas with user input
axis
object. Note thatdrawer
supports visualization of experiment results in multiple canvases tiled into N (row) x M (column) inset grids, which is specified in the optionsubplots
. By default, this is N=1, M=1 and thus no inset grid will be initialized. The data points to draw might be provided with a canvas number defined inSeriesDef.canvas
which defaults toNone
, i.e. no-inset grids.This method should first check the drawer options (
options
) for the axis object and initialize the axis only when it is not provided by the options. Once axis is initialized, this is set to the instance memberself._axis
.
- format_canvas
This method formats the appearance of the canvas. Typically, it updates axis and tick labels. Note that the axis SI unit may be specified in the drawer figure_options. In this case, axis numbers should be auto-scaled with the unit prefix.
Drawing Methods
- scatter
This method draws scatter points on the canvas, like a scatter-plot, with optional error-bars in both the X and Y axes.
- line
This method plots a line from provided X and Y values.
- filled_y_area
This method plots a shaped region bounded by upper and lower Y-values. This method is typically called with interpolated x and a pair of y values that represent the upper and lower bound within certain confidence interval. If this is called multiple times, it may be necessary to set the transparency so that overlapping regions can be distinguished.
- filled_x_area
This method plots a shaped region bounded by upper and lower X-values, as a function of Y-values. This method is a rotated analogue of
filled_y_area()
.
- textbox
This method draws a text-box on the canvas, which is a rectangular region containing some text.
Legends
Legends are generated based off of drawn graphics and their labels or names. These are managed by individual drawer subclasses, and generated when the
format_canvas()
method is called. Legend entries are created when any drawing function is called withlegend=True
. There are three parameters in drawing functions that are relevant to legend generation:name
,label
, andlegend
. If a user would like the graphics drawn onto a canvas to be used as the graphical component of a legend entry; they should setlegend=True
. The legend entry label can be defined in three locations: thelabel
parameter of drawing functions, the"label"
entry inseries_params
, and thename
parameter of drawing functions. These three possible label variables have a search hierarchy given by the order in the aforementioned list. If one of the label variables isNone
, the next is used. If all areNone
, a legend entry is not generated for the given series.The recommended way to customize the legend entries is as follows:
Set the labels in the
series_params
option, keyed on the series names.Initialize the canvas.
Call relevant drawing methods to create the figure. When calling the drawing method that creates the graphic you would like to use in the legend, set
legend=True
. For example,drawer.scatter(...,legend=True)
would use the scatter points as the legend graphics for the given series.Format the canvas and call
figure()
to get the figure.
Options and Figure Options
Drawers have both
options
andfigure_options
available to set parameters that define how to draw and what is drawn, respectively.BasePlotter
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 details on the difference between the two sets of options, see the documentation forBasePlotter
.Note
If a drawer instance is used with a plotter, then there is the potential for any figure option to be overwritten with their value from the plotter. This means that the drawer instance would be modified indirectly when the
BasePlotter.figure()
method is called. This must be kept in mind when creating subclasses ofBaseDrawer
.Options
The following can be set using
set_options()
.- Options
Defined in the class
BaseDrawer
:axis (Any)
Default value:None
Arbitrary object that can be used as a canvas.subplots (Tuple[int, int])
Default value: (1
,1
)Number of rows and columns when the experimental result is drawn in the multiple windows.default_style (PlotStyle)
Default value: {"figsize"
: ("figsize"
, (8
,5
)),"legend_loc"
: ("legend_loc"
,None
),"tick_label_size"
: ("tick_label_size"
,14
),"axis_label_size"
: ("axis_label_size"
,16
),"textbox_rel_pos"
: ("textbox_rel_pos"
, (0.5
,-0.25
)),"textbox_text_size"
: ("textbox_text_size"
,12
),"errorbar_capsize"
: ("errorbar_capsize"
,4
),"symbol_size"
: ("symbol_size"
,6.0
)}The default style for drawer. This must contain all required style parameters fordrawer
, as is defined inPlotStyle.default_style()
. Subclasses can add extra required style parameters by overriding_default_style()
.
Figure options
The following can be set using
set_figure_options()
.- Options
Defined in the class
BaseDrawer
: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 byxval_unit_scale
.yval_unit (str)
Default value:None
Unit of y values. Seexval_unit
for details.xval_unit_scale (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.yval_unit_scale (bool)
Default value:True
Whether to add an SI unit prefix toyval_unit
if needed. Seexval_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[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.custom_style (PlotStyle)
Default value: {}The style definition to use when drawing. This overwrites style parameters indefault_style
inoptions
. Defaults to an empty PlotStyle instance (i.e.,PlotStyle()
).
Initialization
Create a BaseDrawer instance.
Attributes
Return figure object handler to be saved in the database.
Return the figure options.
Return the drawer options.
The combined plot style for this drawer.
Methods
Return the config dictionary for this drawer.
BaseDrawer.filled_x_area
(x_ub, x_lb, y_data)Draw filled area as a function of y-values.
BaseDrawer.filled_y_area
(x_data, y_ub, y_lb)Draw filled area as a function of x-values.
Final cleanup for the canvas appearance.
BaseDrawer.image
(data[, extent, name, ...])Draw an image of numerical values, series names, or RGB/A values.
Initialize the drawer canvas.
BaseDrawer.label_for
(name, label)Get the legend label for the given series, with optional overrides.
BaseDrawer.line
(x_data, y_data[, name, ...])Draw a line.
BaseDrawer.scatter
(x_data, y_data[, x_err, ...])Draw scatter points, with optional error-bars.
BaseDrawer.set_figure_options
(**fields)Set the figure options.
BaseDrawer.set_options
(**fields)Set the drawer options.
BaseDrawer.textbox
(description[, rel_pos])Draw text box.