utopya.plot_funcs.dag package#

This subpackge contains generic plot function implementations, which rely on the DAG framework to select and transform the data.

The plot functions then take care to visualize the data. They should NOT be specialized to work only for one kind of creator, but focus on the creating a visualization from the given data.

Submodules#

utopya.plot_funcs.dag.generic module#

Generic DAG-based plotting functions

utopya.plot_funcs.dag.generic.histogram(*, data: dict, hlpr: utopya.plotting.PlotHelper, x: str, hue: Optional[str] = None, frames: Optional[str] = None, coarsen_by: Optional[int] = None, align: str = 'edge', bin_widths: Optional[Union[str, Sequence[float]]] = None, suptitle_kwargs: Optional[dict] = None, show_histogram_info: bool = True, **bar_kwargs)[source]#

Shows a distribution as a stacked bar plot, allowing animation.

Expects as DAG result counts an xr.DataArray of one, two, or three dimensions. Depending on the hue and frames arguments, this will be represented as a stacked barplot and as an animation, respectively.

Parameters

  • data (dict) – The DAG results

  • hlpr (PlotHelper) – The PlotHelper

  • x (str) – The name of the dimension that represents the position of the histogram bins. By default, these are the bin centers.

  • hue (str, optional) – Which dimension to represent by stacking bars of different hue on top of each other

  • frames (str, optional) – Which dimension to represent by animation

  • coarsen_by (int, optional) – By which factor to coarsen the dimension specified by x. Uses xr.DataArray.coarsen and pads boundary values.

  • align (str, optional) – Where to align bins. By default, uses edge for alignment, as this is more exact for histograms.

  • bin_widths (Union[str, Sequence[float]], optional) – If not given, will use the difference between the x coordinates as bin widths, padding on the right side using the last value If a string, assume that it is a DAG result and retrieve it from data. Otherwise, use it directly for the width argument of plt.bar, i.e. assume it’s a scalar or a sequence of bin widths.

  • suptitle_kwargs (dict, optional) – Description

  • show_histogram_info (bool, optional) – Whether to draw a box with information about the histogram.

  • **bar_kwargs – Passed on hlpr.ax.bar invocation

Returns

None

Raises

ValueError – Bad dimensionality or missing bin_widths DAG result

utopya.plot_funcs.dag.graph module#

This module provides graph plotting functions.

utopya.plot_funcs.dag.graph.graph_array_from_group(graph_group, *, graph_creation: Optional[dict] = None, register_property_maps: Optional[dict] = None, clear_existing_property_maps: bool = True, times: Optional[dict] = None, sel: Optional[dict] = None, isel: Optional[dict] = None) → xarray.core.dataarray.DataArray[source]#

From a GraphGroup creates a DataArray containing the networkx graphs created from the graph group at the specified points in the group’s coordinate space.

From all coordinates provided via the selection kwargs the cartesian product is taken. Each of those points represents one entry in the returned DataArray. The selection kwargs in graph_creation are ignored silently.

Parameters

  • graph_group – The graph group

  • graph_creation (dict, optional) – Graph creation configuration

  • register_property_maps (dict, optional) – Property maps to be registered before graph creation

  • clear_existing_property_maps (bool, optional) – Whether to remove any existing property map at first

  • times (dict, optional) – Deprecated: Equivalent to a sel.time entry

  • sel (dict, optional) – Select by value

  • isel (dict, optional) – Select by index

Returns

networkx graphs with the respective graph group coordinates

Return type

xr.DataArray

utopya.plot_funcs.dag.graph.graph_animation_update(*, hlpr: utopya.plotting.PlotHelper, graphs: Optional[xarray.core.dataarray.DataArray] = None, graph_group=None, graph_creation: Optional[dict] = None, register_property_maps: Optional[dict] = None, clear_existing_property_maps: bool = True, positions: Optional[dict] = None, animation_kwargs: Optional[dict] = None, suptitle_kwargs: Optional[dict] = None, **drawing_kwargs)[source]#

Graph animation frame generator. Yields whenever the plot helper may grab the current frame.

If graphs is given, the networkx graphs in the array are used to create the frames.

Otherwise, use a graph group. The frames are defined via the selectors in animation_kwargs. From all provided coordinates the cartesian product is taken. Each of those points defines one graph and thus one frame. The selection kwargs in graph_creation are ignored silently.

Parameters

  • hlpr (PlotHelper) – The plot helper

  • graphs (xr.DataArray, optional) – Networkx graphs to draw. The array will be flattened beforehand.

  • graph_group (None, optional) – Required if graphs is None. The GraphGroup from which to generate the animation frames as specified via sel and isel in animation_kwargs.

  • graph_creation (dict, optional) – Graph creation configuration. Passed to create_graph_from_group() if graph_group is given.

  • register_property_maps (dict, optional) – Passed to create_graph_from_group() if graph_group is given.

  • clear_existing_property_maps (bool, optional) – Passed to create_graph_from_group() if graph_group is given.

  • positions (dict, optional) – The node position configuration. If update_positions is True the positions are reconfigured for each frame.

  • animation_kwargs (dict, optional) –

    Animation configuration. The following arguments are allowed:

    times (dict, optional):

    Deprecated: Equivaluent to a sel.time entry.

    sel (dict, optional):

    Select by value. Coordinate values (or from_property entry) keyed by dimension name.

    isel (dict, optional):

    Select by index. Coordinate indices keyed by dimension. May be given together with sel if no key appears in both.

    update_positions (bool, optional):

    Whether to reconfigure the node positions for each frame (default=False).

    update_colormapping (bool, optional):

    Whether to reconfigure the nodes’ and edges’ ColorManager for each frame (default=False). If False, the colormapping (and the colorbar) is configured with the first frame and then fixed.

    skip_empty_frames (bool, optional):

    Whether to skip the frames where the selected graph is missing or of a type different than nx.Graph (default=False). If False, such frames are empty.

  • suptitle_kwargs (dict, optional) – Passed on to the PlotHelper’s set_suptitle helper function. Only used in animation mode. The title can be a format string containing a placeholder with the dimension name as key for each dimension along which selection is done. The format string is updated for each frame of the animation. The default is <dim-name> = {<dim-name>} for each dimension.

  • **drawing_kwargs – Passed to GraphPlot

utopya.plot_funcs.dag.graph.draw_graph(*, hlpr: utopya.plotting.PlotHelper, data: dict, graph_group_tag: str = 'graph_group', graph: Optional[Union[networkx.classes.graph.Graph, xarray.core.dataarray.DataArray]] = None, graph_creation: Optional[dict] = None, graph_drawing: Optional[dict] = None, graph_animation: Optional[dict] = None, register_property_maps: Optional[Sequence[str]] = None, clear_existing_property_maps: bool = True, suptitle_kwargs: Optional[dict] = None)[source]#

Draws a graph either from a GraphGroup or directly from a networkx.Graph using the GraphPlot class.

If the graph object is to be created from a graph group the latter needs to be selected via the TransformationDAG. Additional property maps can also be made available for plotting, see register_property_map argument. Animations can be created either from a graph group by using the select interface in graph_animation or by passing a DataArray of networkx graphs via the graph argument.

For more information on how to use the transformation framework, refer to the dantro documentation.

For more information on how to configure the graph layout refer to the GraphPlot documentation.

Parameters

  • hlpr (PlotHelper) – The PlotHelper instance for this plot

  • data (dict) – Data from TransformationDAG selection

  • graph_group_tag (str, optional) – The TransformationDAG tag of the graph group

  • graph (Union[nx.Graph, xr.DataArray], optional) – If given, the data and graph_creation arguments are ignored and this graph is drawn directly. If a DataArray of graphs is given, the first graph is drawn for a single graph plot. In animation mode the (flattened) array represents the animation frames.

  • graph_creation (dict, optional) – Configuration of the graph creation. Passed to GraphGroup.create_graph.

  • graph_drawing (dict, optional) – Configuration of the graph layout. Passed to GraphPlot.

  • graph_animation (dict, optional) –

    Animation configuration. The following arguments are allowed:

    times (dict, optional):

    Deprecated: Equivaluent to a sel.time entry.

    sel (dict, optional):

    Select by value. Dictionary with dimension names as keys. The values may either be coordinate values or a dict with a single from_property (str) entry which specifies a container withing the GraphGroup or registered external data from which the coordinates are extracted.

    isel (dict, optional):

    Select by index. Coordinate indices keyed by dimension. May be given together with sel if no key appears in both.

    update_positions (bool, optional):

    Whether to update the node positions for each frame by recalculating the layout with the parameters specified in graph_drawing.positions. If this parameter is not given or false, the positions are calculated once initially and then fixed.

    update_colormapping (bool, optional):

    Whether to reconfigure the nodes’ and edges’ ColorManager for each frame (default=False). If False, the colormapping (and the colorbar) is configured with the first frame and then fixed.

    skip_empty_frames (bool, optional):

    Whether to skip the frames where the selected graph is missing or of a type different than nx.Graph (default=False). If False, such frames are empty.

  • register_property_maps (Sequence[str], optional) – Names of properties to be registered in the graph group before the graph creation. The property names must be valid TransformationDAG tags, i.e., be available in data. Note that the tags may not conflict with any valid path reachable from inside the selected GraphGroup.

  • clear_existing_property_maps (bool, optional) – Whether to clear any existing property maps from the selected GraphGroup. This is enabled by default to reduce side effects from previous plots. Set this to False if you have property maps registered with the GraphGroup that you would like to keep.

  • suptitle_kwargs (dict, optional) – Passed on to the PlotHelper’s set_suptitle helper function. Only used in animation mode. The title can be a format string containing a placeholder with the dimension name as key for each dimension along which selection is done. The format string is updated for each frame of the animation. The default is <dim-name> = {<dim-name>} for each dimension.

Raises

ValueError – On invalid or non-computed TransformationDAG tags in register_property_maps or invalid graph group tag.

utopya.plot_funcs.dag.time_series module#

A generic, DAG-supporting time series plot

utopya.plot_funcs.dag.time_series.time_series(*, data: dict, hlpr: utopya.plotting.PlotHelper, **plot_kwargs)[source]#

This is a generic plotting function that plots one or multiple time series from the ‘y’ tag that is selected via the DAG framework.

The y data needs to be an xarray object. If y is an xr.DataArray, it is assumed to be one- or two-dimensional. If y is an xr.Dataset, all data variables are plotted and their name is used as the label.

For the x axis values, the corresponding ‘time’ coordinates are used.

Parameters

  • data (dict) – The data selected by the DAG framework

  • hlpr (PlotHelper) – The plot helper

  • **plot_kwargs – Passed on ot matplotlib.pyplot.plot