dantro.plot_creators.pcr_base module

This module implements the base PlotCreator class.

Classes derived from this class create plots for single files.

The interface is defined as an abstract base class and partly implemented by the BasePlotCreator (which still remains abstract).

class dantro.plot_creators.pcr_base.BasePlotCreator(name: str, *, dm: dantro.data_mngr.DataManager, default_ext: str = None, exist_ok: Union[bool, str] = None, raise_exc: bool = None, **plot_cfg)[source]

Bases: dantro.abc.AbstractPlotCreator

The base class for PlotCreators

Note that the plot method remains abstract, thus this class needs to be subclassed and the method implemented!


Whether the DAG should be created and computed here (in the base class). If False, the base class does nothing to create or compute it and the derived classes have to take care of it on their own.




Whether placeholders in the plot config, ResultPlaceholder objects, should be replaced with results from the data transformations.




Whether the data selection and transformation interface is supported by this PlotCreator. If False, the related methods will not be called.




The class variable to use for default extension.




The property-managed actual value for the default extension to use. This value is needed by the PlotManager in order to generate an out_path. It can be changed during runtime, but not by passing arguments to __call__, as at that point the out_path already needs to be fixed.




Whether a default extension is required or not. If True and the default_ext property evaluates to False, an error will be raised.




The supported extensions. If ‘all’, no checks for the extensions are performed




Whether a warning should be shown (instead of an error, when a plot file already exists at the specified output path




Whether to prepare paths in the base class’s __call__ method or not. If the derived class wants to take care of this on their own, this should be set to True and the _prepare_path method, adjusted or not, should be called at another point of the plot execution.



__init__(name: str, *, dm: dantro.data_mngr.DataManager, default_ext: str = None, exist_ok: Union[bool, str] = None, raise_exc: bool = None, **plot_cfg)[source]

Create a PlotCreator instance for a plot with the given name.

Typically, a creator has not be instantiated separately, but the PlotManager takes care of it.

  • name (str) – The name of this plot

  • dm (DataManager) – The data manager that contains the data to plot

  • default_ext (str, optional) – The default extension to use; needs to be in EXTENSIONS, if that class variable is not set to ‘all’. The value given here is needed by the PlotManager to build the output path.

  • exist_ok (Union[bool, str], optional) – If True, no error will be raised when a plot already exists at the specified output path. If None, the value specified in the OUT_PATH_EXIST_OK class variable will be used to determine this behaviour. If skip, will skip the plot, allowing other plots to be carried out; see Skipping Plots.

  • raise_exc (bool, optional) – Whether to raise exceptions during the plot procedure. This does not pertain to all exceptions, but only to those that would unnecessarily stop plotting. Furthermore, whether this setting is used or not depends on the used creator specialization.

  • **plot_cfg – The default configuration for the plot(s) that this creator is supposed to create.


ValueError – On bad default_ext argument

property name

Returns this creator’s name

property classname

Returns this creator’s class name

property logstr

Returns the classname and name of this object; a combination often used in logging…

property dm

Return the DataManager

property plot_cfg

Returns a deepcopy of the plot configuration, assuring that plot configurations are completely independent of each other.

property default_ext

Returns the default extension to use for the plots

property dag

The associated TransformationDAG object. If not set up, raises.

__call__(*, out_path: str, **update_plot_cfg)[source]

Perform the plot, updating the configuration passed to __init__ with the given values and then calling _plot.

  • out_path (str) – The full output path to store the plot at

  • **update_plot_cfg – Keys with which to update the default plot configuration


The return value of the plot() method, which is an abstract method in BasePlotCreator.

get_ext() → str[source]

Returns the extension to use for the upcoming plot by checking the supported extensions and can be subclassed to have different behaviour.

prepare_cfg(*, plot_cfg: dict, pspace: Union[paramspace.paramspace.ParamSpace, dict]) → Tuple[dict, paramspace.paramspace.ParamSpace][source]

Prepares the plot configuration for the PlotManager.

This function is called by the plot manager before the first plot is created.

The base implementation just passes the given arguments through. However, it can be re-implemented by derived classes to change the behaviour of the plot manager, e.g. by converting a plot configuration to a parameter space.

can_plot(creator_name: str, **plot_cfg) → bool[source]

Whether this plot creator is able to make a plot for the given plot configuration. By default, this always returns false.

  • creator_name (str) – The name for this creator used within the PlotManager.

  • **plot_cfg – The plot configuration with which to decide this.


Whether this creator can be used for the given plot config

Return type


_prepare_path(out_path: str, *, exist_ok: Union[bool, str]) → None[source]

Prepares the output path, creating directories if needed, then returning the full absolute path.

This is called from __call__ and is meant to postpone directory creation as far as possible.

  • out_path (str) – The absolute output path to start with

  • exist_ok (Union[bool, str]) – If False, will raise if a file of that name already exists; if True, will emit a warning instead. If 'skip', will initiate skipping of this plot.


FileExistsError – Raised on already existing out path and exist_ok being False.

_check_skipping(*, plot_kwargs: dict)[source]

A method that can be specialized by derived plot creators to check whether a plot should be skipped. Is invoked from the __call__() method, after _perform_data_selection() (for plots with activated data selection via DAG), and prior to _prepare_path() (such that path creation can be avoided).

In cases where this plot is to be skipped, the custom exception SkipPlot should be raised, the error message allowing to specify a reason for skipping the plot.


While the base class method may be a no-op, it should still be called via super()._check_skipping from the derived classes.


plot_kwargs (dict) – The full plot configuration

_perform_data_selection(*, use_dag: bool = None, plot_kwargs: dict, **shared_kwargs) → Tuple[bool, dict][source]

If this plot creator supports data selection and transformation, it is carried out in this method.

This method uses a number of other private methods to carry out the setup of the DAG, computing it and combining its results with the remaining plot configuration. Those methods have access to a subset of the whole configuration, thus allowing to parse the parameters that they need.

This method also sets the _dag attribute, making the created TransformationDAG object available for further processing downstream.

Furthermore, this method invokes placeholder resolution by applying resolve_placeholders() on the plot config.


For specializing the behaviour of the data selection and transform, it is best to specialize NOT this method, but the more granular DAG-related private methods.


If subclassing this method, make sure to either invoke this parent method or set the _dag attribute in the subclass’s method. Also note that, when subclassing, the ability to resolve the placeholders gets lost / has to be re-implemented in the subclass.

  • use_dag (bool, optional) – The main toggle for whether the DAG should be used or not. This is passed as default value to another method, which takes the final decision on whether the DAG is used or not. If None, will NOT use the DAG.

  • plot_kwargs (dict) – The plot configuration

  • **shared_kwargs – Shared keyword arguments that are passed through to the helper methods _use_dag and _get_dag_params


Whether data selection was used and the plot

configuration that can be passed on to the main plot method.

Return type

Tuple[bool, dict]

_get_dag_params(*, select: dict = None, transform: Sequence[dict] = None, compute_only: Sequence[str] = None, dag_options: dict = None, **plot_kwargs) → Tuple[dict, dict][source]

Filters out parameters needed for DAG initialization and compute

  • select (dict, optional) – DAG selection

  • transform (Sequence[dict], optional) – DAG transformation

  • compute_only (Sequence[str], optional) – DAG tags to be computed

  • dag_options (dict, optional) – Other DAG options for initialization

  • **plot_kwargs – The full plot configuration


Tuple of DAG parameters and plot kwargs

Return type

Tuple[dict, dict]

_use_dag(*, use_dag: bool, plot_kwargs: dict, **_kws) → bool[source]

Whether the data transformation framework should be used.

  • use_dag (bool) – The value from the plot configuration

  • plot_kwargs (dict) – The plot configuration

  • **_kws – Any further kwargs that can be used to assess whether the DAG should be used or not. Ignored here.


Whether the DAG should be used or not

Return type


_abc_impl = <_abc_data object>
_create_dag(**dag_params) → dantro.dag.TransformationDAG[source]

Creates the actual DAG object

abstract plot(out_path: str = None, **cfg)

Given a specific configuration, perform a plot.

This method should always be private and only be called from __call__.

_compute_dag(dag: dantro.dag.TransformationDAG, **compute_kwargs) → dict[source]

Compute the dag results

_combine_dag_results_and_plot_cfg(*, dag: dantro.dag.TransformationDAG, dag_results: dict, dag_params: dict, plot_kwargs: dict) → dict[source]

Combines DAG reuslts and plot configuration into one dict. The returned dict is then passed along to the plot method.

The base class method ditches the dag_params and only retains the results, the DAG object itself, and (of course) all the remaining plot configuration.


When subclassing, this is the method to overwrite or extend in order to affect which data gets passed on.