Merge remote-tracking branch 'origin/main' into update_episode_cmorize

Author: LisaBock

.github/workflows/build-check-tutorial-site.yml

@@ -6,7 +6,7 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: "ubuntu-latest"
     steps:
     - uses: actions/checkout@v2
     - name: Setup Ruby

_episodes/00-introduction.md

@@ -2,7 +2,7 @@
 title: "Introduction"
 teaching: 5
 exercises: 10
-compatibility: ESMValTool v2.11.0
+compatibility: ESMValTool v2.12.0
 
 questions:
 - What is ESMValTool?

_episodes/01-quickstart.md

@@ -2,7 +2,7 @@
 title: "Quickstart guide"
 teaching: 2
 exercises: 8
-compatibility: ESMValTool v2.10.0
+compatibility: ESMValTool v2.12.0
 
 questions:
 
@@ -107,4 +107,4 @@ keypoints:
 >   [Running your first recipe][lesson-recipe] episode in this tutorial.
 {: .challenge}
 
-{% include links.md %}
+{% include links.md %}

_episodes/02-installation.md

@@ -2,7 +2,7 @@
 title: "Installation"
 teaching: 10
 exercises: 10
-compatibility: ESMValTool v2.10.0
+compatibility: ESMValTool v2.12.0
 questions:
 - "What are the prerequisites for installing ESMValTool?"
 - "How do I confirm that the installation was successful?"
@@ -146,52 +146,6 @@ installed in it.
 >
 {: .callout}
 
-### Install Julia
-
-Some ESMValTool diagnostics are written in the Julia programming language.
-If you want a full installation of ESMValTool including Julia diagnostics, you need
-to make sure Julia is installed before installing ESMValTool.
-
-In this tutorial, we will not use Julia, but for reference, we have listed the steps
-to install Julia below.
-Complete instructions for installing Julia can be found on the [Julia
-installation page](https://julialang.org/downloads/platform/#linux_and_freebsd).
-
-> ## Julia installation instructions
->
-> First, open a bash terminal and activate the newly created `esmvaltool` environment.
->
-> ```bash
-> conda activate esmvaltool
-> ```
->
-> Next, to install Julia via `mamba`, you can use the following command:
->
-> ```bash
-> mamba install julia
-> ```
-> 
-> To check that the Julia executable can be found, run
->
-> ```bash
-> which julia
-> ```
->
-> to display the path to the Julia executable, it should be
->
-> ```
-> ~/mambaforge/envs/esmvaltool/bin/julia
-> ```
-> {: .output}
->
-> To test that Julia is installed correctly, run
->
-> ```bash
-> julia
-> ```
->
-> to start the interactive Julia interpreter. Press `Ctrl+D` to exit.
-{: .solution}
 
 ### Test that the installation was successful
 
@@ -229,13 +183,13 @@ to display the command line help.
 > > {: .bash}
 > > The version of ESMValTool installed should be displayed on the screen as:
 > > ~~~
-> > ESMValCore: 2.10.0
-> > ESMValTool: 2.10.0
+> > ESMValCore: 2.12.0
+> > ESMValTool: 2.12.0
 > > ~~~
 > > {: .output}
 > Note that on HPC servers such as JASMIN, sometimes a more recent development 
 > version may be displayed for ESMValTool, for e.g. 
-> `ESMValTool: 2.9.0.dev4+g6948d5512`
+> `ESMValTool: 2.12.0.dev71+g2c60b4d97`
 > {: .solution}
 {: .challenge}
 

_episodes/03-configuration.md

@@ -2,7 +2,7 @@
 title: "Configuration"
 teaching: 10
 exercises: 10
-compatibility: ESMValTool v2.10.0
+compatibility: ESMValTool v2.12.0
 
 questions:
 - What is the user configuration file and how should I use it?
@@ -22,7 +22,7 @@ keypoints:
 
 ## The configuration file
 
-For the purposes of this tutorial, we will create a directory in our home directory
+First, for the purposes of this tutorial, we will create a directory in our home directory
 called `esmvaltool_tutorial` and use that as our working directory. The following steps 
 should do that:
 
@@ -38,29 +38,32 @@ This is a [YAML file](https://yaml.org/spec/1.2/spec.html).
 You can get the default configuration file by running:
 
 ~~~bash
-  esmvaltool config get_config_user --path=<target_dir>
+  esmvaltool config get_config_user
 ~~~
-The default configuration file will be downloaded to the directory specified with 
-the `--path` variable. For instance, you can provide the path to your working directory 
-as the `target_dir`. If this option is not used, the file will be saved to the default 
-location: `~/.esmvaltool/config-user.yml`, where `~` is the
+The default configuration file will be downloaded to the default location: 
+`~/.config/esmvaltool/config-user.yml`, where `~` is the
 path to your home directory. Note that files and directories starting with a
-period are "hidden", to see the `.esmvaltool` directory in the terminal use
-`ls -la ~`. Note that if a configuration file by that name already exists in the default 
+period are "hidden", to see the `.config` directory in the terminal use
+`ls -la ~`. 
+With the optional ``--path=<target_dir>`` you can specifiy the directory
+in which the configuration file can be saved. For instance, you can provide
+the path to your working directory as the `target_dir`. 
+Note, if a configuration file by that name already exists in the default 
 location, the `get_config_user` command will not update the file as ESMValTool will not 
 overwrite the file. You will have to move the file first if you want an updated copy of the 
-user configuration file.
+default user configuration file.
 
 
 
 We run a text editor called ``nano`` to have a look inside the configuration file
 and then modify it if needed:
 
 ~~~bash
-  nano ~/.esmvaltool/config-user.yml
+  nano ~/.config/esmvaltool/config-user.yml
 ~~~
 
-Any other editor can be used, e.g.vim.
+If ``nano`` does not work on your system, or if you prefer a different editor, 
+any other editor can be used, e.g. ``vim``.
 
 This file contains the information for:
 
@@ -120,7 +123,7 @@ using the format: YYYYMMDD_HHMMSS.
 
 > ## Set the destination directory
 >
-> Let's name our destination directory ``esmvaltool_output`` in the working directory.
+> Let's name our destination directory ``esmvaltool_output`` in the current directory.
 > ESMValTool should write the output to this path, so make sure you have the disk space
 > to write output to this directory.
 > How do we set this in the `config-user.yml`?
@@ -172,7 +175,7 @@ rootpath:
   default: ~/climate_data
 ```
 These are typically available in the default configuration file you downloaded, so simply 
-removing the machine specific lines should be sufficient to access input data.
+uncommenting the machine specific lines should be sufficient to access input data.
 
 > ## Set the correct rootpath
 >
@@ -228,23 +231,21 @@ removing the machine specific lines should be sufficient to access input data.
 >>```
 >>
 >> - For more information about setting the rootpath, see also the ESMValTool
->> [documentation](https://docs.esmvaltool.org/projects/esmvalcore/en/latest/
-quickstart/find_data.html).
+>> [documentation](https://docs.esmvaltool.org/projects/esmvalcore/en/
+latest/quickstart/find_data.html).
 > {: .solution}
 {: .challenge}
 
 ## Directory structure for the data from different projects
 
 Input data can be from various models, observations and reanalysis data that
-adhere to the [CF/CMOR standard](https://cmor.llnl.gov/). The ``drs`` setting
-describes the file structure.
-
+adhere to the [CF/CMOR standard](https://cmor.llnl.gov/). 
 The ``drs`` setting describes the file structure for several projects (e.g.
 CMIP6, CMIP5, obs4mips, OBS6, OBS) on several key machines
 (e.g. BADC, CP4CDS, DKRZ, ETHZ, SMHI, BSC). For more
 information about ``drs``, you can visit the ESMValTool documentation on
-[Data Reference Syntax (DRS)](https://docs.esmvaltool.org/projects/esmvalcore/
-en/latest/quickstart/find_data.html#cmor-drs).
+[Data Reference Syntax (DRS)](https://docs.esmvaltool.org/projects/ESMValCore/
+en/latest/quickstart/find_data.html#explaining-drs-cmip5-or-drs-cmip6).
 
 > ## Set the correct drs
 >
@@ -293,24 +294,15 @@ en/latest/quickstart/find_data.html#cmor-drs).
 
 > ## Explain the default drs (if working on local machine)
 >
-> 1. In the previous exercise, we set the `drs` of CMIP5 data to `default`.
+> In the previous exercise, we set the `drs` of CMIP5 data to `default`.
 >    Can you explain why?
-> 2. Have a look at the directory structure of the `OBS` data.
->    There is a folder called `Tier1`. What does it mean?
 >
 >> ## Solution
 >>
->> 1. `drs: default` is one way to retrieve data from a ROOT directory that has
+>> `drs: default` is one way to retrieve data from a ROOT directory that has
 >>    no DRS-like structure. ``default`` indicates that all the files are in a
 >>    folder without any structure.
 >>
->> 2. Observational data are organized in Tiers depending on their level of
->>    public availability. Therefore the default directory must be structured
->>    accordingly with sub-directories `TierX` e.g. Tier1, Tier2 or Tier3, even
->>    when `drs: default`. More details can be found in the 
-[documentation](https://docs.esmvaltool.org/projects/esmvalcore/en/latest/
-quickstart/find_data.html#observational-data).
->>
 > {: .solution}
 {: .challenge}
 
@@ -329,8 +321,8 @@ if you want to feed some additional data (e.g. shape files) to your recipe.
 > auxiliary_data_dir: ~/auxiliary_data
 > ```
 > See more information in ESMValTool
-[document](https://docs.esmvaltool.org/projects/ESMValCore/en/latest/quickstart
-/configure.html?highlight=auxiliary_data#user-configuration-file).
+[documentation](https://docs.esmvaltool.org/projects/ESMValCore/en/latest/
+> quickstart/configure.html?highlight=auxiliary_data#top-level-configuration-options).
 {: .callout}
 
 > ## Number of parallel tasks
@@ -353,12 +345,18 @@ amount of memory available in your system.
 
 > ## Make your own configuration file
 >
-> It is possible to have several configuration files with different purposes,
-> for example: config-user_formalised_runs.yml, config-user_debugging.yml.
-> In this case, you have to pass the path of your own configuration file
-> as a command-line option when running the ESMValTool.
+> Configuration files could live in the user configuration directory, which is 
+> by default ``~/.config/esmvaltool``. The directory could be also specified
+> via the command line argument ``--config_dir``.
 > We will learn how to do this in the
 > [next lesson]({{ page.root }}{% link _episodes/04-recipe.md %}).
+>
+> It is possible to have several configuration files with different purposes,
+> for example: config-user_formalised_runs.yml, config-user_debugging.yml.
+> In this case, ESMValTool searches for all YAML files within each of the 
+> configuration directories and merges them together. How this is done is 
+> explained [here](https://docs.esmvaltool.org/projects/ESMValCore/en/
+> latest/quickstart/configure.html#yaml-files).
 {: .callout}
 
 {% include links.md %}

_episodes/04-recipe.md

@@ -2,7 +2,7 @@
 title: "Running your first recipe"
 teaching: 15
 exercises: 15
-compatibility: ESMValTool v2.10.0
+compatibility: ESMValTool v2.12.0
 
 questions:
 - "How to run a recipe?"
@@ -43,7 +43,7 @@ esmvaltool run examples/recipe_python.yml
 or if you have the user configuration file in your current directory then
 
 ```
-esmvaltool run --config_file ./config-user.yml examples/recipe_python.yml
+esmvaltool run --config_dir . examples/recipe_python.yml
 ```
 
 If everything is okay, you should see that ESMValTool is printing a lot of
@@ -80,7 +80,7 @@ Let's dissect what's happening here.
 > > ## Answers
 > >
 > > 1. The config file should be the one we edited in the previous episode,
-> >    something like `/home/<username>/.esmvaltool/config-user.yml` or
+> >    something like `/home/<username>/.config/esmvaltool/config-user.yml` or
  `~/esmvaltool_tutorial/config-user.yml`.
 > > 1. ESMValTool found the recipe in its installation directory, 
 >> something like
@@ -132,8 +132,8 @@ distinguished in the log messages:
 > > following line in the output:
 > >
 > > ```
-> >[134535] INFO    These tasks will be executed: map/tas, timeseries/tas_global, 
->>timeseries/script1, map/script1, timeseries/tas_amsterdam
+> >INFO    [3966381] These tasks will be executed: timeseries/script1,
+> > timeseries/tas_amsterdam, timeseries/tas_global, map/tas, map/script1
 > > ```
 > >
 > > So there are three tasks related to timeseries: global temperature,

_episodes/05-conclusions.md

@@ -2,7 +2,7 @@
 title: "Conclusion of the basic tutorial"
 teaching: 10
 exercises: 0
-compatibility: ESMValTool v2.10.0
+compatibility: ESMValTool v2.12.0
 
 questions:
 - "What do I do now?"
@@ -63,7 +63,7 @@ to be suitable for use by ESMValTool.
 > - [ESMValTool home page](https://www.esmvaltool.org/)
 > - [Papers](https://esmvaltool.org/references/)
 > - [Source code (ESMValTool)](https://github.com/ESMValGroup/ESMValTool)
-> - [Source code (ESMValCore )](https://github.com/ESMValGroup/ESMValCore)
+> - [Source code (ESMValCore)](https://github.com/ESMValGroup/ESMValCore)
 {: .callout}