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 of annual_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 of diurnal_cycle. Input data needs single dimension hour.
benchmarking_map (2D plot): benchmarking version of map. Input data needs dimensions (longitude, latitude).
benchmarking_timeseries (1D plot): benchmarking version of timeseries. Input data needs single dimension time.
benchmarking_zonal (2D plot): benchmarking version of zonal_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 preprocessors esmvalcore.preprocessor.regrid() and esmvalcore.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.

Author#

Manuel Schlund (DLR, Germany)

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 correct plot_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 to matplotlib.rc_context() and used for all plots produced with this diagnostic. Note: fontsizes specified here might be overwritten by the plot-type-specific option fontsize (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}. Use gridline_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(). Use legend_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 by facet_used_for_labels or 'default', e.g., 'CMIP6' if facet_used_for_labels: 'project' or 'historical' if facet_used_for_labels: 'exp'. Dictionary values are dictionaries used as keyword arguments for iris.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 of matplotlib.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 using matplotlib.dates.DateFormatter. If None, 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) the cbar_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 and vmax nor levels is given in plot_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, specify vmin and vmax or levels when using common_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 by facet_used_for_labels or 'default', e.g., 'CMIP6' if facet_used_for_labels: 'project' or 'historical' if facet_used_for_labels: 'exp'. Dictionary values are dictionaries used as keyword arguments for the plot function defined by plot_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 keywords vcenter and halfrange should be used instead of vmin or vmax (see CenteredNorm).
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) the plot_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 option projection_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 of matplotlib.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 using matplotlib.dates.DateFormatter. If None, 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 of matplotlib.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. If None, use order in which data is given.