ACCESS-NRI ENSO diagnostics CLIVAR porting (#3905)

Co-authored-by: Romain Beucher <romain.beucher@anu.edu.au>
Co-authored-by: Charles Turner <52199577+charles-turner-1@users.noreply.github.com>

Author: 3 people

doc/sphinx/source/recipes/figures/enso_metrics/ACCESS-ESM1-5_12seasonality_level_4.png

@@ -134,6 +134,7 @@ Ocean
    recipe_combined_indices
    recipe_esacci_oc
    recipe_enso_ref
+   recipe_enso_clivar
    recipe_oceans
    recipe_sea_surface_salinity
    recipe_russell18jgr

doc/sphinx/source/recipes/figures/enso_metrics/ACCESS-ESM1-5_DJF_ts_telecon.png

@@ -0,0 +1,106 @@
+.. _recipes_enso_diagnostics:
+
+ENSO CLIVAR metrics - reproducing ENSO characteristics, lifecycle, seasonality, teleconnections
+=================================================================================================
+
+Overview
+--------
+
+Reproducing ENSO metrics from the
+[CLIVAR package](https://pcmdi.llnl.gov/pmp-preliminary-results/interactive_plot/portrait_plot/enso_metric/enso_metrics_interactive_portrait_plots_v20231121.html)
+with dive down plots of ENSO diagnostics including characteristics, lifecycle, seasonality, feedbacks and teleconnections.
+
+Available recipes and diagnostics
+---------------------------------
+
+Recipes are stored in esmvaltool/recipes/
+
+* recipe_enso_climatology1.yml
+* recipe_enso_climatology_level2-3.yml
+* recipe_enso_characteristics.yml
+* recipe_enso_divedown9-10_14-15.yml
+* recipe_enso_divedown11-13.yml
+* recipe_enso_feedback.yml
+* recipe_enso_feedbacknhf.yml
+* recipe_enso_teleconnection.yml
+
+Diagnostics are stored in esmvaltool/diag_scripts/enso_metrics/
+
+* **matrix.py**: reads metrics in work_dir from csv file written out in climatology_diagnostic1, use for other groups of metrics
+* **climatology_diagnostic1.py**: computes basic climatology for level 1 metrics
+* **climatology_diagnosticlevel2.py**: creates basic climatology level 2 plots
+* **climatology_diagnosticlevel3.py**: creates basic climatology level 3 plots
+* **enso_diag1metrics.py**: computes basic ENSO characteristics metrics
+* **enso_divedowns/ampseasskew11-13.py**: dive down scripts for ENSO amplitude, seasonality and skewness
+* **enso_divedowns/durdiver_14-15.py**: dive down scripts for ENSO duration and diversity
+* **enso_divedowns/lifecycle_10.py**: dive down scripts for ENSO lifecycle
+* **enso_divedowns/pattern_9.py**: dive down scripts for ENSO pattern
+* **feedback/feedback_metrics_lvl4.py**: feedback level4 plots
+* **feedback/feedback_metrics.py**: feedback level3 plots
+* **feedback/feedback_nhf_lvl3_4.py**: feedback NHF level3-4 plots
+* **feedback/feedback_nhf_metric.py**: feedback NHF metrics
+* **teleconnections_metrics.py**: computes and plots teleconnections metrics
+
+
+User settings in recipe
+-----------------------
+
+#. Script: **matrix.py**
+
+   *Required settings for script*
+
+   * **diag_metrics**: diagnostic name and script name in *yml* of the diagnostic that computes all the metrics so it can find the *csv* in the `work_dir` - eg. diagnostic_metrics/plot_script
+
+
+Variables
+---------
+
+* tos (Omon, monthly)
+* areacello (Ofx)
+* pr (Amon, monthly)
+* ts (Amon, monthly)
+* areacella (fx)
+* tauu (Amon, monthly)
+* zos (Omon, monthly)
+* hfns (hfls+hfss, Amon, monthly)
+
+Observations and reformat scripts
+---------------------------------
+
+* HadISST
+* TropFLUX
+* GPCP-SG
+* ERA-Interim
+
+References
+----------
+
+* [1] https://pcmdi.llnl.gov/pmp-preliminary-results/interactive_plot/portrait_plot/enso_metric/enso_metrics_interactive_portrait_plots_v20231121.html
+* [2] https://github.com/CLIVAR-PRP/ENSO_metrics/
+
+Example plots
+-------------
+
+.. _fig_teleconnections:
+.. figure:: /recipes/figures/enso_metrics/ACCESS-ESM1-5_DJF_ts_telecon.png
+   :align: center
+
+   PR or SST anomalies on Earth (between 60°S-60°N), showing the location associated with ENSO.
+
+.. _fig_seasonality_level4:
+.. figure:: /recipes/figures/enso_metrics/ACCESS-ESM1-5_12seasonality_level_4.png
+   :align: center
+
+   Seasonality level 4 plot of boreal summer/winter SSTA standard deviation.
+
+.. _fig_feedback_level2:
+.. figure:: /recipes/figures/enso_metrics/ACCESS-ESM1-5_SSH_SST_lvl2.png
+   :align: center
+
+   Feedback level 2 plot of SSH and SST anomalies.
+
+.. _fig_metrics:
+.. figure:: /recipes/figures/enso_metrics/plot_matrix.png
+   :align: center
+
+   Portrait plot of normalized metrics for models against reference observation.

doc/sphinx/source/recipes/figures/enso_metrics/ACCESS-ESM1-5_SSH_SST_lvl2.png

@@ -651,6 +651,10 @@ authors:
     name: Charlton-Perez, Andrew
     institute: Univ. of Reading, UK
     orcid:
+  chung_christine:
+    name: Chung, Christine
+    institute: Bureau of Meterology, Australia
+    orcid:
   corti_susanna:
     name: Corti, Susanna
     institute: ISAC-CNR, Torino, Italy
@@ -659,6 +663,10 @@ authors:
     name: Dennis, John
     institute: NCAR, USA
     orcid:
+  gillet_zoe:
+    name: Gillet, Zoe
+    institute: Bureau of Meterology, Australia
+    orcid:
   graf_phoebe:
     name: Graf, Phoebe
     institute: DLR, Germany

doc/sphinx/source/recipes/figures/enso_metrics/plot_matrix.png

@@ -26,7 +26,6 @@ def plotmaps_level2(input_data, grp):
     """Create map plots for pair of input data."""
     fig = plt.figure(figsize=(18, 6))
     proj = ccrs.Orthographic(central_longitude=210.0)
-    data_to_save = []
     for plt_pos, dataset in enumerate(input_data, start=121):
         logger.info(
             "dataset: %s - %s",
@@ -35,9 +34,6 @@ def plotmaps_level2(input_data, grp):
         )
         cube, cbar_label = load_seacycle_stdev(dataset)
 
-        # save data
-        data_to_save.append(cube)
-
         ax1 = plt.subplot(plt_pos, projection=proj)
         ax1.add_feature(cfeature.LAND, facecolor="gray")
         ax1.coastlines()
@@ -65,7 +61,7 @@ def plotmaps_level2(input_data, grp):
     cbar = fig.colorbar(cf1, cax=cax, orientation="horizontal", extend="both")
     cbar.set_label(cbar_label)
 
-    return fig, data_to_save
+    return fig
 
 
 def load_seacycle_stdev(dataset):
@@ -103,8 +99,16 @@ def provenance_record(var_grp, ancestor_files):
             "Time-mean sea surface temperature bias in the "
             + "equatorial Pacific."
         ),
+        "sst_seacycle": (
+            "Bias in the amplitude of the mean seasonal cycle of "
+            + "sea surface temperature in the equatorial Pacific."
+        ),
         "tauu_bias": "Time-mean zonal wind stress bias in the "
         + "equatorial Pacific.",
+        "tauu_seacycle": (
+            "Bias in the amplitude of the mean seasonal cycle of "
+            + "zonal wind stress in the equatorial Pacific."
+        ),
     }
     record = {
         "caption": caption[var_grp],
@@ -145,15 +149,14 @@ def main(cfg):
     # for each select obs and iterate others, obs last
     for grp, var_attr in variable_groups.items():
         logger.info("%s : %d, %s", grp, len(var_attr), pformat(var_attr))
-        # create pairs, add obs first to list
-        pairs = [var_attr[-1]]
         prov = provenance_record(grp, list(cfg["input_data"].keys()))
         for metadata in var_attr:
+            # create pairs, add obs first to list
+            pairs = [var_attr[-1]]
             logger.info("iterate though datasets\n %s", pformat(metadata))
             if metadata["project"] == "CMIP6":
                 pairs.append(metadata)
-                fig, data_cubes = plotmaps_level2(pairs, grp)
-                save_plotdata(data_cubes, grp, pairs, cfg)
+                fig = plotmaps_level2(pairs, grp)
                 filename = "_".join(
                     [
                         metadata["dataset"],