Relevant API References

This is an excerpt of the relevant API references for the plotting framework.

Note

These structures are derived from corresponding dantro structures. For more information, visit the dantro documentation.


utopya.plotting.PlotManager

class utopya.plotting.PlotManager(*args, _model_info_bundle: Optional[utopya.model_registry.info_bundle.ModelInfoBundle] = None, **kwargs)[source]

Bases: dantro.plot_mngr.PlotManager

This is the Utopia-specific version of the dantro PlotManager class

It registers the Utopia-specific plot creators and allows for custom interface specifications.

Sets up a PlotManager.

This additionally stores some Utopia-specific metadata about the model this PlotManager is used with. That information is then used to load some additional model-specific information once a creator is invoked.

CREATORS = {'multiverse': <class 'utopya.plotting.MultiversePlotCreator'>, 'universe': <class 'utopya.plotting.UniversePlotCreator'>}
__init__(*args, _model_info_bundle: Optional[utopya.model_registry.info_bundle.ModelInfoBundle] = None, **kwargs)[source]

Sets up a PlotManager.

This additionally stores some Utopia-specific metadata about the model this PlotManager is used with. That information is then used to load some additional model-specific information once a creator is invoked.

property common_out_dir: str

The common output directory of all plots that were created with this plot manager instance. This uses the plot output paths stored in the plot information dict, specifically the target_dir entry.

If there was no plot information yet, the return value will be empty.

plot_from_cfg(*args, plots_cfg: Optional[Union[dict, str]] = None, **kwargs)[source]

Thin wrapper around parent method that shows which plot configuration file will be used.

__annotations__ = {}
__module__ = 'utopya.plotting'

Plot Creators

utopya.plotting.ExternalPlotCreator

class utopya.plotting.ExternalPlotCreator(name: str, *, base_module_file_dir: Optional[str] = None, style: Optional[dict] = None, **parent_kwargs)[source]

Bases: dantro.plot_creators.pcr_ext.ExternalPlotCreator

This is the Utopia-specific version of dantro’s ExternalPlotCreator.

Its main purpose is to define common settings for plotting. By adding this extra layer, it allows for future extensibility as well.

One of the common settings is that it sets as BASE_PKG the utopya utopya.plot_funcs, which is an extension of those functions supplied by dantro.

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

EXTENSIONS = 'all'
DEFAULT_EXT = 'pdf'
BASE_PKG = 'utopya.plot_funcs'
PLOT_HELPER_CLS

alias of utopya.plotting.PlotHelper

CUSTOM_PLOT_MODULE_NAME = 'model_plots'
CUSTOM_PLOT_MODULE_PATHS = {'Utopia': '/builds/utopia-project/docs/utopia/python/model_plots'}
__abstractmethods__ = frozenset({})
__annotations__ = {}
__module__ = 'utopya.plotting'

utopya.plotting.UniversePlotCreator

class utopya.plotting.UniversePlotCreator(*args, psgrp_path: Optional[str] = None, **kwargs)[source]

Bases: dantro.plot_creators.pcr_psp.UniversePlotCreator, utopya.plotting.ExternalPlotCreator

Makes plotting with data from a single universe more convenient

Initialize a UniversePlotCreator

PSGRP_PATH = 'multiverse'
__abstractmethods__ = frozenset({})
__annotations__ = {}
__module__ = 'utopya.plotting'

utopya.plotting.MultiversePlotCreator

class utopya.plotting.MultiversePlotCreator(*args, psgrp_path: Optional[str] = None, **kwargs)[source]

Bases: dantro.plot_creators.pcr_psp.MultiversePlotCreator, utopya.plotting.ExternalPlotCreator

Makes plotting with data from a all universes more convenient

Initialize a MultiversePlotCreator

Parameters
  • *args – Passed on to parent

  • 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 = 'multiverse'
__abstractmethods__ = frozenset({})
__annotations__ = {}
__module__ = 'utopya.plotting'

is_plot_func() decorator

@utopya.plotting.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]

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

utopya.plotting.PlotHelper

Basic PlotHelper interface

class utopya.plotting.PlotHelper(*, out_path: str, helper_defaults: Optional[dict] = None, update_helper_cfg: Optional[dict] = None, raise_on_error: bool = True, animation_enabled: bool = False)[source]

Bases: dantro.plot_creators._plot_helper.PlotHelper

A specialization of the dantro PlotHelper used in plot creators that are derived from ExternalPlotCreator.

This can be used to add additional helpers for use in Utopia without requiring changes on dantro-side.

Note

The helpers implemented here should try to adhere to the interface exemplified by the dantro PlotHelper class, with the aim that they can then be migrated into dantro in the long run.

Initialize a Plot Helper with a certain configuration.

This configuration is the so-called “base” configuration and is not axis-specific. There is the possibility to specify axis-specific configuration entries.

All entries in the helper configuration are deemed ‘enabled’ unless they explicitly specify enabled: false in their configuration.

Parameters
  • out_path (str) – path to store the created figure. This may be an absolute path or a relative path; the latter is regarded as relative to the current working directory. The home directory indicator ~ is expanded.

  • helper_defaults (dict, optional) – The basic configuration of the helpers.

  • update_helper_cfg (dict, optional) – A configuration used to update the existing helper defaults

  • raise_on_error (bool, optional) – Whether to raise on an exception created on helper invocation or just log the error

  • animation_enabled (bool, optional) – Whether animation mode is enabled.

__annotations__ = {}
__module__ = 'utopya.plotting'

Full PlotHelper interface

class utopya.plotting.PlotHelper(*, out_path: str, helper_defaults: Optional[dict] = None, update_helper_cfg: Optional[dict] = None, raise_on_error: bool = True, animation_enabled: bool = False)[source]

Bases: dantro.plot_creators._plot_helper.PlotHelper

A specialization of the dantro PlotHelper used in plot creators that are derived from ExternalPlotCreator.

This can be used to add additional helpers for use in Utopia without requiring changes on dantro-side.

Note

The helpers implemented here should try to adhere to the interface exemplified by the dantro PlotHelper class, with the aim that they can then be migrated into dantro in the long run.

Initialize a Plot Helper with a certain configuration.

This configuration is the so-called “base” configuration and is not axis-specific. There is the possibility to specify axis-specific configuration entries.

All entries in the helper configuration are deemed ‘enabled’ unless they explicitly specify enabled: false in their configuration.

Parameters
  • out_path (str) – path to store the created figure. This may be an absolute path or a relative path; the latter is regarded as relative to the current working directory. The home directory indicator ~ is expanded.

  • helper_defaults (dict, optional) – The basic configuration of the helpers.

  • update_helper_cfg (dict, optional) – A configuration used to update the existing helper defaults

  • raise_on_error (bool, optional) – Whether to raise on an exception created on helper invocation or just log the error

  • animation_enabled (bool, optional) – Whether animation mode is enabled.

__annotations__ = {}
__module__ = 'utopya.plotting'