pybop.plot.backends.plotly#

Attributes#

ANCHOR_MAP

LINESTYLE_MAP

MARKER_MAP

Classes#

PlotlyBackend

Plotly implementation of the PlotBackend interface.

Module Contents#

class pybop.plot.backends.plotly.PlotlyBackend[source]#

Bases: pybop.plot.backends.base.PlotBackend

Plotly implementation of the PlotBackend interface.

This backend converts backend-agnostic plot definitions into Plotly figures and traces, providing interactive visualisations while maintaining a common plotting API.

static _check_axis_input(axis, raise_error=True)[source]#

Validate that the axis input is a tuple of two numbers.

Parameters:

axis (tuple) – Axis input to validate.

Raises:

ValueError – If the axis input is not a tuple of two numbers.

_figure_layout(style, figure_title)[source]#
_get_line_options(style, opts)[source]#

Populate Plotly line styling options.

Parameters:

  • style (dict) – User-supplied style options.

  • opts (dict) – Trace options dictionary updated in-place.

Return type:

None

colorbar(fig, data, colorscale='viridis', label=None, ax=None)[source]#

Add a standalone colour bar to a figure.

Parameters:

  • fig (plotly.graph_objects.Figure) – Target figure.

  • data (array-like) – Values defining the colour range.

  • colorscale (str, optional) – Plotly colour scale name.

  • label (str, optional) – Colour bar title.

Return type:

None

contour_plot(x, y, z, fig, ax, colorscale='viridis')[source]#

Create a contour plot trace.

Parameters:

  • x (array-like) – Coordinate values.

  • y (array-like) – Coordinate values.

  • z (array-like) – Contour values.

  • colorscale (str, optional) – Plotly colour scale.

  • fig (plotly.graph_objects.Figure) – Target figure.

  • ax (tuple, optional) – Subplot location. If provided, the contour trace is added to the specified subplot.

Returns:

Contour trace.

Return type:

plotly.graph_objects.Contour

create_figure(title: str = None, xaxis_title: str = None, yaxis_title: str = None, traces=None, style: dict = None)[source]#

Create a Plotly figure.

Parameters:

  • title (str, optional) – Figure title.

  • xaxis_title (str, optional) – X-axis label.

  • yaxis_title (str, optional) – Y-axis label.

  • traces (list, optional) – Plotly traces to add to the figure.

  • style (dict, optional) –

    Currently supported options:

    • width in pixels

    • height in pixels

    • xaxis_range: range of the X-axis

    • yaxis_range: range of the Y-axis

    • bg_color: background color of the axis

Returns:

Configured Plotly figure.

Return type:

plotly.graph_objects.Figure

fill_between(x, y_upper, y_lower, color)[source]#

Create a filled region between two curves.

Parameters:

  • x (array-like) – X values.

  • y_upper (array-like) – Upper boundary.

  • y_lower (array-like) – Lower boundary.

  • color (str) – Fill colour.

Returns:

Filled area trace.

Return type:

plotly.graph_objects.Scatter

heatmap(x, y, z, colorscale='viridis')[source]#

Create a heatmap trace.

Parameters:

  • x (array-like) – Coordinate values.

  • y (array-like) – Coordinate values.

  • z (array-like) – Heatmap values.

  • colorscale (str, optional) – Plotly colour scale.

Returns:

Heatmap trace.

Return type:

plotly.graph_objects.Heatmap

histogram_plot(x, name, style=None)[source]#

Create a histogram trace.

Parameters:

  • x (array-like) – Data values.

  • name (str) – Histogram label.

  • style (dict, optional) – Histogram styling options.

Returns:

Histogram trace.

Return type:

plotly.graph_objects.Histogram

legend(fig, axes=None, style: dict = None)[source]#

Configure and display a figure legend.

Parameters:

  • fig (plotly.graph_objects.Figure) – Target figure.

  • style (dict, optional) – Legend styling options including orientation, location and anchor coordinates.

  • axes (tuple, optional) – Subplot axis to apply the legend to (if applicable).

line(x=None, y=None, label=None, style=None)[source]#

Create a line and/or marker trace.

Parameters:

  • x (array-like, optional) – X values.

  • y (array-like) – Y values.

  • label (str, optional) – Legend label.

  • style (dict, optional) –

    Line and marker styling options. Currently supported:

    • linestyle: see LINESTYLE_MAP

    • linewidth

    • color

    • marker: the marker symbol see MARKER_MAP

    • markerfacecolor

    • markeredgecolor

    • markeredgewidth

    • fillstyle (for marker)

Returns:

Scatter trace configured as a line, marker plot, or combined line-marker plot.

Return type:

plotly.graph_objects.Scatter

make_subplots(num_rows: int, num_cols: int, num_plots: int, title=None, style=None)[source]#

Create a figure containing multiple subplots.

Parameters:

  • num_rows (int) – Number of rows in the subplot grid.

  • num_cols (int) – Number of columns in the subplot grid.

  • num_plots (int) – Total number of subplots to create.

  • title (str, optional) – Figure title.

  • xaxis_titles (str or list[str], optional) – X-axis titles.

  • yaxis_titles (str or list[str], optional) – Y-axis titles.

  • style (dict, optional) – Figure styling options.

Returns:

(

figure, axes dictionary, number of rows, number of columns

)

Return type:

tuple

parse_input_axes(figures, axes, num_plots=None, allow_single_axis=True)[source]#

Parse and validate the input axes for plotting.

Parameters:

  • figures (Figure or list[Figure]) – Plotly figure(s) to which the axes belong.

  • axes (tuple or list[tuple]) – Subplot locations specified as (row, col) tuples.

  • num_plots (int, optional) – Number of plots to be displayed.

  • allow_single_axis (bool, optional) – If True, a single axis can be used for all plots.

Returns:

  • tuple –

    (

    list of figures, list of axes, number of rows, number of columns

    )

  • Raises

plot_trace(traces, fig, ax=None)[source]#

Add one or more traces to a figure or subplot.

Parameters:

  • traces (Trace or list[Trace]) – Plotly trace objects to add.

  • fig (plotly.graph_objects.Figure) – Target figure.

  • ax (tuple, optional) – Subplot location. If provided, traces are added to the specified subplot.

Return type:

None

sample_color_scale(data, scale='viridis', d_min=None, d_max=None)[source]#

Sample colours from a Plotly colour scale.

Parameters:

  • data (array-like) – Values to map onto the colour scale.

  • scale (str, optional) – Plotly colour scale name.

  • d_min (float, optional) – Minimum value used for normalisation.

  • d_max (float, optional) – Maximum value used for normalisation.

Returns:

Colours corresponding to the supplied values.

Return type:

list

scatter(x, y, colors, labels=None, colorscale='Greys')[source]#

Create a scatter plot trace.

Parameters:

  • x (array-like) – Point coordinates.

  • y (array-like) – Point coordinates.

  • colors (array-like) – Values used to colour markers.

  • labels (array-like, optional) – Hover labels.

  • colorscale (str, optional) – Plotly colour scale.

Returns:

Scatter trace.

Return type:

plotly.graph_objects.Scatter

show_figure(fig)[source]#

Display one or more Plotly figures.

Parameters:

fig (Figure or iterable[Figure]) – Figure or collection of figures to display.

show_table(header, values, title, fig=None, ax=None)[source]#

Display tabular data as a Plotly table.

Parameters:

  • header (list) – Column headers.

  • values (list) – Table contents.

  • title (str) – Table title.

  • fig (plotly.graph_objects.Figure, optional) – Figure for plotting. If not provided a new figure is created.

  • ax (tuple, optional) – Subplot location. If provided, the table is added to the specified subplot.

Returns:

  • None

  • NOTE (There seems to be a bug in plotly https://github.com/plotly/plotly.py/issues/3424)

  • If any plot with a vline is added to a figure with subplots AFTER a table was added,

  • this may cause an error. This can be avoided by always adding any tables last.

update_axes_ranges(fig, ax, xaxis_range, yaxis_range)[source]#

Update the ranges of the axes in the provided figure.

Parameters:

  • fig (Figure) – Plotly figure containing the axes to update.

  • ax (tuple) – Subplot location.

  • xaxis_range (tuple) – Range for the x-axis.

  • yaxis_range (tuple) – Range for the y-axis.

update_axes_titles(figures, axes, xaxis_titles, yaxis_titles, max_width=40)[source]#

Update the titles of the axes in the provided figures.

Parameters:

  • figures (list[Figure]) – List of plotly figures containing the axes to update.

  • axes (list[tuple]) – List of subplot locations specified as (row, col) tuples.

  • xaxis_titles (list[str]) – List of titles for the X-axes.

  • yaxis_titles (list[str]) – List of titles for the Y-axes.

  • max_width (int, optional) – Maximum width for the axis titles before wrapping. Default is 40 characters.

update_plot_titles(figures, axes, titles, max_text_width=40, pad=0)[source]#

Update the titles of the subplots in the provided figures.

Parameters:

  • figures (list[Figure]) – List of plotly figures containing the subplots to update.

  • axes (list[tuple]) – List of subplot locations specified as (row, col) tuples.

  • titles (list[str]) – List of titles for the subplots.

  • max_text_width (int, optional) – Maximum width for the subplot titles before wrapping. Default is 40 characters.

  • pad (int, optional) – Padding between the title and the subplot. Default is 0. Ignored for plotly. Added for consistency with matplotlib backend.

vline(fig, x, style=None, ax=None)[source]#

Add a vertical reference line to a figure.

Parameters:

  • fig (plotly.graph_objects.Figure) – Target figure.

  • x (float) – X-coordinate of the line.

  • style (dict, optional) – Line styling options.

  • ax (tuple, optional) – Subplot location. If provided, the line is added to the specified subplot.

Returns:

  • None

  • NOTE (There seems to be a bug in plotly https://github.com/plotly/plotly.py/issues/3424) – If any plot with a vline is added to a figure with subplots AFTER a table was added (e.g. using show_table), this may cause an error. This can be avoided by always adding any tables last.

plotly_manager#
pybop.plot.backends.plotly.ANCHOR_MAP#
pybop.plot.backends.plotly.LINESTYLE_MAP#
pybop.plot.backends.plotly.MARKER_MAP#