dantro.plot_creators.pcr_ext module

This module implements the ExternalPlotCreator class, which specialises on creating matplotlib-based plots. These are accessed via ‘external’ modules being imported and plot functions defined in these modules being invoked.

class dantro.plot_creators.pcr_ext.figure_leak_prevention(*, close_current_fig_on_raise: bool = False)[source]

Bases: object

Context manager that aims to prevent superfluous matplotlib figures persisting beyond the context. Such figure objects can aggregate and start memory issues or even representation errors.

Specifically, it does the following:

  • When entering, stores all current figure numbers

  • When exiting regularly, all figures that were opened within the context are closed, except the currently selected figure.

  • When exiting with an exception, the behaviour is the same, unless the close_current_fig_on_raise is set, in which case the currently selected figure is not excluded from closing.

__init__(*, close_current_fig_on_raise: bool = False)[source]

Initialize the context manager

Parameters

close_current_fig_on_raise (bool, optional) – If True, the currently selected figure will not be exempt from the figure closure in case an exception occurs. This flag has no effect when the context is exited without an exception.

__enter__()[source]

Upon entering, store all currently open figure numbers

__exit__(exc_type: type, *args) → None[source]

Iterates over all currently open figures and closes all figures that were not previously open, except the currently selected figure.

If an exception is detected, i.e. exc_type` is **not** None, the current figure is only closed if the context manager was entered with the ``close_current_fig_on_raise flag set.

class dantro.plot_creators.pcr_ext.ExternalPlotCreator(name: str, *, base_module_file_dir: str = None, style: dict = None, **parent_kwargs)[source]

Bases: dantro.plot_creators.pcr_base.BasePlotCreator

This PlotCreator uses external scripts to create plots.

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

alias of dantro.plot_creators._plot_helper.PlotHelper

_AD_IGNORE_FUNC_ATTRS = False
__init__(name: str, *, base_module_file_dir: str = None, style: dict = None, **parent_kwargs)[source]

Initialize an ExternalPlotCreator.

Parameters

  • name (str) – The name of this plot

  • base_module_file_dir (str, optional) – If given, module_file arguments to the _plot method that are relative paths will be seen relative to this directory

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

  • **parent_kwargs – Passed to the parent __init__

Raises

ValueError – On invalid base_module_file_dir argument

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)[source]

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

can_plot(creator_name: str, **cfg) → bool[source]

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

_plot_with_helper(*, out_path: str, plot_func: Callable, helpers: dict, style_context, 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

  • 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

_resolve_plot_func(*, plot_func: Union[str, Callable], module: str = None, module_file: str = None) → Callable[source]
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

_get_module_from_file(path: str)[source]

Returns the module corresponding to the file at the given path

_get_module_via_import(module: str)[source]

Returns the module via import

_prepare_plot_func_args(plot_func: Callable, *args, use_dag: bool = None, **kwargs) → Tuple[tuple, dict][source]

Prepares the args and kwargs passed to the plot function.

The passed args and kwargs are carried over, while the positional arguments are prepended with passing of the data manager.

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

Parameters

  • *args – Additional args

  • **kwargs – Additional kwargs

Returns

(args: tuple, kwargs: dict)

Return type

tuple

_get_dag_params(*, _plot_func: Callable, **cfg) → Tuple[dict, dict][source]

Extends the parent method by making the plot function callable available to the other helper methods and extracting some further information from the plot function.

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

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

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

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

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.

_combine_dag_results_and_plot_cfg(*, dag: dantro.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.

Note

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

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

_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)[source]

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

_declared_plot_func_by_attrs(pf: Callable, creator_name: str) → bool[source]

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

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

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

Parameters

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

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

Returns

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

_abc_impl = <_abc_data object>
_perform_data_selection(*, use_dag: bool = None, plot_kwargs: dict, **shared_kwargs) → Tuple[bool, dict]

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

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

Note

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

Parameters

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

  • plot_kwargs (dict) – The plot configuration

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

Returns

Whether data selection was used and the plot

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

Return type

Tuple[bool, dict]

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

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

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

Parameters

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

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

Raises

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

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

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_ext.is_plot_func(*, creator_type: type = None, creator_name: str = None, use_helper: bool = True, helper_defaults: Union[dict, str] = None, use_dag: bool = None, required_dag_tags: Sequence[str] = None, compute_only_required_dag_tags: bool = True, pass_dag_object_along: bool = False, unpack_dag_results: bool = False, supports_animation=False, add_attributes: dict = None)[source]

Bases: object

This is a decorator class declaring the decorated function as a plotting function to use with ExternalPlotCreator-derived plot creators

__init__(*, creator_type: type = None, creator_name: str = None, use_helper: bool = True, helper_defaults: Union[dict, str] = None, use_dag: bool = None, required_dag_tags: Sequence[str] = None, compute_only_required_dag_tags: bool = True, pass_dag_object_along: bool = False, unpack_dag_results: bool = False, supports_animation=False, add_attributes: dict = None)[source]

Initialize the decorator. Note that the function to be decorated is not passed to this method.

Parameters

  • creator_type (type, optional) – The type of plot creator to use

  • creator_name (str, optional) – The name of the plot creator to use

  • use_helper (bool, optional) – Whether to use a PlotHelper

  • helper_defaults (Union[dict, str], optional) – Default configurations for helpers; these are automatically considered to be enabled. If string-like, will assume this is an absolute path to a YAML file and will load the dict-like configuration from there.

  • use_dag (bool, optional) – Whether to use the data transformation framework.

  • required_dag_tags (Sequence[str], optional) – The DAG tags that are required by the plot function.

  • compute_only_required_dag_tags (bool, optional) – Whether to compute only those DAG tags that are specified as required by the plot function. This is ignored if no required DAG tags were given and can be overwritten by the compute_only argument.

  • pass_dag_object_along (bool, optional) – Whether to pass on the DAG object to the plot function

  • unpack_dag_results (bool, optional) – Whether to unpack the results of the DAG computation directly into the plot function instead of passing it as a dictionary.

  • supports_animation (bool, optional) – Whether the plot function supports animation.

  • add_attributes (dict, optional) – Additional attributes to add to the plot function.

Raises

ValueError – If helper_defaults was a string but not an absolute path.

__call__(func: Callable)[source]

If there are decorator arguments, __call__() is only called once, as part of the decoration process and expects as only argument the function to be decorated.