The aim of the
PlotHelper is to let the plot functions focus on what cannot easily be automated: being the bridge between some selected or transformed data and its visualization.
The plot function should not have to concern itself with things like plot aesthetics, as that can easily be automated.
PlotHelper can make your life easier by quite a lot as it already takes care of setting up and saving a figure and makes large parts of the
matplotlib.pyplot interface accessible via the plot configuration.
That way, you don’t need to touch Python code for trivial tasks like changing the axis limits.
But even more advanced tasks, such as creating an animation, are conveniently done using this framework.
Most importantly, it will make your plots future-proof and let them profit from upcoming features. A glimpse of that can be seen in how easy it is to implement an animated plot, see below.
To learn, how you can enable the PlotHelper in your plot function, check out the section on implementing plot functions.
As an example, the following plot configuration sets the title of the plot as well as the labels and limits of the axes:
my_plot: # ... # Configure the plot helpers helpers: set_title: title: This is My Fancy Plot set_labels: x: $A$ y: Counts $N_A$ set_limits: x: [0, max] y: [1.0, ~]
The enabled helpers are automatically invoked after the plot function has been called and before the plot is saved.
Aside from specifying values in the configuration, helpers can also be dynamically (re-)configured from within the plot function using
PlotHelper.provide_defaults() or be invoked directly using
To ensure that helpers stay disabled, regardless of configuration, you can call
mark_disabled() inside the plot function.
The syntax for each individual helper is in large parts equivalent to matplotlib’s pyplot interface.
It is however wrapped and simplified in some cases, e.g. by using just
y as arguments and gathering such functionality under one helper.
If you get it wrong, the error message aims to be helpful: it provides the full signature and docstring of the invoked helper such that you can adjust the parameters to the required format.
Thus, trial and error is a useful initial approach before digging into the
PlotHelper API reference.
Furthermore, notice how you can combine the capabilities of the plot helper framework with the ability to set the plot style.
The following helper methods are available:
In : from dantro.plot import PlotHelper In : hlpr = PlotHelper(out_path="~/my_output_directory") In : print("\n".join(hlpr.available_helpers)) align_labels annotate autofmt_xdate call despine figcall set_figlegend set_hv_lines set_labels set_legend set_limits set_margins set_scales set_suptitle set_texts set_tick_formatters set_tick_locators set_ticks set_title subplots_adjust
Additionally, there are “special” helpers that help with setting up and storing a figure:
By default, helpers are regarded as axis-level helpers, as they operate on a single axis object.
However, there are some helpers that may only be used on the whole figure, so-called figure-level helpers (e.g.
Axis-specific helper configurations#
PlotHelper is not restricted to a single axis, but it can manage multiple axes aranged on a grid.
A possible plot configuration with axis-specific helpers could look as follows:
my_plot: # ... # Configure the plot helpers helpers: setup_figure: ncols: 2 sharey: True set_limits: x: [0, max] y: [1.0, ~] axis_specific: my_left_axis: axis: [0, 0] set_title: title: This is my left plot my_right_axis: axis: [1, 0] set_title: title: This is my right plot
Putting the above configuration into words:
PlotHelper.setup_figure()helper sets up a figure with with two subfigures that are accessible via the coordinate pairs
set_limitshelper is applied to all existing axes.
Helpers for specific axes can be configured by passing an
axis_specificdictionary. In the plot function, you can then switch axes using the
[0, 0]axis is selected initially).
The keys for the
axis_specific configuration are arbitrary; the axes are defined solely by the internal
While this requires to specify a name for the axis, it also allows convenient recursive updating; thus, it is advisable to choose a somewhat meaningful name.
Alternatively, the axes match can be defined via the update key directly, for instance:
my_plot: # ... helpers: setup_figure: ncols: 2 sharey: True axis_specific: [0, 0]: set_title: title: This is my left plot [1, 0]: axis: [1, 0] set_title: title: This is my right plot
This syntax also supports simple pattern matching to apply axis-specific updates to plots from a whole row or column.
To span over a row or column, simply replace the entry by
None (in YAML:
[0, ~] matches all subplots in the first column and
[~, -1] matches the whole bottom row.
Plot helpers can also be explicitly disabled via the configuration:
helpers: set_labels: enabled: false # ...
By default, an axis-level plot helper is not invoked on an axis that is empty, i.e. an axis that has no artists associated with it. This is to reduce errors that stem from e.g. attempting to extract limit values from an axis without data. If invocation is required nevertheless, it can be explicitly allowed via the
helpers: set_limits: skip_empty_axes: false # ...
Specializing the helper#
PlotHelper already provides a default set of helpers that provide access to most of the matplotlib interface.
If you need any additional customized helpers, you can easily add new methods to a specialization of the helper:
import dantro.plot class MyPlotHelper(dantro.plot.PlotHelper): """A specialization of the dantro ``PlotHelper`` which can be used to add additional helper methods. New helper methods can be added here, names prefixed with ``_hlpr_``. """ def _hlpr_do_stuff(self, **kwargs): """My custom ``do_stuff`` helper""" # Do stuff here ... pass
Note that you will have to communicate this new plot helper type to the creator by setting