Quickstart guide#
Overview
Teaching: 2 min
Exercises: 8 min
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?
Understand the purpose of the quickstart guide
Load and check the ESMValTool environment
Configure ESMValTool
Run a recipe
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 loadto load the ESMValTool environment.Use
esmvaltool --helpto check that the environment is working.Use
esmvaltool config copy defaults/config-user.ymlto create the user configuration file.Use
esmvaltool run [RECIPE].ymlto run a recipe.