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: 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!

DAG_INVOKE_IN_BASE

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.

Type

bool

DAG_SUPPORTED

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

Type

bool

DEFAULT_EXT

The class variable to use for default extension.

Type

str

default_ext

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.

Type

str

DEFAULT_EXT_REQUIRED

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

Type

bool

EXTENSIONS

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

Type

tuple

OUT_PATH_EXIST_OK

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

Type

bool

POSTPONE_PATH_PREPARATION

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.

Type

bool

EXTENSIONS = 'all'
DEFAULT_EXT = None
DEFAULT_EXT_REQUIRED = True
POSTPONE_PATH_PREPARATION = False
OUT_PATH_EXIST_OK = False
DAG_SUPPORTED = False
DAG_INVOKE_IN_BASE = True
__init__(name: str, *, dm: dantro.data_mngr.DataManager, default_ext: str = None, exist_ok: bool = None, **plot_cfg)[source]

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

Parameters

  • 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 (bool, 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.

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

Raises

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

__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.

Parameters

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

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

Returns

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.

Parameters

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

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

Returns

Whether this creator can be used for the given plot config

Return type

bool

_prepare_path(out_path: str, *, exist_ok: bool) → 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.

Parameters

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

  • exist_ok (bool) – If True, will emit a warning instead of an error

Raises

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

_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.

Note

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.

Parameters

  • 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

Returns

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

Parameters

  • 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

Returns

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.

Parameters

  • 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.

Returns

Whether the DAG should be used or not

Return type

bool

_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.

Note

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