Skip to content

Commit ed0bc8a

Browse files
author
BenMGeo
committed
Draft for new "episode 4"
1 parent 203c592 commit ed0bc8a

File tree

2 files changed

+189
-52
lines changed

2 files changed

+189
-52
lines changed

‎_episodes/04-toy-example.md‎

Lines changed: 0 additions & 52 deletions
This file was deleted.

‎_episodes/first_example_recipe.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
title: "Running a recipe (First example)"
3+
teaching: 10
4+
exercises: 25
5+
questions:
6+
- "What is a recipe?"
7+
- "How can I do the same preprocessing on many different datasets?"
8+
- "What are the files and directories after running a recipe?"
9+
- "What happens when I run a recipe?"
10+
objectives:
11+
- "Run an ESMValTool recipe"
12+
- "Understand the purpose of different settings in the recipe"
13+
- "Inspect the output directories"
14+
- "Examine the log information"
15+
keypoints:
16+
- "A recipe does not break by fiddling with it"
17+
- "Log information is useful to How to interpret the first warnings/errors"
18+
- "The dataset section in the recipe relates to Understanding the directory structure of CMIP data on your server/disk and knowing how to use data from different experiments such as CMIP/ScenarioMIP."
19+
---
20+
21+
This episode describes how ESMValTool recipes work, how to run a recipe and how to explore the recipe output. By the end of this episode, you should be able to run your first recipe, look at the recipe output, modify a recipe, explore and run some basic recipe debugging.
22+
23+
## Introduction to Recipes
24+
25+
Recipes are the instructions that you give to ESMValTool that tell it what you want to do. This includes four main section:
26+
- datasets: what datasets you want to use
27+
- the time range and time resolution,
28+
- the MIP, ensemble member,
29+
- the experiment (ie historical, ssp125 etc...)
30+
- the grid type (CMIP6 only)
31+
- This section can also be optional, as datasets can no preprocessing is needed.
32+
33+
- proprocessors: one or preprocessors
34+
- which preprocessor modules to apply
35+
- the order to apply them
36+
- and the preprocesor arguments.
37+
- This section can also be optional, if no preprocessing is needed.
38+
39+
- diagnostics: All the information about diagnostic
40+
-
41+
42+
- description: a brief description of the recipe
43+
- who wrote the recipe, and who maintains it
44+
- which project is responsible for it
45+
- which publications, reference are linked with the recipe
46+
- Note that the authors, publications and references and named in the config-references.yml
47+
48+
This information
49+
50+
## How to run ESMValTool
51+
52+
Once you’ve set up your conda environment and installed ESMValTool (See episode #2) and set up your config-user.yml file to correctly match you local environment, (see episode #3), ESMValTool is invoked using a simple command:
53+
~~~
54+
esmvaltool -c configuration recipe
55+
~~~
56+
57+
To try your hand with a basic recipe, please work through this episode.
58+
59+
60+
## Example recipe
61+
This is a basic recipe that takes a simple dataset and produces a simple plot.
62+
Please copy and paste the following recipe into your ESMValTool working area with the name: recipe_example.yml
63+
64+
# ESMValTool
65+
# recipe_example.yml
66+
---
67+
documentation:
68+
description: |
69+
Demonstrate basic ESMValTool example
70+
71+
authors:
72+
- demora_lee
73+
- Ben
74+
- Ranjini
75+
76+
maintainer:
77+
- demora_lee
78+
79+
references:
80+
- demora2018gmd
81+
# Some plots also appear in ESMValTool paper 2.
82+
83+
projects:
84+
- ukesm
85+
86+
87+
preprocessors:
88+
# --------------------------------------------------
89+
# Time series preprocessors
90+
# --------------------------------------------------
91+
prep_timeseries: # For 0D fields
92+
multi_model_statistics:
93+
span: full
94+
statistics: [mean ]
95+
96+
97+
diagnostics:
98+
# --------------------------------------------------
99+
# Time series diagnostics
100+
# --------------------------------------------------
101+
diag_timeseries_temperature:
102+
variables:
103+
thetaoga:
104+
preprocessor: prep_timeseries
105+
additional_datasets:
106+
- {dataset: CESM1-BGC, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1850, end_year: 2005, }
107+
- {dataset: CNRM-CM5, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1850, end_year: 2005, }
108+
- {dataset: CSIRO-Mk3-6-0, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1850, end_year: 2005, }
109+
- {dataset: CanESM2, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1850, end_year: 2005, }
110+
- {dataset: GFDL-ESM2M, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1861, end_year: 2005, }
111+
- {dataset: HadGEM2-ES, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1859, end_year: 2005, }
112+
- {dataset: IPSL-CM5A-LR, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1850, end_year: 2005, }
113+
- {dataset: MIROC-ESM, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1850, end_year: 2005, }
114+
- {dataset: MPI-ESM-LR, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1850, end_year: 2005, }
115+
- {dataset: NorESM1-M, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1850, end_year: 2005, }
116+
scripts:
117+
timeseries_diag:
118+
script: ocean/diagnostic_timeseries.py
119+
120+
> ## Explore the recipe
121+
>
122+
> Use the command and investigate the sample recipe.
123+
> vim recipe.yml
124+
>
125+
> Please note the datasets, preprocessors, diagnostic sections.
126+
> What is the short_name of the variable being analysed?
127+
> What is the diagnostic script being used?
128+
> How many years of data are being analysed?
129+
> What do you think running this recipe will produce?
130+
{: .challenge}
131+
132+
> ## Not all parts of the recipe are mandatory
133+
> Some functionalities of the example recipe are mandatory, while others are not. E.g., if you miss any of the documentation information, the call will break.
134+
{: .callout}
135+
136+
> ## Running ESMValTool
137+
>
138+
> Use the command:
139+
> esmvaltool -c user-config.yml recipe_example.yml
140+
>
141+
> What
142+
{: .challenge}
143+
144+
145+
> ## Inspect the output:
146+
> Now that you have run the esmvaltool command for the first time, please locate your output directory.
147+
> Each time you run ESMValTool, it will produce a new output directory with the format:
148+
> This directory should contain four folders:
149+
> run work preproc plots
150+
> If you’re missing the preproc directory, then your config-user.yml file has the value remove_preproc_dir set to true.
151+
152+
153+
>
154+
> Please locate and inspect the following files:
155+
> You output plot(s).
156+
> Your main output log file
157+
> Your settings.yml file
158+
> A metadata.yml file
159+
{: .discussion}
160+
161+
162+
> ## Edit the recipe and run
163+
> So far, the example recipe has used global volume-weighted ocean temperature. Please edit this recipe to investigate one of the following fields:
164+
> Land surface temperature
165+
> Atmospheric surface temperature
166+
> Ocean surface temperature (tos)
167+
> You will need to edit the dataset request, c
168+
{: .challenge}
169+
170+
171+
> ## Common issues & tips
172+
>
173+
> ### ESMValTool can’t locate the data
174+
> User didn’t correctly edit user-config.yml
175+
>
176+
> ### Esmvaltool not found
177+
> User didn’t active or correctly install conda
178+
>
179+
> ### Diagnostic path problems
180+
> explain ESMValTool’s methods to determine diagnostic path, and how it should appear in the recipe
181+
>
182+
> ### FX files not found.
183+
>
184+
> ### The preprocessor works but the diagnostic fails:
185+
> How to tell them appart and how to re-run a failed diagnostic (but not the preprocessor)
186+
>
187+
> ### Your recipe’s name/project/reference isn’t recognised by ESMValTool.
188+
>
189+
{: .callout}

0 commit comments

Comments
 (0)