Cold-Point Tropopause (CTP) diagnostic and sample recipe by aoifemcquaid · Pull Request #4565 · ESMValGroup/ESMValTool

aoifemcquaid · 2026-07-23T16:36:01Z

Summary

This PR adds a new tropical cold-point tropopause (CTP) Hovmoeller diagnostic to ESMValTool. It identifies the CTP as the minimum-temperature level in a configurable pressure range and produces longitude-time and latitude-time Hovmoeller plots of CTP temperature, specific humidity, and relative humidity w.r.t. ice, with CTP pressure shown as filled contours. The recipe runs the diagnostic against ERA5 and CMIP6 data.

Files added/changed

esmvaltool/recipes/recipe_tropical_cpt_hovmoeller.yml — new recipe defining ERA5 (native6) and CMIP6 (MPI-ESM1-2-LR) datasets, monthly ta/hus variables, and the diagnostic script config (pressure/latitude bounds, plot filename prefix, resolution/dpi settings).
esmvaltool/diag_scripts/tropopause/cpt_hovmoeller.py — new diagnostic script implementing the CTP calculation and Hovmoeller plotting (details below).

CTP diagnostic workflow

CTP calculation: for each grid point and time step, the script searches for the minimum temperature between the configured pressure bounds (default 500–10 hPaessure as CTP pressure. It then samples specific humidity at that same level to get CTP specific humidity, and derives CTP relative humidity with respect to from the CTP temperature, specific humidity, an-vapour-pressure-over-ice formula. This reduction happens at full model resolution before any spatial averaging.
Plots produced: for each dataset, the script produces two Hovmoeller views: time-vs-longitude (monthly mean, averaged over the -20°S–20°N tropical band, full longitude range) and time-vs-latitude (monthly mean, restricted to -20°S–20°N, averaged over the full longitude range). Each view produces one standalone figure per variable (temperature, specific humidity, RH over ice), with CTP pressure as f variable as black contour lines. Filenames follow {plot_filename}{dataset}{variable}_{lon|lat}.png (e.g. tropical_cpt_hovmoeller_ERA5_temperature_lon.png), giving 6 figures per dataset (12 total for ERA5+CMIP6).
Other processing: datasets are grouped by the alias metadata facet and processed independently; the script also supports
an optional raw-ICON input pathway (file-pattel preprocessing) that can run alongside preprocessed datasets in the same invocation, used for local ICON testing (see below) but not part of this recipe.

Data included

The recipe uses only ERA5 (project: native6) and CMIP6 (MPI-ESM1-2-LR, historical, r1i1p1f1, gn) — both standard ESMValTool-accessible sources. No local or absolute file paths are included in this recipe. A separate ICON-inclusive variant of this recipe (adding a local-path ICON dataset block) exists outside this repository for local development use only and is not part of this PR.

Testing

Run locally end-to-end with ESMValTool via the repo’s pixi environment (project.toml, pixi.lock; ESMValCore dependency pinned to >=2.14.0, ESMValTool dev version v2.14.0-74-g9ea83ca94 per git describe). The recipe completed successfully and produced all expected output plots for every dataset/variable/plot-type combination (12 PNGs: ERA5 and CMIP6, 3 variables each, lon and lat views). No further validation (e.g. against reference/published CTP climatologies) has been performed.

Link to documentation: https://esmvaltool--4565.org.readthedocs.build/en/4565/recipes/recipe_tropical_cpt_hovmoeller.html

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

To help with the number of pull requests:

🙏 We kindly ask you to review two other open pull requests in this repository

…-ML. Longitude hovmoeller plot with CPT P, T, q and RH_i. RH_i derived from other variables.

- Replace the hard-coded local-path-only ICON recipe with ERA5 (native6) and CMIP6 (MPI-ESM1-2-LR), and preserve the original ICON local-path setup as a separate copy outside the repo. - Split each dataset's single 3-panel figure into standalone, self-contained per-variable plots (temperature, specific humidity, RH over ice), so more compatible with ICONEval as plots can be produced independently - Add a parallel time-vs-latitude Hovmoeller view (restricted to -20°/+20°) alongside the existing time-vs-longitude view for every variable/dataset, doubling figure count with a consistent _lon/_lat filename suffix. - Fix main() so preprocessed datasets (ERA5/CMIP6) and a raw ICON block can both run in the same invocation rather than ICON short-circuiting dataset processing, without altering the underlying CTP calculation logic.

CLAassistant · 2026-07-23T16:36:12Z

All committers have signed the CLA.

schlunma

Thanks @aoifemcquaid, looks great already! Just a couple of comments to make the code simpler.

Please remove all special treatment of ICON data, it should be possible to read this without any special treatment in the diagnostic. If you need the ICON data to be on a regular grid with a regular pressure level Z coordinate, you can use the following preprocessors in the recipe:

preprocessors:
  preprocess_icon:
    custom_order: true
    extract_levels:
      levels: {cmor_table: CMIP6, coordinate: plev19}
      scheme: linear
      coordinate: air_pressure
    regrid:
      target_grid: 2x2
      scheme: area_weighted

It would be great if you could also 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 · 2026-07-24T07:45:20Z

+    - weigel_katja
+    - schlund_manuel


Suggested change

- weigel_katja

- schlund_manuel

- mcquaid_aoife

Looks like this has not been changed

schlunma · 2026-07-24T07:45:37Z

+    - weigel_katja
+    - schlund_manuel
+  maintainer:
+    - unmaintained


Suggested change

- unmaintained

- schlund_manuel

Looks like this has not been changed

…into EVA_convection_diagnostics_CTP

schlunma

Thanks so much @aoifemcquaid for addressing my comments! Looks fantastic, just have a couple of minor comments left.

Approving this from a technical point of view. @ESMValGroup/atmosphere would anyone be able to do a quick scientific review of this? Thanks so much!

schlunma · 2026-08-26T13:53:11Z

Any idea where that 110/120 in the colorbar comes from? It looks like this is a linear scale, so there should not be any label at this position. Same for the other example plot:

EDIT: I guess I found it, see my comment below.

schlunma · 2026-08-26T13:56:46Z

+
+    suffix = "lon" if axis == "X" else "lat"
+    view_desc = "longitude-time" if axis == "X" else "latitude-time"
+    basename = f"{cfg.get('plot_filename', 'tropical_cpt_hovmoeller')}_{_safe_name(dataset_label)}"


Suggested change

basename = f"{cfg.get('plot_filename', 'tropical_cpt_hovmoeller')}_{_safe_name(dataset_label)}"

basename = f"{cfg['plot_filename']}_{_safe_name(dataset_label)}"

You use setdefault before, so this is safe.

schlunma · 2026-08-26T13:59:37Z

+    - weigel_katja
+    - schlund_manuel


Looks like this has not been changed

schlunma · 2026-08-26T13:59:52Z

+    - weigel_katja
+    - schlund_manuel
+  maintainer:
+    - unmaintained


Looks like this has not been changed

schlunma · 2026-08-26T14:03:24Z

+
+        cbar = fig.colorbar(cf, ax=ax, orientation="vertical", shrink=0.95)
+        cbar.set_label("CPT pressure [hPa]", fontsize=16)
+        cbar.set_ticks([80, 90, 100, 110, 120])


I guess this is the reason for the weird 110/120 in the plot? Instead of hardcoding it, you can either let matplotlib figure that out or make it configurable in the recipe.

schlunma · 2026-08-26T14:04:28Z

+
+datasets:
+  - {dataset: ERA5, project: native6, type: reanaly, version: v1, tier: 3, alias: ERA5}
+  - {dataset: MPI-ESM1-2-LR, project: CMIP6, exp: historical, ensemble: r1i1p1f1, grid: gn, alias: CMIP6}


Suggested change

- {dataset: MPI-ESM1-2-LR, project: CMIP6, exp: historical, ensemble: r1i1p1f1, grid: gn, alias: CMIP6}

- {dataset: MPI-ESM1-2-LR, project: CMIP6, exp: historical, ensemble: r1i1p1f1, grid: gn, alias: MPI-ESM1-2-LR}

schlunma · 2026-08-26T14:07:28Z

+
+        caption = (
+            f"Tropical CPT {view_desc} Hovmoeller for {dataset_label}: "
+            f"colors show CPT pressure; contours show {title.lower()}."


Suggested change

f"colors show CPT pressure; contours show {title.lower()}."

f"colors show CPT pressure; contours show {title}."

It looks nicer with proper capitalization.

schlunma · 2026-08-26T14:07:49Z

+            cpt_q,
+            lambda x: f"{x * 1e6:.2f}",
+        ),
+        ("rhi", "CPT RH over ice contours [%]", cpt_rhi, "%.0f"),


Suggested change

("rhi", "CPT RH over ice contours [%]", cpt_rhi, "%.0f"),

("rhi", "CPT relative humidity over ice contours [%]", cpt_rhi, "%.0f"),

To be more verbose

katjaweigel · 2026-08-27T07:57:44Z

Thanks so much @aoifemcquaid for addressing my comments! Looks fantastic, just have a couple of minor comments left.

Approving this from a technical point of view. @ESMValGroup/atmosphere would anyone be able to do a quick scientific review of this? Thanks so much!

I can have a look when Levante is up again.

aoifemcquaid added 3 commits July 16, 2026 16:00

Adding inital CPT recipe and diagnostic. Initially hardcoded for ICON…

5e6853b

…-ML. Longitude hovmoeller plot with CPT P, T, q and RH_i. RH_i derived from other variables.

adding name to references

04f6de2

schlunma added the diagnostic label Jul 24, 2026

schlunma added this to the v2.16.0 milestone Jul 24, 2026

schlunma reviewed Jul 24, 2026

View reviewed changes

JurijSchoenfeld mentioned this pull request Jul 30, 2026

Add MJO recipes #3995

Open

16 tasks

aoifemcquaid added 3 commits August 12, 2026 13:08

adding name reference

437cc96

removing ICON data handling

e79b3ae

adding docs for tropical cpt hovmoeller plots

6edec7c

aoifemcquaid marked this pull request as ready for review August 12, 2026 11:14

aoifemcquaid and others added 3 commits August 12, 2026 13:25

Merge branch 'main' into EVA_convection_diagnostics_CTP

93dae1b

Fix Codacy findings in tropical CPT Hovmoeller diagnostic

8b8763f

Merge remote-tracking branch 'origin/EVA_convection_diagnostics_CTP' …

cef1744

…into EVA_convection_diagnostics_CTP

schlunma approved these changes Aug 26, 2026

View reviewed changes

schlunma added looking for scientific reviewer approved by technical reviewer labels Aug 26, 2026

schlunma mentioned this pull request Aug 27, 2026

Adding basic impact diagnostics #4427

Open

11 tasks

katjaweigel added the in scientific review label Sep 11, 2026

	basename = f"{cfg.get('plot_filename', 'tropical_cpt_hovmoeller')}_{_safe_name(dataset_label)}"
	basename = f"{cfg['plot_filename']}_{_safe_name(dataset_label)}"

	- {dataset: MPI-ESM1-2-LR, project: CMIP6, exp: historical, ensemble: r1i1p1f1, grid: gn, alias: CMIP6}
	- {dataset: MPI-ESM1-2-LR, project: CMIP6, exp: historical, ensemble: r1i1p1f1, grid: gn, alias: MPI-ESM1-2-LR}

	f"colors show CPT pressure; contours show {title.lower()}."
	f"colors show CPT pressure; contours show {title}."

	("rhi", "CPT RH over ice contours [%]", cpt_rhi, "%.0f"),
	("rhi", "CPT relative humidity over ice contours [%]", cpt_rhi, "%.0f"),

Conversation

aoifemcquaid commented Jul 23, 2026 • edited by schlunma Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Files added/changed

CTP diagnostic workflow

Data included

Testing

Checklist

Uh oh!

CLAassistant commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

schlunma left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

schlunma left a comment

Choose a reason for hiding this comment

Uh oh!

schlunma Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

katjaweigel commented Aug 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aoifemcquaid commented Jul 23, 2026 •

edited by schlunma

Loading

CLAassistant commented Jul 23, 2026 •

edited

Loading

schlunma Aug 26, 2026 •

edited

Loading