dantro.plot_creators.pcr_decl module

This module implements the DeclarativePlotCreator class

class dantro.plot_creators.pcr_decl.DeclarativePlotCreator(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.plot_creators.pcr_base.BasePlotCreator

This PlotCreator can create plots from a dantro-specific declarative plot configuration. The language is inspired by Vega-Lite but is adapted to working with the different data structures stored in a DataManager.

DAG_INVOKE_IN_BASE = True
DAG_RESOLVE_PLACEHOLDERS = True
DAG_SUPPORTED = False
DEFAULT_EXT = None
DEFAULT_EXT_REQUIRED = True
EXTENSIONS = 'all'
OUT_PATH_EXIST_OK = False
POSTPONE_PATH_PREPARATION = False
__call__(*, out_path: str, **update_plot_cfg)

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.

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

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.

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

Raises

ValueError – On bad default_ext argument

_abc_impl = <_abc_data object>
_check_skipping(*, plot_kwargs: dict)

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.

Note

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

Parameters

plot_kwargs (dict) – The full plot configuration

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

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.

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

Compute the dag results

_create_dag(**dag_params) → dantro.dag.TransformationDAG

Creates the actual DAG object

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

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]

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

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.

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.

Warning

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.

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]

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

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

Raises

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

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

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

can_plot(creator_name: str, **plot_cfg) → bool

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

property classname

Returns this creator’s class name

property dag

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

property default_ext

Returns the default extension to use for the plots

property dm

Return the DataManager

get_ext() → str

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

property logstr

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

property name

Returns this creator’s name

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

property plot_cfg

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

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

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.