Wheeler kiladis diagnostic

[ApexCapybara]

Description

This pr adds a new Wheeler-Kiladis diagnostic and recipe for evaluating tropical wave variability in precipitation and outgoing longwave radiation.

The diagnostic computes normalized wavenumber-frequency spectra from daily equatorially averaged fields over 15S-15N. It is designed to diagnose the representation of tropical variability such as Kelvin waves, equatorial Rossby waves, and broad intraseasonal variability such as the Madden-Julian Oscillation (MJO).

The implementation follows the standard Wheeler-Kiladis workflow:

• preprocessing through standard ESMValTool recipe mechanisms,
• unit conversion where needed,
• conversion to daily means,
• extraction of the tropical belt between 15S and 15N,
• regridding to a regular longitude-latitude grid,
• cosine-latitude averaging over the tropical belt,
• removal of leap days,
• removal of the time mean, linear trend, and annual harmonics,
• optional removal of the zonal mean,
• segmentation into overlapping time windows,
• two-dimensional Fourier transform in time and longitude,
• background normalization using smoothed spectral power,
• plotting of normalized Wheeler-Kiladis spectra with equivalent-depth dispersion curves,
• saving of raw, background, and normalized spectra as NetCDF files,
• provenance recording for plots and output data.

The recipe contains two diagnostics:

1. wheeler_kiladis_pr for precipitation.
2. wheeler_kiladis_rlut for outgoing longwave radiation.

This PR also adds Sphinx documentation for the new recipe and diagnostic, including the scientific motivation, preprocessing workflow, diagnostic options, variables, example plots, outputs, and references.

The diagnostic has been tested locally with precipitation and outgoing longwave radiation inputs, including observational/reanalysis and CMIP6 data.

• Closes #issue_number
• • Link to documentation: doc/sphinx/source/recipes/recipe_wheeler_kiladis_diagnostic.rst
    Added a Sphinx documentation page for the Wheeler-Kiladis recipe, including the diagnostic workflow, recipe options, variables, outputs, example plots, and references.

Example figures (one for precipitation (pr) and another for outgoing longwave radiation (rlut):

---

Checklist

It is the responsibility of the author to make sure the pull request is ready to review. The icons indicate whether the item will be subject to the 🛠 Technical or 🧪 Scientific review.

• 🛠 This pull request has a descriptive title
• 🛠 Code is written according to the code quality guidelines
• 🛠 Documentation is available
• 🛠 Tests run successfully
• 🛠 The list of authors is up to date
• 🛠 Any changed dependencies have been added or removed correctly
• 🛠 All checks below this pull request were successful

New or updated recipe/diagnostic

• 🧪 Recipe runs successfully
• 🧪 Recipe is well documented
• 🧪 Figure(s) and data look as expected from literature
• 🛠 Provenance information has been added

New or updated data reformatting script

Not applicable. This pull request does not add a new data reformatting script.

---

Additional notes for reviewers:

• This pull request is intended for scientific and technical review of the new Wheeler-Kiladis diagnostic.
• The recipe currently supports precipitation (pr) and outgoing longwave radiation (rlut).
• The recipe has been run successfully locally.
• Documentation for the recipe and diagnostic has been added under:
  doc/sphinx/source/recipes/recipe_wheeler_kiladis_diagnostic.rst
• Example figures are included in:
  doc/sphinx/source/recipes/figures/wheeler_kiladis/
• The current default settings are intended as a practical first implementation:
  • tropical averaging region: 15S-15N,
  • daily sampling,
  • segment length: 180 days,
  • segment overlap: 90 days,
  • annual harmonics removed: 3,
  • maximum plotted frequency: 0.5 cycles per day,
  • maximum plotted zonal wavenumber: 15.

[CLAassistant]

All committers have signed the CLA.

[schlunma]

Thanks @ApexCapybara, looks great already! Just a couple of comments to make the code simpler. It would be great if you could add documentation to the recipe/diagnostic (e.g., like done in #3155).

If you want, you can also add your name to the CITATION.cff and .zenodo.json to become an official contributor.

Thanks 🚀

[schlunma]

Great! A couple of small comments to clean up. Apart from that it would great if you could add some documentation and update the citation information (if you like), see #4561 (review).

Thanks so much!! 🚀

[ApexCapybara]

#3995 I just became aware of this implementation of the Wheeler-Kiladis diagnostic.

[princekx]

I did manage to run #4561. Please note, #3995 is a direct implementation of https://www.ncl.ucar.edu/Applications/space_time.shtml. One feature I have included in #3995 is the symmetric/Antisymmetric spilt which is not included here. . Perhaps that part can come from #3995. Also the data processing is slightly different with #3995 default window is 96 days (as specified in WK99) with overlap via negative skip (n_day_skip = -65), and uses custom split-cosine taper. #4561 default window is 180 days with 90-day overlap, and applies a Hann window in time.

Calculation of background is treated quite differently between the two. #3995 follows WK99) as closely as possible. Background calculation is important when interpreting the ratio plots.

#3995 produces separate symmetric and antisymmetric raw spectra, background spectrum, and ratio spectra; also log10-transforms raw/background for some outputs and includes extensive plotting/provenance logic while #4561 returns three numerical products directly: raw power, background power, normalized power; plotting is handled elsewhere. The reason we have included the raw spectra is to compare the spectra between models or with obs. We have specified colour palettes and contour intervals to match the NCL implementation for consistent comparison with plots generated in the past.