Monitoring diagnostic to show multiple datasets in one plot (incl. biases)

Monitoring diagnostic to show multiple datasets in one plot (incl. biases).

Description

This diagnostic can be used to visualize multiple datasets in one plot.

For some plot types, a reference dataset can be defined. For this, use the facet reference_for_monitor_diags: true in the definition of the dataset in the recipe. Note that at most one reference dataset per variable is supported.

Currently supported plot types (use the option plots to specify them):

Time series (plot type timeseries): for each variable separately, all datasets are plotted in one single figure. Input data needs to be 1D with single dimension time.
Maps (plot type map): for each variable and dataset, an individual map is plotted. If a reference dataset is defined, also include this dataset and a bias plot into the figure. Note that if a reference dataset is defined, all input datasets need to be given on the same horizontal grid (you can use the preprocessor esmvalcore.preprocessor.regrid() for this). Input data needs to be 2D with dimensions latitude, longitude.
Vertical profiles (plot type profile): for each variable and dataset, an individual profile is plotted. If a reference dataset is defined, also include this dataset and a bias plot into the figure. 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). Input data needs to be 2D with dimensions latitude, height/air_pressure.

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.
plots: dict, optional: Plot types plotted by this diagnostic (see list above). Dictionary keys must be timeseries, map, or profile. 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. Defaults to {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. Defaults to {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 User configuration file).
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() (affects all plots). By default, uses style: ticks.

Configuration options for plot type `timeseries`

annual_mean_kwargs: dict, optional: Optional keyword arguments for iris.plot.plot() for plotting annual means. These keyword arguments update (and potentially overwrite) the plot_kwargs for the annual mean plots. Use annual_mean_kwargs to not show annual means.
legend_kwargs: dict, optional: Optional keyword arguments for matplotlib.pyplot.legend(). Use legend_kwargs: false to not show legends.
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 single argument for these functions. String arguments can include facets in curly brackets which will be derived from the datasets plotted in the corresponding plot, e.g., {short_name}, {exp}. Facets like {project} that vary between the different datasets will be transformed to something like ambiguous_project. Examples: title: 'Awesome Plot of {long_name}', xlabel: '{short_name}', xlim: [0, 5].

Configuration options for plot type `map`

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}. This option has no effect if no reference dataset is given.
cbar_kwargs: dict, optional: Optional keyword arguments for matplotlib.pyplot.colorbar(). By default, uses orientation: horizontal, aspect: 30.
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. This option has no effect if no reference dataset is given.
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 vmix 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, the use of the plot_kwargs vmin and vmax or levels is highly recommend when using this common_cbar: true. This option has no effect if no reference dataset is given.
fontsize: int, optional (default: 10): Fontsize used for ticks, labels and titles. For the latter, use the given fontsize plus 2. Does not affect suptitles.
gridline_kwargs: dict, optional: Optional keyword arguments for grid lines. By default, color: lightgrey, alpha: 0.5 are used. Use gridline_kwargs: false to not show grid lines.
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 cubes with coordinates latitude and longitude.
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}.
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. This option has no effect if no reference dataset is given. See option plot_kwargs for more details. By default, uses cmap: bwr.
projection: str, optional (default: ‘Robinson’): Projection used for the map plot. Needs to be a valid projection class of cartopy.crs. Keyword arguments can be specified using the option projection_kwargs.
projection_kwargs: dict, optional: Optional keyword arguments for the projection given by projection. For the default projection Robinson, 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 single argument for these functions. 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: True): If True, use rasterization for map plots to produce smaller files. This is only relevant for vector graphics (e.g., output_file_type=pdf,svg,ps).
show_stats: bool, optional (default: True): Show basic statistics on the plots.

Configuration options for plot type `profile`

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}. This option has no effect if no reference dataset is given.
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. This option has no effect if no reference dataset is given.
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 vmix 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, the use of the plot_kwargs vmin and vmax or levels is highly recommend when using this common_cbar: true. This option has no effect if no reference dataset is given.
fontsize: int, optional (default: 10): Fontsize used for ticks, labels and titles. For the latter, use the given fontsize plus 2. Does not affect suptitles.
log_y: bool, optional (default: True): Use logarithmic Y-axis.
plot_func: str, optional (default: ‘contourf’): Plot function used to plot the profiles. Must be a function of iris.plot that supports plotting of 2D cubes with coordinates latitude and height/air_pressure.
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}.
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. This option has no effect if no reference dataset is given. See option plot_kwargs for more details. By default, uses cmap: bwr.
pyplot_kwargs: dict, optional: Optional calls to functions of matplotlib.pyplot. Dictionary keys are functions of matplotlib.pyplot. Dictionary values are used as single argument for these functions. 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: True): If True, use rasterization for profile plots to produce smaller files. This is only relevant for vector graphics (e.g., output_file_type=pdf,svg,ps).
show_y_minor_ticklabels: bool, optional (default: False): Show tick labels for the minor ticks on the Y axis.
show_stats: bool, optional (default: True): Show basic statistics on the plots.

Hint

Extra arguments given to the recipe are ignored, so it is safe to use yaml anchors to share the configuration of common arguments with other monitor diagnostic script.