dantro.plot_creators.pcr_psp module

This implements the ParamSpaceGroup plot creators, based on the ExternalPlotCreator and providing additional functionality for data that is stored in a ParamSpaceGroup.

class dantro.plot_creators.pcr_psp.MultiversePlotCreator(*args, psgrp_path: str = None, **kwargs)[source]

Bases: dantro.plot_creators.pcr_ext.ExternalPlotCreator

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

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

Initialize a MultiversePlotCreator

PSGRP_PATH = None
property psgrp

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

_prepare_plot_func_args(*args, select: dict = None, select_and_combine: dict = 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(*, _plot_func: Callable, select_and_combine: dict, select: dict = None, transform: Sequence[dict] = None, select_base: str = None, select_path_prefix: str = None, **dag_init_params) → dantro.dag.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

  • _plot_func (Callable) – The plot function; passed on to parent method, where tag availability is checked.

  • 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

BASE_PKG = 'dantro.plot_creators.ext_funcs'
DAG_INVOKE_IN_BASE = False
DAG_SUPPORTED = True
DEFAULT_EXT = None
DEFAULT_EXT_REQUIRED = False
EXTENSIONS = 'all'
OUT_PATH_EXIST_OK = False
PLOT_HELPER_CLS

alias of dantro.plot_creators._plot_helper.PlotHelper

POSTPONE_PATH_PREPARATION = False
_AD_IGNORE_FUNC_ATTRS = False
__call__(*, out_path: str, **update_plot_cfg)

Perform the plot, updating the configuration passed to __init__ with the given values and then calling _plot.

Parameters

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

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

Returns

The return value of the plot() method, which is an abstract method in BasePlotCreator.

_abc_impl = <_abc_data object>
_combine_dag_results_and_plot_cfg(*, dag: dantro.dag.TransformationDAG, dag_results: dict, dag_params: dict, plot_kwargs: dict) → dict

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.

Note

This behaviour is different than in the parent class, where the DAG results are passed on as dag_results.

_compute_dag(dag: dantro.dag.TransformationDAG, *, _plot_func: Callable, compute_only: Sequence[str], **compute_kwargs) → dict

Compute the dag results.

This extends the parent method by additionally checking whether all required tags are defined and (after computation) whether all required tags were computed.

_declared_plot_func_by_attrs(pf: Callable, creator_name: str) → bool

Checks whether the given function has attributes set that declare it as a plotting function that is to be used with this creator.

Parameters

  • pf (Callable) – The plot function to check attributes of

  • creator_name (str) – The name under which this creator type is registered to the PlotManager.

Returns

Whether the plot function attributes declare the given plot

function as suitable for working with this specific creator.

Return type

bool

_get_module_from_file(path: str)

Returns the module corresponding to the file at the given path

_get_module_via_import(module: str)

Returns the module via import

_perform_animation(*, hlpr: dantro.plot_creators._plot_helper.PlotHelper, style_context, plot_func: Callable, plot_args: tuple, plot_kwargs: dict, writer: str, writer_kwargs: dict = None, animation_update_kwargs: dict = 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_func (Callable) – plotting function which is to be animated

  • 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, plot_kwargs: dict, **shared_kwargs) → Tuple[bool, dict]

If this plot creator supports data selection and transformation, it is carried out in this method.

This method uses a number of other private methods to carry out the setup of the DAG, computing it and combining its results with the remaining plot configuration. Those methods have access to a subset of the whole configuration, thus allowing to parse the parameters that they need.

Note

For specializing the behaviour of the data selection and transform, it is best to specialize NOT this method, but the more granular DAG-related private methods.

Parameters

  • use_dag (bool, optional) – The main toggle for whether the DAG should be used or not. This is passed as default value to another method, which takes the final decision on whether the DAG is used or not. If None, will NOT use the DAG.

  • plot_kwargs (dict) – The plot configuration

  • **shared_kwargs – Shared keyword arguments that are passed through to the helper methods _use_dag and _get_dag_params

Returns

Whether data selection was used and the plot

configuration that can be passed on to the main plot method.

Return type

Tuple[bool, dict]

_plot_with_helper(*, out_path: str, plot_func: Callable, helpers: dict, style_context, func_kwargs: dict, animation: dict, use_dag: bool)

A helper method that performs plotting using the PlotHelper.

Parameters

  • out_path (str) – The output path

  • plot_func (Callable) – The resolved plot function

  • helpers (dict) – The helper configuration

  • style_context – A style context; can also be DoNothingContext, if no style adjustments are to take place.

  • func_kwargs (dict) – Plot function arguments

  • animation (dict) – Animation parameters

  • use_dag (bool) – Whether a DAG is used in preprocessing or not

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

Prepares the output path, creating directories if needed, then returning the full absolute path.

This is called from __call__ and is meant to postpone directory creation as far as possible.

Parameters

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

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

Raises

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

_prepare_style_context(*, base_style: Union[str, List[str]] = None, rc_file: str = 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

_resolve_plot_func(*, plot_func: Union[str, Callable], module: str = None, module_file: str = None) → Callable
Parameters

  • plot_func (Union[str, Callable]) – The plot function or a name or module string under which it can be imported.

  • module (str) – If plot_func was the name of the plot function, this needs to be the name of the module to import

  • module_file (str) – Path to the file to load and look for the plot_func in. If base_module_file_dir is given, this can also be a path relative to that directory.

Returns

The resolved plot function

Return type

Callable

Raises

TypeError – Upon wrong argument types

_use_dag(*, use_dag: bool, plot_kwargs: dict, _plot_func: Callable) → 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

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

Whether this plot creator is able to make a plot for the given plot configuration.

This checks whether the configuration allows resolving a plot function. If that is the case, it checks whether the plot function has defined some attributes that provide further information on whether the current creator is the desired one.

Parameters

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

  • **cfg – The plot configuration with which to decide this …

Returns

Whether this creator can be used for plotting or not

Return type

bool

property classname

Returns this creator’s class name

property default_ext

Returns the default extension to use for the plots

property dm

Return the DataManager

get_ext() → str

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

property logstr

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

property name

Returns this creator’s name

plot(*, out_path: str, plot_func: Union[str, Callable], module: str = None, module_file: str = None, style: dict = None, helpers: dict = None, animation: dict = None, use_dag: bool = None, **func_kwargs)

Performs the plot operation by calling a specified plot function.

The plot function is specified by its name, which is interpreted as a full module string, or by directly passing a callable.

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

Parameters

  • out_path (str) – The output path for the resulting file

  • plot_func (Union[str, Callable]) – The plot function or a name or module string under which it can be imported.

  • module (str, optional) – If plot_func was the name of the plot function, this needs to be the name of the module to import

  • module_file (str, optional) – Path to the file to load and look for the plot_func in. If base_module_file_dir is given, this can also be a path relative to that directory.

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

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

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

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

Prepares the plot configuration for the PlotManager.

This function is called by the plot manager before the first plot is created.

The base implementation just passes the given arguments through. However, it can be re-implemented by derived classes to change the behaviour of the plot manager, e.g. by converting a plot configuration to a parameter space.

class dantro.plot_creators.pcr_psp.UniversePlotCreator(*args, psgrp_path: str = None, **kwargs)[source]

Bases: dantro.plot_creators.pcr_ext.ExternalPlotCreator

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

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

Initialize a UniversePlotCreator

PSGRP_PATH = None
property psgrp

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: Union[dict, paramspace.paramspace.ParamSpace]) → Tuple[dict, paramspace.paramspace.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:

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

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

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

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

BASE_PKG = 'dantro.plot_creators.ext_funcs'
DAG_INVOKE_IN_BASE = False
DAG_SUPPORTED = True
DEFAULT_EXT = None
DEFAULT_EXT_REQUIRED = False
EXTENSIONS = 'all'
OUT_PATH_EXIST_OK = False
PLOT_HELPER_CLS

alias of dantro.plot_creators._plot_helper.PlotHelper

POSTPONE_PATH_PREPARATION = False
_AD_IGNORE_FUNC_ATTRS = False
__call__(*, out_path: str, **update_plot_cfg)

Perform the plot, updating the configuration passed to __init__ with the given values and then calling _plot.

Parameters

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

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

Returns

The return value of the plot() method, which is an abstract method in BasePlotCreator.

_abc_impl = <_abc_data object>
_combine_dag_results_and_plot_cfg(*, dag: dantro.dag.TransformationDAG, dag_results: dict, dag_params: dict, plot_kwargs: dict) → dict

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.

Note

This behaviour is different than in the parent class, where the DAG results are passed on as dag_results.

_compute_dag(dag: dantro.dag.TransformationDAG, *, _plot_func: Callable, compute_only: Sequence[str], **compute_kwargs) → dict

Compute the dag results.

This extends the parent method by additionally checking whether all required tags are defined and (after computation) whether all required tags were computed.

_create_dag(*, _plot_func: Callable, **dag_params) → dantro.dag.TransformationDAG

Extends the parent method by allowing to pass the _plot_func, which can be used to adjust DAG behaviour …

_declared_plot_func_by_attrs(pf: Callable, creator_name: str) → bool

Checks whether the given function has attributes set that declare it as a plotting function that is to be used with this creator.

Parameters

  • pf (Callable) – The plot function to check attributes of

  • creator_name (str) – The name under which this creator type is registered to the PlotManager.

Returns

Whether the plot function attributes declare the given plot

function as suitable for working with this specific creator.

Return type

bool

_get_module_from_file(path: str)

Returns the module corresponding to the file at the given path

_get_module_via_import(module: str)

Returns the module via import

_perform_animation(*, hlpr: dantro.plot_creators._plot_helper.PlotHelper, style_context, plot_func: Callable, plot_args: tuple, plot_kwargs: dict, writer: str, writer_kwargs: dict = None, animation_update_kwargs: dict = 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_func (Callable) – plotting function which is to be animated

  • 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, plot_kwargs: dict, **shared_kwargs) → Tuple[bool, dict]

If this plot creator supports data selection and transformation, it is carried out in this method.

This method uses a number of other private methods to carry out the setup of the DAG, computing it and combining its results with the remaining plot configuration. Those methods have access to a subset of the whole configuration, thus allowing to parse the parameters that they need.

Note

For specializing the behaviour of the data selection and transform, it is best to specialize NOT this method, but the more granular DAG-related private methods.

Parameters

  • use_dag (bool, optional) – The main toggle for whether the DAG should be used or not. This is passed as default value to another method, which takes the final decision on whether the DAG is used or not. If None, will NOT use the DAG.

  • plot_kwargs (dict) – The plot configuration

  • **shared_kwargs – Shared keyword arguments that are passed through to the helper methods _use_dag and _get_dag_params

Returns

Whether data selection was used and the plot

configuration that can be passed on to the main plot method.

Return type

Tuple[bool, dict]

_plot_with_helper(*, out_path: str, plot_func: Callable, helpers: dict, style_context, func_kwargs: dict, animation: dict, use_dag: bool)

A helper method that performs plotting using the PlotHelper.

Parameters

  • out_path (str) – The output path

  • plot_func (Callable) – The resolved plot function

  • helpers (dict) – The helper configuration

  • style_context – A style context; can also be DoNothingContext, if no style adjustments are to take place.

  • func_kwargs (dict) – Plot function arguments

  • animation (dict) – Animation parameters

  • use_dag (bool) – Whether a DAG is used in preprocessing or not

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

Prepares the output path, creating directories if needed, then returning the full absolute path.

This is called from __call__ and is meant to postpone directory creation as far as possible.

Parameters

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

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

Raises

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

_prepare_plot_func_args(*args, _coords: dict = 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) – The current coordinate descriptor which is then used to retrieve a certain point in parameter space from the state map attribute.

  • **kwargs – Passed along to parent method

Returns

(args, kwargs) for the plot function

Return type

tuple

_prepare_style_context(*, base_style: Union[str, List[str]] = None, rc_file: str = 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

_resolve_plot_func(*, plot_func: Union[str, Callable], module: str = None, module_file: str = None) → Callable
Parameters

  • plot_func (Union[str, Callable]) – The plot function or a name or module string under which it can be imported.

  • module (str) – If plot_func was the name of the plot function, this needs to be the name of the module to import

  • module_file (str) – Path to the file to load and look for the plot_func in. If base_module_file_dir is given, this can also be a path relative to that directory.

Returns

The resolved plot function

Return type

Callable

Raises

TypeError – Upon wrong argument types

_use_dag(*, use_dag: bool, plot_kwargs: dict, _plot_func: Callable) → 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

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

Whether this plot creator is able to make a plot for the given plot configuration.

This checks whether the configuration allows resolving a plot function. If that is the case, it checks whether the plot function has defined some attributes that provide further information on whether the current creator is the desired one.

Parameters

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

  • **cfg – The plot configuration with which to decide this …

Returns

Whether this creator can be used for plotting or not

Return type

bool

property classname

Returns this creator’s class name

property default_ext

Returns the default extension to use for the plots

property dm

Return the DataManager

get_ext() → str

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

property logstr

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

property name

Returns this creator’s name

plot(*, out_path: str, plot_func: Union[str, Callable], module: str = None, module_file: str = None, style: dict = None, helpers: dict = None, animation: dict = None, use_dag: bool = None, **func_kwargs)

Performs the plot operation by calling a specified plot function.

The plot function is specified by its name, which is interpreted as a full module string, or by directly passing a callable.

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

Parameters

  • out_path (str) – The output path for the resulting file

  • plot_func (Union[str, Callable]) – The plot function or a name or module string under which it can be imported.

  • module (str, optional) – If plot_func was the name of the plot function, this needs to be the name of the module to import

  • module_file (str, optional) – Path to the file to load and look for the plot_func in. If base_module_file_dir is given, this can also be a path relative to that directory.

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

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

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

_get_dag_params(*, uni: dantro.groups.pspgrp.ParamSpaceStateGroup, **cfg) → Tuple[dict, dict][source]

Makes the selected universe available and adjusts DAG parameters such that selections can be based on that universe.