pybop.plot#

Submodules#

Classes#

PlotlyManager

Manages the installation and configuration of Plotly for generating visualizations.

StandardPlot

A class for creating and displaying interactive Plotly figures.

StandardSubplot

A class for creating and displaying a set of interactive Plotly figures in a grid layout.

Functions#

contour(call_object[, gradient, bounds, transformed, ...])

Plot a 2D visualisation of a cost landscape using Plotly.

convergence(result[, show])

Plot the convergence of the optimisation algorithm.

dataset(dataset[, signal, trace_names, show])

Quickly plot a PyBOP Dataset using Plotly.

nyquist(problem[, inputs, show])

Generates Nyquist plots for the given problem by evaluating the model's output and target values.

parameters(result[, show])

Plot the evolution of parameters during the optimisation process using Plotly.

problem(problem[, inputs, show])

Produce a quick plot of the target dataset against optimised model output.

surface(result[, bounds, normalise, resolution, show])

Plot a 2D representation of the Voronoi diagram with color-coded regions.

trajectories(x, y[, trace_names, show])

Quickly plot one or more trajectories using Plotly.

Package Contents#

class pybop.plot.PlotlyManager[source]#

Manages the installation and configuration of Plotly for generating visualizations.

This class ensures that Plotly is installed and properly configured to display plots in a web browser.

Upon instantiation, it checks for Plotly’s presence, installs it if missing, and configures the default renderer and browser settings.

go#

The Plotly graph_objects module for creating figures.

Type:

module

pio#

The Plotly input/output module for configuring the renderer.

Type:

module

make_subplots#

The function from Plotly for creating subplot figures.

Type:

function

Examples

>>> plotly_manager = PlotlyManager()
check_browser_availability()[source]#

Confirm a web browser is available for Plotly’s ‘browser’ renderer; provide guidance if not.

check_renderer_settings()[source]#

Check and provide information on setting the Plotly renderer if it’s not already set.

ensure_plotly_installed()[source]#

Check if Plotly is installed and import necessary modules; prompt for installation if missing.

static install_plotly()[source]#

Install the Plotly package using pip. Exit if installation fails.

post_install_setup()[source]#

Import Plotly modules and set the default renderer after installation.

prompt_for_plotly_installation()[source]#

Prompt the user for Plotly installation and install it upon agreement.

go = None#
make_subplots = None#
pio = None#
class pybop.plot.StandardPlot(x=None, y=None, layout=None, layout_options=None, trace_options=None, trace_names=None, trace_name_width=40)[source]#

A class for creating and displaying interactive Plotly figures.

Parameters:

  • x (list or np.ndarray, optional) – X-axis data points.

  • y (list or np.ndarray, optional) – Primary Y-axis data points for simulated model output.

  • layout (Plotly layout, optional) – A layout for the figure, overrides the layout options (default: None).

  • layout_options (dict, optional) – Settings to modify the default layout (default: DEFAULT_LAYOUT_OPTIONS).

  • trace_options (dict, optional) – Settings to modify the default trace type (default: DEFAULT_TRACE_OPTIONS).

  • trace_names (str, optional) – Name(s) for the primary trace(s) (default: None).

  • trace_name_width (int, optional) – Maximum length of the trace names before text wrapping is used (default: 40).

Returns:

The generated Plotly figure.

Return type:

plotly.graph_objs.Figure

__call__(show=True)[source]#

Generate and show the figure.

Parameters:

show (bool, optional) – If True, the figure is shown upon creation (default: True).

add_traces(x, y, trace_names=None, **trace_options)[source]#

Add a set of traces to the plot dictionary.

Parameters:

  • x (list or np.ndarray) – X-axis data points.

  • y (list or np.ndarray) – Primary Y-axis data points for simulated model output.

  • trace_names (str or list[str], optional) – Name(s) for the primary trace(s) (default: None).

create_trace(x, y, **trace_options)[source]#

Create a trace for the Plotly figure.

Returns:

A trace for a Plotly figure.

Return type:

plotly.graph_objs.Scatter

parse_data(x, y)[source]#

Check the type and dimensions of the data and convert if necessary to a list of ‘things plotly can take’, e.g. numpy arrays or lists of numbers.

Parameters:

  • x (list or np.ndarray, optional) – X-axis data points.

  • y (list or np.ndarray, optional) – Primary Y-axis data points for simulated model output.

static remove_brackets(s)[source]#

Remove square brackets from a string and replace with forward slashes as per section 7.1 of the SI Handbook

static wrap_text(text, width)[source]#

Wrap text to a specified width with HTML line breaks.

Parameters:

  • text (str) – The text to wrap.

  • width (int) – The width to wrap the text to.

Returns:

The wrapped text.

Return type:

str

go = None#
layout = None#
trace_name_width = 40#
trace_options#
traces = []#
class pybop.plot.StandardSubplot(x, y, num_rows=None, num_cols=None, axis_titles=None, layout=None, layout_options=DEFAULT_LAYOUT_OPTIONS, subplot_options=DEFAULT_SUBPLOT_OPTIONS, trace_options=DEFAULT_SUBPLOT_TRACE_OPTIONS, trace_names=None, trace_name_width=40)[source]#

Bases: StandardPlot

A class for creating and displaying a set of interactive Plotly figures in a grid layout.

Parameters:

  • x (list or np.ndarray) – X-axis data points.

  • y (list or np.ndarray) – Primary Y-axis data points for simulated model output.

  • num_rows (int, optional) – Number of rows of subplots, can be set automatically (default: None).

  • num_cols (int, optional) – Number of columns of subplots, can be set automatically (default: None).

  • layout (Plotly layout, optional) – A layout for the figure, overrides the layout options (default: None).

  • layout_options (dict, optional) – Settings to modify the default layout (default: DEFAULT_LAYOUT_OPTIONS).

  • trace_options (dict, optional) – Settings to modify the default trace type (default: DEFAULT_TRACE_OPTIONS).

  • trace_names (str, optional) – Name(s) for the primary trace(s) (default: None).

  • trace_name_width (int, optional) – Maximum length of the trace names before text wrapping is used (default: 40).

Returns:

The generated Plotly figure.

Return type:

plotly.graph_objs.Figure

__call__(show)[source]#

Generate and show the set of figures.

Parameters:

show (bool, optional) – If True, the figure is shown upon creation (default: True).

axis_titles = None#
make_subplots = None#
num_cols = None#
num_rows = None#
num_traces = 0#
subplot_options#
pybop.plot.contour(call_object: Problem | OptimisationResult, gradient: bool = False, bounds: numpy.ndarray | None = None, transformed: bool = False, steps: int = 10, show: bool = True, **layout_kwargs)[source]#

Plot a 2D visualisation of a cost landscape using Plotly.

This function generates a contour plot representing the cost landscape for a provided callable cost function over a grid of parameter values within the specified bounds.

Parameters:

  • call_object (pybop.Problem | pybop.OptimisationResult) – Either: - the cost function to be evaluated. Must accept a list of parameter values and return a cost value. - an optimiser result which provides a specific optimisation trace overlaid on the cost landscape.

  • gradient (bool, optional) – If True, the gradient is shown (default: False).

  • bounds (numpy.ndarray | list[list[float]], optional) – A 2x2 array specifying the [min, max] bounds for each parameter. If None, uses parameters.get_bounds_for_plotly.

  • transformed (bool, optional) – Uses the transformed parameter values (as seen by the optimiser) for plotting.

  • steps (int, optional) – The number of grid points to divide the parameter space into along each dimension (default: 10).

  • show (bool, optional) – If True, the figure is shown upon creation (default: True).

  • **layout_kwargs (optional) – Valid Plotly layout keys and their values, e.g. xaxis_title=”Time [s]” or xaxis={“title”: “Time [s]”, font={“size”:14}}

Returns:

The Plotly figure object containing the cost landscape plot.

Return type:

plotly.graph_objs.Figure

Raises:

ValueError – If the cost function does not return a valid cost when called with a parameter list.

pybop.plot.convergence(result: pybop._result.OptimisationResult, show=True, **layout_kwargs)[source]#

Plot the convergence of the optimisation algorithm.

Parameters:

  • result (pybop.OptimisationResult) – Optimisation result containing the history of parameter values and associated cost.

  • show (bool, optional) – If True, the figure is shown upon creation (default: True).

  • **layout_kwargs (optional) – Valid Plotly layout keys and their values, e.g. xaxis_title=”Time [s]” or xaxis={“title”: “Time [s]”, font={“size”:14}}

Returns:

fig – The Plotly figure object for the convergence plot.

Return type:

plotly.graph_objs.Figure

pybop.plot.dataset(dataset, signal=None, trace_names=None, show=True, **layout_kwargs)[source]#

Quickly plot a PyBOP Dataset using Plotly.

Parameters:

  • dataset (object) – A PyBOP dataset.

  • signal (list or str, optional) – The name of the time series to plot (default: “Voltage [V]”).

  • trace_names (list or str, optional) – Name(s) for the trace(s) (default: “Data”).

  • show (bool, optional) – If True, the figure is shown upon creation (default: True).

  • **layout_kwargs (optional) – Valid Plotly layout keys and their values, e.g. xaxis_title=”Time / s” or xaxis={“title”: “Time [s]”, font={“size”:14}}

Returns:

The Plotly figure object for the scatter plot.

Return type:

plotly.graph_objs.Figure

pybop.plot.nyquist(problem, inputs: pybop.parameters.parameter.Inputs = None, show=True, **layout_kwargs)[source]#

Generates Nyquist plots for the given problem by evaluating the model’s output and target values.

Parameters:

  • problem (pybop.Problem) – An instance of a problem class that contains the parameters and methods for evaluation and target retrieval.

  • inputs (Inputs, optional) – Input parameters for the problem. If not provided, the default parameters from the problem instance will be used. These parameters are verified before use (default is None).

  • show (bool, optional) – If True, the plots will be displayed.

  • **layout_kwargs (dict, optional) – Additional keyword arguments for customising the plot layout. These arguments are passed to fig.update_layout().

Returns:

A list of plotly Figure objects, each representing a Nyquist plot for the model’s output and target values.

Return type:

list

Notes

  • The function extracts the real part of the impedance from the model’s output and the real and imaginary parts of the impedance from the target output.

  • For each signal in the problem, a Nyquist plot is created with the model’s impedance plotted as a scatter plot.

  • An additional trace for the reference (target output) is added to the plot.

  • The plot layout can be customised using layout_kwargs.

Example

>>> problem = pybop.EISProblem()
>>> nyquist_figures = nyquist(problem, show=True, title="Nyquist Plot", xaxis_title="Real(Z)", yaxis_title="Imag(Z)")
>>> # The plots will be displayed and nyquist_figures will contain the list of figure objects.
pybop.plot.parameters(result: pybop._result.OptimisationResult, show=True, **layout_kwargs)[source]#

Plot the evolution of parameters during the optimisation process using Plotly.

Parameters:

  • result (pybop.OptimisationResult) – Optimisation result containing the history of parameter values and associated cost.

  • show (bool, optional) – If True, the figure is shown upon creation (default: True).

  • **layout_kwargs (optional) – Valid Plotly layout keys and their values, e.g. xaxis_title=”Time [s]” or xaxis={“title”: “Time [s]”, font={“size”:14}}

Returns:

A Plotly figure object showing the parameter evolution over iterations.

Return type:

plotly.graph_objs.Figure

pybop.plot.problem(problem: pybop.problems.problem.Problem, inputs: pybop.parameters.parameter.Inputs = None, show: bool = True, **layout_kwargs)[source]#

Produce a quick plot of the target dataset against optimised model output.

Generates an interactive plot comparing the simulated model output with an optional target dataset and visualises uncertainty.

Parameters:

  • problem (pybop.Problem) – Problem object with dataset and targets attributes.

  • inputs (Inputs) – Optimised (or example) parameter values.

  • show (bool, optional) – If True, the figure is shown upon creation (default: True).

  • **layout_kwargs (optional) – Valid Plotly layout keys and their values, e.g. xaxis_title=”Time / s” or xaxis={“title”: “Time [s]”, font={“size”:14}}

Returns:

The Plotly figure object for the scatter plot.

Return type:

plotly.graph_objs.Figure

pybop.plot.surface(result: pybop._result.OptimisationResult, bounds=None, normalise=True, resolution=250, show=True, **layout_kwargs)[source]#

Plot a 2D representation of the Voronoi diagram with color-coded regions.

Parameters:#

resultpybop.OptimisationResult

Optimisation result containing the history of parameter values and associated cost.

boundsnumpy.ndarray, optional

A 2x2 array specifying the [min, max] bounds for each parameter. If None, uses cost.parameters.get_bounds_for_plotly.

normalisebool, optional

If True, the voronoi regions are computed using the Euclidean distance between points normalised with respect to the bounds (default: True).

resolutionint, optional

Resolution of the plot. Default is 500.

showbool, optional

If True, the figure is shown upon creation (default: True).

**layout_kwargsoptional

Valid Plotly layout keys and their values, e.g. xaxis_title=”Time [s]” or xaxis={“title”: “Time [s]”, font={“size”:14}}

pybop.plot.trajectories(x, y, trace_names=None, show=True, **layout_kwargs)[source]#

Quickly plot one or more trajectories using Plotly.

Parameters:

  • x (list or np.ndarray) – X-axis data points.

  • y (list or np.ndarray) – Y-axis data points for each trajectory.

  • trace_names (list or str, optional) – Name(s) for the trace(s) (default: None).

  • **layout_kwargs (optional) – Valid Plotly layout keys and their values, e.g. xaxis_title=”Time / s” or xaxis={“title”: “Time [s]”, font={“size”:14}}

Returns:

The Plotly figure object for the scatter plot.

Return type:

plotly.graph_objs.Figure