qcodes.plots.qcmatplotlib

Live plotting in Jupyter notebooks using the nbagg backend and matplotlib

class qcodes.plots.qcmatplotlib.MatPlot(*args, figsize=None, interval=1, subplots=None, num=None, **kwargs)

Bases: BasePlot

Plot x/y lines or x/y/z heatmap data. The first trace may be included in the constructor, other traces can be added with MatPlot.add()

Parameters

• *args – Sequence of data to plot. Each element will have its own subplot. An element can be a single array, or a sequence of arrays. In the latter case, all arrays will be plotted in the same subplot.

• figsize (Tuple[float, float]) – (width, height) tuple in inches to pass to plt.figure. If not provided, figsize is determined from subplots shape

• interval – period in seconds between update checks

• subplots – either a sequence (args) or mapping (kwargs) to pass to plt.subplots. default is a single simple subplot (1, 1) you can use this to pass kwargs to the plt.figure constructor

• num – integer or None specifies the index of the matplotlib figure window to use. If None then open a new window

• **kwargs – passed along to MatPlot.add() to add the first data trace

max_subplot_columns = 3

__getitem__(key)

Subplots can be accessed via indices. :param key: subplot idx

Returns

Subplot with idx key

clear(subplots=None, figsize=None)

Clears the plot window and removes all subplots and traces so that the window can be reused.

add_to_plot(use_offset: bool = False, **kwargs)

adds one trace to this MatPlot.

Parameters

• use_offset – Whether or not ticks can have an offset

• **kwargs – with the exceptions given in the notes below (mostly the data!), these are passed directly to the matplotlib plotting routine.

Returns

Plot handle for trace

Notes

The following special cases apply for kwargs that are not passed directly to the plotting routine.

• subplot: the 1-based axes number to append to (default 1)

• if kwargs include z, we will draw a heatmap (ax.pcolormesh) x, y, and z are passed as positional args to pcolormesh

• without z we draw a scatter/lines plot (ax.plot) x, y, and fmt (if present) are passed as positional args

static default_figsize(subplots)

Provides default figsize for given subplots. :param subplots: shape (nrows, ncols) of subplots :type subplots: Tuple[Int, Int]

Returns

(width, height) of default figsize

for given subplot shape

Return type

Tuple[float, float]

update_plot()

update the plot. The DataSets themselves have already been updated in update, here we just push the changes to the plot.

save(filename=None)

Save current plot to filename, by default to the location corresponding to the default title.

Parameters

filename (Optional[str]) – Location of the file

tight_layout()

Perform a tight layout on the figure. A bit of additional spacing at the top is also added for the title.

rescale_axis()

Rescale axis and units for axis that are in standard units i.e. V, s J … to m μ, m This scales units defined in BasePlot.standardunits only to avoid prefixes on combined or non standard units

add(*args, updater=None, **kwargs)

Add one trace to this plot.

Parameters

• args – optional way to provide x/y/z data without keywords If the last one is 1D, may be y or x, y If the last one is 2D, may be z or x, y, z

• updater – a callable (with no args) that updates the data in this trace if omitted, we will look for DataSets referenced in this data, and call their sync methods.

• kwargs – after inserting info found in args and possibly in set_arrays into x, y, and optionally z, these are passed along to self.add_to_plot.

Returns

Plot handle for trace

Examples

To use custom labels and units pass for example:

>>> plot.add(x=set, y=amplitude,
>>>          xlabel="set",
>>>          xunit="V",
>>>          ylabel= "Amplitude",
>>>          yunit ="V")

Array shapes for 2D plots:

x:(1D-length m), y:(1D-length n), z: (2D- n*m array)

add_updater(updater, plot_config)

Add an updater to the plot.

Parameters

• updater (Callable) – callable (with no args) that updates the data in this trace if omitted, we will look for DataSets referenced in this data, and call their sync methods.

• plot_config (dict) – this is a dictionary that gets populated inside add() via expand_trace(). The reason this is here is to fetch from the data_set the sync method to use it as an updater.

static expand_trace(args, kwargs)

Complete the x, y (and possibly z) data definition for a trace.

Also modifies kwargs in place so that all the data needed to fully specify the trace is present (ie either x and y or x and y and z)

Both __init__ (for the first trace) and the add method support multiple ways to specify the data in the trace:

As *args:

• add(y) or add(z) specify just the main 1D or 2D data, with the setpoint axis or axes implied.

• add(x, y) or add(x, y, z) specify all axes of the data.

And as **kwargs:

• add(x=x, y=y, z=z) you specify exactly the data you want on each axis. Any but the last (y or z) can be omitted, which allows for all of the same forms as with *args, plus x and z or y and z, with just one axis implied from the setpoints of the z data.

This method takes any of those forms and converts them into a complete set of kwargs, containing all of the explicit or implied data to be used in plotting this trace.

Parameters

• args (Tuple[DataArray]) – positional args, as passed to either __init__ or add

• kwargs (Dict(DataArray]) – keyword args, as passed to either __init__ or add. kwargs may contain non-data items in keys other than x, y, and z.

Raises

• ValueError – if the shape of the data does not match that of args

• ValueError – if the data is provided twice

get_default_title()

Get the default title, which for a plot is just a list of DataSet locations. A custom title can be set when adding any trace (via either __init__ or add. these kwargs all eventually end up in self.traces[i][‘config’]) and it looks like we will take the first title we find from any trace… otherwise, if no trace specifies a title, then we combine whatever dataset locations we find.

Note: (alexj): yeah, that’s awkward, isn’t it, and it looks like a weird implementation, feel free to change it 👼

Returns

the title of the figure

Return type

str

static get_label(data_array)

Look for a label in data_array falling back on name.

Parameters

data_array (DataArray) – data array to get label from

Returns

label or name of the data_array

Return type

str

halt()

Stop automatic updates to this plot, by canceling its update widget

latest_plot = None

Auto-updating plot connected to a Jupyter notebook

Parameters

• interval (int) – period in seconds between update checks default 1

• data_keys (str) – sequence of keys in trace config can contain data that we should look for updates in. default ‘xyz’ (treated as a sequence) but add more if for example marker size or color can contain data

replace(*args, updater=None, **kwargs)

Clear all content and add new trace.

Parameters

• args – optional way to provide x/y/z data without keywords If the last one is 1D, may be y or x, y If the last one is 2D, may be z or x, y, z

• updater – a callable (with no args) that updates the data in this trace if omitted, we will look for DataSets referenced in this data, and call their sync methods.

• **kwargs – passed on to self.add()

update()

Update the data in this plot, using the updaters given with MatPlot.add() or in the included DataSets, then include this in the plot.

This is a wrapper routine that the update widget calls, inside this we call self.update() which should be subclassed