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

# Calculating and displaying multiple representations of the CH4 lifetime

Lifetime diagnostic to show multiple datasets in one plot.

## Description

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

Input data needs to be 4D (time,
air_pressure/atmosphere_hybrid_sigma_pressure_coordinate, latitude, longitude).

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

Currently supported plot types (use the option `plots` to specify them):
: - Time series (plot type `timeseries`): all datasets are plotted in one
    single figure.

## Author

Franziska Winterstein (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()`](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.figure.html#matplotlib.pyplot.figure). By
  default, uses `constrained_layout: true`.

m_air: float, optional (default: 28.970)
: Molar mass of air in g/mol.

molarmass: float
: Molar mass of reactant in g/mol.

oxidant: dict
: Oxidant reaction rates for chemical species, e.g., {“oh”: {“A”: 1.85e-20,
  “ER”: 987.0, “b”: 2.82}}.

plots: dict, optional
: Plot types plotted by this diagnostic (see list above). Dictionary keys
  must be `timeseries`.
  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
  [Output](https://docs.esmvaltool.org/projects/ESMValCore/en/latest/quickstart/output.html#outputdata)).

reactant: str
: Name of reactant, e.g., “CH4”.

regions: list of str, optional (default: [“TROP”])
: Regions considered for line plots. Currently, only “TROP” (troposphere) and
  “STRA” (stratosphere) are supported.

savefig_kwargs: dict, optional
: Optional keyword arguments for [`matplotlib.pyplot.savefig()`](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.savefig.html#matplotlib.pyplot.savefig). By
  default, uses `bbox_inches: tight, dpi: 300, orientation: landscape`.

seaborn_settings: dict, optional
: Options for [`seaborn.set_theme()`](https://seaborn.pydata.org/generated/seaborn.set_theme.html#seaborn.set_theme) (affects all plots). By default, uses
  `style: ticks`.

units: str, optional (default: “years”)
: Target units of the lifetime.

weight_type: str
: Type of weighting. If “mass CH4”, use CH4 mass as weights. Otherwise, use
  equal weights.

## Configuration options for plot type `timeseries`

annual_mean: str, optional (default: False)
: Optional switch to turn on annual means to be displayed  ‘only’ or
  additional ‘both’ to the original timeseries. If not set or set to
  `False` only the original timeseries is shown.

annual_mean_kwargs: dict, optional
: Optional keyword arguments for [`iris.plot.plot()`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.plot.html#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.

by_timestep: bool, optional (default: False)
: Calculate lifetime for each time step individually. Slower, but less
  memory-intensive.

display_mean: bool, optional (default: False)
: Show mean over entire period in plot label.

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.

legend_kwargs: dict, optional
: Optional keyword arguments for [`matplotlib.pyplot.legend()`](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.legend.html#matplotlib.pyplot.legend). Use
  `legend_kwargs: false` to not show legends.

plot_kwargs: dict, optional
: Optional keyword arguments for [`iris.plot.plot()`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.plot.html#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()`](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.plot.html#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`](https://matplotlib.org/stable/api/pyplot_summary.html#module-matplotlib.pyplot). Dictionary keys
  are functions of [`matplotlib.pyplot`](https://matplotlib.org/stable/api/pyplot_summary.html#module-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]`.

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