<a id="recipes-ecs"></a>

# Equilibrium climate sensitivity

## Overview

Equilibrium climate sensitivity is defined as the change in global mean
temperature as a result of a doubling of the atmospheric CO<sub>2</sub>
concentration compared to pre-industrial times after the climate system has
reached a new equilibrium. This recipe uses a regression method based on
[Gregory et al. (2004)](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2003GL018747) to calculate it for several CMIP models.

## Available recipes and diagnostics

Recipes are stored in recipes/

* recipe_ecs.yml
* ref/recipe_ref_ecs.yml

Diagnostics are stored in diag_scripts/

* climate_metrics/ecs.py
* climate_metrics/create_barplot.py
* climate_metrics/create_scatterplot.py

## User settings in recipe

* Preprocessor
  > * `area_statistics` (*operation: mean*): Calculate global mean.

<a id="ecs-py"></a>
* Script climate_metrics/ecs.py
  > * `calculate_mmm`, *bool*, optional (default: `True`): Calculate
  >   multi-model mean ECS.
  > * `complex_gregory_plot`, *bool*, optional (default: `False`): Plot
  >   complex Gregory plot (also add response for first `sep_year` years and
  >   last 150 - `sep_year` years, default: `sep_year=20`) if `True`.
  > * `output_attributes`, *dict*, optional: Write additional attributes to
  >   netcdf files.
  > * `read_external_file`, *str*, optional: Read ECS and feedback parameters
  >   from external file. The path can be given relative to this diagnostic
  >   script or as absolute path.
  > * `savefig_kwargs`, *dict*, optional: Keyword arguments for
  >   [`matplotlib.pyplot.savefig()`](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.savefig.html#matplotlib.pyplot.savefig).
  > * `seaborn_settings`, *dict*, optional: Options for
  >   [`seaborn.set_theme()`](https://seaborn.pydata.org/generated/seaborn.set_theme.html#seaborn.set_theme) (affects all plots).
  > * `sep_year`, *int*, optional (default: `20`): Year to separate
  >   regressions of complex Gregory plot. Only effective if
  >   `complex_gregory_plot` is `True`.
  > * `x_lim`, *list of float*, optional (default: `[1.5, 6.0]`): Plot
  >   limits for X axis of Gregory regression plot (T).
  > * `y_lim`, *list of float*, optional (default: `[0.5, 3.5]`): Plot
  >   limits for Y axis of Gregory regression plot (N).

<a id="create-barplot-py"></a>
* Script climate_metrics/create_barplot.py
  > * `add_mean`, *str*, optional: Add a bar representing the mean for each
  >   class.
  > * `label_attribute`, *str*, optional: Cube attribute which is used as
  >   label for different input files.
  > * `order`, *list of str*, optional: Specify the order of the different
  >   classes in the barplot by giving the `label`, makes most sense when
  >   combined with `label_attribute`.
  > * `patterns`, *list of str*, optional: Patterns to filter list of input
  >   data.
  > * `savefig_kwargs`, *dict*, optional: Keyword arguments for
  >   [`matplotlib.pyplot.savefig()`](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.savefig.html#matplotlib.pyplot.savefig).
  > * `seaborn_settings`, *dict*, optional: Options for
  >   [`seaborn.set_theme()`](https://seaborn.pydata.org/generated/seaborn.set_theme.html#seaborn.set_theme) (affects all plots).
  > * `sort_ascending`, *bool*, optional (default: `False`): Sort bars in
  >   ascending order.
  > * `sort_descending`, *bool*, optional (default: `False`): Sort bars in
  >   descending order.
  > * `subplots_kwargs`, *dict*, optional: Keyword arguments for
  >   [`matplotlib.pyplot.subplots()`](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.subplots.html#matplotlib.pyplot.subplots).
  > * `value_labels`, *bool*, optional (default: `False`): Label bars with
  >   value of that bar.
  > * `y_range`, *list of float*, optional: Range for the Y axis of the plot.

<a id="create-scatterplot-py"></a>
* Script climate_metrics/create_scatterplot.py
  > * `dataset_style`, *str*, optional: Name of the style file (located in
  >   `esmvaltool.diag_scripts.shared.plot.styles_python`).
  > * `pattern`, *str*, optional: Pattern to filter list of input files.
  > * `seaborn_settings`, *dict*, optional: Options for
  >   [`seaborn.set_theme()`](https://seaborn.pydata.org/generated/seaborn.set_theme.html#seaborn.set_theme) (affects all plots).
  > * `y_range`, *list of float*, optional: Range for the Y axis of the plot.

## Variables

* *rlut* (atmos, monthly, longitude, latitude, time)
* *rsdt* (atmos, monthly, longitude, latitude, time)
* *rsut* (atmos, monthly, longitude, latitude, time)
* *tas* (atmos, monthly, longitude, latitude, time)

## Observations and reformat scripts

*None*

## References

* Gregory, Jonathan M., et al. “A new method for diagnosing radiative forcing
  and climate sensitivity.” Geophysical research letters 31.3 (2004).

## Example plots

<a id="fig-ecs-1"></a>
![image](recipes/figures/ecs/CanESM2.png)
