<a id="api-esmvaltool-diag-scripts-droughts-diffmap"></a>

# Difference Maps

Plot relative and absolute differences between two time intervals.

A global map is plotted for each dataset with an index (must be unique).
The map shows the difference of the first and last N years
(N = comparison_period).
For multiple datasets a multi-model mean is calculated by default. This can be
disabled using plot_mmm: False. To plot only mmm and skip maps for individual
datasets use plot_models: False.
The diagnostic is applied to each variable by default, but for single variables
another meta key can be chosen for grouping like group_by: project to treat
observations and models separately.
The produced maps can be clipped to non polar landmasses (220, 170, -55, 90)
with clip_land: True.

## Configuration options in recipe

basename: str, optional
: Format string for the plot filename. Can use meta keys and diffmap_metric.
  For multi-model mean the dataset will be set to “MMM”. Data will be saved
  as same name with .nc extension.
  By default: “{short_name}_{exp}_{diffmap_metric}_{dataset}”

clip_land: bool, optional (default: False)
: Clips map plots to non polar land area (220, 170, -55, 90).

comparison_period: int, optional (default: 10)
: Number of years to compare (first and last N years). Must be less or equal
  to half of the total time period.

filters: dict or list, optional
: Filter for metadata keys to select datasets. Only datasets with matching
  values will be processed. This can be useful, if ancestors or preprocessed
  data is available, that should not be processed by the diagnostic.
  If a list of dicts is given, all datasets matching any of the filters will
  be considered.
  By default None.

group_by: str, optional (default: short_name)
: Meta key to loop over for multiple datasets.

metrics: list, optional
: List of metrics to calculate and plot. For the difference (“percent” and
  “diff”) the mean over two comparison periods (“first” and “last”) is
  calculated. The “total” periods mean can be calculated and plotted as well.
  By default [“first”, “last”, “diff”, “total”, “percent”]

mdtol: float, optional (default: 0.5)
: Tolerance for missing data in multi-model mean calculation. 0 means no
  missing data is allowed. At 1 the mean is calculated if any data is
  available.

plot_kwargs: dict, optional
: Kwargs passed to diag_scripts.shared.plot.global_contourf function.
  The “cbar_label” parameter is formatted with meta keys. So placeholders
  like “{short_name}” or “{units}” can be used.
  By default {“cmap”: “RdYlBu”, “extend”: “both”}

plot_kwargs_overwrite: list, optional (default: [])
: List of plot_kwargs dicts for specific metrics (diff, first, latest, total)
  and group_by values (ie. pr, tas for group_by: short_name).
  group and metric can either be strings or lists of strings to be
  applied to all matching plots. Leave any of them empty to apply to all.
  All other given keys are applied to the plot_kwargs dict for this plot.
  Settings will be applied in order of the list, so later entries can
  overwrite previous ones.

plot_mmm: bool, optional (default: True)
: Calculate and plot the average over all datasets.

plot_models: bool, optional (default: True)
: Plot maps for each dataset.

strip_plots: bool, optional (default: False)
: Removes titles, margins and colorbars from plots (to use them in panels).

titles: dict, optional
: Customize plot titles for different metrics. Possible dict keys are
  “first”, “last”, “trend”, “diff”, “total”, “percent”. The values are
  formatted using meta data. Placeholders like “{short_name}” can be used.
  By default {“first”: “Mean Historical”, “last”: “Mean Future”,
  “trend”: “Future - Historical”, “diff”: “Future - Historical”,
  “total”: “Mean Full Period”, “percent”: “Relative Change”}.
