Update and combine drought diagnostics and recipes (#3907)

Co-authored-by: Bettina Gier <[email protected]>

Author: lukruh

esmvaltool/diag_scripts/droughtindex/diag_save_spi.R renamed to archive/legacy_diag_scripts/droughtindex/diag_save_spi.R

@@ -0,0 +1,19 @@
+
+.. _api.esmvaltool.diag_scripts.droughts:
+
+Drought Diagnostics
+===================
+
+The droughts module contains diagnostics for calculation and plotting of drought
+indices and metrics. A general overview is given on the
+:ref:`Droughts documentation page <recipes_droughts>`.
+
+
+Diagnostic scripts
+------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   esmvaltool.diag_scripts.droughts/collect_drought
+   esmvaltool.diag_scripts.droughts/diffmap

esmvaltool/diag_scripts/droughtindex/diag_spei.R renamed to archive/legacy_diag_scripts/droughtindex/diag_spei.R

@@ -0,0 +1,10 @@
+
+.. _api.esmvaltool.diag_scripts.droughts.collect_drought:
+
+Drought Metrics following Martin (2018)
+=======================================
+
+.. automodule:: esmvaltool.diag_scripts.droughts.collect_drought
+   :no-members:
+   :no-inherited-members:
+   :no-show-inheritance:

esmvaltool/diag_scripts/droughtindex/diag_spi.R renamed to archive/legacy_diag_scripts/droughtindex/diag_spi.R

@@ -0,0 +1,10 @@
+
+.. _api.esmvaltool.diag_scripts.droughts.diffmap:
+
+Difference Maps
+===============
+
+.. automodule:: esmvaltool.diag_scripts.droughts.diffmap
+   :no-members:
+   :no-inherited-members:
+   :no-show-inheritance:

esmvaltool/recipes/recipe_spei.yml renamed to archive/legacy_recipes/recipe_spei.yml

@@ -23,6 +23,7 @@ Diagnostic Scripts
 .. toctree::
    :maxdepth: 1
 
+   esmvaltool.diag_scripts.droughts
    esmvaltool.diag_scripts.emergent_constraints
    esmvaltool.diag_scripts.monitor
    esmvaltool.diag_scripts.ocean

doc/sphinx/source/api/esmvaltool.diag_scripts.droughts.rst

@@ -19,34 +19,37 @@ user defined number of days.
 Available recipes and diagnostics
 ---------------------------------
 
-Recipes are stored in recipes/
+Recipes are stored in recipes/droughts/
 
-    * recipe_consecdrydays.yml
+* recipe_cdd.yml
 
-Diagnostics are stored in diag_scripts/droughtindex/
+Diagnostics are stored in diag_scripts/droughts/
 
-    * diag_cdd.py: calculates the longest period of consecutive dry days, and
-      the frequency of dry day periods longer than a user defined length
+* cdd.py: calculates the longest period of consecutive dry days, and
+  the frequency of dry day periods longer than a user defined length
 
 
 User settings in recipe
 -----------------------
 
-#. Script diag_cdd.py
+Script cdd.py
+~~~~~~~~~~~~~~~~~~
 
-   *Required settings (script)*
+plim: float
+    limit for a day to be considered dry [mm/day]
 
-   * plim: limit for a day to be considered dry [mm/day]
+frlim: int
+    the shortest number of consecutive dry days for entering statistic on
+    frequency of dry periods.
 
-   * frlim: the shortest number of consecutive dry days for entering statistic on frequency of dry periods.
+Under ``plot``:
 
-   *Optional settings (script)*
+cmap: str, optional
+    the name of a colormap. cmocean colormaps are also supported.
 
-   Under ``plot``:
-
-   * cmap: the name of a colormap. cmocean colormaps are also supported.
-
-   * other keyword arguments to :func:`esmvaltool.diag_scripts.shared.plot.global_pcolormesh` can also be supplied.
+other keyword arguments to
+:func:`esmvaltool.diag_scripts.shared.plot.global_pcolormesh` can also be
+supplied.
 
 Variables
 ---------

doc/sphinx/source/api/esmvaltool.diag_scripts.droughts/collect_drought.rst

@@ -0,0 +1,92 @@
+.. _recipes_martin18grl:
+
+Drought characteristics following Martin (2018)
+===============================================
+
+Overview
+--------
+
+Following `Martin (2018)`_ drought characteristics are calculated based on the
+standard precipitation index (SPI), see `Mckee et al. (1993)`_.
+These characteristics are frequency, average duration, SPI index and severity
+index of drought events.
+
+.. _`Martin (2018)`: https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2018GL079807
+.. _`Mckee et al. (1993)`: https://climate.colostate.edu/pdfs/relationshipofdroughtfrequency.pdf
+
+
+Available recipes and diagnostics
+---------------------------------
+
+Recipes are stored in ``recipes/droughts/``
+
+   * recipe_martin18grl.yml
+
+Diagnostics are stored in ``diag_scripts/droughts/``
+
+   * :ref:`droughts/spei.R <recipes_spei>`
+   * :ref:`droughts/collect_drought.py <api.esmvaltool.diag_scripts.droughts.collect_drought>`
+
+Functions for metric calculation, plots and utility can be found in
+``droughts/collect_drought_func.py``.
+
+User settings in recipe
+-----------------------
+
+The recipe calculates SPI for two different time periods. The first part
+compares CMIP5 models with the CRU observational dataset. The second part
+compares the last 51 years of the 21st century with the historical period
+(1950-2000) for the RCP8.5 scenario.
+
+The recipe can be run with different CMIP5 and CMIP6 models and one
+observational or reanalysis data set. The latter is specified as
+``reference_dataset`` in the recipe.
+
+The distribution (``distribution: Gamma``) and the representative time scale
+(``smooth_month: 6``) can be changed by the user too. A complete list of
+settings and their description can be found in the
+:ref:`SPEI recipe <recipes_spei>` and
+:ref:`Collect drought API documentation <api.esmvaltool.diag_scripts.droughts.collect_drought>`.
+
+
+Variables
+---------
+
+* *pr* (atmos, monthly, longitude, latitude, time)
+
+
+Observations and reformat scripts
+---------------------------------
+
+*None*
+
+
+References
+----------
+
+- Martin, E.R. (2018). Future Projections of Global Pluvial and Drought Event
+  Characteristics. Geophysical Research Letters, 45, 11913-11920.
+- McKee, T. B., Doesken, N. J., & Kleist, J. (1993). The relationship of drought
+  frequency and duration to time scales. In Proceedings of the 8th Conference on
+  Applied Climatology (Vol. 17, No. 22, pp. 179-183). Boston, MA: American
+  Meteorological Society.
+
+Example plots
+-------------
+
+.. _martin18grl_fig1:
+.. figure:: /recipes/figures/droughtindex/martin18grl_fig1.png
+   :align: center
+   :width: 80%
+
+   Global map of the percentage difference between multi-model mean of 15 CMIP
+   models and the CRU data for the number of drought events [%] based on SPI.
+
+.. _martin18grl_fig2:
+.. figure:: /recipes/figures/droughtindex/martin18grl_fig2.png
+   :align: center
+   :width: 80%
+
+   Global map of the percentage difference between multi-model mean for RCP8.5
+   scenarios (2050-2100) runs and historical data (1950-2000) for 15 CMIP models
+   for the number of drought events [%] based on SPI.