From 7e018fb2f5e8aa4eb37dc3b6af9083d73683143c Mon Sep 17 00:00:00 2001 From: Theo Geddes Date: Fri, 5 Aug 2022 10:19:28 +0100 Subject: [PATCH] fix line length about & glossary(#250) --- _episodes/00-quickstart.md | 103 ------------------------------------ _episodes/09-cmorization.md | 3 +- _episodes/10-debugging.md | 32 +++++++---- _extras/about.md | 3 +- _extras/glossary.md | 74 ++++++++++++++++++-------- 5 files changed, 79 insertions(+), 136 deletions(-) delete mode 100644 _episodes/00-quickstart.md diff --git a/_episodes/00-quickstart.md b/_episodes/00-quickstart.md deleted file mode 100644 index 756f26de..00000000 --- a/_episodes/00-quickstart.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "Quickstart Guide" -teaching: 5 -exercises: 10 -questions: -- How do I set up with ESMValTool quickly? - -objectives: -- Set up the ESMValTool -- Successfully run a recipe - -keypoints: -- The enviroment has to be loaded before the ESMValTool can be used. -- The config file has to be set up. -- The recipe will say 'run was successful' if ran properly. ---- - -## Installing and getting started with the ESMValTool - -To install the ESMValTool please see -[here](https://docs.esmvaltool.org/en/latest/quickstart/installation.html#) - - -## Configuring ESMValtool - -With ESMValTool installed, we can now set up our configuration file (which tells -ESMValTool how to run, where to get data from, and where to output it). - -You can find out more about this in the -[documention](https://docs.esmvaltool.org/projects/ESMValCore/en/latest/quickstart/configure.html). - -In this example, visual studio code is used as the default text editor, so when -'code' is shown on the command line instructions, replace it with syntax for -initialising your favourite text editor. - -1. Ensure you are in the directory you want to get started in: - -~~~bash -esmvaltool config get_config_user -~~~ -2. Open the config-user.yml file: - -~~~bash -code ~/.esmvaltool/config-user.yml -~~~ -3. To set up the config-user.yml file, change the following lines to: - -```yaml - output_dir: ~/pathtoyourworkingdir/esmvaltool_output - download_dir: /anypathyoulike/ - auxiliary_data: /anypathyoulike/auxiliary_data - max_parallel_tasks: 1 - offline: true - rootpath: - default: /anypathyoulike/ - CMIP5: //CMIP5 - CMIP6: //CMIP6 - drs: - CMIP5: default - CMIP6: default -``` - - Here is an example of what it could look like: -```yaml - output_dir: /home/h02/tgeddes/Esmvaltool/esmvaltool_output - download_dir: /home/h02/tgeddes/Esmvaltool/download_data - auxiliary_data_dir: /home/h02/tgeddes/Esmvaltool/auxiliary_data - max_parallel_tasks: 1 - offline: true - rootpath: - default: /project/cma/esmvaltool/obs - CMIP5: /project/cma/esmvaltool/cmip5/output1 - CMIP6: /project/cma/esmvaltool/CMIP6 - OBS: /project/cma/esmvaltool/obs - drs: - CMIP5: BADC - CMIP6: BADC -``` - -## Running a Recipe - -To run a recipe: - -~~~bash -esmvaltool run recipe_radiation_budget.yml -~~~ -If everything has been set up correctly, the last line of code should look -something like this: - -```yaml -2022-08-02 14:00:58,128 UTC [93691] INFO Run was successful -``` - -To view the file used in this example: - -~~~bash - esmvaltool recipes get recipe_radiation_budget.yml - code recipe_radiation_budget.yml -~~~ - -You can find out more about this recipe in the -[documentation](https://docs.esmvaltool.org/en/latest/recipes/recipe_radiation_budget.html). - diff --git a/_episodes/09-cmorization.md b/_episodes/09-cmorization.md index 0cbc49d1..84a51243 100644 --- a/_episodes/09-cmorization.md +++ b/_episodes/09-cmorization.md @@ -64,7 +64,8 @@ that is important for calculating components of the global carbon cycle. See the next section on how to obtain data. As in the previous episode -([Development and Contribution episode]({{ page.root }}{% link _episodes/07-development-setup.md %})), +([Development and Contribution episode]({{ page.root }}{% link + _episodes/07-development-setup.md %})), we will be using the development installation of ESMValTool. diff --git a/_episodes/10-debugging.md b/_episodes/10-debugging.md index a15dbde6..ff940caa 100644 --- a/_episodes/10-debugging.md +++ b/_episodes/10-debugging.md @@ -62,7 +62,8 @@ Let's change the working directory to the folder ``run`` and list its files: ~~~ ~~~ -diag_timeseries_temperature main_log_debug.txt main_log.txt recipe_example.yml resource_usage.txt +diag_timeseries_temperature main_log_debug.txt main_log.txt + recipe_example.yml resource_usage.txt ~~~ {: .output} @@ -150,7 +151,8 @@ and then ctrl + X to exit ``nano``. >20 - ukesm >21 >22 datasets: ->23 - {dataset: HadGEM2-ES, project: CMIP5, exp: historical, mip: Omon, ensemble: r1i1p1, start_year: 1859, end_year: 2005} +>23 - {dataset: HadGEM2-ES, project: CMIP5, exp: historical, mip: Omon, ensemble: +>24 r1i1p1, start_year: 1859, end_year: 2005} >24 >25 preprocessors: >26 prep_timeseries: # For 0D fields @@ -176,7 +178,8 @@ and then ctrl + X to exit ``nano``. ## Keys and values in recipe settings The [ESMValTool -pre-processors](https://docs.esmvaltool.org/projects/ESMValCore/en/latest/recipe/preprocessor.html?highlight=preprocessor) +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, like time manipulation, area manipulation, land-sea masking, variable derivation, etc. Let's add the preprocessor ``extract_region`` to the section ``prep_timeseries``: @@ -218,9 +221,11 @@ The values for the keys ``author``, ``maintainer``, ``projects`` and - A list of ESMValTool author, maintainer, and projects can be found in the -[config-references.yml](https://github.com/ESMValGroup/ESMValTool/blob/master/esmvaltool/config-references.yml). +[config-references.yml](https://github.com/ESMValGroup/ESMValTool/blob/master/ +esmvaltool/config-references.yml). - ESMValTool references in `BibTeX` format can be found in the -[ESMValTool/esmvaltool/references](https://github.com/ESMValGroup/ESMValTool/tree/master/esmvaltool/references) directory. +[ESMValTool/esmvaltool/references](https://github.com/ESMValGroup/ESMValTool/ +tree/master/esmvaltool/references) directory. > ## ESMValTool can’t locate the data > @@ -287,18 +292,23 @@ Let's see what happens if we can change the script path as: ~~~ ~~~ -esmvalcore._task.DiagnosticError: Cannot execute script 'diag_scripts/examples/diagnostic.py' (esmvaltool/diag_scripts/diag_scripts/examples/diagnostic.py): file does not exist. -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. +esmvalcore._task.DiagnosticError: Cannot execute script 'diag_scripts/examples/diagnostic.py' + (esmvaltool/diag_scripts/diag_scripts/examples/diagnostic.py): file does not exist. +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. ~~~ {: .error} The script path should be relative to ``diag_scripts`` directory. It means that the script ``diagnostic_timeseries.py`` is located in ``/diag_scripts/ocean/``. -Alternatively, the script path can be an absolute path. To examine this, we can download the script from the ``ESMValTool`` repository: +Alternatively, the script path can be an absolute path. To examine this, we can + download the script from the ``ESMValTool`` repository: ```bash -wget https://github.com/ESMValGroup/ESMValTool/blob/master/esmvaltool/diag_scripts/ocean/diagnostic_timeseries.py +wget https://github.com/ESMValGroup/ESMValTool/blob/master/esmvaltool/diag_scripts/\ +ocean/diagnostic_timeseries.py ``` One way to get the absolute path is to run: @@ -319,7 +329,9 @@ Then we can update the script path and run the recipe: esmvaltool run recipe_example.yml ~~~ -Now examine `./esmvaltool_output/recipe_example_#_#/run/diag_timeseries_temperature/timeseries_diag/` to see if it worked! +Now examine +`./esmvaltool_output/recipe_example_#_#/run/diag_timeseries_temperature/timeseries_diag/` + to see if it worked! > ## Available recipe and diagnostic scripts > diff --git a/_extras/about.md b/_extras/about.md index dcab29e0..aac48509 100644 --- a/_extras/about.md +++ b/_extras/about.md @@ -73,7 +73,8 @@ Please cite ESMValTool paper as: author = {Mattia Righi and Bouwe Andela and Veronika Eyring and Axel Lauer and Valeriu Predoi and Manuel Schlund and Javier Vegas-Regidor and Lisa Bock and Bj\"{o}rn Br\"{o}tz and Lee de Mora and Faruk Diblen and Laura Dreyer and Niels Drost and Paul Earnshaw and - Birgit Hassler and Nikolay Koldunov and Bill Little and Saskia Loosveldt Tomas and Klaus Zimmermann}, + Birgit Hassler and Nikolay Koldunov and Bill Little and Saskia Loosveldt +Tomas and Klaus Zimmermann}, title = {Earth System Model Evaluation Tool ({ESMValTool}) v2.0 {\textendash} technical overview}, journal = {Geoscientific Model Development} } diff --git a/_extras/glossary.md b/_extras/glossary.md index 3ef37da0..0a46e93b 100644 --- a/_extras/glossary.md +++ b/_extras/glossary.md @@ -6,23 +6,47 @@ title: Glossary - **Amon**: Monthly atmospheric data. -- **CMIP**: The Coupled Model Intercomparison Project (CMIP) aims at better understanding past, present and future climate changes arising from natural, unforced variability or in response to changes in radiative forcing in a multi-model context. For more information, check the [WCR-Climate webpage](https://www.wcrp-climate.org/). - -- **CMOR**: CMOR stands for [*Climate Model Output Rewriter* library](https://pcmdi.github.io/cmor-site/index.html). It comprises a set of C-based functions, with bindings to both Python and FORTRAN 90, that can be used to produce CF-compliant NetCDF files that fulfill the requirements of many of the climate community's standard model experiments. - -- **dataset**: In a recipe, dataset refers to the name of the model or observation data, e.g. HadGEM2-ES. - -- **diagnostic**: In a recipe, the diagnostic section(s) define the tasks that will be executed when running the recipe. It can also include a diagnostic script that converts the preprocessed input data to the desired output like plots or NetCDF files. - -- **ensemble**: An ensemble is a collection of experiments based on standardised inputs. This ensures that ensemble calculations use the same initial states, initialisation methods, and physics details. Ensemble members are named in the rip-nomenclature, *r* for realization, *i* for initialisation and *p* for physics, followed by an integer, e.g. r1i1p1. - -- **experiment**: An experiment is defined as an activity aimed at addressing a specific scientific problem. In CMIP, experiments are numerical experiments with climate models. - -- **grid**: In the dataset section of a recipe, a grid is the array of coordinates on which a variable has been sampled. - -- **mask**: Masks are used to isolate regions. For example, if you apply an ocean mask, then coordinates in the ocean will not be taken into account for the preprocessors/diagnostics. Masks can also be used to work with regions that have missing or invalid entries. - -- **mip**: Typically used to refer to a table of variables in ESMValTool. These are standardized per project, e.g. the [MIP tables for CMIP6](http://clipc-services.ceda.ac.uk/dreq/index/miptable.html). +- **CMIP**: The Coupled Model Intercomparison Project (CMIP) aims at better +understanding past, present and future climate changes arising from natural, +unforced variability or in response to changes in radiative forcing in a +multi-model context. For more information, check the +[WCR-Climate webpage](https://www.wcrp-climate.org/). + +- **CMOR**: CMOR stands for +[*Climate Model Output Rewriter* library](https://pcmdi.github.io/cmor-site/index.html). + It comprises a set of C-based functions, with bindings to both Python and +FORTRAN 90, that can be used to produce CF-compliant NetCDF files that fulfill +the requirements of many of the climate community's standard model experiments. + +- **dataset**: In a recipe, dataset refers to the name of the model or +observation data, e.g. HadGEM2-ES. + +- **diagnostic**: In a recipe, the diagnostic section(s) define the tasks that +will be executed when running the recipe. It can also include a diagnostic +script that converts the preprocessed input data to the desired output like +plots or NetCDF files. + +- **ensemble**: An ensemble is a collection of experiments based on standardised + inputs. This ensures that ensemble calculations use the same initial states, +initialisation methods, and physics details. Ensemble members are named in the + rip-nomenclature, *r* for realization, *i* for initialisation and *p* for +physics, followed by an integer, e.g. r1i1p1. + +- **experiment**: An experiment is defined as an activity aimed at addressing a + specific scientific problem. In CMIP, experiments are numerical experiments + with climate models. + +- **grid**: In the dataset section of a recipe, a grid is the array of +coordinates on which a variable has been sampled. + +- **mask**: Masks are used to isolate regions. For example, if you apply an +ocean mask, then coordinates in the ocean will not be taken into account for +the preprocessors/diagnostics. Masks can also be used to work with regions that + have missing or invalid entries. + +- **mip**: Typically used to refer to a table of variables in ESMValTool. These + are standardized per project, e.g. the + [MIP tables for CMIP6](http://clipc-services.ceda.ac.uk/dreq/index/miptable.html). - **Omon**: Monthly ocean data. @@ -30,11 +54,17 @@ title: Glossary - **preprocessor**: A preprocessor is an operation that is applied to a dataset. -- **project**: In the dataset section of a recipe, "project" Typically refers to a standard experimental protocol for global models, e.g. CMIP. +- **project**: In the dataset section of a recipe, "project" Typically refers +to a standard experimental protocol for global models, e.g. CMIP. -- **RCP**: *Representative Concentration Pathways* are scenarios that represent the full bandwidth of possible future emission trajectories. Depending on population growth and the development of energy production, food production and land use, various emission trajectories are possible. +- **RCP**: *Representative Concentration Pathways* are scenarios that represent + the full bandwidth of possible future emission trajectories. Depending on +population growth and the development of energy production, food production and + land use, various emission trajectories are possible. -- **recipe**: A recipe contains the instructions to be carried out by the ESMValTool. This includes four main sections: datasets, preprocessors, diagnostics and description. +- **recipe**: A recipe contains the instructions to be carried out by the +ESMValTool. This includes four main sections: datasets, preprocessors, +diagnostics and description. - **ta**: CMIP short-name for 'air temperature'. @@ -48,7 +78,9 @@ title: Glossary - **ts**: CMIP short-name for 'surface temperature'. -- **yaml**: YAML is a human-readable data-serialization language. It is commonly used for configuration files and in applications where data is being stored or exchanged. +- **yaml**: YAML is a human-readable data-serialization language. It is +commonly used for configuration files and in applications where data is being +stored or exchanged. > ## Additional info