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.
MplDrawer¶
- class MplDrawer[source]¶
Drawer for MatplotLib backend.
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 (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.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
- DefaultColors = ((0.12156862745098039, 0.4666666666666667, 0.7058823529411765), (1.0, 0.4980392156862745, 0.054901960784313725), (0.17254901960784313, 0.6274509803921569, 0.17254901960784313), (0.8392156862745098, 0.15294117647058825, 0.1568627450980392), (0.5803921568627451, 0.403921568627451, 0.7411764705882353), (0.5490196078431373, 0.33725490196078434, 0.29411764705882354), (0.8901960784313725, 0.4666666666666667, 0.7607843137254902), (0.4980392156862745, 0.4980392156862745, 0.4980392156862745), (0.7372549019607844, 0.7411764705882353, 0.13333333333333333), (0.09019607843137255, 0.7450980392156863, 0.8117647058823529))¶
- DefaultMarkers = ('.', 'o', 'v', '^', '<', '>', '8', 's', 'p', '*', 'h', 'H', 'D', 'd', 'P', 'X')¶
- figure¶
Return figure object handler to be saved in the database.
In the MatplotLib the
Figure
andAxes
are different object. User can pass a part of the figure (i.e. multi-axes) to the drawer optionaxis
. For example, a user wants to combine two different experiment results in the same figure, one can callpyplot.subplots
with two rows and pass one of the generated two axes to each experiment drawer. Once all the experiments complete, the user will obtain the single figure collecting all experimental results.Note that this method returns the entire figure object, rather than a single axis. Thus, the experiment data saved in the database might have a figure collecting all child axes drawings.
- figure_options¶
Return the figure options.
These are typically updated by a plotter instance, and thus may change. It is recommended to set figure options in a parent
BasePlotter
instance that contains theBaseDrawer
instance.
- options¶
Return the drawer options.
- style¶
The combined plot style for this drawer.
The returned style instance is a combination of
options.default_style
andfigure_options.custom_style
. Style parameters set incustom_style
override those set indefault_style
. Ifcustom_style
is not an instance ofPlotStyle
, the returned style is equivalent todefault_style
.- Returns:
The plot style for this drawer.
Methods
- config()¶
Return the config dictionary for this drawer.
- Return type:
Dict
- filled_x_area(x_ub, x_lb, y_data, name=None, label=None, legend=False, **options)[source]¶
Draw filled area as a function of y-values.
- Parameters:
x_ub (Sequence[float]) – The upper boundary of X values.
x_lb (Sequence[float]) – The lower boundary of X values.
y_data (Sequence[float]) – Y values.
name (str | int | float | None) – Name of this series.
label (str | None) – Optional legend label to override
name
andseries_params
.legend (bool) – Whether the drawn area must have a legend entry. Defaults to False. The series label in the legend will be
label
if it is not None. If it is, thenseries_params
is searched for a"label"
entry for the series identified byname
. If this is alsoNone
, thenname
is used as the fallback. If noname
is provided, then no legend entry is generated.options – Valid options for the drawer backend API.
- filled_y_area(x_data, y_ub, y_lb, name=None, label=None, legend=False, **options)[source]¶
Draw filled area as a function of x-values.
- Parameters:
x_data (Sequence[float]) – X values.
y_ub (Sequence[float]) – The upper boundary of Y values.
y_lb (Sequence[float]) – The lower boundary of Y values.
name (str | int | float | None) – Name of this series.
label (str | None) – Optional legend label to override
name
andseries_params
.legend (bool) – Whether the drawn area must have a legend entry. Defaults to False. The series label in the legend will be
label
if it is not None. If it is, thenseries_params
is searched for a"label"
entry for the series identified byname
. If this is alsoNone
, thenname
is used as the fallback. If noname
is provided, then no legend entry is generated.options – Valid options for the drawer backend API.
- hline(y_value, name=None, label=None, legend=False, **options)[source]¶
Draw a horizontal line.
- Parameters:
y_value (float) – Y value for line.
name (str | int | float | None) – Name of this series.
label (str | None) – Optional legend label to override
name
andseries_params
.legend (bool) – Whether the drawn area must have a legend entry. Defaults to False. The series label in the legend will be
label
if it is not None. If it is, thenseries_params
is searched for a"label"
entry for the series identified byname
. If this is alsoNone
, thenname
is used as the fallback. If noname
is provided, then no legend entry is generated.options – Valid options for the drawer backend API.
- image(data, extent=None, name=None, label=None, cmap=None, cmap_use_series_colors=False, colorbar=False, **options)[source]¶
Draw an image of numerical values, series names, or RGB/A values.
- Parameters:
data (ndarray) – The two-/three-dimensional data defining an image. If
data.dims==2
, then the pixel colors are determined bycmap
andcmap_use_series_colors
. Ifdata.dims==3
, then it is assumed thatdata
contains either RGB or RGBA data; which requires the third dimension to have length3
or4
respectively. For RGB/A data, the elements ofdata
must be floats or integers in the range 0-1 and 0-255 respectively. If the data is two-dimensional, there is no limit on the range of the values if they are numerical. Ifcmap_use_series_colors=True
, thendata
contains series names; which can be strings or numerical values, as long as they are appropriate series names.extent (Tuple[float, float, float, float] | None) – An optional tuple
(x_min, x_max, y_min, y_max)
which defines a rectangular region within which the values insidedata
should be plotted. The units ofextent
are the same as those of the X and Y axes for the axis. If None, the extent of the image is taken as(0, data.shape[0], 0, data.shape[1])
. Default is None.name (str | int | float | None) – Name of this image. Used to lookup
canvas
andlabel
inseries_params
.label (str | None) – An optional label for the colorbar, if
colorbar=True
.cmap (str | Any | None) – Optional colormap for assigning colors to the image values, if
data
is not an RGB/A image.cmap
must be a string or object instance which is recognized by the drawer. Defaults to None.cmap_use_series_colors (bool) – Whether to assign colors to the image based on series colors, where the values inside
data
are series names. Ifcmap_use_series_colors=True
,``cmap`` is ignored. This only works for two-dimensional images as three-dimensionaldata
contains explicit colors as RGB/A values. Iflen(data.shape)=3
,cmap_use_series_colours
is ignored. Defaults to False.colorbar (bool) – Whether to add a bar showing the color-value mapping for the image. Defaults to False.
options – Valid options for the drawer backend API.
- label_for(name, label)¶
Get the legend label for the given series, with optional overrides.
This method determines the legend label for a series, with optional overrides
label
and the"label"
entry in theseries_params
option (seeoptions
).label
is returned if it is notNone
, as this is the override with the highest priority. If it isNone
, then the drawer will look for a"label"
entry inseries_params
, for the series identified byname
. If this entry doesn’t exist, or isNone
, thenname
is used as the label. If all these options areNone
, thenNone
is returned; signifying that a legend entry for the provided series should not be generated. Note thatlabel_for()
will convertname
tostr
when it is returned.- Parameters:
name (str | int | float | None) – The name of the series.
label (str | int | float | None) – Optional label override.
- Returns:
The legend entry label, or
None
.- Return type:
str | None
- line(x_data, y_data, name=None, label=None, legend=False, **options)[source]¶
Draw a line.
- Parameters:
x_data (Sequence[float]) – X values.
y_data (Sequence[float]) – Y values.
name (str | int | float | None) – Name of this series.
label (str | None) – Optional legend label to override
name
andseries_params
.legend (bool) – Whether the drawn area must have a legend entry. Defaults to False. The series label in the legend will be
label
if it is not None. If it is, thenseries_params
is searched for a"label"
entry for the series identified byname
. If this is alsoNone
, thenname
is used as the fallback. If noname
is provided, then no legend entry is generated.options – Valid options for the drawer backend API.
- scatter(x_data, y_data, x_err=None, y_err=None, name=None, label=None, legend=False, **options)[source]¶
Draw scatter points, with optional error-bars.
- Parameters:
x_data (Sequence[float]) – X values.
y_data (Sequence[float]) – Y values.
x_err (Sequence[float] | None) – Optional error for X values.
y_err (Sequence[float] | None) – Optional error for Y values.
name (str | int | float | None) – Name of this series.
label (str | None) – Optional legend label to override
name
andseries_params
.legend (bool) – Whether the drawn area must have a legend entry. Defaults to False. The series label in the legend will be
label
if it is not None. If it is, thenseries_params
is searched for a"label"
entry for the series identified byname
. If this is alsoNone
, thenname
is used as the fallback. If noname
is provided, then no legend entry is generated.options – Valid options for the drawer backend API.
- set_figure_options(**fields)¶
Set the figure options.
- Parameters:
fields – The fields to update the figure options
- Raises:
AttributeError – If an unknown figure option is encountered.
- set_options(**fields)¶
Set the drawer options.
- Parameters:
fields – The fields to update the options
- Raises:
AttributeError – If an unknown options is encountered.
- textbox(description, rel_pos=None, **options)[source]¶
Draw text box.
- Parameters:
description (str) – A string to be drawn inside a report box.
rel_pos (Tuple[float, float] | None) – Relative position of the text-box. If None, the default
textbox_rel_pos
from the style is used.options – Valid options for the drawer backend API.