4.6.13 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
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 (napar    i.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, None, None]

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.