dantro.plot.creators package

dantro.plot.creators package#

This sub-package implements non-abstract dantro plot creator classes, based on BasePlotCreator

ALL_PLOT_CREATORS = {'base': <class 'dantro.plot.creators.base.BasePlotCreator'>, 'external': <class 'dantro.plot.creators.pyplot.PyPlotCreator'>, 'multiverse': <class 'dantro.plot.creators.psp.MultiversePlotCreator'>, 'pyplot': <class 'dantro.plot.creators.pyplot.PyPlotCreator'>, 'universe': <class 'dantro.plot.creators.psp.UniversePlotCreator'>}#: A mapping of plot creator names to the corresponding types

Submodules#

dantro.plot.creators.base module#

This module implements BasePlotCreator, the base class for plot creators.

The interface is defined as an abstract base class and partly implemented by the BasePlotCreator, which is no longer abstract but has only the functionality that is general enough for all derived creators to profit from.

_fmt_time(t)#

_DAG_OBJECT_CACHE: Dict[str, TransformationDAG] = {}#: A dict holding the previously-used TransformationDAG objects to allow re-using them in another plot function. The keys are hashes of the configuration used in creating the DAG.

class BasePlotCreator(name: str, *, dm: DataManager, plot_func: Callable, default_ext: str | None = None, exist_ok: bool | str | None = None, raise_exc: bool | None = None, **plot_cfg)[source]#

Bases: AbstractPlotCreator

The base class for plot creators.

It provides the following functionality:

Resolving a plot function, which can be a directly given callable, an importable module and name, or a path to a Python file that is to be imported.
Parsing plot configuration arguments.
Optionally, performing data selection from the associated DataManager using the data transformation framework.
Invoking the plot function.

As such, the this base class is agnostic to the exact way of how plot output is generated; the plot function is responsible for that.

EXTENSIONS: Tuple[str] | str = 'all'#: A tuple of supported file extensions. If all, no checks for the extensions are performed.

DEFAULT_EXT = None#: The default file extension to use; is only used if no default extension is specified during initialization

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

POSTPONE_PATH_PREPARATION: bool = False#: 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.

OUT_PATH_EXIST_OK: bool = False#: Whether a warning should be shown (instead of an error), when a plot file already exists at the specified output path

DAG_USE_DEFAULT: bool = False#: Whether the data transformation framework is enabled by default; this can still be controlled by the use_dag argument of the plot configuration.

DAG_RESOLVE_PLACEHOLDERS: bool = True#: Whether placeholders in the plot config, ResultPlaceholder objects, should be replaced with results from the data transformations.

DAG_TO_KWARG_MAPPING: Dict[str, str] = {'dag_object': 'dag', 'results_dict': 'data'}#: The keyword argument names by which to pass the data transformation results (results_dict) or the TransformationDAG object itself (dag_object) to the plot function.

__init__(name: str, *, dm: DataManager, plot_func: Callable, default_ext: str | None = None, exist_ok: bool | str | None = None, raise_exc: bool | None = None, **plot_cfg)[source]#

Create a plot creator 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 base_module_file_dir or default_ext

property name: str#: Returns this creator’s name

property classname: str#: Returns this creator’s class name

property logstr: str#: Returns the classname and name of this object; a combination often used in logging…

property dm: DataManager#: Return the DataManager

property plot_func: Callable#: Returns the plot function

property plot_func_name: str#: Returns a readable name of the plot function

property plot_cfg: Dict[str, dict]#: Returns a deepcopy of the plot configuration, assuring that plot configurations are completely independent of each other.

property default_ext: str#: Returns the default extension to use for the plots

property dag: TransformationDAG#: 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().

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.

plot(*, out_path: str, use_dag: bool | None = None, **func_kwargs)[source]#

Prepares plot function arguments, then invokes it.

Parameters:

out_path (str) – The output path for the resulting file
use_dag (bool, optional) – Whether to use the Data Transformation Framework to select and transform data that can be used in the plotting function. If not given, will query the plot function attributes for whether the DAG should be used. If not, the data selection has to occur separately inside the plot function. Note that this may require a different plot function signature.
**func_kwargs – Passed on to the plot function

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: ParamSpace | dict) → Tuple[dict, ParamSpace][source]#

Prepares the plot configuration for the PlotManager. This function is called by the manager before the first plot is to be 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.

_abc_impl = <_abc._abc_data object>#

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

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.

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

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

_prepare_plot_func_args(*, use_dag: bool | None = None, **kwargs) → Tuple[tuple, dict][source]#

Prepares the arguments passed to the plot function.

The passed keyword arguments are carried over; no positional arguments are possible. Subsequently, possible signatures look as follows:

When using the data transformation framework, there are no positional arguments.
When not using the data transformation framework, the only positional argument is the DataManager instance that is associated with this plot.

Note

When subclassing this function, the parent method (this one) should still be called to maintain base functionality.

Parameters:

use_dag (bool, optional) – Whether to use the data transformation framework
**kwargs – Additional kwargs

Returns:

an (empty) tuple of positional arguments and a: dict of keyword arguments.

Return type:

Tuple[tuple, dict]

_invoke_plot_func(*args, plot_func_kwargs: dict | None = None, **kwargs)[source]#

Method that invokes the plot function with the prepared arguments.

On failure or success, a DAG visualization may be created.

Parameters:

*args – Plot function positional arguments
plot_func_kwargs (dict, optional) – Usually, plot function keyword arguments are specified via **kwargs; however, as dantro uses some keyword arguments for its own functionality, not all of them can be passed on to the plot function. In such cases, they can be specified via this dict and they will be passed to the plot function in addition to the **kwargs.
**kwargs – Plot function keyword arguments from the top level of the plot configuration.

_perform_data_selection(*, use_dag: bool | None = 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.

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 first inspect whether the plot function declared that the DAG is to be used. If still 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]

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

Whether the DAG should be used or not. This method extends that of the base class by additionally checking the plot function attributes for any information regarding the DAG.

This relies on the is_plot_func decorator to set a number of function attributes.

Filters out and parses parameters that are needed for initialization of the TransformationDAG in _setup_dag() and computation in _compute_dag().

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
dag_object_cache (dict, optional) – Cache options for the DAG object itself. Expected keys are read, write, clear.
dag_visualization (dict, optional) – If given, controls whether the DAG used for data transformations should also be plotted, e.g. to make debugging easier.
invocation_options (dict, optional) – Controls whether to pass certain objects on to the plot functio or not. Supported keys are pass_dag_object_along and unpack_dag_results, which take precedence over the plot function attributes of the same name which are set by the plot function decorator is_plot_func.
**plot_kwargs – The remaining plot configuration

Returns:

Tuple of DAG parameter dict and plot kwargs

Return type:

Tuple[dict, dict]

_setup_dag(init_params: dict, *, read: bool = False, write: bool = False, clear: bool = False, collect_garbage: bool | None = None, use_copy: bool = True) → TransformationDAG[source]#

Creates a TransformationDAG object from the given initialization parameters. Optionally, will use a hash of the initialization parameters to reuse a deep copy of a cached object.

In case no cached version was available or caching was disabled, uses _create_dag() to create the object.

Parameters:

init_params (dict) – Initialization parameters, passed on to the _create_dag method.
read (bool, optional) – Whether to read from memory cache
write (bool, optional) – Whether to write to memory cache
clear (bool, optional) – Whether to clear the whole memory cache, can be useful if many objects were stored and memory runs low. Afterwards, garbage collection may be required to actually free the memory; see collect_garbage.
collect_garbage (bool, optional) – If True, will invoke garbage collection; this may be required after clearing the cache but may also be useful to invoke separately from that. If None, will invoke garbage collection automatically if the cache was set to be cleared.
use_copy (bool, optional) – Whether to work on a (deep) copy of the cached DAG object. This reduces memory footprint, but may not bring a noticeable speedup.

_create_dag(**dag_params) → TransformationDAG[source]#: Creates the actual DAG object

_compute_dag(dag: TransformationDAG, *, compute_only: Sequence[str], **compute_kwargs) → dict[source]#

Compute the dag results.

This checks whether all required tags (set by the is_plot_func decorator) are set to be computed.

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

Returns a dict of plot configuration and data, where all the DAG results are stored in. In case where the DAG results are to be unpacked, the DAG results will be made available as separate keyword arguments instead of as the single data keyword argument.

Furthermore, if the plot function specified in its attributes that the DAG object is to be passed along, this is the place where it is included or excluded from the arguments.

_generate_DAG_vis(*, scenario: str, enabled: bool = True, plot_enabled: bool = True, export_enabled: bool = True, raise_exc: bool = None, when: dict = None, output: dict = None, export: dict = None, generation: dict = None, max_num_nodes: int = 256, **plot_kwargs) → DiGraph | None[source]#

Generates a DAG representation according to certain criteria and using generate_nx_graph(), then invokes visualize() to create the actual visualization output.

This method also allows to export the DAG representation using export_graph(), which can then be used for externally working with the DAG representation.

Also see DAG Visualization and Graph representation and visualization.

Parameters:

scenario (str) – The scenario in which the generation is invoked; this is used to describe the context in which this method was invoked and also becomes part of the output file name. See when for scenarios with certain names. If you want to use a different name, make sure to set when.always, such that no scenario lookup occurs.
enabled (bool, optional) – If False, will return None.
plot_enabled (bool, optional) – Whether plotting is enabled. The result of the when evaluation overrules this.
export_enabled (bool, optional) – Whether exporting is enabled. The result of the when evaluation overrules this.
raise_exc (bool, optional) – Whether to raise exceptions if anything goes wrong within this method. If None, will behave in the same way as the creator does. For example, if set to False, an error in generating a DAG representation will not lead to an error being raised.
when (dict, optional) –
A dict that specifies in which situations the generation should actually be carried out. May contain the following keys:
- always: Will always generate output.
- only_once: If True, will only generate output from one scenario, skipping further invocations.
- on_compute_error, on_compute_success, and on_plot_error, on_plot_success: Will generate output only in certain named scenarios. These can be a boolean toggle or 'debug' in which case the creator’s debug flag decides whether output is generated for that scenario. Note that the raise_exc argument does not play a role for that!
output (dict, optional) –
A dict specifying where the DAG plot and potential exported files are written to. Allowed keys are:
- plot_dir: If None, will write output aside the plot output itself. Can also be an absolute path.
- path_fstr: A format string that specifies the actual output path and should/can contain the keys plot_dir, name, and scenario.
export (dict, optional) –
Export specification, using networkx’s write methods. Possible keys:
- manipulate_attrs: Dict that controls manipulation of node or edge attributes, sometimes necessary for export. These are passed to manipulate_attributes().
- any further keyword arguments define the output formats that are to be used. They can be of type Dict[str, Union[bool, dict]], where the string should correspond to the name of a networkx writer method. The boolean is used to enable or disable a writer. If a dict is given, its content is passed to the writer method. Also see export_graph(), where this is implemented.
generation (dict, optional) – Graph generation arguments passed to generate_nx_graph().
max_num_nodes (int, optional) – If given, do not continue with the visualization if the generated graph has more than this amount of nodes. Exporting is not affected by this.
**plot_kwargs – Plotting-related arguments, passed on to visualize().

Returns:

Either the generated graph object: or None, if not enabled or when was evaluated to not generating a DAG representation.

Return type:

Union[DiGraph, None]

dantro.plot.creators.psp module#

Plot creators working on ParamSpaceGroup. These are based on the PyPlotCreator and provide additional functionality for data that is stored such a format.

See Plots from Multidimensional Data for more information.

_parse_subspace_selector(unis: str | dict, *, pspace: ParamSpace) → dict[source]#

Parses a universe specifier into a ParamSpace subspace selector, such that it can be used to call activate_subspace().

Parameters:

unis (Union[str, dict]) – The universe descriptor, which can be either a string (all, single, first, last, random, or any) or subspace selector.
pspace (ParamSpace) – The ParamSpace for which the selector should be constructed.

class MultiversePlotCreator(*args, psgrp_path: str | None = None, **kwargs)[source]#

Bases: PyPlotCreator

A MultiversePlotCreator is an PyPlotCreator that allows data to be selected before being passed to the plot function.

__init__(*args, psgrp_path: str | None = None, **kwargs)[source]#

Initialize a MultiversePlotCreator

Parameters:

*args – Passed on to parent class.
psgrp_path (str, optional) – The path to the associated ParamSpaceGroup that is to be used for these multiverse plots.
**kwargs – Passed on to parent

PSGRP_PATH: str = None#: Where the ParamSpaceGroup object is expected within the DataManager

property psgrp: ParamSpaceGroup#: Retrieves the parameter space group associated with this plot creator by looking up a certain path in the data manager.

_check_skipping(*, plot_kwargs: dict)[source]#

Adds a skip condition for plots with this creator:

Controlled by the expected_multiverse_ndim argument, this plot will be skipped if the dimensionality of the associated ParamSpaceGroup is not specified in the set of permissible dimensionalities. If that argument is not given or None, this check will not be carried out.

_prepare_plot_func_args(*args, select: dict | None = None, select_and_combine: dict | None = None, **kwargs) → Tuple[tuple, dict][source]#

Prepares the arguments for the plot function.

This also implements the functionality to select and combine data from the Multiverse and provide it to the plot function. It can do so via the associated ParamSpaceGroup directly or by creating a TransformationDAG that leads to the same results.

Warning

The select_and_combine argument behaves slightly different to the select argument! In the long term, the select argument will be deprecated.

Parameters:

*args – Positional arguments to the plot function.
select (dict, optional) – If given, selects and combines multiverse data using select(). The result is an xr.Dataset and it is made available to the plot function as mv_data argument.
select_and_combine (dict, optional) – If given, interfaces with the DAG to select, transform, and combine data from the multiverse via the DAG.
**kwargs – Keyword arguments for the plot function. If DAG usage is enabled, these contain further arguments like transform that are filtered out accordingly.

Returns:

The (args, kwargs) tuple for calling the plot: function. These now include either the DAG results or the additional mv_data key.

Return type:

Tuple[tuple, dict]

Raises:

TypeError – If both or neither of the arguments select and/or select_and_combine were given.

_get_dag_params(*, select_and_combine: dict, **cfg) → Tuple[dict, dict][source]#: Extends the parent method by extracting the select_and_combine argument that handles MultiversePlotCreator behaviour

_create_dag(*, select_and_combine: dict, select: dict | None = None, transform: Sequence[dict] | None = None, select_base: str | None = None, select_path_prefix: str | None = None, **dag_init_params) → TransformationDAG[source]#

Extends the parent method by translating the select_and_combine argument into selection of tags from a universe subspace, subsequent transformations, and a combine operation, that aligns the data in the desired fashion.

This way, the select() method’s behaviour is emulated in the DAG.

Parameters:

select_and_combine (dict) – The parameters to define which data from the universes to select and combine before applying further transformations.
select (dict, optional) – Additional select operations; these are not applied to each universe but only globally, after the select_and_combine nodes are added.
transform (Sequence[dict], optional) – Additional transform operations that are added to the DAG after both the select_and_combine- and select-related transformations were added.
select_base (str, optional) – The select base for the select argument. These are not relevant for the selection that occurs via the select_and_combine argument and is only set after all select_and_combine-related transformations are added to the DAG.
select_path_prefix (str, optional) – The selection path prefix for the select argument. Cannot be used here.
**dag_init_params – Further initialization arguments to the DAG.

Returns:

The populated DAG object.

Return type:

TransformationDAG

DAG_INVOKE_IN_BASE = True#: Whether DAG invocation should happen in the base class method _prepare_plot_func_args(). If False, can/need to invoke the data selection separately in the desired place inside the derived class.

DAG_RESOLVE_PLACEHOLDERS: bool = True#: Whether placeholders in the plot config, ResultPlaceholder objects, should be replaced with results from the data transformations.

DAG_SUPPORTED = True#: Whether this creator supports Data Transformation Framework

DAG_TO_KWARG_MAPPING: Dict[str, str] = {'dag_object': 'dag', 'results_dict': 'data'}#: The keyword argument names by which to pass the data transformation results (results_dict) or the TransformationDAG object itself (dag_object) to the plot function.

DAG_USE_DEFAULT: bool = False#: Whether the data transformation framework is enabled by default; this can still be controlled by the use_dag argument of the plot configuration.

DEFAULT_EXT = None#: The default file extension

DEFAULT_EXT_REQUIRED: bool = False#: Whether a default extension needs to be specified

EXTENSIONS: Tuple[str] | str = 'all'#: Allowed file extensions; all means that every extension is allowed and that there are no checks performed.

OUT_PATH_EXIST_OK: bool = False#: Whether a warning should be shown (instead of an error), when a plot file already exists at the specified output path

PLOT_HELPER_CLS#: alias of PlotHelper

POSTPONE_PATH_PREPARATION: bool = False#: 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.

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

_abc_impl = <_abc._abc_data object>#

_build_style_context(**rc_params)#: Constructs the matplotlib style context manager, if parameters were given, otherwise returns the DoNothingContext

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

Furthermore, if the plot function specified in its attributes that the DAG object is to be passed along, this is the place where it is included or excluded from the arguments.

_compute_dag(dag: TransformationDAG, *, compute_only: Sequence[str], **compute_kwargs) → dict#

Compute the dag results.

This checks whether all required tags (set by the is_plot_func decorator) are set to be computed.

Generates a DAG representation according to certain criteria and using generate_nx_graph(), then invokes visualize() to create the actual visualization output.

This method also allows to export the DAG representation using export_graph(), which can then be used for externally working with the DAG representation.

Also see DAG Visualization and Graph representation and visualization.

Parameters:

scenario (str) – The scenario in which the generation is invoked; this is used to describe the context in which this method was invoked and also becomes part of the output file name. See when for scenarios with certain names. If you want to use a different name, make sure to set when.always, such that no scenario lookup occurs.
enabled (bool, optional) – If False, will return None.
plot_enabled (bool, optional) – Whether plotting is enabled. The result of the when evaluation overrules this.
export_enabled (bool, optional) – Whether exporting is enabled. The result of the when evaluation overrules this.
raise_exc (bool, optional) – Whether to raise exceptions if anything goes wrong within this method. If None, will behave in the same way as the creator does. For example, if set to False, an error in generating a DAG representation will not lead to an error being raised.
when (dict, optional) –
A dict that specifies in which situations the generation should actually be carried out. May contain the following keys:
- always: Will always generate output.
- only_once: If True, will only generate output from one scenario, skipping further invocations.
- on_compute_error, on_compute_success, and on_plot_error, on_plot_success: Will generate output only in certain named scenarios. These can be a boolean toggle or 'debug' in which case the creator’s debug flag decides whether output is generated for that scenario. Note that the raise_exc argument does not play a role for that!
output (dict, optional) –
A dict specifying where the DAG plot and potential exported files are written to. Allowed keys are:
- plot_dir: If None, will write output aside the plot output itself. Can also be an absolute path.
- path_fstr: A format string that specifies the actual output path and should/can contain the keys plot_dir, name, and scenario.
export (dict, optional) –
Export specification, using networkx’s write methods. Possible keys:
- manipulate_attrs: Dict that controls manipulation of node or edge attributes, sometimes necessary for export. These are passed to manipulate_attributes().
- any further keyword arguments define the output formats that are to be used. They can be of type Dict[str, Union[bool, dict]], where the string should correspond to the name of a networkx writer method. The boolean is used to enable or disable a writer. If a dict is given, its content is passed to the writer method. Also see export_graph(), where this is implemented.
generation (dict, optional) – Graph generation arguments passed to generate_nx_graph().
max_num_nodes (int, optional) – If given, do not continue with the visualization if the generated graph has more than this amount of nodes. Exporting is not affected by this.
**plot_kwargs – Plotting-related arguments, passed on to visualize().

Returns:

Either the generated graph object: or None, if not enabled or when was evaluated to not generating a DAG representation.

Return type:

Union[DiGraph, None]

_invoke_plot_func(*args, plot_func_kwargs: dict | None = None, **kwargs)#

Method that invokes the plot function with the prepared arguments.

On failure or success, a DAG visualization may be created.

Parameters:

*args – Plot function positional arguments
plot_func_kwargs (dict, optional) – Usually, plot function keyword arguments are specified via **kwargs; however, as dantro uses some keyword arguments for its own functionality, not all of them can be passed on to the plot function. In such cases, they can be specified via this dict and they will be passed to the plot function in addition to the **kwargs.
**kwargs – Plot function keyword arguments from the top level of the plot configuration.

_perform_animation(*, hlpr: PlotHelper, style_context, plot_args: tuple, plot_kwargs: dict, writer: str, writer_kwargs: dict | None = None, animation_update_kwargs: dict | None = None)#

Prepares the Writer and checks for valid animation config.

Parameters:

hlpr (PlotHelper) – The plot helper
style_context – The style context to enter before starting animation
plot_args (tuple) – positional arguments to plot_func
plot_kwargs (dict) – keyword arguments to plot_func
writer (str) – name of movie writer with which the frames are saved
writer_kwargs (dict, optional) –
A dict of writer parameters. These are associated with the chosen writer via the top level key in writer_kwargs. Each dictionary container has three further keys queried, all optional:

init:
passed to Writer.__init__ method

saving:
passed to Writer.saving method

grab_frame:
passed to Writer.grab_frame method
animation_update_kwargs (dict, optional) – Passed to the animation update generator call.

Raises:

ValueError – if the animation is not supported by the plot_func or if the writer is not available

_perform_data_selection(*, use_dag: bool | None = 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 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

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 first inspect whether the plot function declared that the DAG is to be used. If still 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]

_plot_with_helper(*, out_path: str, helpers: dict, style: dict, func_kwargs: dict, animation: dict, use_dag: bool)#

A helper method that performs plotting using the PlotHelper.

Parameters:

out_path (str) – The output path
helpers (dict) – plot helper configuration
style (dict) – style configuration
func_kwargs (dict) – Plot function arguments, including helpers and style …
animation (dict) – Animation parameters
use_dag (bool) – Whether a DAG is used in preprocessing or not

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

_prepare_style_context(*, base_style: str | List[str] | None = None, rc_file: str | None = None, ignore_defaults: bool = False, **update_rc_params) → dict#

Builds a dictionary with rcparams for use in a matplotlib rc context

Parameters:

base_style (Union[str, List[str]], optional) – The matplotlib style to use as a basis for the generated rc parameters dict.
rc_file (str, optional) – path to a YAML file containing rc parameters. These are used to update those of the base styles.
ignore_defaults (bool, optional) – Whether to ignore the rc parameters that were given to the __init__ method
**update_rc_params – All further parameters update those that are already provided by base_style and/or rc_file arguments.

Returns:

The rc parameters dictionary, a valid dict to enter a: matplotlib style context with

Return type:

dict

Raises:

ValueError – On invalid arguments

_setup_dag(init_params: dict, *, read: bool = False, write: bool = False, clear: bool = False, collect_garbage: bool | None = None, use_copy: bool = True) → TransformationDAG#

Creates a TransformationDAG object from the given initialization parameters. Optionally, will use a hash of the initialization parameters to reuse a deep copy of a cached object.

In case no cached version was available or caching was disabled, uses _create_dag() to create the object.

Parameters:

init_params (dict) – Initialization parameters, passed on to the _create_dag method.
read (bool, optional) – Whether to read from memory cache
write (bool, optional) – Whether to write to memory cache
clear (bool, optional) – Whether to clear the whole memory cache, can be useful if many objects were stored and memory runs low. Afterwards, garbage collection may be required to actually free the memory; see collect_garbage.
collect_garbage (bool, optional) – If True, will invoke garbage collection; this may be required after clearing the cache but may also be useful to invoke separately from that. If None, will invoke garbage collection automatically if the cache was set to be cleared.
use_copy (bool, optional) – Whether to work on a (deep) copy of the cached DAG object. This reduces memory footprint, but may not bring a noticeable speedup.

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

Whether the DAG should be used or not. This method extends that of the base class by additionally checking the plot function attributes for any information regarding the DAG.

This relies on the is_plot_func decorator to set a number of function attributes.

property classname: str#: Returns this creator’s class name

property dag: TransformationDAG#: The associated TransformationDAG object. If not set up, raises.

property default_ext: str#: Returns the default extension to use for the plots

property dm: DataManager#: 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: str#: Returns the classname and name of this object; a combination often used in logging…

property name: str#: Returns this creator’s name

plot(*, out_path: str, style: dict | None = None, helpers: dict | None = None, animation: dict | None = None, use_dag: bool | None = None, **func_kwargs)#

Performs the plot operation.

In addition to the behavior of the base class’s plot(), this method integrates the plot helper framework, style contexts and the animation mode.

Alternatively, the base module can be loaded from a file path.

Parameters:

out_path (str) – The output path for the resulting file
style (dict, optional) –
Parameters that determine the aesthetics of the created plot; basically matplotlib rcParams. From them, a style context is entered before calling the plot function. Valid keys:

base_style (str, List[str], optional):
names of valid matplotlib styles

rc_file (str, optional):
path to a YAML RC parameter file that is used to update the base style

ignore_defaults (bool, optional):
Whether to ignore the default style passed to the __init__ method

further keyword arguments:
will update the RC parameter dict yet again. Need be valid matplotlib RC parameters in order to have any effect.
helpers (dict, optional) – helper configuration passed to PlotHelper initialization if enabled
animation (dict, optional) – animation configuration
use_dag (bool, optional) – Whether to use the Data Transformation Framework to select and transform data that can be used in the plotting function. If not given, will query the plot function attributes for whether the DAG should be used. See Plot Data Selection for more information.
**func_kwargs – Passed to the imported function

Raises:

ValueError – On superfluous helpers or animation arguments in cases where these are not supported

property plot_cfg: Dict[str, dict]#: Returns a deepcopy of the plot configuration, assuring that plot configurations are completely independent of each other.

property plot_func: Callable#: Returns the plot function

property plot_func_name: str#: Returns a readable name of the plot function

prepare_cfg(*, plot_cfg: dict, pspace: ParamSpace | dict) → Tuple[dict, ParamSpace]#

Prepares the plot configuration for the PlotManager. This function is called by the manager before the first plot is to be created.

class UniversePlotCreator(*args, psgrp_path: str | None = None, **kwargs)[source]#

Bases: PyPlotCreator

A UniversePlotCreator is an PyPlotCreator that allows looping of all or a selected subspace of universes.

__init__(*args, psgrp_path: str | None = None, **kwargs)[source]#

Initialize a UniversePlotCreator

Parameters:

*args – Passed on to parent class
psgrp_path (str, optional) – Specifies the location of the ParamSpaceGroup within the data tree. If given, overwrites the class variable default.
**kwargs – Passed on to parent class

PSGRP_PATH: str = None#: Where the ParamSpaceGroup object is expected within the DataManager

DAG_INVOKE_IN_BASE = True#: Whether DAG invocation should happen in the base class method _prepare_plot_func_args(). If False, can/need to invoke the data selection separately in the desired place inside the derived class.

DAG_RESOLVE_PLACEHOLDERS: bool = True#: Whether placeholders in the plot config, ResultPlaceholder objects, should be replaced with results from the data transformations.

DAG_SUPPORTED = True#: Whether this creator supports Data Transformation Framework

DAG_TO_KWARG_MAPPING: Dict[str, str] = {'dag_object': 'dag', 'results_dict': 'data'}#: The keyword argument names by which to pass the data transformation results (results_dict) or the TransformationDAG object itself (dag_object) to the plot function.

DAG_USE_DEFAULT: bool = False#: Whether the data transformation framework is enabled by default; this can still be controlled by the use_dag argument of the plot configuration.

DEFAULT_EXT = None#: The default file extension

DEFAULT_EXT_REQUIRED: bool = False#: Whether a default extension needs to be specified

EXTENSIONS: Tuple[str] | str = 'all'#: Allowed file extensions; all means that every extension is allowed and that there are no checks performed.

OUT_PATH_EXIST_OK: bool = False#: Whether a warning should be shown (instead of an error), when a plot file already exists at the specified output path

PLOT_HELPER_CLS#: alias of PlotHelper

POSTPONE_PATH_PREPARATION: bool = False#: 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.

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

_abc_impl = <_abc._abc_data object>#

_build_style_context(**rc_params)#: Constructs the matplotlib style context manager, if parameters were given, otherwise returns the DoNothingContext

_check_skipping(*, plot_kwargs: dict)#

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: TransformationDAG, dag_results: dict, dag_params: dict, plot_kwargs: dict) → dict#

Furthermore, if the plot function specified in its attributes that the DAG object is to be passed along, this is the place where it is included or excluded from the arguments.

_compute_dag(dag: TransformationDAG, *, compute_only: Sequence[str], **compute_kwargs) → dict#

Compute the dag results.

This checks whether all required tags (set by the is_plot_func decorator) are set to be computed.

_create_dag(**dag_params) → TransformationDAG#: Creates the actual DAG object

Generates a DAG representation according to certain criteria and using generate_nx_graph(), then invokes visualize() to create the actual visualization output.

This method also allows to export the DAG representation using export_graph(), which can then be used for externally working with the DAG representation.

Also see DAG Visualization and Graph representation and visualization.

Parameters:

scenario (str) – The scenario in which the generation is invoked; this is used to describe the context in which this method was invoked and also becomes part of the output file name. See when for scenarios with certain names. If you want to use a different name, make sure to set when.always, such that no scenario lookup occurs.
enabled (bool, optional) – If False, will return None.
plot_enabled (bool, optional) – Whether plotting is enabled. The result of the when evaluation overrules this.
export_enabled (bool, optional) – Whether exporting is enabled. The result of the when evaluation overrules this.
raise_exc (bool, optional) – Whether to raise exceptions if anything goes wrong within this method. If None, will behave in the same way as the creator does. For example, if set to False, an error in generating a DAG representation will not lead to an error being raised.
when (dict, optional) –
A dict that specifies in which situations the generation should actually be carried out. May contain the following keys:
- always: Will always generate output.
- only_once: If True, will only generate output from one scenario, skipping further invocations.
- on_compute_error, on_compute_success, and on_plot_error, on_plot_success: Will generate output only in certain named scenarios. These can be a boolean toggle or 'debug' in which case the creator’s debug flag decides whether output is generated for that scenario. Note that the raise_exc argument does not play a role for that!
output (dict, optional) –
A dict specifying where the DAG plot and potential exported files are written to. Allowed keys are:
- plot_dir: If None, will write output aside the plot output itself. Can also be an absolute path.
- path_fstr: A format string that specifies the actual output path and should/can contain the keys plot_dir, name, and scenario.
export (dict, optional) –
Export specification, using networkx’s write methods. Possible keys:
- manipulate_attrs: Dict that controls manipulation of node or edge attributes, sometimes necessary for export. These are passed to manipulate_attributes().
- any further keyword arguments define the output formats that are to be used. They can be of type Dict[str, Union[bool, dict]], where the string should correspond to the name of a networkx writer method. The boolean is used to enable or disable a writer. If a dict is given, its content is passed to the writer method. Also see export_graph(), where this is implemented.
generation (dict, optional) – Graph generation arguments passed to generate_nx_graph().
max_num_nodes (int, optional) – If given, do not continue with the visualization if the generated graph has more than this amount of nodes. Exporting is not affected by this.
**plot_kwargs – Plotting-related arguments, passed on to visualize().

Returns:

Either the generated graph object: or None, if not enabled or when was evaluated to not generating a DAG representation.

Return type:

Union[DiGraph, None]

_invoke_plot_func(*args, plot_func_kwargs: dict | None = None, **kwargs)#

Method that invokes the plot function with the prepared arguments.

On failure or success, a DAG visualization may be created.

Parameters:

*args – Plot function positional arguments
plot_func_kwargs (dict, optional) – Usually, plot function keyword arguments are specified via **kwargs; however, as dantro uses some keyword arguments for its own functionality, not all of them can be passed on to the plot function. In such cases, they can be specified via this dict and they will be passed to the plot function in addition to the **kwargs.
**kwargs – Plot function keyword arguments from the top level of the plot configuration.

Prepares the Writer and checks for valid animation config.

Parameters:

hlpr (PlotHelper) – The plot helper
style_context – The style context to enter before starting animation
plot_args (tuple) – positional arguments to plot_func
plot_kwargs (dict) – keyword arguments to plot_func
writer (str) – name of movie writer with which the frames are saved
writer_kwargs (dict, optional) –
A dict of writer parameters. These are associated with the chosen writer via the top level key in writer_kwargs. Each dictionary container has three further keys queried, all optional:

init:
passed to Writer.__init__ method

saving:
passed to Writer.saving method

grab_frame:
passed to Writer.grab_frame method
animation_update_kwargs (dict, optional) – Passed to the animation update generator call.

Raises:

ValueError – if the animation is not supported by the plot_func or if the writer is not available

_perform_data_selection(*, use_dag: bool | None = 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 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

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 first inspect whether the plot function declared that the DAG is to be used. If still 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]

_plot_with_helper(*, out_path: str, helpers: dict, style: dict, func_kwargs: dict, animation: dict, use_dag: bool)#

A helper method that performs plotting using the PlotHelper.

Parameters:

out_path (str) – The output path
helpers (dict) – plot helper configuration
style (dict) – style configuration
func_kwargs (dict) – Plot function arguments, including helpers and style …
animation (dict) – Animation parameters
use_dag (bool) – Whether a DAG is used in preprocessing or not

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

_prepare_style_context(*, base_style: str | List[str] | None = None, rc_file: str | None = None, ignore_defaults: bool = False, **update_rc_params) → dict#

Builds a dictionary with rcparams for use in a matplotlib rc context

Parameters:

base_style (Union[str, List[str]], optional) – The matplotlib style to use as a basis for the generated rc parameters dict.
rc_file (str, optional) – path to a YAML file containing rc parameters. These are used to update those of the base styles.
ignore_defaults (bool, optional) – Whether to ignore the rc parameters that were given to the __init__ method
**update_rc_params – All further parameters update those that are already provided by base_style and/or rc_file arguments.

Returns:

The rc parameters dictionary, a valid dict to enter a: matplotlib style context with

Return type:

dict

Raises:

ValueError – On invalid arguments

_setup_dag(init_params: dict, *, read: bool = False, write: bool = False, clear: bool = False, collect_garbage: bool | None = None, use_copy: bool = True) → TransformationDAG#

Creates a TransformationDAG object from the given initialization parameters. Optionally, will use a hash of the initialization parameters to reuse a deep copy of a cached object.

In case no cached version was available or caching was disabled, uses _create_dag() to create the object.

Parameters:

init_params (dict) – Initialization parameters, passed on to the _create_dag method.
read (bool, optional) – Whether to read from memory cache
write (bool, optional) – Whether to write to memory cache
clear (bool, optional) – Whether to clear the whole memory cache, can be useful if many objects were stored and memory runs low. Afterwards, garbage collection may be required to actually free the memory; see collect_garbage.
collect_garbage (bool, optional) – If True, will invoke garbage collection; this may be required after clearing the cache but may also be useful to invoke separately from that. If None, will invoke garbage collection automatically if the cache was set to be cleared.
use_copy (bool, optional) – Whether to work on a (deep) copy of the cached DAG object. This reduces memory footprint, but may not bring a noticeable speedup.

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

Whether the DAG should be used or not. This method extends that of the base class by additionally checking the plot function attributes for any information regarding the DAG.

This relies on the is_plot_func decorator to set a number of function attributes.

property classname: str#: Returns this creator’s class name

property dag: TransformationDAG#: The associated TransformationDAG object. If not set up, raises.

property default_ext: str#: Returns the default extension to use for the plots

property dm: DataManager#: 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: str#: Returns the classname and name of this object; a combination often used in logging…

property name: str#: Returns this creator’s name

plot(*, out_path: str, style: dict | None = None, helpers: dict | None = None, animation: dict | None = None, use_dag: bool | None = None, **func_kwargs)#

Performs the plot operation.

In addition to the behavior of the base class’s plot(), this method integrates the plot helper framework, style contexts and the animation mode.

Alternatively, the base module can be loaded from a file path.

Parameters:

out_path (str) – The output path for the resulting file
style (dict, optional) –
Parameters that determine the aesthetics of the created plot; basically matplotlib rcParams. From them, a style context is entered before calling the plot function. Valid keys:

base_style (str, List[str], optional):
names of valid matplotlib styles

rc_file (str, optional):
path to a YAML RC parameter file that is used to update the base style

ignore_defaults (bool, optional):
Whether to ignore the default style passed to the __init__ method

further keyword arguments:
will update the RC parameter dict yet again. Need be valid matplotlib RC parameters in order to have any effect.
helpers (dict, optional) – helper configuration passed to PlotHelper initialization if enabled
animation (dict, optional) – animation configuration
use_dag (bool, optional) – Whether to use the Data Transformation Framework to select and transform data that can be used in the plotting function. If not given, will query the plot function attributes for whether the DAG should be used. See Plot Data Selection for more information.
**func_kwargs – Passed to the imported function

Raises:

ValueError – On superfluous helpers or animation arguments in cases where these are not supported

property plot_cfg: Dict[str, dict]#: Returns a deepcopy of the plot configuration, assuring that plot configurations are completely independent of each other.

property plot_func: Callable#: Returns the plot function

property plot_func_name: str#: Returns a readable name of the plot function

property psgrp: ParamSpaceGroup#: Retrieves the parameter space group associated with this plot creator by looking up a certain path in the data manager.

prepare_cfg(*, plot_cfg: dict, pspace: dict | ParamSpace) → Tuple[dict, ParamSpace][source]#

Converts a regular plot configuration to one that can be configured to iterate over multiple universes via a parameter space.

This is implemented in the following way:

Extracts the universes key from the configuration and parses it, ensuring it is a valid dict for subspace specification

Creates a new ParamSpace object that additionally contains the parameter dimensions corresponding to the universes. These are stored in a _coords dict inside the returned plot configuration.

Apply the parsed universes key to activate a subspace of the newly created parameter space.

As a mapping from coordinates to state numbers is needed, the corresponding active state mapping is saved as an attribute to the plot creator, such that it is available later when the state number needs to be retrieved only be the info of the current coordinates.

_prepare_plot_func_args(*args, _coords: dict | None = None, _uni_id: int | None = None, **kwargs) → Tuple[tuple, dict][source]#

Prepares the arguments for the plot function and implements the special arguments required for ParamSpaceGroup-like data: selection of a single universe from the given coordinates.

Parameters:

*args – Passed along to parent method
_coords (dict, optional) – The current coordinate descriptor which is then used to retrieve a certain point in parameter space from the state map attribute.
_uni_id (int, optional) – If given, use this ID to select a universe from the ParamSpaceGroup (and ignore the _coords argument)
**kwargs – Passed along to parent method

Returns:

(args, kwargs) for the plot function

Return type:

tuple

_get_dag_params(*, uni: ParamSpaceStateGroup, **cfg) → Tuple[dict, dict][source]#: Makes the selected universe available and adjusts DAG parameters such that selections can be based on that universe.

dantro.plot.creators.pyplot module#

This module implements the PyPlotCreator class, which specializes on creating matplotlib.pyplot-based plots.

class PyPlotCreator(name: str, *, backend: str = 'agg', style: dict | None = None, **parent_kwargs)[source]#

Bases: BasePlotCreator

A plot creator that is specialized on creating plots using matplotlib.pyplot. On top of the capabilities of BasePlotCreator, this class contains specializations for the matplotlib-based plotting backend:

The PlotHelper provides an interface to a wide range of the matplotlib.pyplot interface, allowing to let the plot function itself focus on generating a visual representation of the data and removing boilerplate code; see The PlotHelper.
There are so-called “style contexts” that a plot can be generated in, allowing to have consistent and easily adjsutable aesthetics; see Adjusting a Plot’s Style.
By including the matplotlib.animation framework, allows to easily implement plot functions that generate animation output.

For more information, refer to the user manual.

EXTENSIONS: Tuple[str] | str = 'all'#: Allowed file extensions; all means that every extension is allowed and that there are no checks performed.

DEFAULT_EXT = None#: The default file extension

DEFAULT_EXT_REQUIRED: bool = False#: Whether a default extension needs to be specified

DAG_SUPPORTED = True#: Whether this creator supports Data Transformation Framework

DAG_INVOKE_IN_BASE = True#: Whether DAG invocation should happen in the base class method _prepare_plot_func_args(). If False, can/need to invoke the data selection separately in the desired place inside the derived class.

PLOT_HELPER_CLS#

Which PlotHelper class to use

alias of PlotHelper

__init__(name: str, *, backend: str = 'agg', style: dict | None = None, **parent_kwargs)[source]#

Initialize a creator for matplotlib.pyplot-based plots.

Parameters:

name (str) – The name of this plot
style (dict, optional) – The default style context defintion to enter before calling the plot function. This can be used to specify the aesthetics of a plot. It is evaluated here once, stored as attribute, and can be updated when the plot method is actually called.
**parent_kwargs – Passed to the parent’s __init__().

DAG_RESOLVE_PLACEHOLDERS: bool = True#: Whether placeholders in the plot config, ResultPlaceholder objects, should be replaced with results from the data transformations.

DAG_TO_KWARG_MAPPING: Dict[str, str] = {'dag_object': 'dag', 'results_dict': 'data'}#: The keyword argument names by which to pass the data transformation results (results_dict) or the TransformationDAG object itself (dag_object) to the plot function.

DAG_USE_DEFAULT: bool = False#: Whether the data transformation framework is enabled by default; this can still be controlled by the use_dag argument of the plot configuration.

OUT_PATH_EXIST_OK: bool = False#: Whether a warning should be shown (instead of an error), when a plot file already exists at the specified output path

POSTPONE_PATH_PREPARATION: bool = False#: 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.

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

_abc_impl = <_abc._abc_data object>#

_check_skipping(*, plot_kwargs: dict)#

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: TransformationDAG, dag_results: dict, dag_params: dict, plot_kwargs: dict) → dict#

Furthermore, if the plot function specified in its attributes that the DAG object is to be passed along, this is the place where it is included or excluded from the arguments.

_compute_dag(dag: TransformationDAG, *, compute_only: Sequence[str], **compute_kwargs) → dict#

Compute the dag results.

This checks whether all required tags (set by the is_plot_func decorator) are set to be computed.

_create_dag(**dag_params) → TransformationDAG#: Creates the actual DAG object

Generates a DAG representation according to certain criteria and using generate_nx_graph(), then invokes visualize() to create the actual visualization output.

This method also allows to export the DAG representation using export_graph(), which can then be used for externally working with the DAG representation.

Also see DAG Visualization and Graph representation and visualization.

Parameters:

scenario (str) – The scenario in which the generation is invoked; this is used to describe the context in which this method was invoked and also becomes part of the output file name. See when for scenarios with certain names. If you want to use a different name, make sure to set when.always, such that no scenario lookup occurs.
enabled (bool, optional) – If False, will return None.
plot_enabled (bool, optional) – Whether plotting is enabled. The result of the when evaluation overrules this.
export_enabled (bool, optional) – Whether exporting is enabled. The result of the when evaluation overrules this.
raise_exc (bool, optional) – Whether to raise exceptions if anything goes wrong within this method. If None, will behave in the same way as the creator does. For example, if set to False, an error in generating a DAG representation will not lead to an error being raised.
when (dict, optional) –
A dict that specifies in which situations the generation should actually be carried out. May contain the following keys:
- always: Will always generate output.
- only_once: If True, will only generate output from one scenario, skipping further invocations.
- on_compute_error, on_compute_success, and on_plot_error, on_plot_success: Will generate output only in certain named scenarios. These can be a boolean toggle or 'debug' in which case the creator’s debug flag decides whether output is generated for that scenario. Note that the raise_exc argument does not play a role for that!
output (dict, optional) –
A dict specifying where the DAG plot and potential exported files are written to. Allowed keys are:
- plot_dir: If None, will write output aside the plot output itself. Can also be an absolute path.
- path_fstr: A format string that specifies the actual output path and should/can contain the keys plot_dir, name, and scenario.
export (dict, optional) –
Export specification, using networkx’s write methods. Possible keys:
- manipulate_attrs: Dict that controls manipulation of node or edge attributes, sometimes necessary for export. These are passed to manipulate_attributes().
- any further keyword arguments define the output formats that are to be used. They can be of type Dict[str, Union[bool, dict]], where the string should correspond to the name of a networkx writer method. The boolean is used to enable or disable a writer. If a dict is given, its content is passed to the writer method. Also see export_graph(), where this is implemented.
generation (dict, optional) – Graph generation arguments passed to generate_nx_graph().
max_num_nodes (int, optional) – If given, do not continue with the visualization if the generated graph has more than this amount of nodes. Exporting is not affected by this.
**plot_kwargs – Plotting-related arguments, passed on to visualize().

Returns:

Either the generated graph object: or None, if not enabled or when was evaluated to not generating a DAG representation.

Return type:

Union[DiGraph, None]

Filters out and parses parameters that are needed for initialization of the TransformationDAG in _setup_dag() and computation in _compute_dag().

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
dag_object_cache (dict, optional) – Cache options for the DAG object itself. Expected keys are read, write, clear.
dag_visualization (dict, optional) – If given, controls whether the DAG used for data transformations should also be plotted, e.g. to make debugging easier.
invocation_options (dict, optional) – Controls whether to pass certain objects on to the plot functio or not. Supported keys are pass_dag_object_along and unpack_dag_results, which take precedence over the plot function attributes of the same name which are set by the plot function decorator is_plot_func.
**plot_kwargs – The remaining plot configuration

Returns:

Tuple of DAG parameter dict and plot kwargs

Return type:

Tuple[dict, dict]

_invoke_plot_func(*args, plot_func_kwargs: dict | None = None, **kwargs)#

Method that invokes the plot function with the prepared arguments.

On failure or success, a DAG visualization may be created.

Parameters:

*args – Plot function positional arguments
plot_func_kwargs (dict, optional) – Usually, plot function keyword arguments are specified via **kwargs; however, as dantro uses some keyword arguments for its own functionality, not all of them can be passed on to the plot function. In such cases, they can be specified via this dict and they will be passed to the plot function in addition to the **kwargs.
**kwargs – Plot function keyword arguments from the top level of the plot configuration.

_perform_data_selection(*, use_dag: bool | None = 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 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

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 first inspect whether the plot function declared that the DAG is to be used. If still 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 | 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.

_prepare_plot_func_args(*, use_dag: bool | None = None, **kwargs) → Tuple[tuple, dict]#

Prepares the arguments passed to the plot function.

The passed keyword arguments are carried over; no positional arguments are possible. Subsequently, possible signatures look as follows:

When using the data transformation framework, there are no positional arguments.
When not using the data transformation framework, the only positional argument is the DataManager instance that is associated with this plot.

Note

When subclassing this function, the parent method (this one) should still be called to maintain base functionality.

Parameters:

use_dag (bool, optional) – Whether to use the data transformation framework
**kwargs – Additional kwargs

Returns:

an (empty) tuple of positional arguments and a: dict of keyword arguments.

Return type:

Tuple[tuple, dict]

_setup_dag(init_params: dict, *, read: bool = False, write: bool = False, clear: bool = False, collect_garbage: bool | None = None, use_copy: bool = True) → TransformationDAG#

Creates a TransformationDAG object from the given initialization parameters. Optionally, will use a hash of the initialization parameters to reuse a deep copy of a cached object.

In case no cached version was available or caching was disabled, uses _create_dag() to create the object.

Parameters:

init_params (dict) – Initialization parameters, passed on to the _create_dag method.
read (bool, optional) – Whether to read from memory cache
write (bool, optional) – Whether to write to memory cache
clear (bool, optional) – Whether to clear the whole memory cache, can be useful if many objects were stored and memory runs low. Afterwards, garbage collection may be required to actually free the memory; see collect_garbage.
collect_garbage (bool, optional) – If True, will invoke garbage collection; this may be required after clearing the cache but may also be useful to invoke separately from that. If None, will invoke garbage collection automatically if the cache was set to be cleared.
use_copy (bool, optional) – Whether to work on a (deep) copy of the cached DAG object. This reduces memory footprint, but may not bring a noticeable speedup.

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

Whether the DAG should be used or not. This method extends that of the base class by additionally checking the plot function attributes for any information regarding the DAG.

This relies on the is_plot_func decorator to set a number of function attributes.

property classname: str#: Returns this creator’s class name

property dag: TransformationDAG#: The associated TransformationDAG object. If not set up, raises.

property default_ext: str#: Returns the default extension to use for the plots

property dm: DataManager#: 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: str#: Returns the classname and name of this object; a combination often used in logging…

property name: str#: Returns this creator’s name

property plot_cfg: Dict[str, dict]#: Returns a deepcopy of the plot configuration, assuring that plot configurations are completely independent of each other.

property plot_func: Callable#: Returns the plot function

property plot_func_name: str#: Returns a readable name of the plot function

prepare_cfg(*, plot_cfg: dict, pspace: ParamSpace | dict) → Tuple[dict, ParamSpace]#

Prepares the plot configuration for the PlotManager. This function is called by the manager before the first plot is to be created.

plot(*, out_path: str, style: dict | None = None, helpers: dict | None = None, animation: dict | None = None, use_dag: bool | None = None, **func_kwargs)[source]#

Performs the plot operation.

In addition to the behavior of the base class’s plot(), this method integrates the plot helper framework, style contexts and the animation mode.

Alternatively, the base module can be loaded from a file path.

Parameters:

out_path (str) – The output path for the resulting file
style (dict, optional) –
Parameters that determine the aesthetics of the created plot; basically matplotlib rcParams. From them, a style context is entered before calling the plot function. Valid keys:

base_style (str, List[str], optional):
names of valid matplotlib styles

rc_file (str, optional):
path to a YAML RC parameter file that is used to update the base style

ignore_defaults (bool, optional):
Whether to ignore the default style passed to the __init__ method

further keyword arguments:
will update the RC parameter dict yet again. Need be valid matplotlib RC parameters in order to have any effect.
helpers (dict, optional) – helper configuration passed to PlotHelper initialization if enabled
animation (dict, optional) – animation configuration
use_dag (bool, optional) – Whether to use the Data Transformation Framework to select and transform data that can be used in the plotting function. If not given, will query the plot function attributes for whether the DAG should be used. See Plot Data Selection for more information.
**func_kwargs – Passed to the imported function

Raises:

ValueError – On superfluous helpers or animation arguments in cases where these are not supported

_plot_with_helper(*, out_path: str, helpers: dict, style: dict, func_kwargs: dict, animation: dict, use_dag: bool)[source]#

A helper method that performs plotting using the PlotHelper.

Parameters:

out_path (str) – The output path
helpers (dict) – plot helper configuration
style (dict) – style configuration
func_kwargs (dict) – Plot function arguments, including helpers and style …
animation (dict) – Animation parameters
use_dag (bool) – Whether a DAG is used in preprocessing or not

_prepare_style_context(*, base_style: str | List[str] | None = None, rc_file: str | None = None, ignore_defaults: bool = False, **update_rc_params) → dict[source]#

Builds a dictionary with rcparams for use in a matplotlib rc context

Parameters:

base_style (Union[str, List[str]], optional) – The matplotlib style to use as a basis for the generated rc parameters dict.
rc_file (str, optional) – path to a YAML file containing rc parameters. These are used to update those of the base styles.
ignore_defaults (bool, optional) – Whether to ignore the rc parameters that were given to the __init__ method
**update_rc_params – All further parameters update those that are already provided by base_style and/or rc_file arguments.

Returns:

The rc parameters dictionary, a valid dict to enter a: matplotlib style context with

Return type:

dict

Raises:

ValueError – On invalid arguments

_build_style_context(**rc_params)[source]#: Constructs the matplotlib style context manager, if parameters were given, otherwise returns the DoNothingContext

Prepares the Writer and checks for valid animation config.

Parameters:

hlpr (PlotHelper) – The plot helper
style_context – The style context to enter before starting animation
plot_args (tuple) – positional arguments to plot_func
plot_kwargs (dict) – keyword arguments to plot_func
writer (str) – name of movie writer with which the frames are saved
writer_kwargs (dict, optional) –
A dict of writer parameters. These are associated with the chosen writer via the top level key in writer_kwargs. Each dictionary container has three further keys queried, all optional:

init:
passed to Writer.__init__ method

saving:
passed to Writer.saving method

grab_frame:
passed to Writer.grab_frame method
animation_update_kwargs (dict, optional) – Passed to the animation update generator call.

Raises:

ValueError – if the animation is not supported by the plot_func or if the writer is not available

dantro.plot.creators package

Contents

dantro.plot.creators package#

Submodules#

dantro.plot.creators.base module#

dantro.plot.creators.psp module#

dantro.plot.creators.pyplot module#