Merge pull request #111 from oloapinivad/cleaning-diagnostic

Reorganizing ecmean classes

CHANGELOG.md

@@ -8,7 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 Unreleased is the current development version, which is currently lying in `main` branch.
 
 - Allowing for configuration file as dictionary (#106)
-- GlobalMean and PerformanceIndices classe introduced (#110)
+- GlobalMean and PerformanceIndices classe introduced (#110, #111)
 
 ## [v0.1.11]
 

dev-environment.yml

@@ -7,7 +7,7 @@ name : dev-ecmean
 channels:
   - conda-forge
 dependencies:
-  - python=>3.9,<3.13
+  - python>=3.9,<3.13
   - libnetcdf
   - xesmf
   - eccodes

docs/sphinx/source/conf.py

@@ -29,7 +29,7 @@
 napoleon_numpy_docstring = False
 
 templates_path = ["_templates"]
-autoclass_content='both'
+autoclass_content = 'both'
 exclude_patterns = []
 
 
@@ -42,4 +42,4 @@
     "collapse_navigation": False,
     "sticky_navigation": True,
     "navigation_depth": 4,
-}
+}

docs/sphinx/source/performanceindices.rst

@@ -5,10 +5,24 @@ Main concepts
 ^^^^^^^^^^^^^
 
 The ``performance_indices`` command is based on the ``performance_indices.py`` script which computes the `Reichler and Kim Performance Indices <https://journals.ametsoc.org/view/journals/bams/89/3/bams-89-3-303.xml>`_, usually known as PIs. 
-Some minor differences from the original definition has been introduced, so that the PIs are computed on a common (user defined) grid rather than on the original grid.
+Some minor differences from the original definition has been introduced, so that the PIs are computed on a common grid (user defined, 1deg by default) rather than on the original observational grid.
+
 From the original definition a few improvements has been introduced, producing the PIs also for a set of selected regions and seasons. 
 
-PIs are the root mean square error of a 2D field normalized by the interannual variance estimated from the observations. Larger values implies worse performance of the climate models.
+PIs are computed as the root mean square error of a 2D field normalized by the interannual variance estimated from the observations, as follows:
+
+.. math::
+
+   \text{PI} = \frac{\sum \left( \text{Model climatology} - \text{Observation climatology} \right)^2}{\text{Observation variance}}
+
+Larger values implies worse performance of the climate models.
+For sake of simplicity, they can be normalized by the CMIP6 ensemble average, 
+so that values smaller than one implies a better results than CMIP6 ensemble average.
+
+.. note :: 
+
+   3D fields (e.g. zonal wind, temperature, etc.) are treated as 2D fields by performing the zonal average. 
+   All vertical levels are considered, and if mismatch is found between the model and the observations, the model data are linearly interpolated to the observation grid.
 
 Usage
 ^^^^^
@@ -79,7 +93,7 @@ Optional Arguments
 
 .. option:: -r RESOLUTION
 
-    Only EC22: Specify the resolution of the climatology (r180x90 or r360x180).
+    Only EC23: Specify the resolution of the climatology (r180x90 or r360x180).
 
 .. option:: -o DIR, --outputdir DIR
 
@@ -101,9 +115,10 @@ Usage example for EC-Earth4 (running on 4 cores for EC-Earth4 experment ABC1)::
 Output
 ^^^^^^
 
-The result is produced in a form a YAML file, indicating PIs for each variable, region and season, that can be stored for later evaluation. 
-Most importantly, a figure is produced showing a score card for the different regions, variables and seasons.
-For the sake of simplicity, the PIs figure is computed as the ratio between the model PI and the average value estimated over the (precomputed) ensemble of CMIP6 models. 
+The result is produced in a form a YAML file, indicating PIs for each variable, region and season, that is stored for later evaluation. 
+Most importantly, a figure is produced showing a "score card" for the different regions, variables and seasons.
+
+For the sake of simplicity, the PIs figure is shown as the ratio between the model PI and the average value estimated over the (precomputed) ensemble of CMIP6 models. 
 An example of the the output for a single year of the EC-Earth3 historical simulation is shown here below.
 
 .. figure:: _static/pitestfigure.png
@@ -113,20 +128,47 @@ An example of the the output for a single year of the EC-Earth3 historical simul
 
    An example for a single year of the EC-Earth3 historical r1i1p1f1 simulation. Values smaller than one implies a better results than CMIP6 ensemble average.
 
+Climatology computaton
+^^^^^^^^^^^^^^^^^^^^^^
+
+The performance indices built on the comparison between model data and a pre-computed climatology of several variables. Only the ``EC23`` climatology is currently recommended for usage.
+
+Climatology is computed by the ``ecmean/utils/clim-create.py`` script, which is included in the repository for documentation.
+It is based on a YML file which is tells the script where to retrieve the data, identifying all the required data folder, names and description. 
+The tool loops over the variable and produces the yearly and seasonal average of the climate, as well as the interannual variance required for PIs. 
+
 .. note ::
-  Such plot is currently available for the EC23 climatology only, which is currently computed on a 30-year time window from 1990 to 2019 using about 10 CMIP6 models.
-  Similarly, season-dependent computation are available only for EC23.
-  Details on the field and models used are reported in the ``ecmean/climatology/EC23/pi_climatology_EC23.yml`` file.
+  PIs strongly depends on the interannual variance of the reference datasates. Some datasets have extremely low values which leads to unrealistic large PIs. 
+  To avoid that grid points with unrealistic low variance affect the computation of the PIs, a filter to exclude outlier is introduced. This is based on the 5-sigma of the log10 distribution of each variable and each season. 
+  If the variance of a grid point is above or below the 5-sigma, the grid point is excluded from the computation of the PIs.
+  However, some fields as specific humidity (`hus`) are still characterized by very large PIs (due to stratospheric low variances).
+
+Current climatology has been developed making use of high-resolution data (e.g. CRU, ERA5, MSWEP, etc.) and is defined as ``EC23``, using a 1x1 deg resolution and being the default. 
+Properties of each climatology - as which interpolation method and which CMIP6 models has been used - can be inspected looking at ``ecmean/climatology/{clim}/pi_climatology_ECE23.yml`` files.
 
+CMIP6 comparison
+^^^^^^^^^^^^^^^^
 
-Climatologies available
-^^^^^^^^^^^^^^^^^^^^^^^
+Once the climatology is created, the script ``ecmean/utils/cmip6-clim-evaluate.py`` is used to run iteratively on a set of CMIP6 models and to compute the multi model mean of the PIs (for each region and season).
+A single ensemble member is used for each CMIP6 model, which is regridded toward the climatology grid. For CMIP6 models, a 30-year time window from 1981 to 2010 is used.
+This is then stored in the ``ecmean/climatology/{clim}/pi_climatology_{clim}.yml`` and then used to provide a ratio between the original PI and the CMIP6 ensemble. 
 
-The performance indices built on the comparison between model data and a pre-computed climatology of several variables.
-The ECmean climatology - from the previous CDO-based code - is currently defined as ``RK08``, and although still available, is not recommended for use since it is based on old datasets (e.g. ERA40). 
+Historical simulations for 12 CMIP6 models have been considered for the reference data climatology, namely:
 
-A new climatology has been developed making use of high-resolution data (e.g. CRU, ERA5, MSWEP, etc.) and is now defined as ``EC23``, using a 1x1 deg resolution and being the new default. 
-Properties of each climatology - as which interpolation method and which CMIP6 models has been used - can be inspected looking at ``ecmean/climatology/{clim}/pi_climatology_{clim}.yml`` files.
+- EC-Earth3
+- IPSL-CM6A-LR
+- FGOALS-g3
+- TaiESM1
+- CanESM5
+- CESM2
+- MIROC6
+- MPI-ESM1-2-HR
+- AWI-CM-1-1-MR
+- CMCC-CM2-SR5
+- NorESM2-MM
+- GFDL-CM4
+
+However for some variable issues with the grids or lack of data have been found, so that the number of models used for each variable is reported in the table below.
 
 .. list-table:: Data used in EC23 climatology
    :header-rows: 1
@@ -176,19 +218,9 @@ Properties of each climatology - as which interpolation method and which CMIP6 m
      - 6 CMIP6 models over 1981-2010
 
 
-Climatology computation
-^^^^^^^^^^^^^^^^^^^^^^^
+.. note:: 
 
-Climatology is computed by the ``ecmean/utils/clim-create.py`` script, which is included in the repository for documentation.
-It is based on a YML file which is tells the script where to retrieve the data, identifying all the required data folder and names. 
-The tool loops over the variable and produces the yearly and seasonal average of the climate, as well as the interannual variance required for PIs. 
+  The older ECmean climatology - from the previous CDO-based code - is currently defined as ``RK08``, and although still available, is not recommended for use since it is based on old datasets (e.g. ERA40). 
 
 
-.. note ::
-  PIs strongly depends on the interannual variance of the reference datasates. Some datasets have extremely low values which leads to incredibly large PIs. 
-  To avoid that grid points with unrealistic low variance affect the computation of the PIs, a filter to exclude outlier is introduced. This is based on the 5-sigma of the log10 distribution of each variable and each season. 
-  However, some fields as specific humidity (`hus`) are still characterized by very large PIs (due to stratospheric low variances).
-
-Once the climatology is created, the script ``ecmean/utils/cmip6-clim-evaluate.py`` is used to run iteratively on a set of CMIP6 models and to compute the multi model mean of the PIs (for each region and season).
-This is then stored in the ``ecmean/climatology/{clim}/pi_climatology_{clim}.yml`` and then used to provide a ratio between the original PI and the CMIP6 ensemble. 
 

ecmean/__init__.py

@@ -1,6 +1,6 @@
 """ECmean4 module"""
 
-__version__ = '0.1.11'
+__version__ = '0.1.12'
 
 # functions to be accessible everywhere
 from ecmean.libs.diagnostic import Diagnostic