Skip to content

Commit b3701c3

Browse files
SarahAlidoostSarahAlidoost
committed
update the content
1 parent 1451b50 commit b3701c3

File tree

1 file changed

+298
-8
lines changed

1 file changed

+298
-8
lines changed

‎_episodes/06-debugging.md‎

Lines changed: 298 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,309 @@
11
---
2-
title: "Creating a diagnostic script"
2+
title: "Debugging"
33
teaching: 0
44
exercises: 0
55
questions:
6-
- "Key question (FIXME)"
6+
- "How can I handle errors/warnings?"
77
objectives:
8-
- "First learning objective. (FIXME)"
8+
- "Fix a broken recipe"
99
keypoints:
10-
- "First key point. Brief Answer to questions. (FIXME)"
10+
- "The log files contain information about errors and warnings."
1111
---
12-
FIXME
1312

14-
{% include links.md %}
13+
Every user encounters errors. Once you know why you get certain types of errors,
14+
they become much easier to fix.
15+
The good news is, ``ESMValTool`` creates a record of the output messages and stores them in log files.
16+
They can be used for debugging or monitoring the process.
17+
This lesson helps to understand what the different types of errors are and when you are likely to encounter them.
18+
19+
## log files
20+
21+
Each time we run the ESMValTool, it will produce a new output directory.
22+
This directory should contain the ``run`` folder that is automatically generated by ESMValTool.
23+
To examine this, we run an example recipe that can be found in:
24+
[recipe_example.yml](link).
25+
Let's download it to our working directory ``esmvaltool_tutorial`` that was created during
26+
the [Setup]({{ page.root }}{% link setup.md %}).
27+
28+
In a new terminal, go to our working directory ``esmvaltool_tutorial`` where
29+
both files ``user-config.yml`` and ``recipe_example.yml`` are located and run the recipe:
30+
31+
~~~bash
32+
cd esmvaltool_tutorial
33+
esmvaltool -c user-config.yml recipe_example.yml
34+
~~~
35+
36+
~~~
37+
esmvaltool: command not found
38+
~~~
39+
{: .error}
40+
41+
ESMValTool encounters this error because
42+
the conda environment ``esmvaltool`` has not been activated.
43+
To fix the error, before running the recipe, activate the environment:
44+
45+
~~~bash
46+
conda activate esmvaltool
47+
~~~
48+
49+
> ## conda environment
50+
>
51+
> More information about conda environment can be found at
52+
[Installation]({{ page.root }}{% link _episodes/02-installation.md %})
53+
{: .callout}
54+
55+
Let's change the working directory to the folder ``run`` and list its files:
56+
57+
~~~bash
58+
cd path_to_output_directory/run
59+
ls
60+
~~~
61+
62+
~~~
63+
main_log_debug.txt main_log.txt recipe_example.yml resource_usage.txt
64+
~~~
65+
{: .output}
66+
67+
In the ``main_log_debug.txt`` and ``main_log.txt``, ESMValTool tells us the output messages,
68+
warnings and possible errors that might happen during pre-processings.
69+
To inspect them, we can look inside the files. For example:
70+
71+
~~~bash
72+
cat main_log.txt
73+
~~~
74+
75+
> ## Different log files
76+
>
77+
> In the ``run`` directory, there are two log files ``main_log_debug.txt`` and ``main_log.txt``.
78+
What are their differences?
79+
>
80+
>> ## Solution
81+
>>
82+
>> The ``main_log_debug.txt`` contains the output messages from the pr-processors whereas
83+
the ``main_log.txt`` shows general errors and warnings that might happen in running the recipe and diagnostics script.
84+
> {: .solution}
85+
{: .challenge}
86+
87+
If you encounter an error and don’t know what it means, it is important to read the log information.
88+
Sometimes knowing where the error occurred is enough to fix it, even if you don’t entirely understand the message.
89+
However, note that you may not always be able to find the error or fix it.
90+
In that case, ESMValTool community helps you figure out what went wrong.
91+
92+
Let's change some settings in the recipe to run a regional pre-processor.
93+
We run a text editor called ``Nano`` to open the recipe file:
94+
95+
~~~bash
96+
cd esmvaltool_tutorial
97+
nano recipe_example.yml
98+
~~~
99+
100+
> ## Text editor side note
101+
>
102+
> No matter what editor you use, you will need to know where it searches
103+
for and saves files. If you start it from the shell, it will (probably)
104+
use your current working directory as its default location. We use ``nano``
105+
in examples here because it is one of the least complex text editors.
106+
Press <kbd>ctrl</kbd> + <kbd>O</kbd> to save the file,
107+
and then <kbd>ctrl</kbd> + <kbd>X</kbd> to exit ``nano``.
108+
{: .callout}
109+
110+
>## See the recipe_example.yml
111+
>~~~YAML
112+
>01 # ESMValTool
113+
>02 # recipe_example.yml
114+
>03 ---
115+
>04 documentation:
116+
>05 description: Demonstrate basic ESMValTool example
117+
>06
118+
>07 authors:
119+
>08 - demora_lee
120+
>09 - mueller_benjamin
121+
>10 - swaminathan_ranjini
122+
>11
123+
>12 maintainer:
124+
>13 - demora_lee
125+
>14
126+
>15 references:
127+
>16 - demora2018gmd
128+
>17 # Some plots also appear in ESMValTool paper 2.
129+
>18
130+
>19 projects:
131+
>20 - ukesm
132+
>21
133+
>22 datasets:
134+
>23 - {dataset: HadGEM2-ES, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1859, end_year: 2005}
135+
>24
136+
>25 preprocessors:
137+
>26 prep_timeseries: # For 0D fields
138+
>27 annual_statistics:
139+
>28 operator: mean
140+
>29
141+
>30 diagnostics:
142+
>31 # --------------------------------------------------
143+
>32 # Time series diagnostics
144+
>33 # --------------------------------------------------
145+
>34 diag_timeseries_temperature:
146+
>35 description: simple_time_series
147+
>36 variables:
148+
>37 timeseries_variable:
149+
>38 short_name: thetaoga
150+
>39 preprocessor: prep_timeseries
151+
>40 scripts:
152+
>41 timeseries_diag:
153+
>42 script: ocean/diagnostic_timeseries.py
154+
>~~~
155+
{: .solution}
156+
157+
We change the ``projects`` value ``ukesm`` to ``tutorial``:
158+
~~~YAML
159+
19 projects:
160+
20 - tutorial
161+
~~~
15162
16-
Important part here is to introduce the standard tools that allow users to access ESMValTool settings configs.
163+
Also, let's add the preprocessor ``extract_region`` to the section ``prep_timeseries``:
17164

165+
~~~YAML
166+
25 preprocessors:
167+
26 prep_timeseries: # For 0D fields
168+
27 annual_statistics:
169+
28 operator: mean
170+
29 extract_region:
171+
30 start_longitude: -10
172+
31 end_longitude: 40
173+
32 start_latitude: 27
174+
33 end_latitude: 70
175+
~~~
18176

19-
This file should be renamed to advanced: creating a diagnostic
177+
Then, we save the file and run the recipe:
178+
~~~bash
179+
esmvaltool -c user-config.yml recipe_example.yml
180+
~~~
181+
182+
~~~
183+
ValueError: Tag 'tutorial' does not exist in section 'projects' of esmvaltool/config-references.yml
184+
2020-06-29 18:09:56,641 UTC [46055] INFO If you suspect this is a bug or need help,
185+
please open an issue on https://github.com/ESMValGroup/ESMValTool/issues and
186+
attach the run/recipe_*.yml and run/main_log_debug.txt files from the output directory.
187+
~~~
188+
{: .error}
189+
190+
The values for the keys ``author``, ``maintainer``, ``projects`` and ``references`` in the recipe should be known by ESMValTool.
191+
192+
> ## ESMValTool pre-processors
193+
>
194+
> The [ESMValTool pre-processors](https://docs.esmvaltool.org/projects/ESMValCore/en/latest/recipe/preprocessor.html?highlight=preprocessor) cover a broad range of operations on the input data,
195+
like time manipulation, area manipulation, land-sea masking, variable derivation, ... .
196+
{: .callout}
197+
198+
> ## ESMValTool can’t locate the data
199+
>
200+
> You are assisting a researcher with ``ESMValTool``. The researcher changes the ``project`` entry to ``CMIP6``
201+
and runs the recipe. However, ESMValTool encounters an error like:
202+
>
203+
~~~bash
204+
esmvalcore._recipe_checks.RecipeError: Missing data
205+
2020-06-29 17:26:41,303 UTC [43830] INFO If you suspect this is a bug or need help,
206+
please open an issue on https://github.com/ESMValGroup/ESMValTool/issues and
207+
attach the run/recipe_*.yml and run/main_log_debug.txt files from the output directory.
208+
~~~
209+
What suggestions would you give the researcher for fixing the error?
210+
>
211+
>> ## Solution
212+
>>
213+
>> 1. inspect the ``main_log.txt``
214+
>> 2. check the user-config.yml to see if the correct directory for input data is introduced.
215+
>> 3. check the available data, regarding exp, mip, ensemble, start_year, and end_year
216+
>> 4. check the variable name in the ``diag_timeseries_temperature`` section in the recipe.
217+
> {: .solution}
218+
{: .challenge}
219+
220+
> ## Check pre-processed data
221+
>
222+
> The setting ``save_intermediary_cubes`` in the configuration file can be used
223+
save the pre-processed data. More information about this setting can be found at
224+
[Configuration]({{ page.root }}{% link _episodes/03-configuration.md %})
225+
{: .callout}
226+
227+
The result of the pre-processors is passed to the ``diagnostic_timeseries.py`` script,
228+
that is introduced in the recipe as:
229+
230+
~~~YAML
231+
40 scripts:
232+
41 timeseries_diag:
233+
42 script: ocean/diagnostic_timeseries.py
234+
~~~
235+
236+
The diagnostic scripts are located in the folder ``diag_scripts`` in
237+
the ESMValTool installation directory ``path_to_esmvaltool``.
238+
To find ``path_to_esmvaltool`` on your system,
239+
see [Installation]({{ page.root }}{% link_episodes/02-installation.md %}).
240+
241+
let's see if we can change the script path as:
242+
243+
~~~YAML
244+
40 scripts:
245+
41 timeseries_diag:
246+
42 script: diag_scripts/ocean/diagnostic_timeseries.py
247+
~~~
248+
249+
~~~bash
250+
esmvaltool -c user-config.yml recipe_example.yml
251+
~~~
252+
253+
~~~
254+
esmvalcore._task.DiagnosticError: Cannot execute script 'diag_scripts/examples/diagnostic.py' (esmvaltool/diag_scripts/diag_scripts/examples/diagnostic.py): file does not exist.
255+
2020-06-29 20:39:31,669 UTC [53008] INFO If you suspect this is a bug or need help, please open an issue on https://github.com/ESMValGroup/ESMValTool/issues and attach the run/recipe_*.yml and run/main_log_debug.txt files from the output directory.
256+
~~~
257+
{: .error}
258+
259+
The script path should be relative to ``diag_scripts`` directory.
260+
It means that the script ``diagnostic_timeseries.py`` is located in ``path_to_esmvaltool/diag_scripts/ocean/``.
261+
Alternatively, the script path can be an absolute path.
262+
To examine this, we change the script path and run the recipe:
263+
264+
~~~YAML
265+
40 scripts:
266+
41 timeseries_diag:
267+
42 script: path_to_esmvaltool/diag_scripts/ocean/diagnostic_timeseries.py
268+
~~~
269+
270+
~~~bash
271+
esmvaltool -c user-config.yml recipe_example.yml
272+
~~~
273+
274+
> ## Available recipe and diagnostic scripts
275+
>
276+
> ESMValTool provides a broad suite of
277+
[recipes and diagnostic](https://docs.esmvaltool.org/en/latest/recipes/index.html)
278+
scripts for different disciplines like atmosphere, climate metrics, future projections,
279+
IPCC, land, ocean, ....
280+
{: .callout}
281+
282+
> ## Re-running a diagnostic
283+
>
284+
> Look at the ``main_log.txt`` file and answer the following question:
285+
How to re-run the diagnostic script?
286+
>
287+
>> ## Solution
288+
>>
289+
>> The ``main_log.txt`` file contains information on how to re-run the diagnostic script
290+
without re-running the pre-processors:
291+
>>
292+
~~~bash
293+
2020-06-29 20:36:32,844 UTC [52810] INFO To re-run this diagnostic script, run:
294+
~~~
295+
>>
296+
>> If you run the command in the next line, you will be able to re-run the diagnostic.
297+
> {: .solution}
298+
{: .challenge}
299+
300+
> ## Memory issues
301+
>
302+
> If you run out of memory, try setting ``max_parallel_tasks`` to 1.
303+
Then, check the amount of memory you need for that by inspecting
304+
the file ``run/resource_usage.txt`` in the output directory.
305+
Using the number there you can increase the number of parallel tasks again to a reasonable number
306+
for the amount of memory available in your system.
307+
{: .callout}
308+
309+
{% include links.md %}

0 commit comments

Comments
 (0)