diff --git a/doc/sphinx/source/tutorials/episode_1_introduction.rst b/doc/sphinx/source/tutorials/episode_1_introduction.rst new file mode 100644 index 0000000000..10474e0def --- /dev/null +++ b/doc/sphinx/source/tutorials/episode_1_introduction.rst @@ -0,0 +1,178 @@ +.. _epsiode_1: + +Introduction +===================== + +.. admonition:: Overview + :class: note + + .. grid:: 2 + :gutter: 1 + :margin: 3 3 0 5 + + .. grid-item-card:: Timings + :columns: 12 + + * Teaching: 5 min + * Exercises: 10 min + + .. grid-item-card:: Questions + + * What is ESMValTool? + * Who are the people behind ESMValTool? + + .. grid-item-card:: Learning outcomes + + * Familiarization with ESMValTool + * Synchronize expectations + + .. grid-item-card:: Compatibility + :columns: 12 + + ESMValTool v2.15.0 + + +What is ESMValTool? +------------------- + +This tutorial is a first introduction to ESMValTool. Before diving into the +technical steps, let’s talk about what ESMValTool is all about. + +.. admonition:: What is ESMValTool? + :class: admonition-todo + + What do you already know about or expect from ESMValTool? + + .. dropdown:: ESMValTool is... + :color: secondary + :icon: eye + + ESMValTool is many things, but in this tutorial we will focus on the + following traits: + + * **A tool to analyse climate data** + * **A collection of diagnostics for reproducible climate science** + * **A community effort** + +A tool to analyse climate data +------------------------------ + +ESMValTool takes care of finding, opening, checking, fixing, concatenating, +and preprocessing CMIP data and several other supported datasets. + +The central component of ESMValTool that we will see in this tutorial is the +**recipe**. Any ESMValTool recipe is basically a set of instructions to +reproduce a certain result. The basic structure of a recipe is as follows: + +* **Documentation** with relevant (citation) information +* **Datasets** that should be analysed +* **Preprocessor** steps that must be applied +* **Diagnostic** scripts performing more specific evaluation steps + +An example recipe could look like this: + +.. code-block:: bash + + documentation: + title: This is an example recipe. + description: Example recipe + authors: + - lastname_firstname + + datasets: + - {dataset: UKESM1-0-LL, project: CMIP6, exp: historical, mip: Amon, + ensemble: r1i1p1f2, start_year: 1960, end_year: 2005} + + preprocessors: + global_mean: + area_statistics: + operator: mean + + diagnostics: + hockeystick_plot: + description: plot of global mean temperature change + variables: + temperature: + short_name: tas + preprocessor: global_mean + scripts: hockeystick.py + +.. admonition:: Understanding the different sections of the recipe + :class: admonition-todo + + Try to figure out the meaning of the different dataset keys. Hint: they can + be found in the documentation of ESMValTool. + + .. dropdown:: Solution + :color: secondary + :icon: eye + + The keys are explained in the ESMValCore documentation, in **The + recipe format** section under + :ref:`Overview `. + + +A collection of diagnostics for reproducible climate science +------------------------------------------------------------ + +More than a tool, ESMValTool is a collection of publicly available recipes and +diagnostic scripts. This makes it possible to easily reproduce important +results. + +.. admonition:: Explore the available recipes + :class: admonition-todo + + Go to the :doc:`ESMValTool documentation ` + and explore the **Recipes** section in the sidebar. Which recipe(s) would + you like to try? + +A community effort +------------------ + +ESMValTool is built and maintained by an active community of scientists and +software engineers. It is an open source project to which anyone can +contribute. Many of the interactions take place on GitHub. Here, we briefly +introduce you to some of the most important pages. + +.. admonition:: Meet the ESMValGroup + :class: admonition-todo + + Go to https://github.com/ESMValGroup. This is the + GitHub page of our 'organization'. Have a look around. How many + collaborators are there? Do you know any of them? + + Near the top of the page there are 3 pinned repositories: ESMValTool, + ESMValCore and Community. Visit each of the repositories. How many people + have contributed to each of them? Can you also find out how many people + have contributed to this tutorial? + +.. admonition:: Issues and pull requests + :class: admonition-todo + + Go back to the repository pages of `ESMValTool `_ or `ESMValCore `_. There are tabs for ‘issues’ and ‘pull requests’. You can use + the labels to navigate them a bit more. How many open issues are about + enhancements of ESMValTool? And how many bugs have been fixed in + ESMValCore? There is also an ‘insights’ tab, where you can see a summary + of recent activity. How many issues have been opened and closed in the + past month? + +Conclusion +---------- + +This concludes the introduction of the tutorial. You now have a basic +knowledge of ESMValTool and its community. The following episodes will walk +you through the installation, configuration and running your first recipes. + +.. admonition:: Key points + :class: important + + * ESMValTool provides a reliable interface to analyse and evaluate climate + data + * A large collection of recipes and diagnostic scripts is already available + * ESMValTool is built and maintained by an active community of scientists + and developers + +.. _`PyData Theme documentation: Admonitions`: https://pydata-sphinx-theme.readthedocs.io/en/stable/examples/kitchen-sink/admonitions.html +.. _`Font Awesome`: https://fontawesome.com/search?ic=free-collection diff --git a/doc/sphinx/source/tutorials/episode_2_quickstart.rst b/doc/sphinx/source/tutorials/episode_2_quickstart.rst new file mode 100644 index 0000000000..cdc052ac48 --- /dev/null +++ b/doc/sphinx/source/tutorials/episode_2_quickstart.rst @@ -0,0 +1,154 @@ +.. _episode_2_quickstart: + +Quickstart guide +================ + +.. admonition:: Overview + :class: note + + .. grid:: 2 + :gutter: 1 + :margin: 3 3 0 5 + + .. grid-item-card:: Timings + :columns: 12 + + * Teaching: 2 min + * Exercises: 8 min + + .. grid-item-card:: Questions + + * 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? + + .. grid-item-card:: Learning outcomes + + * Understand the purpose of the quickstart guide + * Load and check the ESMValTool environment + * Configure ESMValTool + * Run a recipe + + .. grid-item-card:: Compatibility + :columns: 12 + + ESMValTool v2.15.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. + +.. admonition:: Purpose of the quickstart guide + :class: discussion + + 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 +:doc:`Installation ` episode in this tutorial. + +Load the ESMValTool environment by following the instructions in the +:ref:`ESMValTool installation and environment activation guide `. +This will typically involving loading a module like so: + +.. code-block:: bash + + module load esmvaltool + +Check the ESMValTool environment by accessing the help for ESMValTool: + +.. code-block:: bash + + esmvaltool --help + +.. admonition:: Check the ESMValTool environment + :class: admonition-todo + + 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``: + +.. code-block:: bash + + 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 +:doc:`Configuration ` episode in this tutorial. + +.. admonition:: Configure the tool + :class: admonition-todo + + 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: + +.. code-block:: bash + + 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: + +.. code-block:: bash + + 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: + +.. code-block:: bash + + YYYY-MM-DD HH:mm:SS, NNN UTC [NNNNN] INFO Wrote recipe output to: + file:///$HOME/esmvaltool_output/recipe_python_``_