ESMValTool is mostly used as a command line tool. Whenever your Conda environment for ESMValTool is active, you can run the command esmvaltool. See running esmvaltool in the ESMValCore documentation for an introduction to the esmvaltool command.

Running your first recipe#

There is a step-by-step tutorial available in the ESMValTool tutorial on how to run your first recipe. It can be found here.

An example recipe is available in the ESMValTool installation folder as examples/recipe_python.yml.

This recipe finds data from BCC-ESM1 and CanESM2 and creates two plot types:

  • a global map plot that shows the monthly mean 2m surface air temperature in January 2000.

  • a time series plot that shows the globally averaged annual mean 2m surface air temperature and compares it to the one in Amsterdam.

To run this recipe and automatically download the required climate data from ESGF to the local directory ~/climate_data, run

esmvaltool run examples/recipe_python.yml --search_esgf=when_missing

The --search_esgf=when_missing option tells ESMValTool to search for and download the necessary climate data files, if they cannot be found locally. The data only needs to be downloaded once, every following run will re-use previously downloaded data. If you have all required data available locally, you can run the tool with --search_esgf=never argument (the default). Note that in that case the required data should be located in the directories specified in your user configuration file. A third option --search_esgf=always is available. With this option, the tool will first check the ESGF for the needed data, regardless of any local data availability; if the data found on ESGF is newer than the local data (if any) or the user specifies a version of the data that is available only from the ESGF, then that data will be downloaded; otherwise, local data will be used. Recall that the chapter Configuring ESMValTool provides an explanation of how to create your own config-user.yml file.

See running esmvaltool in the ESMValCore documentation for a more complete introduction to the esmvaltool command.

Available diagnostics and metrics#

Although ESMValTool can be used to download data, analyze it using ESMValCore’s preprocessing modules, and the creation of your own analysis code, its main purpose is the continuously growing set of diagnostics and metrics that it directly provides to the user. These metrics and diagnostics are provided as a set of preconfigured recipes that users can run or customize for their own analysis. The latest list of available recipes can be found here.

In order to make the management of these installed recipes easier, ESMValTool provides the recipes command group with utilities that help the users in discovering and customizing the provided recipes.

The first command in this group allows users to get the complete list of installed recipes printed to the console:

esmvaltool recipes list

If the user then wants to explore any one of these recipes, they can be printed using the following command

esmvaltool recipes show recipe_name.yml

Note that there is no recipe_name.yml shipped with ESMValTool, replace this with a recipes that is available, for example examples/recipe_python.yml. Finally, to get a local copy that can then be customized and run, users can run the following command

esmvaltool recipes get recipe_name.yml

Note that the esmvaltool run recipe_name.yml command will first look if recipe_name.yml is the path to an existing file. If this is the case, it will run that recipe. If not, it will look if it is a relative path to an existing recipe with respect to the recipes directory in your ESMValTool installation and run that.

Running multiple recipes#

Have a look at Running multiple recipes if you are interested in running multiple recipes in parallel.