Monitoring diagnostic to show multiple datasets in one plot (incl. biases)#
Monitoring diagnostic to visualize multiple datasets.
Description#
This diagnostic can be used to visualize multiple datasets in a single plot. A large variety of different plot types is supported.
Currently supported plot types#
Plot types can be specified with the recipe option plots
. All plots can be
customized with additional plot-specific options.
1d_profile
(1D plot): plot 1D profile. Input data needs single dimension altitude or air_pressure.annual_cycle
(1D plot): plot annual cycle. Input data needs single dimension month_number.benchmarking_annual_cycle
(1D plot): benchmarking version ofannual_cycle
. Input data needs single dimension month_number.benchmarking_boxplot
(boxplot): plot boxplot. Input data needs to be scalar.benchmarking_diurnal_cycle
(1D plot): benchmarking version ofdiurnal_cycle
. Input data needs single dimension hour.benchmarking_map
(2D plot): benchmarking version ofmap
. Input data needs dimensions (longitude, latitude).benchmarking_timeseries
(1D plot): benchmarking version oftimeseries
. Input data needs single dimension time.benchmarking_zonal
(2D plot): benchmarking version ofzonal_mean_profile
. Input data needs dimensions (latitude, altitude) or latitude, air_pressure.diurnal_cycle
(1D plot): plot diurnal cycle. Input data needs single dimension hour.hovmoeller_anncyc_vs_lat_or_lon
(2D plot): plot Hovmoeller plot. Input data needs dimensions (month_number, latitude) or (month_number, longitude).hovmoeller_time_vs_lat_or_lon
(2D plot): plot Hovmoeller plot. Input data needs dimensions (time, latitude) or (time, longitude).hovmoeller_z_vs_time
(2D plot): plot Hovmoeller plot. Input data needs dimensions (time, altitude) or (time, air_pressure).map
(2D plot): plot map plot. Input data needs dimensions (longitude, latitude).timeseries
(1D plot): plot time series. Input data needs single dimension time.variable_vs_lat
(1D plot): plot variable vs. latitude. Input data needs single dimension latitude.zonal_mean_profile
(2D plot): plot zonal mean profile. Input data needs dimensions (latitude, altitude) or latitude, air_pressure.
Each plot type belongs to one or more classes which define how the data is plotted:
Class 1D plot: for each variable separately, all datasets are plotted in one single figure. Input data needs to be 1D.
Class 2D plot: for each variable and dataset, an individual figure is plotted. Input data needs to be 2D. A single reference dataset can be defined by setting the facet
reference_for_monitor_diags: True
in the dataset definition in the recipe. In this case, three panels are plotted, incl. a bias. Note that if a reference dataset is defined, all input datasets need to be given on the same horizontal and vertical grid (you can use the preprocessorsesmvalcore.preprocessor.regrid()
andesmvalcore.preprocessor.extract_levels()
for this).Class boxplot: one figure for all datasets is plotted. Input data needs to be 0D.
In addition, for many plot types, a benchmarking version exists
(benchmarking_*
). These plots include envelopes (1D plots) or hatching (2D
plots) to visualize data ranges (e.g., multi-model percentiles) in addition to
the data itself. For these plots, at least one benchmarking dataset needs to be
defined by setting the facet benchmark_dataset: True
in the dataset
definition in the recipe. Reference datasets are not supported for 2D
benchmarking diagnostics.
Configuration options in recipe#
- facet_used_for_labels: str, optional (default: ‘dataset’)
Facet used to label different datasets in plot titles and legends. For example,
facet_used_for_labels: 'dataset'
will use dataset names in plot titles and legends;facet_used_for_labels: 'exp'
will use experiments in plot titles and legends. In addition,facet_used_for_labels
is used to select the correctplot_kwargs
for the different datasets (see configuration options for the different plot types below).- figure_kwargs: dict, optional
Optional keyword arguments for
matplotlib.pyplot.figure()
. By default, uses{constrained_layout: True}
.- group_variables_by: str, optional (default: ‘short_name’)
Facet which is used to create variable groups. For each variable group, an individual plot is created.
- matplotlib_rc_params: dict, optional
Optional
matplotlib.RcParams
used to customize matplotlib plots. Options given here will be passed tomatplotlib.rc_context()
and used for all plots produced with this diagnostic. Note: fontsizes specified here might be overwritten by the plot-type-specific optionfontsize
(see below).- plots: dict
Plot types plotted by this diagnostic (see list above). Dictionary keys must be elements of the list above. Dictionary values are dictionaries used as options for the corresponding plot. The allowed options for the different plot types are given below.
- plot_filename: str, optional
Filename pattern for the plots. By default, uses
'{plot_type}_{real_name}_{dataset}_{mip}_{exp}_{ensemble}'
. All tags (i.e., the entries in curly brackets, e.g.,'{dataset}'
, are replaced with the corresponding tags).- plot_folder: str, optional
Path to the folder to store figures. By default, uses
'{plot_dir}/../../{dataset}/{exp}/{modeling_realm}/{real_name}'
. All tags (i.e., the entries in curly brackets, e.g.,'{dataset}'
, are replaced with the corresponding tags).'{plot_dir}'
is replaced with the default ESMValTool plot directory (i.e.,output_dir/plots/diagnostic_name/script_name/
, see Output).- savefig_kwargs: dict, optional
Optional keyword arguments for
matplotlib.pyplot.savefig()
. By default, uses{bbox_inches: 'tight', dpi: 300, orientation: 'landscape'}
.- seaborn_settings: dict, optional
Options for
seaborn.set_theme()
(affects all plots). By default, uses{style: 'ticks'}
.
Configuration options for 1D plots#
- aspect_ratio: float, optional (default: None)
Aspect ratio of the plot.
- caption: str, optional
Figure caption used for provenance tracking. Can include facets in curly brackets which will be derived from the corresponding dataset, e.g.,
{project}
,{short_name}
,{exp}
. By default, uses a very basic caption.- envelope_kwargs: dict, optional
Optional keyword arguments for
iris.plot.fill_between()
. By default, uses{alpha: 0.8, facecolor: 'lightblue', linewidth: 0.0, zorder: 1.0}
. Only relevant for benchmarking plots.- gridline_kwargs: dict, optional
Optional keyword arguments for grid lines. By default, uses
{color: 'lightgrey', alpha: 0.5}
. Usegridline_kwargs: False
to not show grid lines.- hlines: list of dict, optional
Horizontal lines to show in plot. Each list element corresponds to one line, and each list element should contain a dictionary with keywords arguments passed to
matplotlib.axes.Axes.axhline()
. Example:[{y: 0}, {y: 1, color: 'red'}]
.- legend_kwargs: dict, optional
Optional keyword arguments for
matplotlib.pyplot.legend()
. Uselegend_kwargs: False
to not show legends.- log_x: bool, optional (default: False)
Use logarithmic X-axis.
- log_y: bool, optional (default: False)
Use logarithmic Y-axis.
- plot_kwargs: dict, optional
Optional keyword arguments for
iris.plot.plot()
. Dictionary keys are elements identified byfacet_used_for_labels
or'default'
, e.g.,'CMIP6'
iffacet_used_for_labels: 'project'
or'historical'
iffacet_used_for_labels: 'exp'
. Dictionary values are dictionaries used as keyword arguments foriris.plot.plot()
. String arguments can include facets in curly brackets which will be derived from the corresponding dataset, e.g.,{project}
,{short_name}
,{exp}
. Examples:{default: {linestyle: '-', label: '{project}'}, CMIP6: {color: 'red', linestyle: '--'}, OBS: {color: 'black'}}
.- pyplot_kwargs: dict, optional
Optional calls to functions of
matplotlib.pyplot
. Dictionary keys are functions ofmatplotlib.pyplot
. Dictionary values are used as argument(s) for these functions (if values are dictionaries, these are interpreted as keyword arguments; otherwise a single argument is assumed). String arguments can include facets in curly brackets which will be derived from the corresponding dataset, e.g.,{project}
,{short_name}
,{exp}
. Examples:{title: 'Awesome Plot of {long_name}'}
,{xlabel: '{short_name}'}
,{xlim: [0, 5]}
.- rasterize: bool, optional (default: False)
If
True
, use rasterization for plots to produce smaller files. This is only relevant for vector graphics (e.g.,output_file_type: 'pdf'
).- time_format: str, optional (default: None)
strftime()
format string that is used to format the time axis usingmatplotlib.dates.DateFormatter
. IfNone
, use the default formatting imposed by the iris plotting function.- transpose_axes: bool, optional (default: False)
Swap X- and Y-axis.
- x_major_formatter: str, optional (default: None)
Format string for
matplotlib.ticker.FormatStrFormatter
used to format major tick labels of X-axis.- x_minor_formatter: str, optional (default: None)
Format string for
matplotlib.ticker.FormatStrFormatter
used to format minor tick labels of X-axis.- y_major_formatter: str, optional (default: None)
Format string for
matplotlib.ticker.FormatStrFormatter
used to format major tick labels of Y-axis.- y_minor_formatter: str, optional (default: None)
Format string for
matplotlib.ticker.FormatStrFormatter
used to format minor tick labels of Y-axis.
Configuration options for 2D plots#
- aspect_ratio: float, optional (default: None)
Aspect ratio of the plot.
- caption: str, optional
Figure caption used for provenance tracking. Can include facets in curly brackets which will be derived from the corresponding dataset, e.g.,
{project}
,{short_name}
,{exp}
. By default, uses a very basic caption.- cbar_label: str, optional (default: ‘{short_name} [{units}]’)
Colorbar label. Can include facets in curly brackets which will be derived from the corresponding dataset, e.g.,
{project}
,{short_name}
,{exp}
.- cbar_label_bias: str, optional (default: ‘Δ{short_name} [{units}]’)
Colorbar label for plotting biases. Can include facets in curly brackets which will be derived from the corresponding dataset, e.g.,
{project}
,{short_name}
,{exp}
. Only relevant for plots including reference datasets.- cbar_kwargs: dict, optional
Optional keyword arguments for
matplotlib.pyplot.colorbar()
. By default, uses{orientation: 'vertical'}
.- cbar_kwargs_bias: dict, optional
Optional keyword arguments for
matplotlib.pyplot.colorbar()
for plotting biases. These keyword arguments update (and potentially overwrite) thecbar_kwargs
for the bias plot. Only relevant for plots including reference datasets.- common_cbar: bool, optional (default: False)
Use a common colorbar for the top panels (i.e., plots of the dataset and the corresponding reference dataset) when using a reference dataset. If neither
vmin
andvmax
norlevels
is given inplot_kwargs
, the colorbar bounds are inferred from the dataset in the top left panel, which might lead to an inappropriate colorbar for the reference dataset (top right panel). Thus, specifyvmin
andvmax
orlevels
when usingcommon_cbar: True
. Only relevant for plots including reference datasets.- fontsize: int, optional (default: None)
Fontsize used for ticks, labels and titles. For the latter, use the given fontsize plus 2. Does not affect suptitles. If not given, use default matplotlib values. For a more fine-grained definition of fontsizes, use the option
matplotlib_rc_params
(see above).- gridline_kwargs: dict, optional (default: False)
Optional keyword arguments for grid lines. Use
gridline_kwargs: False
to not show grid lines.- log_x: bool, optional (default: False)
Use logarithmic X-axis.
- log_y: bool, optional (default: False)
Use logarithmic Y-axis.
- plot_func: str, optional (default: ‘contourf’)
Plot function used to plot the maps. Must be a function of
iris.plot
that supports plotting of 2D data.- plot_kwargs: dict, optional
Optional keyword arguments for the plot function defined by
plot_func
. Dictionary keys are elements identified byfacet_used_for_labels
or'default'
, e.g.,'CMIP6'
iffacet_used_for_labels: 'project'
or'historical'
iffacet_used_for_labels: 'exp'
. Dictionary values are dictionaries used as keyword arguments for the plot function defined byplot_func
. String arguments can include facets in curly brackets which will be derived from the corresponding dataset, e.g.,{project}
,{short_name}
,{exp}
. Examples:{default: {levels: 2}, CMIP6: {vmin: 200, vmax: 250}}
. In addition to the normalization options supported by the plot function, the option{norm: 'centered'}
can be specified. In this case, the keywordsvcenter
andhalfrange
should be used instead ofvmin
orvmax
(seeCenteredNorm
).- plot_kwargs_bias: dict, optional
Optional keyword arguments for the plot function defined by
plot_func
for plotting biases. These keyword arguments update (and potentially overwrite) theplot_kwargs
for the bias plot. By default, uses{cmap: 'bwr', norm: 'centered'}
. Only relevant for plots including reference datasets.- projection: str, optional (default: None)
Projection used for the plot. Needs to be a valid projection class of
cartopy.crs
. Keyword arguments can be specified using the optionprojection_kwargs
. For map plots,'Robinson'
is used as default.- projection_kwargs: dict, optional
Optional keyword arguments for the projection given by
projection
. For map plots, the default keyword arguments{central_longitude: 10}
are used.- pyplot_kwargs: dict, optional
Optional calls to functions of
matplotlib.pyplot
. Dictionary keys are functions ofmatplotlib.pyplot
. Dictionary values are used as argument(s) for these functions (if values are dictionaries, these are interpreted as keyword arguments; otherwise a single argument is assumed). String arguments can include facets in curly brackets which will be derived from the corresponding dataset, e.g.,{project}
,{short_name}
,{exp}
. Examples:{title: 'Awesome Plot of {long_name}'}
,{xlabel: '{short_name}'}
,{xlim: [0, 5]}
.- rasterize: bool, optional (default: False)
If
True
, use rasterization for plots to produce smaller files. This is only relevant for vector graphics (e.g.,output_file_type: 'pdf'
).- show_stats: bool, optional (default: True)
Show basic statistics on the plots.
- time_format: str, optional (default: None)
strftime()
format string that is used to format the time axis usingmatplotlib.dates.DateFormatter
. IfNone
, use the default formatting imposed by the iris plotting function.- transpose_axes: bool, optional (default: False)
Swap X- and Y-axis.
- x_major_formatter: str, optional (default: None)
Format string for
matplotlib.ticker.FormatStrFormatter
used to format major tick labels of X-axis.- x_minor_formatter: str, optional (default: None)
Format string for
matplotlib.ticker.FormatStrFormatter
used to format minor tick labels of X-axis.- x_pos_stats_avg: float, optional (default: 0.01)
Text X-position of average (shown on the left) in Axes coordinates. Can be adjusted to avoid overlap with the figure. Only relevant if
show_stats: True
.- x_pos_stats_bias: float, optional (default: 0.7)
Text X-position of bias statistics (shown on the right) in Axes coordinates. Can be adjusted to avoid overlap with the figure. Only relevant if
show_stats: True
.- y_major_formatter: str, optional (default: None)
Format string for
matplotlib.ticker.FormatStrFormatter
used to format major tick labels of Y-axis.- y_minor_formatter: str, optional (default: None)
Format string for
matplotlib.ticker.FormatStrFormatter
used to format minor tick labels of Y-axis.
Configuration options for boxplots#
- caption: str, optional
Figure caption used for provenance tracking. Can include facets in curly brackets which will be derived from the corresponding dataset, e.g.,
{project}
,{short_name}
,{exp}
. By default, uses a very basic caption.- fontsize: int, optional (default: None)
Fontsize used for ticks, labels and titles. For the latter, use the given fontsize plus 2. Does not affect suptitles. If not given, use default matplotlib values. For a more fine-grained definition of fontsizes, use the option
matplotlib_rc_params
(see above).- plot_kwargs: dict, optional
Optional keyword arguments for
seaborn.boxplot()
.- pyplot_kwargs: dict, optional
Optional calls to functions of
matplotlib.pyplot
. Dictionary keys are functions ofmatplotlib.pyplot
. Dictionary values are used as argument(s) for these functions (if values are dictionaries, these are interpreted as keyword arguments; otherwise a single argument is assumed). String arguments can include facets in curly brackets which will be derived from the corresponding dataset, e.g.,{project}
,{short_name}
,{exp}
. Examples:{title: 'Awesome Plot of {long_name}'}
,{xlabel: '{short_name}'}
,{xlim: [0, 5]}
.- scatter_kwargs: dict, optional
Optional keyword arguments for
matplotlib.pyplot.scatter()
(used to plot marks for benchmarking dataset). By default, uses{marker: 'x', s: 200, linewidths: 2, color: 'red', zorder: 3}
.- var_order: list of str, optional (default: None)
Order in which variables are plotted. Must be elements identified via
group_variables_by
. IfNone
, use order in which data is given.