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: 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_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: bool = None, **plot_cfg)

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

_abc_impl = <_abc_data object>
_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.

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]

_prepare_path(out_path: str, *, exist_ok: bool) → 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 (bool) – If True, will emit a warning instead of an error

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