Climatic Impact-Driver Diagnostic#

Diagnostic vizualizing Climatic Impact-Drivers.

Description#

This diagnostic vizualizes Climatic Impact-Drivers that were defined in Elling et al. (2026) for various models.

This diagnostic adapts the monitor/multi_datasets.py diagnostic adding a pre-processing routine to allow for plots of the number of days in a year that certain thresholds are exceeded. With this diagnostic, multiple datasets can be visualized in a single plot.

Plot types can be specified with the recipe option ‘plots’ and the pre- processing option can be called directly.

Recipe configuration options#

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 or coordinate which is used to create variable groups. For each variable group, an individual plot is created. Specifying a coordinate allows to create one plot for each point along a dimension. For example, when used in combination with the preprocessor function esmvalcore.preprocessor.extract_shape() the shape_id coordinate can be used to create one plot for each shape.

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 below). Dictionary keys must be elements of the list below. Dictionary values are dictionaries used as options for the corresponding plot.

plot_filename: str, optional

Filename pattern for the plots. By default, uses '{plot_type}_{real_name}_{dataset}_{mip}_{exp}_{ensemble}' or '{plot_type}_{real_name}_{dataset}_{mip}_{exp}_{ensemble}_threshold_{threshold}' if a threshold exsists. 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'}.

threshold_conversion: dict, optional

Replace the given dataset by the count of on how many days the data exceeds a certain threshold at some point of time. Dictonary keys are the following:

threshold: float

The threshold which should be exceeded for days to add to the count.

inverted: bool, optional

Optional boolean that can be set to true to count the days on which the values drop below the threshold at some point of time instead. The default value is false.

accumulated: bool, optional

Optional boolean that must be set to true to check if the daily accumulated amount is exceeding the threshold for variables that are accumulating over time (e.g. absolute amount of precipitation or snow) if the temporal resolution is shorter than daily. For all other variables (i.e. variables for which the number of days on which the absolute value of the variable exceeds the threshold at some point in time should be counted) use the default value. The default value is false.

Supported plot types#

timeseries (1D plot):

Plot time series. Input data needs single dimension time. For each variable separately, all datasets are plotted in one single figure. Input data needs to be 1D.

map (2D plot):

Plot map plot. Input data needs dimensions (longitude, latitude). 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).

Additional options for timeseries#

aspect_ratio: float, optional (default: None)

Aspect ratio of the plot.

axes_kwargs: dict, optional

Optional calls to methods of the corresponding matplotlib.axes.Axes instance. Dictionary keys are functions of matplotlib.axes.Axes. 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: {set_title: 'Awesome Plot of {long_name}'}, {set_xlabel: '{short_name}'}, {set_xlim: [0, 5]}.

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.

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 gridlines.

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.

Additional options for map#

aspect_ratio: float, optional (default: None)

Aspect ratio of the plot.

axes_kwargs: dict, optional

Optional calls to methods of the corresponding matplotlib.axes.Axes instance. Dictionary keys are functions of matplotlib.axes.Axes. 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: {set_title: 'Plot of {long_name}'}, {set_xlabel: '{short_name}'}, {set_xlim: [0, 5]}.

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: 'Plot {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.