Generic Plots
Contents
Generic Plots#
You can directly use generic plot functions provided by dantro. For a detailed description visit the plot function section in the dantro documentation.
Errorbar and Errorbands#
For errorbar plots, two options are available: the errorbar plot uses bars to represent a symmetric confidence interval; the errorband plot uses a shaded area.
The corresponding base plot configurations are called .dag.generic.errorbar
and .dag.generic.errorbands
.
For more information, refer to the docstrings below and to the dantro documentation.
- dantro.plot_creators.ext_funcs.generic.errorbar(*, data: dict, hlpr: dantro.plot_creators._plot_helper.PlotHelper, x: Optional[str] = None, hue: Optional[str] = None, frames: Optional[str] = None, auto_encoding: Union[bool, dict] = False, hue_fstr: str = '{value:}', use_bands: bool = False, fill_between_kwargs: Optional[dict] = None, suptitle_kwargs: Optional[dict] = None, **errorbar_kwargs) None [source]#
A DAG-based generic errorbar plot.
Deprecated since version 0.15: This function is deprecated. Instead, the more capable and generic
errorbars()
function orfacet_grid()
withkind: errorbars
can be used. The interface is mostly the same, but data is expected asxr.Dataset
instead of as two separate arrays.This plot expects data to be provided via plot_creator_dag. Expected tags are
y
andyerr
and both should be labelled xarray.DataArray objects. Depending on the given layout encoding specifiers (x
,hue
, andframes
), data may be 1D, 2D, or 3D. The auto-encoding feature is supported.Uses
plot_errorbar()
for plotting individual lines.- Parameters
data (dict) – The DAG results dict which should contain entries
y
andyerr
, both labelled xr.DataArray objects.hlpr (PlotHelper) – The PlotHelper
x (str, optional) – The dimension to represent on the x-axis. If not given, it will be inferred. If no coordinates are associated with the dimension, trivial coordinates are used.
hue (str, optional) – Name of the dimension to respresent via the hue colors of the errorbar lines. For adjusting the property cycle of the lines, see pcr_ext_style.
frames (str, optional) – Name of the dimension to represent via the frames of an animation. If given, this will automatically enable animation mode and requires
animation
arguments being specified in the plot configuration. See pcr_ext_animations.auto_encoding (Union[bool, dict], optional) – Whether to choose the layout encoding options automatically, i.e. select
x
,hue
, andframes
according to the given data’s dimensionality. For further options, can pass a dict. See dag_generic_auto_encoding for more info.hue_fstr (str, optional) – A format string for the labels used when creating a plot with
hue
specified. Available keys:dim
(which is equivalent tohue
), andvalue
, which is set to the value of the corresponding coordinate along that dimension.use_bands (bool, optional) – Whether to use error bands instead of bars
fill_between_kwargs (dict, optional) – If using error bands, these arguments are passed on to
hlpr.ax.fill_between
. This would be the place to adjustalpha
; if not given, the corresponding line’salpha
value will be used, reduced to 20%.suptitle_kwargs (dict, optional) – Key passed on to the PlotHelper’s
set_suptitle
helper function. Only used if animations are enabled. Thetitle
entry can be a format string with the following keys, which are updated for each frame of the animation:dim
,value
. Default:{dim:} = {value:.3g}
.**errorbar_kwargs – Passed on to
hlpr.ax.errorbar
- Returns
None
- Raises
ValueError – Upon badly shaped data
- dantro.plot_creators.ext_funcs.generic.errorbands(*, data: dict, hlpr: dantro.plot_creators._plot_helper.PlotHelper, **kwargs)[source]#
A DAG-based generic errorbands plot.
Invokes
errorbar()
withuse_bands = True
. See there for available arguments.
Facet Grid#
Faceting plotting functions are able to represent high-dimensional data using subplots and animations.
Utopia makes use of the facet_grid
plotting function implemented in dantro.
It is accessible via the base configuration key .dag.generic.facet_grid
.
For more information, refer to the docstrings below and to the dantro documentation.
- dantro.plot_creators.ext_funcs.generic.facet_grid(*, data: dict, hlpr: dantro.plot_creators._plot_helper.PlotHelper, kind: Optional[Union[dict, str]] = None, frames: Optional[str] = None, auto_encoding: Union[bool, dict] = False, suptitle_kwargs: Optional[dict] = None, squeeze: bool = True, **plot_kwargs)[source]#
A generic facet grid plot function for high dimensional data.
This function calls the
data['data'].plot
function if no plotkind
is given, otherwisedata['data'].plot.<kind>
. It is designed for plotting with xarray objects, i.e. xr.DataArray and xr.Dataset. Specifying the kind of plot requires the data to be of one of those types and have a dimensionality that can be represented in these plots. See the correponding API documentation for more information.In most cases, this function creates a so-called FacetGrid object that automatically layouts and chooses a visual representation that fits the dimensionality of the data. To specify which data dimension should be represented in which way, it supports a declarative syntax: via the optional keyword arguments
x
,y
,row
,col
, and/orhue
(available options are listed in the corresponding plot function documentation), the representation of the data dimensions can be selected. This is referred to as “layout encoding”.dantro not only wraps this interface, but adds the following functionality:
the
frames
layout encoding argument, which behaves in the same way as the other encodings, but leads to an animation being generated, thus opening up one further dimension of representation,the
auto_encoding
feature, which allows to select layout- encodings automatically,and the
kind: 'auto'
option, which can be used in conjunction withauto_encoding
to choose the plot kind automatically as well.allows
col_wrap: 'auto'
, which selects the value such that the figure becomes more square-like (requiresauto_encoding: true
)allows to register additional plot
kind
values that create plots with a custom single-axis plotting function, using themake_facet_grid_plot
decorator.
For details about auto-encoding and how the plot
kind
is chosen, seedetermine_encoding()
anddetermine_plot_kind()
.Note
When specifying
frames
, theanimation
arguments need to be specified. See here for more information on the expected animation parameters.The value of the
animation.enabled
key is not relevant for this function; it will automatically enter or exit animation mode, depending on whether theframes
argument is given or not. This uses the animation mode switching feature.Note
Internally, this function calls
.squeeze
on the selected data, thus being more tolerant with data that has size-1 dimension coordinates. To suppress this behaviour, set thesqueeze
argument accordingly.Warning
Depending on
kind
and the dimensionality of the data, some plot functions might create their own figure, disregarding any previously set up figure. This includes the figure from the plot helper.To control figure aesthetics, you can either specify matplotlib RC style parameters (via the
style
argument), or you can use theplot_kwargs
to pass arguments to the respective plot functions. For the latter, refer to the respective documentation to find out about available arguments.- Parameters
data (dict) – The data selected by the data transformation framework, expecting the
data
key.hlpr (PlotHelper) – The plot helper
kind (str, optional) – The kind of plot to use. Options are:
contourf
,contour
,imshow
,line
,pcolormesh
,step
,hist
,scatter
,errorbars
and any plot kinds that were additionally registered via themake_facet_grid_plot
decorator. Withauto
, dantro chooses an appropriate kind by itself; this setting is useful when also using theauto_encoding
feature; see dag_generic_facet_grid_auto_kind for more information. If None is given, xarray automatically determines it using the dimensionality of the data, frequently falling back tohist
for higher-dimensional data or lacking specifiers.frames (str, optional) – Data dimension from which to create animation frames. If given, this results in the creation of an animation. If not given, a single plot is generated. Note that this requires
animation
options as part of the plot configuration.auto_encoding (Union[bool, dict], optional) – Whether to choose the layout encoding options automatically. For further options, can pass a dict. See dag_generic_auto_encoding for more info.
suptitle_kwargs (dict, optional) – Key passed on to the PlotHelper’s
set_suptitle
helper function. Only used if animations are enabled. Thetitle
entry can be a format string with the following keys, which are updated for each frame of the animation:dim
,value
. Default:{dim:} = {value:.3g}
.squeeze (bool, optional) – whether to squeeze the data before plotting, such that size-1 dimensions do not take up encoding dimensions.
**plot_kwargs – Passed on to
<data>.plot
or<data>.plot.<kind>
These should include the layout encoding specifiers (x
,y
,hue
,col
, and/orrow
).
- Raises
AttributeError – Upon unsupported
kind
valueValueError – Upon any upstream error in invocation of the xarray plotting capabilities. This wraps the given error message and provides additional information that helps to track down why the plotting failed.