Skip to content

Commit bdba357

Browse files
author
BenMGeo
committed
adds more detail to the recipe explanation
adds the recipe as a file (not linked yet)
1 parent 27c5be7 commit bdba357

File tree

2 files changed

+141
-76
lines changed

2 files changed

+141
-76
lines changed

‎_episodes/first_example_recipe.md‎

Lines changed: 99 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -56,11 +56,11 @@ Recipes are the instructions that you give to ESMValTool that tell it what you w
5656

5757
Note that the authors, publications and references are to be named in the config-references.yml
5858

59-
This information
59+
This information ...
6060

6161
## How to run ESMValTool
6262

63-
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:
63+
Once you’ve set up your conda environment and installed ESMValTool (see episode #2 LINK) and set up your config-user.yml file to correctly match you local environment, (see episode #3 LINK), ESMValTool is invoked using a simple command:
6464
~~~
6565
esmvaltool -c configuration recipe
6666
~~~
@@ -69,63 +69,92 @@ esmvaltool -c configuration recipe
6969
To try your hand with a basic recipe, please work through this episode.
7070

7171

72-
## Example recipe
73-
This is a basic recipe that takes a simple dataset and produces a simple plot.
74-
Please copy and paste the following recipe into your ESMValTool working area with the name: recipe_example.yml
72+
## Introduction to the example recipe
73+
Threcipe presented here is a simple, basic recipe that takes a single dataset and produces a time series plot.
7574

76-
# ESMValTool
77-
# recipe_example.yml
78-
---
79-
documentation:
80-
description: |
81-
Demonstrate basic ESMValTool example
82-
83-
authors:
84-
- demora_lee
85-
- mueller_benjamin
86-
- swaminathan_ranjini
87-
88-
maintainer:
89-
- demora_lee
90-
91-
references:
92-
- demora2018gmd
93-
# Some plots also appear in ESMValTool paper 2.
94-
95-
projects:
96-
- ukesm
97-
98-
datasets:
99-
- {dataset: HadGEM2-ES, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1859, end_year: 2005, }
100-
101-
preprocessors:
102-
prep_timeseries: # For 0D fields
103-
annual_statistics:
104-
operator: mean
105-
106-
diagnostics:
107-
# --------------------------------------------------
108-
# Time series diagnostics
109-
# --------------------------------------------------
110-
diag_timeseries_temperature:
111-
variables:
112-
timeseries_variable:
113-
short_name: thetaoga
114-
preprocessor: prep_timeseries
115-
scripts:
116-
timeseries_diag:
117-
script: ocean/diagnostic_timeseries.py
75+
Please copy and paste the following recipe into your ESMValTool working area with the name: recipe_example.yml
11876

77+
>## recipe_example.yml
78+
>~~~YAML
79+
> # ESMValTool
80+
> # recipe_example.yml
81+
> ---
82+
> documentation:
83+
> description: Demonstrate basic ESMValTool example
84+
>
85+
> authors:
86+
> - demora_lee
87+
> - mueller_benjamin
88+
> - swaminathan_ranjini
89+
>
90+
> maintainer:
91+
> - demora_lee
92+
>
93+
> references:
94+
> - demora2018gmd
95+
> # Some plots also appear in ESMValTool paper 2.
96+
>
97+
> projects:
98+
> - ukesm
99+
>
100+
> datasets:
101+
> - {dataset: HadGEM2-ES, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1859, end_year: 2005}
102+
>
103+
> preprocessors:
104+
> prep_timeseries: # For 0D fields
105+
> annual_statistics:
106+
> operator: mean
107+
>
108+
> diagnostics:
109+
> # --------------------------------------------------
110+
> # Time series diagnostics
111+
> # --------------------------------------------------
112+
> diag_timeseries_temperature:
113+
> description: simple_time_series
114+
> variables:
115+
> timeseries_variable:
116+
> short_name: thetaoga
117+
> preprocessor: prep_timeseries
118+
> scripts:
119+
> timeseries_diag:
120+
> script: ocean/diagnostic_timeseries.py
121+
>~~~
122+
{: .solution}
119123
120124
> ## Explore the recipe
121-
>
122125
> Use the command and investigate the sample recipe.
123126
> ~~~
124-
> vim recipe.yml
127+
> vim recipe_example.yml
125128
> ~~~
126129
> {: .source}
127130
>
128-
> Please note the datasets, preprocessors, diagnostic sections.
131+
132+
Please note the following sections:
133+
- documentation: lines 4-20
134+
135+
The documentation consists of the following information:
136+
- description: a one line description of the recipe
137+
- authors: a list of authors (linked to esmvaltool/config-references.yml)
138+
- maintainer: a list of maintainers (linked to esmvaltool/config-references.yml)
139+
- references: a list of references (linked to a bibtexfile in esmvaltool/references with the same name)
140+
- projects: a list of projects (linked to esmvaltool/config-references.yml)
141+
142+
143+
- datasets: lines 22-23
144+
The dataset definition consists of a list of dictionaries with the information on the datasets.
145+
[List of entries?]
146+
147+
148+
- preprocessors: lines 25-28
149+
The definition for different preprocessors or combinations.
150+
[go into detail]
151+
152+
153+
- diagnostic section: lines 30-42
154+
The information of which diagnostic script to run with which variables.
155+
[go into detail]
156+
157+
129158
> What is the short_name of the variable being analysed?
130159
> What is the diagnostic script being used?
131160
> How many years of data are being analysed?
@@ -185,29 +214,23 @@ Please copy and paste the following recipe into your ESMValTool working area wit
185214
{: .challenge}
186215
187216
188-
> ## Common issues & tips
189-
>
190-
> ### Esmvaltool not found
191-
> Can you run the command “esmvaltool -h”. If no, then it’s possible that the conda environment isn’t activated. Please return to the installation section, epside [2] LINK.
192-
>
193-
> ### ESMValTool can’t locate the data
194-
> The error message is “esmvalcore._recipe_checks.RecipeError: Missing data”
195-
> Which computing machine are you using? Does your user-config.yml file reflect your machine's settings? Is the dataset’s name in the correct order?
196-
>
197-
>
198-
> ### Diagnostic path problems
199-
> The directory path to your diagnostics code is set relative to the esmvaltool/diag_scripts subdirectory. Is the code placed in this subdirectory? Is it spelled correctly?
200-
>
201-
>
202-
> ### FX files not found.
203-
>
204-
>
205-
> ### The preprocessor works but the diagnostic fails:
206-
> If your preprocessor works fine but your diagnostic script fails, congratulations! A failed diagnostic means that you won’t need to re-run the preprocessor. In your “run/main_log.txt” run output, you should see a line that reads: “To re-run this diagnostic script, run:”, followed by a line with a command that will allow you to re-run your diagnostic script only. Append this line with the “-i” option after the python script you call to re-run your diagnostic.
207-
>
208-
>
209-
> ### Your recipe’s name/project/reference isn’t recognised by ESMValTool.
210-
> Error message is “ValueError: Tag 'NAME' does not exist in section 'authors' of path/esmvaltool/config-references.yml”
211-
> Most likely, you added your own name to the recipe in the description section, but didn’t add it to the esmvaltool/config-references.yml file, where the names are linked to an email address, institute, and ORCID Identity.
212-
>
213-
{: .callout}
217+
## Common issues & tips
218+
219+
### Esmvaltool not found
220+
Can you run the command “esmvaltool -h”. If no, then it’s possible that the conda environment isn’t activated. Please return to the installation section, epside [2] LINK.
221+
222+
### ESMValTool can’t locate the data
223+
The error message is “esmvalcore._recipe_checks.RecipeError: Missing data”
224+
Which computing machine are you using? Does your user-config.yml file reflect your machine's settings? Is the dataset’s name in the correct order?
225+
226+
### Diagnostic path problems
227+
The directory path to your diagnostics code is set relative to the esmvaltool/diag_scripts subdirectory. Is the code placed in this subdirectory? Is it spelled correctly?
228+
229+
### FX files not found.
230+
231+
### The preprocessor works but the diagnostic fails:
232+
If your preprocessor works fine but your diagnostic script fails, congratulations! A failed diagnostic means that you won’t need to re-run the preprocessor. In your “run/main_log.txt” run output, you should see a line that reads: “To re-run this diagnostic script, run:”, followed by a line with a command that will allow you to re-run your diagnostic script only. Append this line with the “-i” option after the python script you call to re-run your diagnostic.
233+
234+
### Your recipe’s name/project/reference isn’t recognised by ESMValTool.
235+
Error message is “ValueError: Tag 'NAME' does not exist in section 'authors' of path/esmvaltool/config-references.yml”
236+
Most likely, you added your own name to the recipe in the description section, but didn’t add it to the esmvaltool/config-references.yml file, where the names are linked to an email address, institute, and ORCID Identity.

‎data/recipe_example.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# ESMValTool
2+
# recipe_example.yml
3+
---
4+
documentation:
5+
description: Demonstrate basic ESMValTool example
6+
7+
authors:
8+
- demora_lee
9+
- mueller_benjamin
10+
- swaminathan_ranjini
11+
12+
maintainer:
13+
- demora_lee
14+
15+
references:
16+
- demora2018gmd
17+
# Some plots also appear in ESMValTool paper 2.
18+
19+
projects:
20+
- ukesm
21+
22+
datasets:
23+
- {dataset: HadGEM2-ES, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1859, end_year: 2005}
24+
25+
preprocessors:
26+
prep_timeseries: # For 0D fields
27+
annual_statistics:
28+
operator: mean
29+
30+
diagnostics:
31+
# --------------------------------------------------
32+
# Time series diagnostics
33+
# --------------------------------------------------
34+
diag_timeseries_temperature:
35+
description: simple_time_series
36+
variables:
37+
timeseries_variable:
38+
short_name: thetaoga
39+
preprocessor: prep_timeseries
40+
scripts:
41+
timeseries_diag:
42+
script: ocean/diagnostic_timeseries.py

0 commit comments

Comments
 (0)