dantro.plot_mngr module

This module implements the PlotManager class, which handles the configuration of multiple plots and prepares the data and configuration to pass to the PlotCreator.

exception dantro.plot_mngr.PlottingError

Bases: Exception

Custom exception class for all plotting errors

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception dantro.plot_mngr.PlotConfigError

Bases: ValueError, dantro.plot_mngr.PlottingError

Raised when there were errors in the plot configuration

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception dantro.plot_mngr.InvalidCreator

Bases: ValueError, dantro.plot_mngr.PlottingError

Raised when an invalid creator was specified

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception dantro.plot_mngr.PlotCreatorError

Bases: dantro.plot_mngr.PlottingError

Raised when an error occured in a plot creator

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class dantro.plot_mngr.PlotManager(*, dm: dantro.data_mngr.DataManager, base_cfg: Union[dict, str] = None, update_base_cfg: Union[dict, str] = None, plots_cfg: Union[dict, str] = None, out_dir: Optional[str] = '{timestamp:}/', out_fstrs: dict = None, creator_init_kwargs: Dict[str, dict] = None, default_creator: str = None, auto_detect_creator: bool = False, save_plot_cfg: bool = True, raise_exc: bool = False, cfg_exists_action: str = 'raise')

Bases: object

The PlotManager takes care of configuring plots and calling the configured PlotCreator classes that then carry out the plots.

CREATORS

The mapping of creator names to classes. When it is desired to subclass PlotManager and extend the creator mapping, use dict(**pcr.ALL) to inherit the default creator mapping.

Type

dict

DEFAULT_OUT_FSTRS

The default values for the output format strings.

Type

dict

CREATORS = {'declarative': <class 'dantro.plot_creators.pcr_decl.DeclarativePlotCreator'>, 'external': <class 'dantro.plot_creators.pcr_ext.ExternalPlotCreator'>, 'multiverse': <class 'dantro.plot_creators.pcr_psp.MultiversePlotCreator'>, 'universe': <class 'dantro.plot_creators.pcr_psp.UniversePlotCreator'>, 'vega': <class 'dantro.plot_creators.pcr_vega.VegaPlotCreator'>}

DEFAULT_OUT_FSTRS = {'path': '{name:}{ext:}', 'plot_cfg': '{basename:}_cfg.yml', 'plot_cfg_sweep': '{name:}/sweep_cfg.yml', 'state': '{name:}_{val:}', 'state_join_char': '__', 'state_name_replace_chars': [], 'state_no': '{no:0{digits:d}d}', 'state_val_replace_chars': [('/', '-')], 'state_vector_join_char': '-', 'sweep': '{name:}/{state_no:}__{state:}{ext:}', 'timestamp': '%y%m%d-%H%M%S'}

__init__(*, dm: dantro.data_mngr.DataManager, base_cfg: Union[dict, str] = None, update_base_cfg: Union[dict, str] = None, plots_cfg: Union[dict, str] = None, out_dir: Optional[str] = '{timestamp:}/', out_fstrs: dict = None, creator_init_kwargs: Dict[str, dict] = None, default_creator: str = None, auto_detect_creator: bool = False, save_plot_cfg: bool = True, raise_exc: bool = False, cfg_exists_action: str = 'raise')

Initialize the PlotManager

The initialization comes with three (optional) hierarchical levels to make the configuration of plots versatile, flexible, and avoid copy- paste of configurations: The first two result in a so-called “base” configuration, a collection of available, but disabled plot configs. The third specifies the default plots, which can use the based_on feature to base their configuration on any of the configurations from the base plot configuration.

Specifically:

1. The base_cfg contains a set of plot configurations that form

   a repertoire of configurations. These are not performed by default, but can be imported.

2. The update_base_cfg contains plot configurations that are

   possibly derived from the base repertoire. This happens in the following way: First by recursive update of existing entries, and second by resolving the based_on: a_base_plot again by recursive update.

3. The plots_cfg holds enabled plot configurations, possibly

   derived from the base configuration using the based_on feature, e.g. based_on: a_base_plot; this happens by recursive update.

Parameters

• dm (DataManager) – The DataManager-derived object to read the plot data from.

• base_cfg (Union[dict, str], optional) – The default base config or a path to a yaml-file to import. The base config defines a set of plot configuration that other plot configurations can declare themselves based_on.

• update_base_cfg (Union[dict, str], optional) – An update config to the base config or a path to a yaml-file to import which recursively updates the base_cfg.

• plots_cfg (Union[dict, str], optional) – The default plots config or a path to a yaml-file to import

• out_dir (Union[str, None], optional) – If given, will use this output directory as basis for the output path for each plot. The path can be a format-string; it is evaluated upon call to the plot command. Available keys: timestamp, name, … For a relative path, this will be relative to the DataManager’s output directory. Absolute paths remain absolute. If this argument evaluates to False, the DataManager’s output directory will be the output directory.

• out_fstrs (dict, optional) –

  Format strings that define how the output path is generated. The dict given here updates the DEFAULT_OUT_FSTRS class variable which holds the default values.

  Keys: timestamp (%-style), path, sweep, state, plot_cfg, state, state_no, state_join_char, state_vector_join_char.

  Available keys for path: name, timestamp, ext.

  Additionally, for sweep: state_no, state_vector,

  state.

• creator_init_kwargs (Dict[str, dict], optional) – If given, these kwargs are passed to the initialization calls of the respective creator classes.

• default_creator (str, optional) – If given, a plot without explicit creator declaration will use this creator as default.

• auto_detect_creator (bool, optional) – If true, and no default creator is given, will try to automatically deduce the creator using the given plot arguments. All creators registered with this PlotManager instance are candidates.

• save_plot_cfg (bool, optional) – If True, the plot configuration is saved to a yaml file alongside the created plot.

• raise_exc (bool, optional) – Whether to raise exceptions if there are errors raised from the plot creator or errors in the plot configuration. If False, the errors will only be logged.

• cfg_exists_action (str, optional) – Behaviour when a config file already exists. Can be: raise (default), skip, append, overwrite, or overwrite_nowarn.

Raises

• InvalidCreator – When an invalid default creator was chosen

• KeyError – Upon bad based_on in update_base_cfg

property out_fstrs

Returns the dict of output format strings

property plot_info

Returns a list of dicts with info on all plots

property base_cfg

Returns a deep copy of the base configuration

_parse_out_dir(fstr: str, *, name: str) → str

Evaluates the format string to create an output directory.

Note that the directories are _not_ created; this is outsourced to the plot creator such that it happens as late as possible.

Parameters

• fstr (str) – The format string to evaluate and create a directory at

• name (str) – Name of the plot

• timestamp (float, optional) – Description

Returns

The path of the created directory

Return type

str

_parse_out_path(creator: dantro.plot_creators.pcr_base.BasePlotCreator, *, name: str, out_dir: str, file_ext: str = None, state_no: int = None, state_no_max: int = None, state_vector: Tuple[int] = None, dims: dict = None) → str

Given a creator and (optionally) parameter sweep information, a full and absolute output path is generated, including the file extension.

Note that the directories are _not_ created; this is outsourced to the plot creator such that it happens as late as possible.

Parameters

• creator (BasePlotCreator) – The creator instance, used to extract information on the file extension.

• name (str) – The name of the plot

• out_dir (str) – The absolute output directory, prepended to all generated paths

• file_ext (str, optional) – The file extension to use

• state_no (int, optional) – The state number, starting with 0

• state_no_max (int, optional) – The maximum state number

• state_vector (Tuple[int], optional) – The state vector with info on how far each state dimension has progressed in the sweep

• dims (dict, optional) – The dict of parameter dimensions of the sweep that is carried out.

Returns

The fully parsed output path for this plot

Return type

str

_resolve_based_on(*, cfg: dict, based_on: Union[str, Tuple[str]] = None, work_on_deepcopy: bool = True) → dict

Resolves the based_on reference in a plot configuration

Parameters

• cfg (dict) – The plot configuration that will be used to recursively update the specified base configurations.

• based_on (Union[str, Tuple[str]], optional) – The name or names of the base configuration entries to use for updating

• work_on_deepcopy (bool, optional) – Whether to work on a deepcopy

Returns

The plot configuration derived from the one at based_on

Return type

dict

Raises

KeyError – If based_on value is not a key in self._base_cfg

_get_plot_creator(creator: Optional[str], *, name: str, init_kwargs: dict, from_pspace: paramspace.paramspace.ParamSpace = None, plot_cfg: dict, auto_detect: bool = None) → dantro.plot_creators.pcr_base.BasePlotCreator

Determines which plot creator to use by looking at the given arguments. If set, tries to auto-detect from the arguments, which creator is to be used.

Then, sets up the corresponding creator and returns it.

This method is called from the plot() method.

Parameters

• creator (Union[str, None]) – The name of the creator to be found. Can be None, if no argument was given to the plot method.

• name (str) – The name of the plot

• init_kwargs (dict) – Additional creator initialization parameters

• from_pspace (ParamSpace, optional) – If the plot is to be creatd from a parameter space, that parameter space.

• plot_cfg (dict) – The plot configuration

• auto_detect (bool, optional) – Whether to auto-detect the creator. If none, the value given at initialization is used.

Returns

The selected creator object, fully initialized.

Return type

BasePlotCreator

Raises

InvalidCreator – If the creator argument was invalid or auto- detection failed.

_invoke_creator(plot_creator: Callable, *, out_path: str, **plot_cfg) → Any

This method wraps the plot creator’s __call__ and is the last PlotManager method that is called prior to handing over to the selected plot creator. It takes care of invoking the plot creator’s __call__ method and handling potential error messages and return values.

Parameters

• plot_creator (Callable) – The currently used creator

• out_path (str) – The plot output path

• **plot_cfg – The plot configuration

Returns

The return value of the plot creator’s __call__ method

Return type

Any

Raises

PlotCreatorError – On error within the plot creator

_store_plot_info(name: str, *, plot_cfg: dict, creator_name: str, save: bool, target_dir: str, **info)

Stores all plot information in the plot_info list and, if save is set, also saves it using the _save_plot_cfg method.

_save_plot_cfg(cfg: dict, *, name: str, creator_name: str, target_dir: str, exists_action: str = None, is_sweep: bool = False) → str

Saves the given configuration under the top-level entry name to a yaml file.

Parameters

• cfg (dict) – The plot configuration to save

• name (str) – The name of the plot

• creator_name (str) – The name of the creator

• target_dir (str) – The directory path to store the file in

• exists_action (str, optional) – What to do if a plot configuration already exists. Can be: overwrite, overwrite_nowarn, skip, append, raise. If None, uses the value of the cfg_exists_action argument given during initialization.

• is_sweep (bool, optional) – Set if the configuration refers to a plot in sweep mode, for which a different format string is used

Returns

The path the config was saved at (mainly used for testing)

Return type

str

Raises

ValueError – For invalid exists_action argument

plot_from_cfg(*, plots_cfg: Union[dict, str] = None, plot_only: List[str] = None, out_dir: str = None, **update_plots_cfg) → None

Create multiple plots from a configuration, either a given one or the one passed during initialization.

This is mostly a wrapper around the plot function, allowing additional ways of how to configure and create plots.

Parameters

• plots_cfg (dict, optional) – The plots configuration to use. If not given, the one specified during initialization is used. If a string is given, will assume it is a path and load the file.

• plot_only (List[str], optional) – If given, create only those plots from the resulting configuration that match these names. This will lead to the enabled key being ignored, regardless of its value.

• out_dir (str, optional) – A different output directory; will use the one passed at initialization if the given argument evaluates to False.

• **update_plots_cfg – If given, it is used to update the plots_cfg recursively. Note that on the top level the _names_ of the plots are placed; this cannot be used to make all plots have a common property.

Raises

PlotConfigError – Empty or invalid plot configuration

plot(name: str, *, based_on: Union[str, Tuple[str]] = None, from_pspace: Union[dict, paramspace.paramspace.ParamSpace] = None, **plot_cfg) → dantro.plot_creators.pcr_base.BasePlotCreator

Create plot(s) from a single configuration entry.

A call to this function resolves the based_on feature and passes the derived plot configuration to self._plot(), which actually carries out the plots.

Note that more than one plot can result from a single configuration entry, e.g. when plots were configured that have more dimensions than representable in a single file.

Parameters

• name (str) – The name of this plot

• based_on (Union[str, Tuple[str]], optional) – A key or a sequence of keys of entries in the base config that should be used as the basis of this plot. The given plot configuration is then used to recursively update (a copy of) those base configuration entries.

• from_pspace (Union[dict, ParamSpace], optional) – If given, execute a parameter sweep over these parameters, re-using the same creator instance. If this is a dict, a ParamSpace is created from it.

• **plot_cfg – The plot configuration, including some parameters that the plot manager will evaluate (and consequently: does not pass on to the plot creator)

Returns

The PlotCreator used for these plots

Return type

BasePlotCreator

_plot(name: str, *, creator: str = None, out_dir: str = None, from_pspace: paramspace.paramspace.ParamSpace = None, file_ext: str = None, save_plot_cfg: bool = None, auto_detect_creator: bool = None, creator_init_kwargs: dict = None, **plot_cfg) → dantro.plot_creators.pcr_base.BasePlotCreator

Create plot(s) from a single configuration entry.

A call to this function creates a single PlotCreator, which is also returned after all plots are finished.

Note that more than one plot can result from a single configuration entry, e.g. when plots were configured that have more dimensions than representable in a single file.

Parameters

• name (str) – The name of this plot

• creator (str, optional) – The name of the creator to use. Has to be part of the CREATORS class variable. If not given, the argument default_creator given at initialization will be used.

• out_dir (str, optional) – If given, will use this directory as out directory. If not, will use the default value given at initialization.

• file_ext (str, optional) – The file extension to use, including the leading dot!

• from_pspace (ParamSpace, optional) – If given, execute a parameter sweep over these parameters, re-using the same creator instance

• save_plot_cfg (bool, optional) – Whether to save the plot config. If not given, uses the default value from initialization.

• auto_detect_creator (bool, optional) – Whether to attempt auto- detection of the creator argument. If given, this argument overwrites the value given at PlotManager initialization.

• creator_init_kwargs (dict, optional) – Passed to the plot creator during initialization. Note that the arguments given at initialization of the PlotManager are updated by this.

• **plot_cfg – The plot configuration to pass on to the plot creator.

Returns

The PlotCreator used for these plots

Return type

BasePlotCreator

Raises

PlotConfigError – If no out directory was specified here or at initialization.