4.6.15 pde.tools.plotting module

Tools for plotting and controlling plot output using context managers.

`add_scaled_colorbar`	Add a vertical color bar to an image plot.
`disable_interactive`	Context manager disabling the interactive mode of matplotlib.
`plot_on_axes`	Decorator for a plot method or function that uses a single axes.
`plot_on_figure`	Decorator for a plot method or function that fills an entire figure.
`PlotReference`	Contains all information to update a plot element.
`BasicPlottingContext`	Basic plotting using just matplotlib.
`JupyterPlottingContext`	Plotting in a jupyter widget using the inline backend.
`get_plotting_context`	Returns a suitable plotting context.
`napari_add_layers`	adds layers to a napari viewer

class BasicPlottingContext(fig_or_ax=None, title=None, show=True)[source]

Bases: PlottingContextBase

Basic plotting using just matplotlib.

Parameters:

fig_or_ax – If axes are given, they are used. If a figure is given, it is set as active.
title (str) – The shown in the plot
show (bool) – Flag determining whether plots are actually shown

class JupyterPlottingContext(title=None, show=True)[source]

Bases: PlottingContextBase

Plotting in a jupyter widget using the inline backend.

Parameters:

title (str) – The shown in the plot
show (bool) – Flag determining whether plots are actually shown

close()[source]: Close the plot.

supports_update: bool = False

Flag indicating whether the context supports that plots can be updated with out redrawing the entire plot.

The jupyter backend (inline) requires replotting of the entire figure, so an update is not supported.

class PlotReference(ax, element, parameters=None)[source]

Bases: object

Contains all information to update a plot element.

Parameters:

ax (matplotlib.axes.Axes) – The axes of the element
element (matplotlib.artist.Artist) – The actual element
parameters (dict) – Parameters to recreate the plot element

ax

element

parameters

class PlottingContextBase(title=None, show=True)[source]

Bases: object

Base class of the plotting contexts.

Example

The context wraps calls to the matplotlib.pyplot interface:

context = PlottingContext()
with context:
    plt.plot(...)
    plt.xlabel(...)

Parameters:

title (str) – The shown in the plot
show (bool) – Flag determining whether plots are actually shown

close()[source]: Close the plot.

fig: mpl_figure.Figure | None

supports_update: bool = True: Flag indicating whether the context supports that plots can be updated with out redrawing the entire plot.

add_scaled_colorbar(axes_image, ax=None, aspect=20, pad_fraction=0.5, label='', **kwargs)[source]

Add a vertical color bar to an image plot.

The height of the colorbar is now adjusted to the plot, so that the width determined by aspect is now given relative to the height. Moreover, the gap between the colorbar and the plot is now given in units of the fraction of the width by pad_fraction.

Inspired by https://stackoverflow.com/a/33505522/932593

Parameters:

axes_image (matplotlib.cm.ScalarMappable) – Mappable object, e.g., returned from matplotlib.pyplot.imshow()
ax (matplotlib.axes.Axes) – The current figure axes from which space is taken for the colorbar. If omitted, the axes in which the axes_image is shown is taken.
aspect (float) – The target aspect ratio of the colorbar
pad_fraction (float) – Width of the gap between colorbar and image
label (str) – Set a label for the colorbar
**kwargs – Additional parameters are passed to colorbar call

Returns:

The resulting Colorbar object

Return type:

Colorbar

disable_interactive()[source]

Context manager disabling the interactive mode of matplotlib.

This context manager restores the previous state after it is done. Details of the interactive mode are described in matplotlib.interactive().

get_plotting_context(context=None, title=None, show=True)[source]

Returns a suitable plotting context.

Parameters:

context – An instance of PlottingContextBase or an instance of matplotlib.axes.Axes or matplotlib.figure.Figure to determine where the plotting will happen. If omitted, the context is determined automatically.
title (str) – The title shown in the plot
show (bool) – Determines whether the plot is shown while the simulation is running. If False, the files are created in the background.

Returns:

The plotting context

Return type:

PlottingContextBase

in_ipython()[source]

Try to detect whether we are in an ipython shell, e.g., a jupyter notebook.

Return type:: bool

napari_add_layers(viewer, layers_data)[source]

adds layers to a napari viewer

Parameters:

viewer (napari.viewer.Viewer) – The napari application
layers_data (dict) – Data for all layers that will be added.

napari_viewer(grid, run=None, close=False, **kwargs)[source]

Creates an napari viewer for interactive plotting.

Parameters:

grid (pde.grids.base.GridBase) – The grid defining the space
run (bool) – Whether to run the event loop of napari.
close (bool) – Whether to close the viewer immediately (e.g. for testing)
**kwargs – Extra arguments are passed to napari.Viewer

Return type:

Generator[napari.viewer.Viewer]

class nested_plotting_check[source]

Bases: object

Context manager that checks whether it is the root plotting call.

Example

The context manager can be used in plotting calls to check for nested plotting calls:

with nested_plotting_check() as is_outermost_plot_call:
    make_plot(...)  # could potentially call other plotting methods
    if is_outermost_plot_call:
        plt.show()

plot_on_axes(wrapped=None, update_method=None)[source]

Decorator for a plot method or function that uses a single axes.

This decorator adds typical options for creating plots that fill a single axes. These options are available via keyword arguments. To avoid redundancy in describing these options in the docstring, the placeholder {PLOT_ARGS} can be added to the docstring of the wrapped function or method and will be replaced by the appropriate text. Note that the decorator can be used on both functions and methods.

Example

The following example illustrates how this decorator can be used to implement plotting for a given class. In particular, supplying the update_method will allow efficient dynamical plotting:

class State:
    def __init__(self) -> None:
        self.data = np.arange(8)

    def _update_plot(self, reference):
        reference.element.set_ydata(self.data)

    @plot_on_axes(update_method="_update_plot")
    def plot(self, ax):
        (line,) = ax.plot(np.arange(8), self.data)
        return PlotReference(ax, line)


@plot_on_axes
def make_plot(ax):
    ax.plot(...)

When update_method is absent, the method can still be used for plotting, but dynamic updating, e.g., by pde.trackers.PlotTracker, is not possible.

Parameters:

wrapped (callable) – Function to be wrapped
update_method (callable or str) – Method to call to update the plot. The argument of the new method will be the result of the initial call of the wrapped method.

plot_on_figure(wrapped=None, update_method=None)[source]

Decorator for a plot method or function that fills an entire figure.

This decorator adds typical options for creating plots that fill an entire figure. This decorator adds typical options for creating plots that fill a single axes. These options are available via keyword arguments. To avoid redundancy in describing these options in the docstring, the placeholder {PLOT_ARGS} can be added to the docstring of the wrapped function or method and will be replaced by the appropriate text. Note that the decorator can be used on both functions and methods.

Example

The following example illustrates how this decorator can be used to implement plotting for a given class. In particular, supplying the update_method will allow efficient dynamical plotting:

class State:
    def __init__(self) -> None:
        self.data = np.random.random((2, 8))

    def _update_plot(self, reference):
        ref1, ref2 = reference
        ref1.element.set_ydata(self.data[0])
        ref2.element.set_ydata(self.data[1])

    @plot_on_figure(update_method="_update_plot")
    def plot(self, fig):
        ax1, ax2 = fig.subplots(1, 2)
        (l1,) = ax1.plot(np.arange(8), self.data[0])
        (l2,) = ax2.plot(np.arange(8), self.data[1])
        return [PlotReference(ax1, l1), PlotReference(ax2, l2)]


@plot_on_figure
def make_plot(fig): ...

When update_method is not supplied, the method can still be used for plotting, but dynamic updating, e.g., by pde.trackers.PlotTracker, is not possible.

Parameters:

wrapped (callable) – Function to be wrapped
update_method (callable or str) – Method to call to update the plot. The argument of the new method will be the result of the initial call of the wrapped method.