pybop.plot#

Submodules#

Attributes#

DEFAULT_BACKEND

current_backend

Functions#

chains(result[, show, backend, figures, axes])

Plot posterior distributions for each chain.

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

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

convergence(result[, show, backend, figures, axes])

Plot the convergence of the optimisation algorithm.

dataset(dataset[, signal, labels, show, backend, ...])

Quickly plot a PyBOP Dataset using Plotly.

distribution(parameters[, posterior, title, ...])

Plot the posterior on top of the prior distribution for a Bayesian optimisation result.

get_backend([backend])

Get instance of PlotBackend class for a given plotting backend

get_backend_from_figure([backend, figures])

Get instance of PlotBackend class from a provided figure or from a specified backend.

nyquist(problem[, inputs, show, title, backend, ...])

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

parameters(result[, title, show, backend, figures, axes])

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

parse_data(x, y)

Check the type and dimensions of the data and convert if necessary to a list

posterior(result[, backend, show, figures, axes])

Plot the summed posterior distribution across chains.

predictive(result[, number_of_traces, ...])

Plot the predictive posterior of a Bayesian optimisation result.

problem(problem[, inputs, title, show, backend, ...])

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

remove_brackets(s)

Remove square brackets from a string and replace with forward slashes

summary_table(result[, backend, figures, axes, show])

Display summary statistics in a table.

surface(result[, title, bounds, normalise, ...])

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

trace(result[, show, backend, figures, axes])

Plot trace plots for the posterior samples.

trajectories(x, y[, title, xaxis_title, yaxis_title, ...])

Quickly plot one or more trajectories.

use_backend(backend)

Select a plotting backend to be used for all subsequent plots.

wrap_text(text, width[, backend])

Wrap text to a specified width with HTML line breaks.

Package Contents#

pybop.plot.chains(result: pybop.samplers.base_pints_sampler.SamplingResult, show=True, backend=None, figures=None, axes=None)[source]#

Plot posterior distributions for each chain.

Parameters:

  • result (pybop.SamplingResult) – The result of the sampling process.

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

  • backend (str or pybop.plot.backends.PlotBackend, optional) – Select a plotting backend. If None, the current default backend is used.

  • figures (figure object, optional) – Figure for plotting. If not provided a new figure is created.

  • axes (axis, optional) – The axes to be used for plotting. A single axis is expected.

Returns:

  • None (if show is True)

  • Figure object (if show is False) – The figure object for the chain plots.

pybop.plot.contour(call_object: Problem | Result, gradient: bool = False, bounds: numpy.ndarray | None = None, transformed: bool = False, steps: int = 10, title='Cost Landscape', show: bool = True, backend: str | pybop.plot.backends.PlotBackend = None, figures=None, axes=None)[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.Result) – 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.

  • title (str, optional) – The title of the figure (default: “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).

  • backend (str or pybop.plot.backends.PlotBackend, optional) – The plotting backend to be used.

  • figures (figure object or list of figure objects, optional) – Either a single figure or the same number of figures as axes.

  • axes (single axis or list of axes, optional) – plotly: axes expected to be of the form tuple(row, col) If gradient is false this must be a single axis. If gradient is true this must be one axis for the cost contour plot and one axis for each parameter to plot the gradient.

Returns:

  • None (if show is True)

  • figure object containing the cost landscape (if show is False and gradient is False)

  • tuple (fig, grad_figs) (if show is False and gradient is True) – fig - figure object containing the cost landscape grad_figs - list of figure objects containing the gradient for each parameter

Raises:

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

pybop.plot.convergence(result: pybop._result.Result, show: bool = True, backend: str = None, figures=None, axes=None)[source]#

Plot the convergence of the optimisation algorithm.

Parameters:

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

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

  • backend (str or pybop.plot.backends.PlotBackend, optional) – Select a plotting backend. If None, the current default backend is used.

  • figures (figure object, optional) – Figure for plotting. If not provided a new figure is created

  • axes (axis, optional) – The axis to be used for plotting plotly: axis expected to be of the form tuple(row, col)

Returns:

  • fig (if show is False; plotly.graph_objs.Figure or matplotlib.figure.Figure) – The figure object for the convergence plot.

  • None (if show is True)

pybop.plot.dataset(dataset, signal=None, labels=None, show=True, backend=None, figures=None, axes=None)[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]”).

  • labels (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).

  • backend (str or pybop.plot.backends.PlotBackend, optional) – The plotting backend to be used.

  • figures (figure object, optional) – Figure for plotting. If not provided a new figure is created

  • axes (axis, optional) – Thes axis to be used for plotting plotly: axis expected to be of the form tuple(row, col)

Returns:

  • fig (if show is False; plotly.graph_objs.Figure or matplotlib.figure.Figure) – The figure object for the scatter plot.

  • None (if show is True)

pybop.plot.distribution(parameters: pybop.parameters.parameter.Parameters, posterior: pybop.parameters.parameter.Parameters | None = None, title: str = 'Prior and Posterior Distributions', n_samples: int = 100, transformed: bool = False, show: bool = True, backend: str = None, figures=None, axes=None)[source]#

Plot the posterior on top of the prior distribution for a Bayesian optimisation result.

Parameters:

  • parameters (pybop.Parameters) – The prior distribution of the parameters.

  • posterior (pybop.Parameters, optional) – The posterior distribution of the parameters (default: None).

  • title (str, optional) – The title of the figure (default: “Prior and Posterior Distributions”).

  • n_samples (int, optional) – The number of samples to use for plotting the distributions (default: 100).

  • transformed (bool, optional) – If True, the transformed distributions are plotted (default: False).

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

  • backend (str or pybop.plot.backends.PlotBackend, optional) – Select a plotting backend. If None, the current default backend is used.

  • figures (figure object, optional) – Figure for plotting. If not provided a new figure is created. Can be a single figure or one figure per parameter.

  • axes (axis, optional) – The axes to be used for plotting. One axis per parameter is expected. plotly: axes expected to be of the form list of tuple(row, col)

Returns:

  • fig (if show is False; plotly.graph_objs.Figure or matplotlib.figure.Figure) – The figure object for the distribution plot. Returns a list of figures if multiple figures are provided for plotting.

  • None (if show is True)

pybop.plot.get_backend(backend=None)[source]#

Get instance of PlotBackend class for a given plotting backend

Parameters:

backend (str or pybop.plot.backends.PlotBackend, optional) – The plotting backend to be used (default: pybop.plot.current_backend)

pybop.plot.get_backend_from_figure(backend=None, figures=None)[source]#

Get instance of PlotBackend class from a provided figure or from a specified backend. If both are provided, the figure’s backend takes precedence.

Parameters:

  • backend (str or pybop.plot.backends.PlotBackend, optional) – The plotting backend to be used (default: pybop.plot.current_backend)

  • figures (figure object, optional) – Figure for plotting. If not provided a new figure is created

Returns:

Instance of the selected plotting backend.

Return type:

pybop.plot.backends.PlotBackend

pybop.plot.nyquist(problem, inputs: pybop.parameters.parameter.Inputs = None, show=True, title='Nyquist Plot', backend=None, figures=None, axes=None)[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.

  • title (str, optional) – The title of the figure

  • 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.

  • backend (str or pybop.plot.backends.PlotBackend, optional) – The plotting backend to be used.

  • figures (figure object or list of figure objects, optional) – Either a single figure or the same number of figures as axes.

  • axes (single axis or list of axes, optional) – plotly: axes expected to be of the form tuple(row, col) Number of axes must agree with number of targets for the problem.

Returns:

fig or list of figs – A single figure or a list of figures containing the Nyquist plots for each target in the problem. If show is True, the figures will be displayed and None will be returned.

Return type:

plotly.graph_objs.Figure or matplotlib.figure.Figure

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.

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.Result, title: str = 'Parameter Convergence', show: bool = True, backend: str = None, figures=None, axes=None)[source]#

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

Parameters:

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

  • title (str, optional) – The title of the plot (default: “Parameter Convergence”).

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

  • backend (str or pybop.plot.backends.PlotBackend, optional) – The plotting backend to be used

  • figures (figure object , optional) – Figure for plotting. If not provided a new figure is created. Can be a single figure or one figure per parameter.

  • axes (single axis or list of axes, optional) – axes for plotting plotly: axes expected to be of the form tuple(row, col) Number of axis must either agree with the number of parameters or be a single axis for all parameters.

Returns:

  • fig (if show is False; plotly.graph_objs.Figure or matplotlib.figure.Figure) – The figure object for the parameter plot. Returns a list of figures if multiple figures are provided for plotting.

  • None (if show is True)

pybop.plot.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.

pybop.plot.posterior(result: pybop.samplers.base_pints_sampler.SamplingResult, backend=None, show=True, figures=None, axes=None)[source]#

Plot the summed posterior distribution across chains.

Parameters:

  • result (pybop.SamplingResult) – The result of the sampling process.

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

  • backend (str or pybop.plot.backends.PlotBackend, optional) – Select a plotting backend. If None, the current default backend is used.

  • figures (figure object, optional) – Figure for plotting. If not provided a new figure is created.

  • axes (axis, optional) – The axes to be used for plotting. A single axis is expected.

Returns:

  • None (if show is True)

  • Figure object (if show is False) – The figure object for the posterior distribution plot.

pybop.plot.predictive(result: BayesianOptimisationResult | SamplingResult, number_of_traces: int = 8, data_legend_entry=None, rvs_legend_entry=None, pdf_plot=None, pdf_label: str = 'PDF', colour_scale='viridis', show: bool = True, backend: str | None = None, figures=None, axes=None)[source]#

Plot the predictive posterior of a Bayesian optimisation result.

Parameters:

  • result (pybop.BayesianOptimisationResult or pybop.SamplingResult) – The result of the Bayesian optimisation or sampling process.

  • number_of_traces (int, optional) – The number of posterior predictive traces to plot (default: 8).

  • data_legend_entry (str, optional) – The legend entry for the observed data (default: None).

  • rvs_legend_entry (str, optional) – The legend entry for the random variable samples (default: None).

  • pdf_plot (tuple, optional) – A tuple containing the x and y values for a PDF plot to overlay on the predictive plot (default: None).

  • pdf_label (str, optional) – The label for the PDF plot (default: “PDF”).

  • colour_scale (str, optional) – The colour scale to use for the predictive traces (default: “viridis”).

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

  • backend (str or pybop.plot.backends.PlotBackend, optional) – Select a plotting backend. If None, the current default backend is used.

  • figures (figure object, optional) – Figure for plotting. If not provided a new figure is created for each problem. Can be a single figure or one figure per problem.

  • axes (axis, optional) – The axes to be used for plotting. One axis per problem is expected. plotly: axes expected to be of the form list of tuple(row, col)

Returns:

  • None (if show is True)

  • Figure or list of figures (if show is False) – If show is False, returns a single figure or a list of figures containing the predictive posterior for each problem.

pybop.plot.problem(problem: pybop.problems.problem.Problem, inputs: pybop.parameters.parameter.Inputs = None, title='Scatter Plot', show: bool = True, backend: str = None, figures=None, axes=None)[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.

  • title (str, optional:) – The title of the plot (default: “Scatter Plot”)

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

  • backend (str or pybop.plot.backends.PlotBackend, optional) – The plotting backend to be used.

  • figures (figure object, optional) – Figure for plotting. If not provided a new figure is created for each problem. Can be a single figure or one figure per target.

  • axes (axis, optional) – The axes to be used for plotting. One axis per target is expected. plotly: axes expected to be of the form list of tuple(row, col)

Returns:

  • None (if show is True)

  • Figure or list of figures (if show is False) – A single figure or a list of figures containing the plots for each target in the problem. If show is True, the figures will be displayed and None will be returned.

pybop.plot.remove_brackets(s)[source]#

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

pybop.plot.summary_table(result: pybop.samplers.base_pints_sampler.SamplingResult, backend=None, figures=None, axes=None, show=True)[source]#

Display summary statistics in a table.

Parameters:

  • result (pybop.SamplingResult) – The result of the sampling process.

  • backend (str or pybop.plot.backends.PlotBackend, optional) – Select a plotting backend. If None, the current default backend is used.

  • figures (figure object, optional) – Figure for plotting. If not provided a new figure is created.

  • axes (axis, optional) – The axes to be used for plotting. A single axis is expected.

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

Returns:

  • None (if show is True)

  • Figure object (if show is False) – The figure object for the summary statistics table.

pybop.plot.surface(result: pybop._result.Result, title='Voronoi Cost Landscape', bounds=None, normalise=True, resolution=250, show=True, backend=None, figures=None, axes=None)[source]#

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

Parameters:#

resultpybop.Result

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

title: str, optional

The title of the plot (default: “Voronoi Cost Landscape”)

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).

backend: str or pybop.plot.backends.PlotBackend, optional

The plotting backend to be used.

figures: figure object, optional

Figure for plotting. If not provided a new figure is created.

axes: axis, optional

The axes to be used for plotting. A single axis is expected.

returns:

  • None (if show is True)

  • Figure object (if show is False)

pybop.plot.trace(result: pybop.samplers.base_pints_sampler.SamplingResult, show=True, backend=None, figures=None, axes=None)[source]#

Plot trace plots for the posterior samples.

Parameters:

  • result (pybop.SamplingResult) – The result of the sampling process.

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

  • backend (str or pybop.plot.backends.PlotBackend, optional) – Select a plotting backend. If None, the current default backend is used.

  • figures (figure object, optional) – Figure for plotting. If not provided a new figure is created. Can be a single figure or one figure per parameter.

  • axes (single axis or list of axes, optional) – axes for plotting plotly: axes expected to be of the form tuple(row, col) Number of axis must either agree with the number of parameters or be a single axis for all parameters.

Returns:

  • None (if show is True)

  • Figure or list of figures (if show is False) – If show is False, returns a single figure or a list of figures containing the trace plots for each parameter.

pybop.plot.trajectories(x, y, title: str = None, xaxis_title: str = None, yaxis_title: str = None, labels=None, label_width=20, show=True, backend=None, figures=None, axes=None)[source]#

Quickly plot one or more trajectories.

Parameters:

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

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

  • title (str, optional) – The title of the figure

  • xaxis_title (str, optional) – Sets the title/label of the x-axis

  • yaxis_title (str, optional) – Sets the title/label of the y-axis Settings to modify the default trace type (default: DEFAULT_TRACE_OPTIONS).

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

  • label_width (int, optional) – Maximum length of the labels before text wrapping is used (default: 20).

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

  • backend (str or pybop.plot.backends.PlotBackend, optional) – The plotting backend to be used.

  • figures (figure object, optional) – Figure for plotting. If not provided a new figure is created

  • axes (axis, optional) – Thes axis to be used for plotting plotly: axis expected to be of the form tuple(row, col)

Returns:

  • fig (if show is False; plotly.graph_objs.Figure or matplotlib.figure.Figure)

  • None (if show is True)

pybop.plot.use_backend(backend)[source]#

Select a plotting backend to be used for all subsequent plots.

Parameters:

backend (str or pybop.plot.backends.PlotBackend) – The plotting backend to be used.

pybop.plot.wrap_text(text, width, backend='matplotlib')[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

pybop.plot.DEFAULT_BACKEND = 'matplotlib'#
pybop.plot.current_backend = 'matplotlib'#