Lindenlaub25 recipes

doc/sphinx/source/recipes/droughts/recipe_consecdrydays.rst

@@ -65,4 +65,5 @@ Example plots
    :align:   center
    :width:   14cm
 
-   Example of the number of occurrences with consecutive dry days of more than five days in the period 2001 to 2002 for the CMIP5 model bcc-csm1-1-m.
+   Example of the number of occurrences with consecutive dry days of more than
+   five days in the period 2001 to 2002 for the CMIP5 model bcc-csm1-1-m.

doc/sphinx/source/recipes/droughts/recipe_lindenlaub25.rst

@@ -0,0 +1,81 @@
+
+.. _recipes_martin18grl:
+
+Agricultural Droughts in CMIP6 Future Projections
+=================================================
+
+Overview
+--------
+
+The two recipes presented here evaulate historical simulations of 18 CMIP6
+models and analyse their projections for three different future pathways.
+The results are published in Lindenlaub (2025).
+
+
+Available recipes and diagnostics
+---------------------------------
+
+Recipes are stored in ``recipes/droughts/``
+
+   * recipe_lindenlaub25_historical.yml
+   * recipe_lindenlaub25_scenarios.yml
+
+Diagnostics used by this recipes:
+
+   * droughts/pet.R
+   * droughts/spei.R
+   * :ref:`droughts/diffmap.py <api.esmvaltool.diag_scripts.droughts.diffmap>`
+   * :ref:`droughts/distribution.py <api.esmvaltool.diag_scripts.droughts.distribution>`
+   * :ref:`droughts/event_area_timeseries.py <api.esmvaltool.diag_scripts.droughts.event_area_timeseries>`
+   * :ref:`droughts/pattern_correlation.py <api.esmvaltool.diag_scripts.droughts.pattern_correlation>`
+   * :ref:`droughts/timeseries_scenarios.py <api.esmvaltool.diag_scripts.droughts.timeseries_scenarios>`
+   * :ref:`droughts/regional_hexagons.py <api.esmvaltool.diag_scripts.droughts.regional_hexagons>`
+
+Data
+----
+
+Soil moisture is evaluated and discussed, but not required for PET and SPEI
+calculation.
+``tasmin``, ``tasmax``, ``sfcWind``, ``ps``, ``rsds`` are used to approximate
+``evspsblpot`` for ERA5 and 18 CMIP6 datasets.
+``SPEI`` is calculated from ``evspsblpot`` and ``pr``.
+
+
+TODO: ERA5 native on the fly or cmorizer?
+
+Reference Data (ERA5, CDS-SM, CRU) can be downloaded and cmorized by the
+esmvaltool executing the `data` command:
+
+```
+esmvaltool data download ERA5 pr
+esmvaltool data format ERA5 pr
+```
+
+``tasmin`` and ``tasmax`` are not directly available in the monthly averaged data
+product. The download script `diag_scripts/droughts/download_era5_tasminmax.py`
+can be used to download and preprocess the data based on the
+``minimum_2m_temperature_since_previous_post_processing`` and
+``maximum_2m_temperature_since_previous_post_processing`` variables from ERA5
+daily data on single levels. The output files are compatible with the esmvaltool
+and can be copied into the ``native6/Tier3/ERA5/v1/mon/``
+directory. Using the esmvaltool environment ensures that all required libraries
+are available. The script can be run with the following command:
+
+```
+python diag_scripts/droughts/download_era5_tasminmax.py
+```
+
+For more options use the ``--help`` flag.
+
+The CMIP6 data can be downloaded automatically by the ESMValTool. Just ensure
+that ``esgf_download`` is set to ``True`` or ``when_missing`` in the
+user configuration.
+
+Figures
+-------
+
+References
+----------
+
+* Lindenlaub, L. (2025). Agricultural Droughts in CMIP6 Future Projections.
+  Journal of Climate, 38(1), 1-15. https://doi.org/10.1029/2025JC012345

esmvaltool/diag_scripts/droughts/diffmap.py

@@ -74,7 +74,6 @@
 from __future__ import annotations
 
 import logging
-import os
 from collections import defaultdict
 from pathlib import Path
 
@@ -210,7 +209,10 @@ def plot(
     basename: str,
     kwargs: dict | None = None,
 ) -> str:
-    """Plot map using diag_scripts.shared module."""
+    """Plot map using diag_scripts.shared module.
+
+    Returns the plot filename.
+    """
     plotfile = get_plot_filename(basename, cfg)
     plot_kwargs = cfg.get("plot_kwargs", {}).copy()
     if kwargs is not None:
@@ -231,7 +233,7 @@ def plot(
     add_cyclic_point(cube.data, cube.coord("longitude").points)
     mapplot = global_contourf(cube, **plot_kwargs)
     if cfg.get("clip_land", False):
-        plt.gca().set_extent((220, 170, -55, 90))
+        plt.gca().set_extent((220, 170, -55, 90))  # type: ignore[attr-defined]
     plt.title(meta.get("title", basename))
     if cfg.get("strip_plots", False):
         plt.gca().set_title(None)
@@ -285,15 +287,15 @@ def calculate_diff(cfg, meta, mm_data, output_meta, group) -> None:
         cube = pp.extract_time(
             cube, cfg["start_year"], 1, 1, cfg["end_year"], 12, 31
         )
-    dtime = cfg.get("comparison_period", 10) * 12
-    cubes = {}
+    dtime = cfg["comparison_period"] * 12
+    cubes: dict[Cube] = {}
     cubes["total"] = cube.collapsed("time", MEAN)
     do_metrics = cfg.get("metrics", METRICS)
     norm = (
         int(meta["end_year"])
         - int(meta["start_year"])
         + 1  # count full end year
-        - cfg.get("comparison_period", 10)  # decades center to center
+        - cfg["comparison_period"]  # decades center to center
     ) / 10
     cubes["first"] = cube[0:dtime].collapsed("time", MEAN)
     cubes["last"] = cube[-dtime:].collapsed("time", MEAN)
@@ -335,26 +337,22 @@ def calculate_diff(cfg, meta, mm_data, output_meta, group) -> None:
 def calculate_mmm(cfg, meta, mm_data, output_meta, group) -> None:
     """Calculate multi-model mean for a given metric."""
     for metric in cfg.get("metrics", METRICS):
-        drop = cfg.get("dropcoords", ["time", "height"])
         meta = meta.copy()  # don't modify meta in place:
-        meta["dataset"] = "MMM"
         meta["diffmap_metric"] = metric
         basename = cfg["basename"].format(**meta)
-        mmm, _ = utils.mmm(
-            mm_data[metric],
-            dropcoords=drop,
-            dropmethods=metric != "diff",
-            mdtol=cfg.get("mdtol", 0.3),
+        results = pp.multi_model_statistics(
+            mm_data[metric], "overlap", ["mean"], ignore_scalar_coords=True
         )
+        mmm = results["mean"]
         meta["title"] = f"Multi-model Mean ({cfg['titles'][metric]})"
         if cfg.get("plot_mmm", True):
             plot_kwargs = cfg.get("plot_kwargs", {}).copy()
             overwrites = cfg.get("plot_kwargs_overwrite", [])
             apply_plot_kwargs_overwrite(plot_kwargs, overwrites, metric, group)
-            plotfile = plot(cfg, meta, mmm, basename, kwargs=plot_kwargs)
+            plot_file = plot(cfg, meta, mmm, basename, kwargs=plot_kwargs)
             prov = _get_provenance(cfg, meta)
             prov["ancestors"] = meta["ancestors"]
-            utils.log_provenance(cfg, plotfile, prov)
+            utils.log_provenance(cfg, plot_file, prov)
         if cfg.get("save_mmm", True):
             work_file = str(Path(cfg["work_dir"]) / f"{basename}.nc")
             meta["filename"] = work_file
@@ -365,8 +363,8 @@ def calculate_mmm(cfg, meta, mm_data, output_meta, group) -> None:
 
 def set_defaults(cfg: dict) -> None:
     """Update cfg with default values from diffmap.yml in place."""
-    config_fpath = os.path.realpath(__file__)[:-3] + ".yml"
-    with open(config_fpath, encoding="utf-8") as config_file:
+    config_fpath = Path(__file__).with_suffix(".yml")
+    with config_fpath.open() as config_file:
         defaults = yaml.safe_load(config_file)
     for key, val in defaults.items():
         cfg.setdefault(key, val)