Add documentation for Wheeler-Kiladis diagnostic

Author: ApexCapybara

.gitignore

@@ -56,6 +56,7 @@ __pycache__/
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.
 *.manifest
 *.spec
+
 # Installer logs
 pip-log.txt
 pip-delete-this-directory.txt
@@ -73,6 +74,7 @@ coverage.xml
 
 # Jupyter Notebook
 .ipynb_checkpoints
+
 *.tmp
 *.orig
 /c

doc/sphinx/source/recipes/figures/wheeler_kiladis/ERA5_pr_wk_normalized_example.png

@@ -66,6 +66,7 @@ Atmosphere
    recipe_aod_aeronet_assess
    recipe_surface_trace_gas
    recipe_weathertyping
+   recipe_wheeler_kiladis_diagnostic
 
 Climate metrics
 ^^^^^^^^^^^^^^^

doc/sphinx/source/recipes/figures/wheeler_kiladis/MPI-ESM1-2-LR_rlut_wk_normalized_example.png

@@ -0,0 +1,131 @@
+.. _recipe_wheeler_kiladis_diagnostic:
+
+Wheeler-Kiladis tropical wave spectra
+=====================================
+
+Overview
+--------
+
+This recipe computes normalized Wheeler-Kiladis wavenumber-frequency
+spectra for tropical precipitation and outgoing longwave radiation.
+
+The diagnostic is intended to evaluate tropical wave variability,
+including Kelvin waves, equatorial Rossby waves, and broad intraseasonal
+variability such as the Madden-Julian Oscillation.
+
+The recipe uses standard ESMValTool preprocessors to convert units,
+compute daily means, extract the tropical belt between 15S and 15N, and
+regrid the data to a regular latitude-longitude grid. The diagnostic then
+computes a cosine-latitude-weighted equatorial mean, removes leap days,
+removes the time mean, linear trend, and annual harmonics, optionally
+removes the zonal mean, computes two-dimensional Fourier spectra in time
+and longitude, estimates a smoothed background spectrum, and plots
+normalized spectra with optional shallow-water dispersion curves.
+
+The diagnostic saves raw, background, and normalized Wheeler-Kiladis
+spectra as NetCDF files and records provenance information for both data
+outputs and figures.
+
+Available recipes and diagnostics
+---------------------------------
+
+Recipes are stored in ``esmvaltool/recipes/``:
+
+    * ``recipe_wheeler_kiladis_diagnostic.yml``
+
+Diagnostics are stored in ``esmvaltool/diag_scripts/wheeler_kiladis/``:
+
+    * ``wheeler_kiladis.py``: ESMValTool wrapper for running the
+      Wheeler-Kiladis diagnostic.
+    * ``spectra.py``: utilities for preparing equatorial fields and
+      computing wavenumber-frequency spectra.
+    * ``plot.py``: plotting utilities for normalized Wheeler-Kiladis
+      spectra and theoretical dispersion curves.
+
+User settings in recipe
+-----------------------
+
+#. Script ``wheeler_kiladis/wheeler_kiladis.py``
+
+   *Optional settings for script*
+
+   * ``annual_harmonics``: Number of annual harmonics removed during
+     seasonal-cycle correction. Default: 3.
+
+   * ``remove_zonal_mean``: If ``True``, remove the zonal mean before
+     the wavenumber-frequency transform. This emphasizes propagating
+     equatorial disturbances. Default: ``True``.
+
+   * ``segment_length``: Length of each spectral segment in days.
+     Default: 180.
+
+   * ``segment_overlap``: Overlap between consecutive spectral segments
+     in days. Default: 90.
+
+   * ``sampling_frequency_per_day``: Sampling frequency of the input
+     data in samples per day. For daily data, this should be 1.0.
+     Default: 1.0.
+
+   * ``sigma_freq``: Gaussian smoothing width in the frequency direction
+     used to estimate the background spectrum. Default: 4.0.
+
+   * ``sigma_wn``: Gaussian smoothing width in the zonal-wavenumber
+     direction used to estimate the background spectrum. Default: 4.0.
+
+   * ``max_wavenumber``: Maximum zonal wavenumber shown in the plot.
+     Default: 15.
+
+   * ``max_frequency``: Maximum frequency shown in the plot in cycles
+     per day. Default: 0.5.
+
+   * ``period_ticks``: Periods in days shown as labels on the frequency
+     axis. Default: ``[2, 3, 5, 10, 20, 30, 60, 100]``.
+
+   * ``equivalent_depths``: Equivalent depths in metres used to draw
+     theoretical shallow-water dispersion curves. Default:
+     ``[8, 12, 25, 50]``.
+
+   * ``show_dispersion``: If ``True``, overlay theoretical Kelvin and
+     equatorial Rossby wave dispersion curves. Default: ``True``.
+
+   * ``mask_zero_wavenumber``: If ``True``, mask the
+     zonal-wavenumber-zero column in the normalized spectrum plot. This
+     is useful when the zonal mean has been removed. Default: ``True``.
+
+Variables
+---------
+
+* pr (atmos, daily, longitude, latitude, time)
+* rlut (atmos, daily, longitude, latitude, time)
+
+Example plots
+-------------
+
+.. _wk_era5_pr_example:
+.. figure:: /recipes/figures/wheeler_kiladis/ERA5_pr_wk_normalized_example.png
+   :align: center
+
+   Normalized Wheeler-Kiladis spectrum for ERA5 precipitation.
+
+.. _wk_persiann_cdr_pr_example:
+.. figure:: /recipes/figures/wheeler_kiladis/PERSIANN-CDR_pr_wk_normalized_example.png
+   :align: center
+
+   Normalized Wheeler-Kiladis spectrum for PERSIANN-CDR precipitation.
+
+.. _wk_mpi_esm1_2_lr_rlut_example:
+.. figure:: /recipes/figures/wheeler_kiladis/MPI-ESM1-2-LR_rlut_wk_normalized_example.png
+   :align: center
+
+   Normalized Wheeler-Kiladis spectrum for MPI-ESM1-2-LR outgoing
+   longwave radiation.
+
+References
+----------
+
+* Wheeler, M. C. and Kiladis, G. N. (1999): Convectively Coupled
+  Equatorial Waves: Analysis of Clouds and Temperature in the
+  Wavenumber-Frequency Domain.
+* Kiladis, G. N. et al. (2009): Convectively Coupled Equatorial Waves.
+* Hannah et al. (2020): Evaluation of tropical variability using
+  Wheeler-Kiladis-type spectra.

doc/sphinx/source/recipes/figures/wheeler_kiladis/PERSIANN-CDR_pr_wk_normalized_example.png

@@ -31,59 +31,63 @@
 remove_zonal_mean : bool, optional
     Remove the zonal mean prior to spectral analysis. This is
     commonly done in Wheeler-Kiladis diagnostics to emphasize
-    propagating equatorial wave signals.
+    propagating equatorial wave signals. Default: True.
 
 segment_length : int, optional
     Length of each spectral segment [days]. The default value of
-    180 days is widely used in Wheeler-Kiladis analyses and
+    180 days is commonly used in Wheeler-Kiladis analyses and
     provides a balance between frequency resolution and statistical
     sampling.
 
 segment_overlap : int, optional
-    Overlap between consecutive segments [days]. A value of
-    90 days corresponds to 50% overlap and increases the number
+    Overlap between consecutive segments [days]. The default value
+    of 90 days corresponds to 50% overlap and increases the number
     of spectra contributing to the ensemble average.
 
 sampling_frequency_per_day : float, optional
     Sampling frequency of the input data [samples day^-1].
-    Daily data correspond to a value of 1.0.
+    The default value is 1.0, corresponding to daily data.
 
 sigma_freq : float, optional
     Gaussian smoothing width in the frequency direction used
     for background-spectrum estimation. The default value of
-    4.0 provides a smoothly varying background spectrum suitable
-    for normalization.
+    4.0 provides sufficient smoothing to represent the broad
+    spectral background while retaining its large-scale structure.
 
 sigma_wn : float, optional
     Gaussian smoothing width in the zonal-wavenumber direction
     used for background-spectrum estimation. The default value
-    of 4.0 provides adequate smoothing while preserving the
-    large-scale spectral envelope.
+    of 4.0 provides a smoothly varying background spectrum
+    suitable for normalization while preserving the large-scale
+    spectral envelope.
 
 max_wavenumber : int, optional
-    Maximum zonal wavenumber shown in diagnostic plots.
+    Maximum zonal wavenumber displayed in diagnostic plots.
+    Default: 15.
 
 max_frequency : float, optional
-    Maximum frequency shown in diagnostic plots [cycles day^-1].
+    Maximum frequency displayed in diagnostic plots
+    [cycles day^-1]. Default: 0.5.
 
 period_ticks : list of int, optional
-    Period values [days] displayed on the frequency axis of the
-    diagnostic plots.
+    Periods [days] shown as labels on the frequency axis.
+    Default: [2, 3, 5, 10, 20, 30, 60, 100].
 
 equivalent_depths : list of float, optional
     Equivalent depths [m] used to draw theoretical shallow-water
-    dispersion curves. Typical values are 8, 12, 25 and 50 m,
-    which span the range commonly associated with convectively
-    coupled equatorial waves.
+    dispersion curves. The default values [8, 12, 25, 50] span
+    the range commonly associated with convectively coupled
+    equatorial waves.
 
 show_dispersion : bool, optional
     If True, overlay theoretical Kelvin and equatorial Rossby
-    wave dispersion curves on the normalized WK spectrum.
+    wave dispersion curves on the normalized Wheeler-Kiladis
+    spectrum. Default: True.
 
 mask_zero_wavenumber : bool, optional
-    Mask the zonal wavenumber zero column in the normalized
-    spectrum plot. This is often useful when the zonal mean
-    has been removed.
+    If True, mask the zonal-wavenumber-zero column in the
+    normalized spectrum plot. This is often useful when the
+    zonal mean has been removed. Default: True.
 
 Outputs
 -------
@@ -169,9 +173,9 @@ def _process_regular_dataset(cfg, attrs):
 
     raw, background, normalized = compute_wk_spectra(
         data_anom,
-        segment_length=cfg["segment_length"],
-        segment_overlap=cfg["segment_overlap"],
-        samples_per_day=cfg["sampling_frequency_per_day"],
+        segment_length=cfg.get("segment_length", 180),
+        segment_overlap=cfg.get("segment_overlap", 90),
+        samples_per_day=cfg.get("sampling_frequency_per_day", 1.0),
         sigma_freq=cfg.get("sigma_freq", 4.0),
         sigma_wn=cfg.get("sigma_wn", 4.0),
     )
@@ -198,37 +202,36 @@ def _make_method_caption(cfg, attrs, label):
     """Create a method caption describing WK settings."""
     dataset = attrs.get("dataset", label)
 
-    start_year = attrs.get(
-        "start_year",
-        cfg.get("start_year", "unknown"),
-    )
+    start_year = attrs.get("start_year")
+    end_year = attrs.get("end_year")
 
-    end_year = attrs.get(
-        "end_year",
-        cfg.get("end_year", "unknown"),
-    )
+    caption = f"Wheeler-Kiladis spectrum for {dataset}. "
+
+    if start_year is not None and end_year is not None:
+        caption += f"Period: {start_year}-{end_year}. "
 
-    caption = (
-        f"Wheeler-Kiladis spectrum for {dataset}. "
-        f"Period: {start_year}-{end_year}. "
+    caption += (
         "Region: 15S-15N, all longitudes. "
         "Data are converted to daily means and equatorially averaged. "
         f"Anomalies are computed after removing the time mean, linear trend, "
         f"and the first {cfg.get('annual_harmonics', 3)} annual harmonics. "
     )
 
     if cfg.get("remove_zonal_mean", True):
-        caption += "The zonal mean is removed before the wavenumber-frequency transform. "
+        caption += (
+            "The zonal mean is removed before the "
+            "wavenumber-frequency transform. "
+        )
 
     caption += (
-        f"Spectra are computed using {cfg['segment_length']}-day windows "
-        f"with {cfg['segment_overlap']}-day overlap. "
-        f"Background normalization uses Gaussian smoothing with "
+        f"Spectra are computed using "
+        f"{cfg.get('segment_length', 180)}-day windows "
+        f"with {cfg.get('segment_overlap', 90)}-day overlap. "
+        "Background normalization uses Gaussian smoothing with "
         f"sigma_freq={cfg.get('sigma_freq', 4.0)} and "
         f"sigma_wn={cfg.get('sigma_wn', 4.0)}. "
         "Positive zonal wavenumber denotes eastward propagation."
     )
-
     return caption
 
 

doc/sphinx/source/recipes/index.rst

@@ -32,11 +32,6 @@ documentation:
 YEARS: &years
   timerange: 2001/2002
 
-SCRIPT_YEARS: &script_years
-  start_year: 2001
-  end_year: 2002
-
-
 preprocessors:
   wk_tropics_pr:
     convert_units:
@@ -74,8 +69,6 @@ preprocessors:
       scheme: linear
 
 
-
-
 diagnostics:
 
   wheeler_kiladis_pr:
@@ -111,18 +104,13 @@ diagnostics:
       main:
         script: wheeler_kiladis/wheeler_kiladis.py
 
-        variable: pr
-
-        latitude_bounds: [-15., 15.]
-        lon_resolution: 2.5
-
         segment_length: 180
         segment_overlap: 90
         sampling_frequency_per_day: 1.0
 
         annual_harmonics: 3
         remove_zonal_mean: true
-        mask_zero_wavenumber: true
+        mask_zero_wavenumber: false
 
         sigma_freq: 4.0
         sigma_wn: 4.0
@@ -133,9 +121,6 @@ diagnostics:
         equivalent_depths: [8, 12, 25, 50]
         show_dispersion: true
 
-        normalized_vmin: 0.0
-        normalized_vmax: 4.0
-
 
   wheeler_kiladis_rlut:
     title: Wheeler-Kiladis spectra of tropical outgoing longwave radiation
@@ -168,11 +153,6 @@ diagnostics:
       main:
         script: wheeler_kiladis/wheeler_kiladis.py
 
-        variable: rlut
-
-        latitude_bounds: [-15., 15.]
-        lon_resolution: 2.5
-
         segment_length: 180
         segment_overlap: 90
         sampling_frequency_per_day: 1.0
@@ -189,6 +169,3 @@ diagnostics:
         period_ticks: [2, 3, 5, 10, 20, 30, 60, 100]
         equivalent_depths: [8, 12, 25, 50]
         show_dispersion: true
-
-        normalized_vmin: 0.0
-        normalized_vmax: 4.0