Running a recipe

This chapter explains how to run a recipe in ESMValTool.

Finding a suitable recipe

When searching for a suitable or interesting recipe for your use case, the first place to look is the ESMValTool documentation on all available recipes. This documentation however does not offer to browse through all the figures the recipes produce. This is however provided by DKRZ. In case you are searching for diagnostics for a specific variable or based on an interest to compare with observations, Tab. 1. Eyring et al. (2020) is a good source. A similar but not that extensive categorisation of recipes is available here. It tries to give extra information on whether the diagnostics are single or multi model(s)/member(s) as well as for which CMIP generation the recipe is originally written and therefore optimised.

For a simple overview of the recipes sorted by name use the command

esmvaltool recipes list

The chosen recipes can afterwards be downloaded by

esmvaltool recipes get recipe_name.yml

Executing a recipe

To run a recipe a user configuration file is necessary config-user.yml. In this file information about the input data path and the output directory is defined. It also specifies additional directories, for auxiliary variables, and data which possibly was downloaded from ESGF. A parameter enables to decide whether to search data on ESGF or not. For using ESGF an extra file with login parameters is needed (esgf-pyclient.yml). The recipe can be executed in three ways:

a) by calling esmvaltool directly from the terminal prompt:

esmvaltool run recipe_example.yml

In case of not using esmvaltool downloaded with conda but downloaded with singularity, as it is the case for CERFACS data and compute server Scylla, defining an alias might be necessary.

alias esmvaltool='module purge ; module load tools/singularity ; singularity run -B /archive -B /data/scratch /data/softs/local/singularity/images/esmvaltool28.sif'

b) Alternatively, it is possible to run the recipe by submitting a sbatch job. The recipe is defined inside that file. This might be the preferred way of executing a recipe. Within the job-file, the same command as above is used.

sbatch esmvaltool_singularity.job

c) we can as well run the recipe in a Python API.

from esmvalcore._main import ESMValTool
esm = ESMValTool()
esm.run(recipe, **kwargs)

This function is very versatile in its arguments. An argument can be e.g. any key from the config-user file such as search_esgf or output_dir or useful booleans like skip_nonexistent which indicates to skip not available datasets. With check_level it is possible to customize the data checker strictness, meaning that one can control which issues are interpreted as errors. One can find the exhaustive list of possible arguments by having a look in esmvalcore in the class ESMValTool function run.