Merge branch 'distance_metric_preproc' into test_distance_metric

.zenodo.json

@@ -178,6 +178,11 @@
             "name": "Kazeroni, Rémi",
             "orcid": "0000-0001-7205-9528"
         },
+        {
+            "affiliation": "GEOMAR, Germany",
+            "name": "Hohn, David",
+            "orcid": "0000-0002-5317-1247"
+        },
         {
             "affiliation": "DLR, Germany",
             "name": "Bauer, Julian"
@@ -190,6 +195,15 @@
         {
             "affiliation": "Forschungszentrum Juelich, Germany",
             "name": "Benke, Joerg"
+        },
+        {
+            "affiliation": "BSC, Spain",
+            "name": "Martin-Martinez, Eneko",
+            "orcid": "0000-0002-9213-7818"
+        },
+        {
+            "affiliation": "DLR, Germany",
+            "name": "Cammarano, Diego"
         }
     ],
     "description": "ESMValCore: A community tool for pre-processing data from Earth system models in CMIP and running analysis scripts.",

CITATION.cff

@@ -199,6 +199,15 @@ authors:
     affiliation: "Forschungszentrum Juelich (FZJ), Germany"
     family-names: Benke
     given-names: Joerg
+  -
+    affiliation: "BSC, Spain"
+    family-names: Martin-Martinez
+    given-names: Eneko
+    orcid: "https://orcid.org/0000-0002-9213-7818"
+  -
+    affiliation: "DLR, Germany"
+    family-names: Cammarano
+    given-names: Diego
 
 cff-version: 1.2.0
 date-released: 2023-12-19

README.md

@@ -5,7 +5,7 @@
 [![Chat on Matrix](https://matrix.to/img/matrix-badge.svg)](https://matrix.to/#/#ESMValGroup_Lobby:gitter.im)
 [![CircleCI](https://circleci.com/gh/ESMValGroup/ESMValCore/tree/main.svg?style=svg)](https://circleci.com/gh/ESMValGroup/ESMValCore/tree/main)
 [![codecov](https://codecov.io/gh/ESMValGroup/ESMValCore/branch/main/graph/badge.svg?token=wQnDzguwq6)](https://codecov.io/gh/ESMValGroup/ESMValCore)
-[![Codacy Badge](https://app.codacy.com/project/badge/Grade/5d496dea9ef64ec68e448a6df5a65783)](https://www.codacy.com/gh/ESMValGroup/ESMValCore?utm_source=github.com&utm_medium=referral&utm_content=ESMValGroup/ESMValCore&utm_campaign=Badge_Grade)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/5d496dea9ef64ec68e448a6df5a65783)](https://app.codacy.com/gh/ESMValGroup/ESMValCore/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
 [![Docker Build Status](https://img.shields.io/docker/cloud/build/esmvalgroup/esmvalcore)](https://hub.docker.com/r/esmvalgroup/esmvalcore/)
 [![Anaconda-Server Badge](https://img.shields.io/conda/vn/conda-forge/ESMValCore?color=blue&label=conda-forge&logo=conda-forge&logoColor=white)](https://anaconda.org/conda-forge/esmvalcore)
 [![Github Actions Test](https://github.com/ESMValGroup/ESMValCore/actions/workflows/run-tests.yml/badge.svg)](https://github.com/ESMValGroup/ESMValCore/actions/workflows/run-tests.yml)

doc/api/esmvalcore.regridding_schemes.rst

@@ -0,0 +1,23 @@
+.. _regridding_schemes:
+
+Regridding schemes
+==================
+
+Iris natively supports data regridding with its :meth:`iris.cube.Cube.regrid`
+method and a set of predefined regridding schemes provided in the
+:mod:`~iris.analysis` module (further details are given on `this
+<https://scitools-iris.readthedocs.io/en/latest/userguide/interpolation_and_regridding.html>`__
+page).
+Here, further regridding schemes are provided that are compatible with
+:meth:`iris.cube.Cube.regrid`.
+
+Example:
+
+.. code:: python
+
+   from esmvalcore.preprocessor.regrid_schemes import ESMPyAreaWeighted
+
+   regridded_cube = cube.regrid(target_grid, ESMPyAreaWeighted())
+
+.. automodule:: esmvalcore.preprocessor.regrid_schemes
+   :no-show-inheritance:

doc/api/esmvalcore.rst

@@ -17,5 +17,6 @@ library. This section documents the public API of ESMValCore.
    esmvalcore.iris_helpers
    esmvalcore.local
    esmvalcore.preprocessor
+   esmvalcore.regridding_schemes
    esmvalcore.typing
    esmvalcore.experimental

doc/quickstart/configure.rst

@@ -382,8 +382,8 @@ corresponding command line arguments ``--search_esgf=when_missing`` or
    tool by pressing the ``Ctrl`` and ``C`` keys on your keyboard simultaneously
    several times, edit the recipe so it contains fewer datasets and try again.
 
-For downloading some files (e.g. those produced by the CORDEX project),
-you need to log in to be able to download the data.
+For downloading some files, you may need to log in to be able to download the
+data.
 
 See the
 `ESGF user guide <https://esgf.github.io/esgf-user-support/user_guide.html>`_

doc/quickstart/find_data.rst

@@ -121,13 +121,13 @@ ERA5
 - Supported variables: ``cl``, ``clt``, ``evspsbl``, ``evspsblpot``, ``mrro``, ``pr``, ``prsn``, ``ps``, ``psl``, ``ptype``, ``rls``, ``rlds``, ``rsds``, ``rsdt``, ``rss``, ``uas``, ``vas``, ``tas``, ``tasmax``, ``tasmin``, ``tdps``, ``ts``, ``tsn`` (``E1hr``/``Amon``), ``orog`` (``fx``)
 - Tier: 3
 
-.. note:: According to the description of Evapotranspiration and potential Evapotranspiration on the Copernicus page 
+.. note:: According to the description of Evapotranspiration and potential Evapotranspiration on the Copernicus page
   (https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels-monthly-means?tab=overview):
-  "The ECMWF Integrated Forecasting System (IFS) convention is that downward fluxes are positive. 
+  "The ECMWF Integrated Forecasting System (IFS) convention is that downward fluxes are positive.
   Therefore, negative values indicate evaporation and positive values indicate condensation."
-  
+
   In the CMOR table, these fluxes are defined as positive, if they go from the surface into the atmosphere:
-  "Evaporation at surface (also known as evapotranspiration): flux of water into the atmosphere due to conversion 
+  "Evaporation at surface (also known as evapotranspiration): flux of water into the atmosphere due to conversion
   of both liquid and solid phases to vapor (from underlying surface and vegetation)."
   Therefore, the ERA5 (and ERA5-Land) CMORizer switches the signs of ``evspsbl`` and ``evspsblpot`` to be compatible with the CMOR standard used e.g. by the CMIP models.
 
@@ -388,7 +388,9 @@ This grid file can either be specified as absolute or relative (to
 with the facet ``horizontal_grid`` in the recipe or the extra facets (see
 below), or retrieved automatically from the `grid_file_uri` attribute of the
 input files.
-In the latter case, the file is downloaded once and then cached.
+In the latter case, ESMValCore first searches the input directories specified
+for ICON for a grid file with that name, and if that was not successful, tries
+to download the file and cache it.
 The cached file is valid for 7 days.
 
 ESMValCore can automatically make native ICON data `UGRID
@@ -398,7 +400,7 @@ The UGRID conventions provide a standardized format to store data on
 unstructured grids, which is required by many software packages or tools to
 work correctly.
 An example is the horizontal regridding of native ICON data to a regular grid.
-While the built-in :ref:`unstructured_nearest scheme <built-in regridding
+While the built-in :ref:`nearest scheme <built-in regridding
 schemes>` can handle unstructured grids not in UGRID format, using more complex
 regridding algorithms (for example provided by the
 :doc:`iris-esmf-regrid:index` package through :ref:`generic regridding
@@ -420,7 +422,7 @@ This automatic UGRIDization is enabled by default, but can be switched off with
 the facet ``ugrid: false`` in the recipe or the extra facets (see below).
 This is useful for diagnostics that do not support input data in UGRID format
 (yet) like the :ref:`Psyplot diagnostic <esmvaltool:recipes_psyplot_diag>` or
-if you want to use the built-in :ref:`unstructured_nearest scheme <built-in
+if you want to use the built-in :ref:`nearest scheme <built-in
 regridding schemes>` regridding scheme.
 
 For 3D ICON variables, ESMValCore tries to add the pressure level information
@@ -467,7 +469,7 @@ Key                 Description                      Default value if not specif
 =================== ================================ ===================================
 ``horizontal_grid`` Absolute or relative (to         If not given, use file attribute
                     ``auxiliary_data_dir`` defined   ``grid_file_uri`` to retrieve ICON
-                    in the                           grid file
+                    in the                           grid file (see details above)
                     :ref:`user configuration file`)
                     path to the ICON grid file
 ``latitude``        Standard name of the latitude    ``latitude``