Quickstart guide#

Overview

Timings
  • Teaching: 2 min

  • Exercises: 8 min

Questions
  • What is the purpose of the quickstart guide?

  • How do I load and check the ESMValTool environment?

  • How do I configure ESMValTool?

  • How do I run a recipe?

Learning outcomes
  • Understand the purpose of the quickstart guide

  • Load and check the ESMValTool environment

  • Configure ESMValTool

  • Run a recipe

Compatibility

ESMValTool v2.16.0

What is the purpose of the quickstart guide?#

The purpose of the quickstart guide is to enable a user of ESMValTool to run ESMValTool as quickly as possible by making the minimum number of changes.

Purpose of the quickstart guide

The purpose of this quickstart guide is to get you running with ESMValTool as quickly as possible without requiring a full tutorial walkthrough.

How do I load and check the ESMValTool environment?#

For this quickstart guide, it is assumed that ESMValTool has already been installed at the site where it will be run. If this is not the case, see the Installation episode in this tutorial.

Load the ESMValTool environment by following the instructions in the ESMValTool installation and environment activation guide. This will typically involving loading a module like so:

module load esmvaltool

Check the ESMValTool environment by accessing the help for ESMValTool:

esmvaltool --help

Check the ESMValTool environment

Run the command above to confirm that your ESMValTool environment is loaded correctly and that the command-line interface is available.

How do I configure ESMValTool?#

Create the ESMValTool user configuration file. By default, this file is written to ~/.config/esmvaltool/config-user.yml:

esmvaltool config copy defaults/config-user.yml

Edit the ESMValTool user configuration file using your favourite text editor to uncomment the lines relating to the site where ESMValTool will be run.

For more details about the ESMValTool user configuration file, see the Configuration episode in this tutorial.

Configure the tool

Create the user configuration file and adjust the settings for the machine on which you are running ESMValTool.

How do I run a recipe?#

Run the example Python recipe:

esmvaltool run examples/recipe_python.yml

Wait for the recipe to complete. If the recipe completes successfully, the last line printed to the screen at the end of the log will look something like:

YYYY-MM-DD HH:mm:SS, NNN UTC [NNNNN] INFO    Run was successful

View the output of the recipe by opening the HTML file produced by ESMValTool. The location of this file is printed to the screen near the end of the log:

YYYY-MM-DD HH:mm:SS, NNN UTC [NNNNN] INFO    Wrote recipe output to:
file:///$HOME/esmvaltool_output/recipe_python_[DATE]_[TIME]/index.html

For more details about running recipes, see the Running your first recipe episode in this tutorial.

Run an example recipe

Try running the example recipe above and confirm that the run completes successfully before moving on to other recipes.

Conclusion#

This quickstart guide introduces the minimum steps needed to get ESMValTool running on your system. Once the environment is loaded, configured, and a recipe has been run successfully, you are ready to explore the wider tutorial and more advanced workflows.

Key points

  • The purpose of the quickstart guide is to enable a user to run ESMValTool as quickly as possible without having to go through the whole tutorial.

  • Use module load to load the ESMValTool environment.

  • Use esmvaltool --help to check that the environment is working.

  • Use esmvaltool config copy defaults/config-user.yml to create the user configuration file.

  • Use esmvaltool run [RECIPE].yml to run a recipe.