qblox_scheduler.analysis.visualization.mpl_plotting#

Module containing matplotlib and xarray plotting utilities.

Naming convention: plotting functions that require Xarray object(s) as inputs are named plot_xr_....

Functions#

plot_complex_points(...)

Plots complex points with (by default) different colors and markers on

get_unit_from_attrs(→ str)

Extracts and formats the unit/units from an xarray.DataArray attribute.

plot_xr_complex(...)

Plots the real and imaginary parts of complex data. Points are colored by default

plot_xr_complex_on_plane(...)

Plots complex data on the imaginary plane. Points are colored by default

set_suptitle_from_dataset(→ None)

Sets the suptitle of a matplotlib figure based on

set_cyclic_colormap(→ None)

Sets a cyclic colormap on a matplolib 2D color plot if cyclic units are detected.

plot_textbox(→ matplotlib.text.Text)

Plot a textbox with sensible defaults using text.

plot_fit(→ list[matplotlib.lines.Line2D])

Plot a fit of an lmfit model with a real domain.

plot_fit_complex_plane(→ None)

Plot a fit of an lmfit model with a real domain in the complex plane.

flex_colormesh_plot_vs_xy(, transpose)

Add a rectangular block to a color plot using

plot_2d_grid(, transpose, ...)

Creates a heatmap of x,y,z data that was acquired on a grid expects three "columns"

Module Contents#

plot_complex_points(points: list[numbers.Complex] | numpy.typing.NDArray[numpy.complexfloating], colors: list | None = None, labels: list | None = None, markers: list | None = None, legend: bool = True, ax: matplotlib.axes.Axes | None = None, **kwargs) → tuple[matplotlib.figure.Figure | matplotlib.figure.SubFigure | None, matplotlib.axes.Axes][source]#

Plots complex points with (by default) different colors and markers on the imaginary plane using matplotlib.axes.Axes.plot().

Intended for a small number of points.

Example

_ = plot_complex_points([1 + 1j, -1.5 - 2j])

Parameters:

  • ax – A matplotlib axis to plot on.

  • points – Array of complex numbers.

  • colors – Colors to use for each point.

  • labels – Labels to use for each point. Defaults to f"|{i}>"

  • markers – Markers to use for each point.

  • legend – Calls legend() if True.

  • **kwargs – Keyword arguments passed to the plot().

get_unit_from_attrs(data_array: xarray.DataArray, str_format: str = ' [{}]') → str[source]#

Extracts and formats the unit/units from an xarray.DataArray attribute.

Parameters:

  • data_array – Xarray array (coordinate or variable).

  • str_format – String that will be formatted if a unit is found.

Returns:

: str_format string formatted with the data_array.unit or data_array.units, with that order of precedence. Empty string is returned if none of these arguments are present.

plot_xr_complex(var: xarray.DataArray, marker_scatter: str = 'o', label_real: str = 'Real', label_imag: str = 'Imag', cmap: str = 'viridis', c: numpy.ndarray | None = None, kwargs_line: dict | None = None, kwargs_scatter: dict | None = None, title: str = '{} [{}]; shape = {}', legend: bool = True, ax: matplotlib.axes.Axes | None = None) → tuple[matplotlib.figure.Figure | matplotlib.figure.SubFigure | None, matplotlib.axes.Axes][source]#

Plots the real and imaginary parts of complex data. Points are colored by default according to their order in the array.

Parameters:

  • var – 1D array of complex data.

  • marker_scatter – Marker used for the scatter plot.

  • label_real – Label for legend.

  • label_imag – Label for legend.

  • cmap – The colormap to use for coloring the points.

  • c – Color of the points. Defaults to an array of integers.

  • kwargs_line – Keyword arguments passed to matplotlib.axes.Axes.plot().

  • kwargs_scatter – Keyword arguments passed to matplotlib.axes.Axes.scatter().

  • title – Axes title. By default gets formatted with var.long_name, var.name and var.shape``.

  • legend – Calls legend() if True.

  • ax – The matplotlib axes. If None a new axes (and figure) is created.

plot_xr_complex_on_plane(var: xarray.DataArray, marker: str = 'o', label: str = 'Data on imaginary plane', cmap: str = 'viridis', c: numpy.ndarray | None = None, xlabel: str = 'Real{}{}{}', ylabel: str = 'Imag{}{}{}', legend: bool = True, ax: matplotlib.axes.Axes | None = None, **kwargs) → tuple[matplotlib.figure.Figure | matplotlib.figure.SubFigure | None, matplotlib.axes.Axes][source]#

Plots complex data on the imaginary plane. Points are colored by default according to their order in the array.

Parameters:

  • var – 1D array of complex data.

  • marker – Marker used for the scatter plot.

  • label – Data label for the legend.

  • cmap – The colormap to use for coloring the points.

  • c – Color of the points. Defaults to an array of integers.

  • xlabel – Label o x axes.

  • ylabel – Label o y axes.

  • legend – Calls legend() if True.

  • ax – The matplotlib axes. If None a new axes (and figure) is created.

set_suptitle_from_dataset(fig: matplotlib.figure.Figure, dataset: xarray.Dataset, prefix: str = '') → None[source]#

Sets the suptitle of a matplotlib figure based on

  • (optional) prefix;

  • dataset.name;

  • dataset.tuid,

Intended for tagging figures with unique ID of the original dataset.

Parameters:

  • prefix – Optional string to pre-pend, e.g., x0-y0.

  • fig – The matplotlib figure.

  • dataset – A dataset expected to have a .name and a .tuid" attributes.

set_cyclic_colormap(image_or_collection: matplotlib.image.AxesImage | matplotlib.collections.QuadMesh | matplotlib.collections.Collection, shifted: bool = False, unit: Literal['deg', 'rad'] = 'deg', clim: tuple | None = None) → None[source]#

Sets a cyclic colormap on a matplolib 2D color plot if cyclic units are detected.

See also

Using cyclic colormaps

Parameters:

  • image_or_collection – A matplotlib object returned by either one of pcolor(), pcolormesh(), imshow() or matshow().

  • shifted – Chooses between "twilight_shifted"/"twilight" colormap and the colormap range.

  • unit – Used to fix the colormap range.

  • clim – The colormap limit.

plot_textbox(ax: matplotlib.axes.Axes, text: str, **kw) → matplotlib.text.Text[source]#

Plot a textbox with sensible defaults using text.

Parameters:

  • ax – The Axes on which to plot.

  • text – The text of the textbox.

Returns:

: the new text object

plot_fit(ax, fit_res, plot_init: bool = True, plot_numpoints: int = 1000, range_casting: Literal['abs', 'angle', 'real', 'imag'] = 'real', fit_kwargs: dict | None = None, init_kwargs: dict | None = None) → list[matplotlib.lines.Line2D][source]#

Plot a fit of an lmfit model with a real domain.

Parameters:

  • ax – axis on which to plot the fit.

  • fit_res – an lmfit fit results object.

  • plot_init – if True, plot the initial guess of the fit.

  • plot_numpoints – the number of points used on which to evaluate the fit.

  • range_casting – how to plot fit functions that have a complex range. Casting of values happens using absolute, angle, real and imag. Angle is in degrees.

  • fit_kwargs – Matplotlib pyplot formatting and label keyword arguments for the fit plot. default value is {“color”: “C3”, “label”: “Fit”}

  • optional – Matplotlib pyplot formatting and label keyword arguments for the fit plot. default value is {“color”: “C3”, “label”: “Fit”}

  • init_kwargs – Matplotlib pyplot formatting and label keyword arguments for the init plot. default value is {“color”: “grey”, “linestyle”: “–”, “label”: “Guess”}

  • optional – Matplotlib pyplot formatting and label keyword arguments for the init plot. default value is {“color”: “grey”, “linestyle”: “–”, “label”: “Guess”}

Returns:

: list of matplotlib pyplot Line2D objects

plot_fit_complex_plane(ax, fit_res, plot_init: bool = True, plot_numpoints: int = 1000) → None[source]#

Plot a fit of an lmfit model with a real domain in the complex plane.

flex_colormesh_plot_vs_xy(xvals: numpy.ndarray, yvals: numpy.ndarray, zvals: numpy.ndarray, ax: matplotlib.axes.Axes, normalize: bool = False, log: bool = False, cmap: str = 'viridis', vlim: tuple = (None, None), transpose: bool = False) → matplotlib.collections.QuadMesh[source]#

Add a rectangular block to a color plot using pcolormesh().

Parameters:

  • xvals – Length N array corresponding to settable x0.

  • yvals – Length M array corresponding to settable x1.

  • zvals – M*N array corresponding to gettable yi.

  • ax – Axis to which to add the colormesh.

  • normalize – If True, normalizes each row of data.

  • log – if True, uses a logarithmic colorscale.

  • cmap – Colormap to use. See matplotlib docs for choosing an appropriate colormap.

  • vlim – Limits of the z-axis.

  • transpose – If True transposes the figure.

Returns:

: The created matplotlib QuadMesh.

Warning

The grid orientation for the zvals is the same as is used in pcolormesh(). Note that the column index corresponds to the x-coordinate, and the row index corresponds to y. This can be counter.intuitive: zvals(y_idx, x_idx) and can be inconsistent with some arrays of zvals (such as a 2D histogram from numpy).

plot_2d_grid(x, y, z, xlabel: str, xunit: str, ylabel: str, yunit: str, zlabel: str, zunit: str, ax: matplotlib.axes.Axes, cax: matplotlib.axes.Axes | None = None, add_cbar: bool = True, title: str | None = None, normalize: bool = False, log: bool = False, cmap: str = 'viridis', vlim: tuple = (None, None), transpose: bool = False) → tuple[matplotlib.collections.QuadMesh, matplotlib.colorbar.Colorbar | None][source]#

Creates a heatmap of x,y,z data that was acquired on a grid expects three “columns” of data of equal length.

Parameters:

  • x – Length N array corresponding to x values.

  • y – Length N array corresponding to y values.

  • z – Length N array corresponding to gettable z values.

  • xlabel – x label to add to the heatmap.

  • ylabel – y label to add to the heatmap.

  • xunit – x unit used in unit aware axis labels.

  • yunit – y unit used in unit aware axis labels.

  • zlabel – Label used for the colorbar.

  • ax – Axis to which to add the colormesh.

  • cax – Axis on which to add the colorbar, if set to None, will create a new axis.

  • add_cbar – if True, adds a colorbar.

  • title – Text to add as title to the axis.

  • normalize – if True, normalizes each row of data.

  • log – if True, uses a logarithmic colorscale

  • cmap –

    The colormap to use. See matplotlib docs for choosing an appropriate colormap.

  • vlim – limits of the z-axis.

  • transpose – if True transposes the figure.

Returns:

: The new matplotlib QuadMesh and Colorbar.