Using the `Plotter` class¶

Description¶

The Plotter class aims to provide a framework, which can be used to handle default values and collect common codeblocks needed for different plotting frameworks. The Plotter class is a base class that should be subclassed for different Plotting backends. See MatplotlibPlotter or BokehPlotter for examples. The subclass provides a dictionary of all the keys that should be handled by the plotter class. The Plotter class provides a hierarchy of overwriting these parameters (Higher numbers take precedence).

Function defaults set with Plotter.set_defaults() with default_type='function'
Global defaults set with Plotter.set_defaults()
Parameters set with Plotter.set_parameters()

The subclasses should then also provide the plotting backend specific useful code snippets. For example showing colorbars, legends, and so on …

For a list of these functions you can look at the respective documentation (MatplotlibPlotter or BokehPlotter)

Writing a plotting function¶

In the following we will go through a few examples of how to write a simple plotting function using the Plotter class. We will be focusing on the MatplotlibPlotter, but all of this is very similar for other plotting backends.

Local instance¶

Even though the Plotter class is meant to be used globally or on the module level, it can also be useful locally for simplifying simple plotting scripts. Here we have a example of a function producing a single plot with the given data for the x and y coordinates.

def plot_with_defaults(x,y,**kwargs):
   from masci_tools.vis.matplotlib_plotter import MatplotlibPlotter

   #First we instantiate the MatplotlibPlotter class
   plot_params = MatplotlibPlotter()

   #Now we process the given arguments
   plot_params.set_parameters(**kwargs)

   #Set up the axis, on which to plot the data
   ax = plot_params.prepare_plot(xlabel='X', ylabel='Y', title='Single Scatterplot')

   #The plot_kwargs provides a way to get the keyword arguments for the
   #actual plotting call to `plot` in this case.
   plot_kwargs = plot_params.plot_kwargs()

   ax.plot(x, y, **plot_kwargs)

   #The MatplotlibPlotter has a lot of small helper functions
   #In this case we just want to set the limits and scale of the
   #axis if they were given
   plot_params.set_scale(ax)
   plot_params.set_limits(ax)
   plot_params.save_plot('figure')

   return ax

import numpy as np

x = np.linspace(-1, 1, 10)
y = x**2

#Some examples
plot_with_defaults(x, y)
plot_with_defaults(x, y, limits={'x': (0,1)})
plot_with_defaults(x, y, marker='s', markersize=20)

Global/Module level instance¶

The local instance already gives us reusable code snippets to avoid common pitfalls when doing matplotlib/bokeh plots. But when instantiating the Plotter class locally we have no way of letting the user modify the global defaults.

However, when handling global state we need to be careful to not leave the instance of the Plotter class in an inconsistent state. If an error is thrown inside the plotting routine the parameters would stay set and may lead to very unexpected results. For this reason every plotting function using a global or module level instance of these plotters should be decorated with the ensure_plotter_consistency() decorator. This does two things:

If an error occurs in the decorated function the parameters will be reset before the error is raised
It makes sure that nothing inside the plotting routine changed the user defined defaults

Let us take the previous example and convert it to use a global instance

from masci_tools.vis.matplotlib_plotter import MatplotlibPlotter
from masci_tools.vis.parameters import ensure_plotter_consistency

#First we instantiate the MatplotlibPlotter class
plot_params = MatplotlibPlotter()

#The decorator needs to get the plotter object
#that is used inside the function
@ensure_plotter_consistency(plot_params)
def plot_with_defaults(x,y,**kwargs):

   #Now we process the given arguments
   plot_params.set_parameters(**kwargs)

   #Set up the axis, on which to plot the data
   ax = plot_params.prepare_plot(xlabel='X', ylabel='Y', title='Single Scatterplot')

   #The plot_kwargs provides a way to get the keyword arguments for the
   #actual plotting call to `plot` in this case.
   plot_kwargs = plot_params.plot_kwargs()

   ax.plot(x, y, **plot_kwargs)

   #The MatplotlibPlotter has a lot of small helper functions
   #In this case we just want to set the limits and scale of the
   #axis if they were given
   plot_params.set_scale(ax)
   plot_params.set_limits(ax)
   plot_params.save_plot('figure')

   return ax

import numpy as np

x = np.linspace(-1, 1, 10)
y = x**2

#Some examples
plot_with_defaults(x, y)
plot_params.set_defaults(marker='s', markersize=20)
plot_with_defaults(x, y, limits={'x': (0,1)})
plot_with_defaults(x, y)

The Plotter.set_defaults() method is exposed in the two main modules for plotting masci_tools.vis.plot_methods masci_tools.vis.bokeh_plots as the functions masci_tools.vis.plot_methods.set_mpl_plot_defaults() and masci_tools.vis.bokeh_plots.set_bokeh_plot_defaults() specific to the plotter instance that is used in these modules.

Function defaults¶

Some functions may want to set function specific defaults, that make sense inside the function, but may not be useful globally. The following example sets the default linewidth for our function to 6.

Note

Function defaults are also reset by the ensure_plotter_consistency() decorator, when the plotting function terminates successfully or in an error

from masci_tools.vis.matplotlib_plotter import MatplotlibPlotter
from masci_tools.vis.parameters import ensure_plotter_consistency

#First we instantiate the MatplotlibPlotter class
plot_params = MatplotlibPlotter()

#The decorator needs to get the plotter object
#that is used inside the function
@ensure_plotter_consistency(plot_params)
def plot_with_defaults(x,y,**kwargs):

   #Set the function defaults
   plot_params.set_defaults(default_type='function', linewidth=6)

   #Now we process the given arguments
   plot_params.set_parameters(**kwargs)

   #Set up the axis, on which to plot the data
   ax = plot_params.prepare_plot(xlabel='X', ylabel='Y', title='Single Scatterplot')

   #The plot_kwargs provides a way to get the keyword arguments for the
   #actual plotting call to `plot` in this case.
   plot_kwargs = plot_params.plot_kwargs()

   ax.plot(x, y, **plot_kwargs)

   #The MatplotlibPlotter has a lot of small helper functions
   #In this case we just want to set the limits and scale of the
   #axis if they were given
   plot_params.set_scale(ax)
   plot_params.set_limits(ax)
   plot_params.save_plot('figure')

   return ax

import numpy as np

x = np.linspace(-1, 1, 10)
y = x**2

#Some examples
plot_with_defaults(x, y)
plot_params.set_defaults(marker='s', markersize=20)
plot_with_defaults(x, y, limits={'x': (0,1)})
plot_with_defaults(x, y)

Passing keyword arguments directly to plot calls¶

The plotter classes have a restricted set of keys that they recognize as valid parameters. This set is of course not complete, since there is a vast number of parameters you can set for all plotting backends. In our previous examples unknown keys will immediately lead to an error in the call to Plotter.set_parameters(). To enable this functionality we can provide the continue_on_error=True as an argument to this method.

Then the unknown keys are ignored and are returned in a dictionary. Additionally you can explicitly bypass the plotter object if you provide arguments in a dictionary with the name extra_kwargs it will be ignored, unpacked and returned along with the unknown keys

Warning

Be careful with the this feature and especially the extra_kwargs, since there is no check for name clashes with this argument. You might also run into situations, where arguments of different names collide with arguments provided by the Plotter

from masci_tools.vis.matplotlib_plotter import MatplotlibPlotter
from masci_tools.vis.parameters import ensure_plotter_consistency

#First we instantiate the MatplotlibPlotter class
plot_params = MatplotlibPlotter()

#The decorator needs to get the plotter object
#that is used inside the function
@ensure_plotter_consistency(plot_params)
def plot_with_defaults(x,y,**kwargs):

   #Set the function defaults
   plot_params.set_defaults(default_type='function', linewidth=6)

   #Now we process the given arguments (unknown ones are returned)
   kwargs = plot_params.set_parameters(continue_on_error=True, **kwargs)

   #Set up the axis, on which to plot the data
   ax = plot_params.prepare_plot(xlabel='X', ylabel='Y', title='Single Scatterplot')

   #The plot_kwargs provides a way to get the keyword arguments for the
   #actual plotting call to `plot` in this case.
   plot_kwargs = plot_params.plot_kwargs()

   ax.plot(x, y, **plot_kwargs, **kwargs)

   #The MatplotlibPlotter has a lot of small helper functions
   #In this case we just want to set the limits and scale of the
   #axis if they were given
   plot_params.set_scale(ax)
   plot_params.set_limits(ax)
   plot_params.save_plot('figure')

   return ax

import numpy as np

x = np.linspace(-1, 1, 10)
y = x**2

#The key markerfacecolor is not known to the MatplotlibPlotter
plot_with_defaults(x, y, markerfacecolor='red', markersize=20)

Multiple plotting calls¶

The plotter classes also provide support for multiple plotting calls with different data sets in a single plotting function. To enable this feature we need to set two properties on the Plotter; single_plot to False and num_plots to the number of plot calls made in this function. The plot specific parameters can then be specified in two ways. Shown behind the two ways is the way to set the color of the second data set to red.

List of values (None for unspecified values) [None,'red']
Dict with integer indices for the specified values {1: 'red'}

Unspecified values are replaced with the previously set defaults.

Note

The num_plots and single_plot properties are also reset by the ensure_plotter_consistency()

from masci_tools.vis.matplotlib_plotter import MatplotlibPlotter
from masci_tools.vis.parameters import ensure_plotter_consistency

#First we instantiate the MatplotlibPlotter class
plot_params = MatplotlibPlotter()

#The decorator needs to get the plotter object
#that is used inside the function
@ensure_plotter_consistency(plot_params)
def plot_2lines_with_defaults(x,y,**kwargs):

   plot_params.single_plot = False
   plot_params.num_plots = 2

   #Set the function defaults
   plot_params.set_defaults(default_type='function', linewidth=6)

   #Now we process the given arguments (unknown ones are returned)
   kwargs = plot_params.set_parameters(continue_on_error=True, **kwargs)

   #Set up the axis, on which to plot the data
   ax = plot_params.prepare_plot(xlabel='X', ylabel='Y', title='Single Scatterplot')

   #The plot_kwargs provides a way to get the keyword arguments for the
   #actual plotting call to `plot` in this case.
   #For multiple plots this will be a list of dicts
   #of length `num_plots`
   plot_kwargs = plot_params.plot_kwargs()

   ax.plot(x[0], y[0], **plot_kwargs[0], **kwargs)
   ax.plot(x[1], y[1], **plot_kwargs[1], **kwargs)

   #The MatplotlibPlotter has a lot of small helper functions
   #In this case we just want to set the limits and scale of the
   #axis if they were given
   plot_params.set_scale(ax)
   plot_params.set_limits(ax)
   plot_params.save_plot('figure')

   return ax

import numpy as np

x = np.linspace(-1, 1, 10)
y = x**2
y2 = x**3

#The key markerfacecolor is not known to the MatplotlibPlotter
plot_2lines_with_defaults([x,x], [y,y2])
plot_2lines_with_defaults([x,x], [y,y2],
                          color={1:'red'}, linestyle=['--',None])

Custom function specific parameters¶

You might have situations, where you want to have some function specific parameters, that should pull from the previously set defaults or even a custom default value.

The Plotter.add_parameter() method is implemented exactly for this purpose. It creates a new key to be handled by the plotter class and with the arguments default_from or default_value we can specify what the defaults should be. default_value sets a specific value, default_from specifies a key from the plotter class from which to take the default value.

The plot_kwargs() method then can take keyword arguments to replace the arguments to take with your custom parameters

Note

These added parameters live on the function defaults and parameters level, meaning they will be removed by the ensure_plotter_consistency() decorator after the function finishes

from masci_tools.vis.matplotlib_plotter import MatplotlibPlotter
from masci_tools.vis.parameters import ensure_plotter_consistency

#First we instantiate the MatplotlibPlotter class
plot_params = MatplotlibPlotter()

#The decorator needs to get the plotter object
#that is used inside the function
@ensure_plotter_consistency(plot_params)
def plot_shifted_with_defaults(x,y,**kwargs):

   #Set the function defaults
   plot_params.set_defaults(default_type='function', linewidth=6)

   plot_params.add_parameter('linestyle_shifted',
                             default_from='linestyle')

   #Now we process the given arguments (unknown ones are returned)
   kwargs = plot_params.set_parameters(continue_on_error=True, **kwargs)

   #Set up the axis, on which to plot the data
   ax = plot_params.prepare_plot(xlabel='X', ylabel='Y', title='Single Scatterplot')

   #The plot_kwargs provides a way to get the keyword arguments for the
   #actual plotting call to `plot` in this case.
   plot_kwargs = plot_params.plot_kwargs()
   ax.plot(x, y, **plot_kwargs, **kwargs)

   #This call replaces the parameter linestyle with our custom
   #parameter linestyle_shifted
   plot_kwargs = plot_params.plot_kwargs(linestyle='linestyle_shifted')
   ax.plot(x, y+2, **plot_kwargs, **kwargs)

   #The MatplotlibPlotter has a lot of small helper functions
   #In this case we just want to set the limits and scale of the
   #axis if they were given
   plot_params.set_scale(ax)
   plot_params.set_limits(ax)
   plot_params.save_plot('figure')

   return ax

import numpy as np

x = np.linspace(-1, 1, 10)
y = x**2

plot_shifted_with_defaults(x, y)
plot_shifted_with_defaults(x, y, linestyle_shifted='--')

Nested plotting functions¶

More complex plotting routines might want to call other plotting routines to simplify their structure. However, this has a side-effect when working with the Plotter class and the ensure_plotter_consistency() decorator. Since the decorator resets the parameters and function defaults after a plotting function has been called you lose everything that you might have modified in the enclosing plotting function.

If you do need access to these parameters after calling a nested plotting function the NestedPlotParameters() contextmanager is implemented. It defines a local scope, in which a plotting function can change the parameters and function defaults. After exiting the local scope the parameters and function defaults are always in the same state as when the with block was entered (Even if an error is raised). The nested plotting function will also start with the state that was set before.

Usage is shown here:

from masci_tools.vis.matplotlib_plotter import MatplotlibPlotter
from masci_tools.vis.parameters import ensure_plotter_consistency
from masci_tools.vis.parameters import NestedPlotParameters


#First we instantiate the MatplotlibPlotter class
plot_params = MatplotlibPlotter()

@ensure_plotter_consistency(plot_params)
def nested_plot_function(x, y, **kwargs):

   plot_params.set_defaults(default_type='function',
                            linewidth=10, linestyle='--')

   #The contextmanager also needs a reference to the plotter object
   #to manage
   with NestedPlotParameters(plot_params):
      ax = plot_with_defaults(x,y,**kwargs)

   #Will plot with the above set defaults
   plot_kwargs = plot_params.plot_kwargs()
   ax.plot(x, y+2, **plot_kwargs)
   plot_params.save_plot('figure')
   
   return ax

@ensure_plotter_consistency(plot_params)
def plot_with_defaults(x,y,**kwargs):

   #Set the function defaults
   plot_params.set_defaults(default_type='function', linewidth=6)

   #Now we process the given arguments
   plot_params.set_parameters(**kwargs)

   #Set up the axis, on which to plot the data
   ax = plot_params.prepare_plot(xlabel='X', ylabel='Y', title='Single Scatterplot')

   #The plot_kwargs provides a way to get the keyword arguments for the
   #actual plotting call to `plot` in this case.
   plot_kwargs = plot_params.plot_kwargs()

   ax.plot(x, y, **plot_kwargs)

   #The MatplotlibPlotter has a lot of small helper functions
   #In this case we just want to set the limits and scale of the
   #axis if they were given
   plot_params.set_scale(ax)
   plot_params.set_limits(ax)

   return ax

import numpy as np

x = np.linspace(-1, 1, 10)
y = x**2

nested_plot_function(x, y)
nested_plot_function(x, y, linewidth=1)

Using the `Plotter` class¶

Description¶

Writing a plotting function¶

Local instance¶

Global/Module level instance¶

Function defaults¶

Passing keyword arguments directly to plot calls¶

Multiple plotting calls¶

Custom function specific parameters¶

Nested plotting functions¶

Table of Contents

Previous topic

Next topic

This Page

Using the Plotter class¶

Description¶

Writing a plotting function¶

Local instance¶

Global/Module level instance¶

Function defaults¶

Passing keyword arguments directly to plot calls¶

Multiple plotting calls¶

Custom function specific parameters¶

Nested plotting functions¶

Using the `Plotter` class¶