Merge branch 'main' into cmorize_ersst

.circleci/config.yml

@@ -27,6 +27,7 @@ commands:
           name: Log versions
           command: |
             . /opt/conda/etc/profile.d/conda.sh
+            conda env export --name base > /logs/base_environment.yml
             conda activate esmvaltool
             esmvaltool version
             dpkg -l > /logs/versions.txt
@@ -40,6 +41,7 @@ commands:
           command: |
             . /opt/conda/etc/profile.d/conda.sh
             conda activate esmvaltool
+            mamba --version
             pytest -n 4 --junitxml=test-reports/report.xml
             esmvaltool version
             esmvaltool -- --help
@@ -232,7 +234,7 @@ jobs:
     # Test building documentation
     docker:
       - image: condaforge/mambaforge:latest
-    resource_class: small
+    resource_class: medium
     steps:
       - checkout
       - run:
@@ -265,7 +267,7 @@ jobs:
             # Install prerequisites
             mkdir /logs
             # Install ESMValTool in a new conda environment
-            mamba create -y --name esmvaltool -c conda-forge esmvaltool julia 'python=3.10' >> /logs/conda.txt 2>&1
+            mamba create -y --name esmvaltool -c conda-forge esmvaltool julia 'python=3.11' >> /logs/conda.txt 2>&1
             # Activate the environment
             set +x; conda activate esmvaltool; set -x
             # install the Julia dependencies

README.md

@@ -8,7 +8,7 @@
 [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/79bf6932c2e844eea15d0fb1ed7e415c)](https://www.codacy.com/gh/ESMValGroup/ESMValTool?utm_source=github.com&utm_medium=referral&utm_content=ESMValGroup/ESMValTool&utm_campaign=Badge_Coverage)
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/79bf6932c2e844eea15d0fb1ed7e415c)](https://www.codacy.com/gh/ESMValGroup/ESMValTool?utm_source=github.com&utm_medium=referral&utm_content=ESMValGroup/ESMValTool&utm_campaign=Badge_Grade)
 [![Docker Build Status](https://img.shields.io/docker/cloud/build/esmvalgroup/esmvaltool.svg)](https://hub.docker.com/r/esmvalgroup/esmvaltool/)
-[![Anaconda-Server Badge](https://img.shields.io/badge/Anaconda.org-2.9.0-blue.svg)](https://anaconda.org/conda-forge/esmvaltool)
+[![Anaconda-Server Badge](https://img.shields.io/conda/vn/conda-forge/ESMValTool?color=blue&label=conda-forge&logo=conda-forge&logoColor=white)](https://anaconda.org/conda-forge/esmvaltool)
 ![stand with Ukraine](https://badgen.net/badge/stand%20with/UKRAINE/?color=0057B8&labelColor=FFD700)
 
 ![esmvaltoollogo](https://raw.githubusercontent.com/ESMValGroup/ESMValTool/main/doc/sphinx/source/figures/ESMValTool-logo-2.png)

doc/sphinx/source/api/esmvaltool.diag_scripts.monitor.rst

@@ -11,6 +11,7 @@ Examples
 --------
 
 * :ref:`recipe_monitor`
+* :ref:`recipe_model_evaluation`
 
 
 Diagnostic scripts

doc/sphinx/source/community/code_documentation.rst

@@ -442,7 +442,10 @@ name to the list of authors in ``CITATION.cff`` and generate the entry for the
 ::
 
    pip install cffconvert
-   cffconvert --format zenodo --outfile .zenodo.json
+   cffconvert --infile CITATION.cff --format zenodo --outfile .zenodo.json
+
+Presently, this method unfortunately discards entries `communities`
+and `grants` from that file; please restore them manually.
 
 Note that authors of recipes and/or diagnostics also need to be added to the file
 `esmvaltool/config-references.yml <https://github.com/ESMValGroup/ESMValTool/blob/main/esmvaltool/config-references.yml>`__,

doc/sphinx/source/faq.rst

@@ -113,9 +113,15 @@ a symbolic link to it so it gets picked up at every re-run iteration:
 Can ESMValTool plot arbitrary model output?
 ===========================================
 
-Recipe :ref:`recipe_monitor` allows for the plotting of any preprocessed model.
-The plotting parameters are set through a yaml configuration file, and the
-type of plots to be generated are determined in the recipe.
+:ref:`recipe_model_evaluation` provides a set of recipes that can be used for a
+basic climate model evaluation with observational data.
+This is especially useful to get an overview of the general performance of a
+simulation.
+
+Furthermore, recipe :ref:`recipe_monitor` allows for the plotting of any
+preprocessed model.
+The plotting parameters are set through a yaml configuration file, and the type
+of plots to be generated are determined in the recipe.
 
 Moreover, recipe :ref:`recipes_psyplot_diag` and the corresponding diagnostic
 :ref:`psyplot_diag.py <api.esmvaltool.diag_scripts.psyplot_diag>` provide a

doc/sphinx/source/input.rst

@@ -112,6 +112,13 @@ ESMValTool currently supports two ways to perform this reformatting (aka
    checks and fixes').  Details on this second method are given at the
    :ref:`end of this chapter <inputdata_native_datasets>`.
 
+A collection of readily CMORized OBS and OBS6 datasets can be accessed directly on CEDA/JASMIN and DKRZ. At CEDA/JASMIN
+OBS and OBS6 data is stored in the `esmeval` Group Workspace (GWS), and to be granted read (and execute) permissions to the
+GWS, one must apply at https://accounts.jasmin.ac.uk/services/group_workspaces/esmeval/ ; after permission has been granted, the user
+is encouraged to use the data locally, and not move it elsewhere, to minimize both data transfers and
+stale disk usage; to note that Tier 3 data is subject to data protection restrictions; for further inquiries,
+the GWS is adminstered by [Valeriu Predoi](mailto:[email protected]).
+
 Using a CMORizer script
 -----------------------
 
@@ -397,7 +404,7 @@ A list of the datasets for which a CMORizers is available is provided in the fol
 +------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+
 | NOAAGlobalTemp               | tasa (Amon)                                                                                          |   2  | Python          |
 +------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+
-| NSIDC-0116-[nh|sh]           | usi, vsi (day)                                                                                       |   3  | Python          |
+| NSIDC-0116-[nh|sh] [#note4]_ | usi, vsi (day)                                                                                       |   3  | Python          |
 +------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+
 | OceanSODA-ETHZ               | areacello (Ofx), co3os, dissicos, fgco2, phos, spco2, talkos (Omon)                                  |   2  | Python          |
 +------------------------------+------------------------------------------------------------------------------------------------------+------+-----------------+
@@ -437,6 +444,10 @@ A list of the datasets for which a CMORizers is available is provided in the fol
             can be found in the corresponding section of `recipe_check_obs.yml
             <https://github.com/ESMValGroup/ESMValTool/blob/main/esmvaltool/recipes/examples/recipe_check_obs.yml>`__.
 
+.. [#note4] The cmoriser requires PROJ>=9.3. Previous version of PROJ will return an error:
+            ``Internal Proj Error: proj_create: unhandled axis direction: UNKNOWN)``
+            You can check the version of PROJ in your conda environment by running:
+            ``conda list PROJ``.
 
 .. _inputdata_native_datasets:
 

doc/sphinx/source/recipes/index.rst

@@ -21,6 +21,7 @@ large variety of input data.
 .. toctree::
    :maxdepth: 1
 
+   recipe_model_evaluation
    recipe_monitor
    recipe_psyplot
    recipe_seaborn

doc/sphinx/source/recipes/recipe_model_evaluation.rst

@@ -0,0 +1,98 @@
+.. _recipe_model_evaluation:
+
+General model evaluation
+========================
+
+Overview
+--------
+
+These recipes and diagnostics provide a basic climate model evaluation with
+observational data.
+This is especially useful to get an overview of the performance of a
+simulation.
+The diagnostics used here allow plotting arbitrary preprocessor output, i.e.,
+arbitrary variables from arbitrary datasets.
+
+
+Available recipes and diagnostics
+---------------------------------
+
+Recipes are stored in `recipes/model_evaluation`
+
+* recipe_model_evaluation_basics.yml
+* recipe_model_evaluation_clouds_clim.yml
+* recipe_model_evaluation_clouds_cycles.yml
+* recipe_model_evaluation_precip_zonal.yml
+
+Diagnostics are stored in `diag_scripts/monitor/`
+
+* :ref:`multi_datasets.py
+  <api.esmvaltool.diag_scripts.monitor.multi_datasets>`:
+  Monitoring diagnostic to show multiple datasets in one plot (incl. biases).
+
+
+User settings
+-------------
+
+It is recommended to use a vector graphic file type (e.g., SVG) for the output
+format when running this recipe, i.e., run the recipe with the command line
+option ``--output_file_type=svg`` or use ``output_file_type: svg`` in your
+:ref:`esmvalcore:user configuration file`.
+Note that map and profile plots are rasterized by default.
+Use ``rasterize: false`` in the recipe to disable
+this.
+
+
+Recipe settings
+~~~~~~~~~~~~~~~
+
+A list of all possible configuration options that can be specified in the
+recipe is given for each diagnostic individually (see links given for the
+available diagnostics in the previous section).
+
+
+Variables
+---------
+
+Any, but the variables' number of dimensions should match the ones expected by
+each diagnostic (see links given for the available diagnostics in the previous
+section).
+
+
+Example plots
+-------------
+
+.. _fig_1:
+.. figure::  /recipes/figures/model_evaluation/map_tas_MPI-ESM1-2-HR_Amon.jpg
+   :align:   center
+   :width:   14cm
+
+Global climatology of 2m near-surface air temperature.
+
+.. _fig_2:
+.. figure::  /recipes/figures/model_evaluation/map_swcre_MPI-ESM1-2-HR_Amon.jpg
+   :align:   center
+   :width:   14cm
+
+Global climatology of the shortwave cloud radiative effect (SWCRE).
+
+.. _fig_3:
+.. figure::  /recipes/figures/model_evaluation/timeseries_rtnt_ambiguous_dataset_Amon.jpg
+   :align:   center
+   :width:   14cm
+
+Time series of the global mean top-of-the-atmosphere net radiative flux.
+
+.. _fig_4:
+.. figure::  /recipes/figures/model_evaluation/variable_vs_lat_pr_Amon.jpg
+   :align:   center
+   :width:   14cm
+
+Zonal mean precipitation.
+
+.. _fig_5:
+.. figure::  /recipes/figures/model_evaluation/annual_cycle_clt_southerocean_Amon.jpg
+   :align:   center
+   :width:   14cm
+
+Annual cycle of Southern Ocean total cloud cover.

doc/sphinx/source/recipes/recipe_monitor.rst

@@ -18,19 +18,18 @@ Available recipes and diagnostics
 
 Recipes are stored in `recipes/monitor`
 
-   * recipe_monitor.yml
-   * recipe_monitor_with_refs.yml
+* recipe_monitor.yml
+* recipe_monitor_with_refs.yml
 
 Diagnostics are stored in `diag_scripts/monitor/`
 
-   * :ref:`monitor.py <api.esmvaltool.diag_scripts.monitor.monitor>`:
-     Monitoring diagnostic to plot arbitrary preprocessor output.
-   * :ref:`compute_eofs.py <api.esmvaltool.diag_scripts.monitor.compute_eofs>`:
-     Monitoring diagnostic to plot EOF maps and associated PC timeseries.
-   * :ref:`multi_datasets.py
-     <api.esmvaltool.diag_scripts.monitor.multi_datasets>`:
-     Monitoring diagnostic to show multiple datasets in one plot (incl.
-     biases).
+* :ref:`monitor.py <api.esmvaltool.diag_scripts.monitor.monitor>`:
+  Monitoring diagnostic to plot arbitrary preprocessor output.
+* :ref:`compute_eofs.py <api.esmvaltool.diag_scripts.monitor.compute_eofs>`:
+  Monitoring diagnostic to plot EOF maps and associated PC timeseries.
+* :ref:`multi_datasets.py
+  <api.esmvaltool.diag_scripts.monitor.multi_datasets>`:
+  Monitoring diagnostic to show multiple datasets in one plot (incl. biases).
 
 
 User settings

esmvaltool/diag_scripts/ipcc_ar5/ch12_calc_zonal_cont_diff_mmm_stippandhatch.ncl

@@ -78,13 +78,6 @@ begin
 end
 
 begin
-  ; Get environment variables
-  if (isatt(diag_script_info, "plot_type")) then
-    file_type = diag_script_info@plot_type
-  else
-    file_type = "pdf"
-  end if
-
   ; Output netcdf directory
   work_dir = config_user_info@work_dir
   system("mkdir -p " + work_dir)

esmvaltool/diag_scripts/ipcc_ar5/ch12_plot_map_diff_mmm_stipp.ncl

@@ -51,13 +51,6 @@ begin
 end
 
 begin
-  ; Get environment variables
-  if (isatt(diag_script_info, "plot_type")) then
-    file_type = diag_script_info@plot_type
-  else
-    file_type = "pdf"
-  end if
-
   ; Output netcdf directory
   work_dir = config_user_info@work_dir
   system("mkdir -p " + work_dir)

esmvaltool/diag_scripts/ipcc_ar5/ch12_plot_ts_line_mean_spread.ncl

@@ -48,13 +48,6 @@ end
 
 
 begin
-  ; Get environment variables
-  if (isatt(diag_script_info, "plot_type")) then
-    file_type = diag_script_info@plot_type
-  else
-    file_type = "pdf"
-  end if
-
   ; Output netcdf directory
   work_dir = config_user_info@work_dir
   system("mkdir -p " + work_dir)
@@ -251,11 +244,10 @@ begin
   draw(wks)
   frame(wks)
 
-  log_info(" Wrote " + plot_dir + "/" + outfile + "." + file_type)
+  log_info(" Wrote " + wks@fullname)
 
   ; collect meta-data
   nc_file = datapath
-  plot_file = plot_dir + "/" + outfile + "." + file_type
 
   if (isatt(diag_script_info, "spread")) then
     spread_str = diag_script_info@spread
@@ -279,7 +271,7 @@ begin
   authors = (/"lorenz_ruth"/)
   references = (/"collins13ipcc"/)
   infiles = metadata_att_as_array(info_items, "filename")
-  log_provenance(nc_file, plot_file, caption, statistics, domains, \
+  log_provenance(nc_file, wks@fullname, caption, statistics, domains, \
                  plot_types, authors, references, infiles)
 
   leave_msg(DIAG_SCRIPT, "")

esmvaltool/diag_scripts/ipcc_ar5/ch12_plot_zonal_diff_mmm_stipp.ncl

@@ -48,12 +48,6 @@ begin
 end
 
 begin
-  ; Get environment variables
-  if (isatt(diag_script_info, "plot_type")) then
-    file_type = diag_script_info@plot_type
-  else
-    file_type = "pdf"
-  end if
   ; Output netcdf directory
   work_dir = config_user_info@work_dir
   system("mkdir -p " + work_dir)

esmvaltool/diag_scripts/ipcc_ar5/ch12_snw_area_change_fig12-32.ncl

@@ -66,13 +66,6 @@ begin
 end
 
 begin
-  ; Get environment variables
-  if (isatt(diag_script_info, "plot_type")) then
-    file_type = diag_script_info@plot_type
-  else
-    file_type = "pdf"
-  end if
-
   ; Output netcdf directory
   work_dir = config_user_info@work_dir
   system("mkdir -p " + work_dir)

esmvaltool/diag_scripts/ipcc_ar5/ch12_ts_line_mean_spread.ncl

@@ -47,13 +47,6 @@ begin
 end
 
 begin
-  ; Get environment variables
-  if (isatt(diag_script_info, "plot_type")) then
-    file_type = diag_script_info@plot_type
-  else
-    file_type = "pdf"
-  end if
-
   ; Output netcdf directory
   work_dir = config_user_info@work_dir
   system("mkdir -p " + work_dir)

esmvaltool/diag_scripts/monitor/monitor_base.py

@@ -97,7 +97,9 @@ def __init__(self, config):
         )
         plot_folder = plot_folder.replace('{plot_dir}',
                                           self.cfg[names.PLOT_DIR])
-        self.plot_folder = os.path.abspath(plot_folder)
+        self.plot_folder = os.path.abspath(
+            os.path.expandvars(os.path.expanduser(plot_folder))
+        )
         self.plot_filename = config.get(
             'plot_filename',
             '{plot_type}_{real_name}_{dataset}_{mip}_{exp}_{ensemble}')
@@ -293,11 +295,7 @@ def get_plot_folder(self, var_info):
             'real_name': self._real_name(var_info['variable_group']),
             **var_info
         }
-        folder = os.path.expandvars(
-            os.path.expanduser(
-                list(_replace_tags(self.plot_folder, info))[0]
-            )
-        )
+        folder = list(_replace_tags(self.plot_folder, info))[0]
         if self.plot_folder.startswith('/'):
             folder = '/' + folder
         if not os.path.isdir(folder):

esmvaltool/diag_scripts/tebaldi21esd/calc_table_changes.ncl

@@ -53,13 +53,6 @@ begin
 end
 
 begin
-  ; Get environment variables
-  if (isatt(diag_script_info, "plot_type")) then
-    file_type = diag_script_info@plot_type
-  else
-    file_type = "pdf"
-  end if
-
   ; Output netcdf directory
   work_dir = config_user_info@work_dir
   system("mkdir -p " + work_dir)