Configuration ============= Configuration file ------------------ A template configuration file is included in the repository, with the folder definitions and all the details that can be manually adjusted. You will need to copy the original template to create your own local configuration file :: > cp config.tmpl config.yml and then edit the required folders before running the script. General configuration --------------------- These are the mandatory properties to be set up before running ecmean. interface The interface to access the model files (see below). So far supported interfaces are ``EC-Earth4``, ``CMIP6``, ``CMIP5``. model The model name: it could be ``EC-Earth4`` if running with the same interface, but could be any of the CMIP5/CMIP6 models. dirs: exp Where the data from the experiments are dirs: tab Where the output should be placed dirs: fig Where the output figures should be placed (for ``performance_indices`` only) .. note:: You could call a specific configuration file with ``-c config_myconfig.yml`` when executing the |ecmean| commands (see Usage section), so that you can have multiple models on the same machine. Global Mean configuration ------------------------- The configuration file also defines the details of the global mean. Modifications to this are not necessary, but please be aware that the variable convention follows a CMOR-like definition. **variables**: the main block to control variables. It is divided in three sub-blocks: ``atm``, ``oce`` and ``ice``. Each of them contains the list of fields to be processed. ``atm`` includes atmospheric fields, ``oce`` includes oceanic fields and ``ice`` includes sea-ice fields. ``tab`` includes the list of fields to be reported in the output table. **regions**: the list of regions on which compute the PI. Four regions are supported. Supported regions are: ``Global`` (90S-90N), ``North Midlat`` (30N-90N), ``Tropical`` (30S-30N), ``South Midlat`` (90S-30S). For EC26 reference, other regions are also available: ``NH`` (20N-90N), ``SH`` (20S-90S), ``Equatorial`` (20S-20N), ``North Pole`` (60N-90N), ``South Pole`` (60S-90S). **seasons**: the list of seasons on which to compute the PI. Four standard seasons are supported, expressed as 3-character strings (e.g. ``DJF``). ``ALL`` defines the yearly average. Default includes yearly, winter and summer. **reference**: the global mean reference climatology. EC23 (without the tas global variable and for the period 1990-2020), HIST26 (with the tas global variable and for the period 1980-2010) and PDAY26 (with the tas global variable available and for the period 2000-2024) are available. Performance indices configuration --------------------------------- The configuration file also defines the details of the performance indices. Modifications to this are not necessary, but please be aware that the variable convention follows a CMOR-like definition. **variables**: The main block to control variables. All blocks should be lists. It is divided into four sub-blocks: ``atm2d``, ``atm3d``, ``oce`` and ``ice``. Each of them contains the list of fields to be processed. ``atm2d`` includes atmospheric 2d fields, ``atm3d`` includes atmospheric 3d fields, ``oce`` includes oceanic fields and ``ice`` includes sea-ice fields. **regions**: the list of regions on which to compute the PI. Four regions are supported. Default regions are: ``Global`` (90S-90N), ``North Midlat`` (30N-90N), ``Tropical`` (30S-30N), ``South Midlat`` (90S-30S). For EC24 and EC26 climatologies, other regions are also available: ``NH`` (20N-90N), ``SH`` (20S-90S), ``Equatorial`` (20S-20N), ``North Pole`` (60N-90N), ``South Pole`` (60S-90S). **seasons**: the list of seasons on which to compute the PI. ``ALL`` defines the yearly average. Also ``DJF`` and ``JJA`` are supported. **climatology**: the climatology to be used. EC23, EC24, HIST26 (for the period 1980-2010) and PDAY26 (for the period 2000-2024) are available. Interface files --------------- Conversion from model variables - as well as the correspondent file structure - is handled by an interface-dependent file ``ecmean/interfaces/interface_*.yml`` that can support EC-Earth4, CMIP5 and CMIP6 models. New interface files can be developed exploiting the flexible file handling to increase the range of supported models. It is important to provide land-sea masks for both atmospheric and oceanic grids, and when possible - recommended for non-regular grids - it is important to also provide files indicating grid cell areas. These latter are used for interpolation and weighted averages. ecmean has a few routines that try to compute each grid cell area from lon/lat boundaries, but this can fail for non-regular grids. .. note:: It is not necessary to modify the interface file, but it could be required if - for example - your CMIP5/6 directory tree does not reflect exactly the one available on ESGF. Of course, if some specific management of the model grid is requested - for example if the model grid does not follow standard naming conventions - it may be necessary to intervene directly within the code. A function named ``xr_preproc()`` within ``ecmean/libs/ncfixers.py`` might be adjusted in this case to allow for a correct interpretation of the model grid. CMOR compatibility ------------------ It is possible to use |ecmean| tools also to analyze CMOR-like files for CMIP5 or CMIP6. This assumes a standard ESGF directory structure but you can change it by modifying the corresponding interface files ``ecmean/interfaces/interface_CMIP5.yml`` and ``ecmean/interfaces/interface_CMIP6.yml``. In order to allow masking and interpolation you will need some files to guide |ecmean|. ``fx`` variables ``sftlf`` and ``areacella`` are required for the atmospheric domain, while ``Ofx`` variables ``sftof`` and ``areacello`` are required for the oceanic domain. At least one of these files is required for each domain, but it is recommended to provide both.