CLIMADA-project · emanuel-schmid · Feb 8, 2023 · Jan 12, 2023 · Jan 12, 2023 · Jan 12, 2023
@@ -8,26 +8,30 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Content\n",
     "\n",
-    "1. [Why tutorials](#WHY)\n",
-    "2. [Basic structure](#Structure)\n",
-    "3. [Good examples](#Examples)"
+    "## Content\n",
+    "\n",
+    "- [Why tutorials](#Why-tutorials)\n",
+    "- [Basic structure](#Basic-structure)\n",
+    "- [Good examples](#Good-examples)"
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "##  1. <a id='WHY'>Why tutorials</a>\n",
+    "## Why tutorials\n",
     "\n",
     "**Main goal:**<br>\n",
     "The main goal of the tutorials is it to give a complete overview on:\n",
-    "* essential CLIMADA components\n",
-    "* introduce newly developed modules and features\n",
+    "\n",
+    "- essential CLIMADA components\n",
+    "- introduce newly developed modules and features\n",
     "\n",
     "More specifically, tutorials should introduce CLIMADA users to the core functionalities and modules and guide users in their application. Hence, each new module created needs to be accompanied with a tutorial. The following sections give an overview of the basic structure desired for CLIMADA tutorials.\n",
     "\n",
@@ -36,28 +40,30 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## 2. <a id='Structure'>Basic structure</a>\n",
+    "## Basic structure\n",
     "\n",
     "Every tutorial should cover the following main points. Additional features characteristic to the modules presented can and should be added as seen fit."
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### Introduction\n",
     "\n",
-    "* What is the feature presented? <br>\n",
-    "Briefly describe the feature and introduce how it's presented in the CLIMADA framework.<br>\n",
-    "<br>\n",
-    "* What is its data structure?<br>\n",
-    "Present and overview (in the form of a table for example) of where the feature is built into CLIMADA. What class does it belong to, what are the variables of the feature, what is their data structure.<br>\n",
-    "<br>\n",
-    "* Table of content:<br>\n",
-    "How is this tutorial structured?"
+    "- What is the feature presented?\\\n",
+    "  Briefly describe the feature and introduce how it's presented in the CLIMADA framework.\n",
+    "\n",
+    "- What is its data structure?\\\n",
+    "  Present and overview (in the form of a table for example) of where the feature is built into CLIMADA. What class does it belong to, what are the variables of the feature, what is their data structure.\n",
+    "\n",
+    "- Table of content:\\\n",
+    "  How is this tutorial structured?"
    ]
   },
   {
@@ -71,27 +77,30 @@
    "source": [
     "### Illustration of feature functionality and application\n",
     "\n",
-    "Walk users through the core functions of the module and illustrate how the feature can be used. This obviously is dependent on the feature itself. \n",
+    "Walk users through the core functions of the module and illustrate how the feature can be used. This obviously is dependent on the feature itself.\n",
     "A few core points should be considered when creating the tutorial:\n",
-    "* **SIZE MATTERS!** \n",
-    "    * each notebook as a total should not exceed the critical (yet vague) size of \"a couple MB\"\n",
-    "    * keep the size of data you use as examples in the tutorial in mind\n",
-    "    * we aim for computational efficiency\n",
-    "    * a lean, well-organized, concise notebook is more informative than a long, messy all-encompassing one.\n",
-    "    \n",
-    "* follow the general CLIMADA naming convention for the notebook. For example: \"climada_hazard_TropCyclone.ipynb\"\n",
+    "\n",
+    "- **SIZE MATTERS!** \n",
+    "  - each notebook as a total should not exceed the critical (yet vague) size of \"a couple MB\"\n",
+    "  - keep the size of data you use as examples in the tutorial in mind\n",
+    "  - we aim for computational efficiency\n",
+    "  - a lean, well-organized, concise notebook is more informative than a long, messy all-encompassing one.\n",
+    "\n",
+    "- follow the general CLIMADA naming convention for the notebook. For example: \"climada_hazard_TropCyclone.ipynb\"\n",
     "![image-2.png](attachment:image-2.png)"
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## 3. <a id='Examples'>Good examples</a>\n",
+    "## Good examples\n",
     "\n",
     "The following examples can be used as templates and inspiration for your tutorial:\n",
-    "* https://github.com/CLIMADA-project/climada_python/blob/main/doc/tutorial/climada_entity_Exposures.ipynb\n",
-    "* https://github.com/CLIMADA-project/climada_python/blob/main/doc/tutorial/climada_hazard_Hazard.ipynb"
+    "\n",
+    "- https://github.com/CLIMADA-project/climada_python/blob/main/doc/tutorial/climada_entity_Exposures.ipynb\n",
+    "- https://github.com/CLIMADA-project/climada_python/blob/main/doc/tutorial/climada_hazard_Hazard.ipynb"
    ]
   }
  ],

@@ -13,15 +13,15 @@
    "source": [
     "## Content\n",
     "\n",
-    "1. [Constants](#Const)\n",
-    "    1. [Hard Coded](#ConstHard)\n",
-    "    2. [Configurable](#ConstConf)\n",
-    "    3. [Where to put constants?](#ConstWhere)\n",
-    "2. [Configuration](#Conf)\n",
-    "    1. [Config files](#ConfFiles)\n",
-    "    2. [Accessing configuration values](#ConfAccess)\n",
-    "    3. [Default Configuration](#ConfDefault)\n",
-    "    4. [Test Configuration](#ConfTest)\n"
+    "- [Constants](#Constants)\n",
+    "    - [Hard Coded](#Hard-Coded)\n",
+    "    - [Configurable](#Configurable)\n",
+    "    - [Where to put constants?](#Where-to-put-constants?)\n",
+    "- [Configuration](#Configurable)\n",
+    "    - [Configuration files](#Configuration-files)\n",
+    "    - [Accessing configuration values](#Accessing-configuration-values)\n",
+    "    - [Default Configuration](#Default-Configuration)\n",
+    "    - [Test Configuration](#Test-Configuration)\n"
    ]
   },
   {
@@ -30,7 +30,7 @@
     "tags": []
    },
    "source": [
-    "## 1. <a id=\"Const\">Constants</a>\n",
+    "## Constants \n",
     "\n",
     "Constants are values that, once initialized, are never changed during the runtime of a program. In Python constants are assigned to variables with capital letters by convention, and vice versa, variables with capital letters are supposed to be constants.\n",
     "\n",
@@ -48,7 +48,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 1.A. <a id='ConstHard'>Hard Coded</a>\n",
+    "### Hard Coded \n",
+    "\n",
     "Hard coding constants is the preferred way to deal with strings that are used to identify objects or files."
    ]
   },
@@ -169,7 +170,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "###  1.B. <a id='ConstConf'>Configurable</a>\n",
+    "### Configurable\n",
+    "\n",
     "When it comes to absolute paths, it is urgently suggested to not use hard coded constant values, for the obvious reasons. But also relative paths can cause problems. In particular, they may point to a location where the user has not sufficient access permissions. In order to avoid these problems, _all_ paths constants in CLIMADA are supposed to be defined through configuration.\\\n",
     "<b style='color:darkred;font-size:100%'> &rarr; paths must be configurable </b>\n",
     "\n",
@@ -184,22 +186,24 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "###  1.C. <a id='ConstWhere'>Where to put constants?</a>\n",
+    "###  Where to put constants? \n",
+    "\n",
     "As a general rule, constants are defined in the module where they intrinsically belong to. If they belong equally to different modules though or they are meant to be used globally, there is the module `climada.util.constants` which is compiling constants CLIMADA wide."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "##  2. <a id='Conf'>Configuration</a>"
+    "## Configuration "
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "###  2.A. <a id='ConfFiles'>Configuration files</a>\n",
+    "### Configuration files \n",
+    "\n",
     "The proper place to define constants that a user may want (or need) to change without changing the CLIMADA installation are the configuration files.\\\n",
     "These are files in _json_ format with the name `climada.conf`. There is a default config file that comes with the installation of CLIMADA. But it's possible to have several of them. In this case they are complementing one another.\n",
     "\n",
@@ -226,7 +230,6 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "\n",
     "#### Format\n",
     "\n",
     "A configuration file is a JSON file, with the additional restriction, that all keys must be strings without a '.' (dot) character .\\\n",
@@ -248,7 +251,6 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "\n",
     "#### Referenced Configuration Values\n",
     "\n",
     "Configuration string values can be referenced from other configuration values. E.g.\n",
@@ -265,7 +267,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "###  2.B. <a id='ConfAccess'>Accessing configuration values</a>\n",
+    "### Accessing configuration values \n",
+    "\n",
     "Configuration values can be accessed through the (constant) `CONFIG` from the `climada` module:"
    ]
   },
@@ -302,7 +305,6 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "\n",
     "#### Data Types\n",
     "\n",
     "The configuration itself and its attributes have the data type `climada.util.config.Config`"
@@ -332,7 +334,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The actual configuration values can be accessed as basic types (float, int, str), provided the definition is according to the respective data type:"
+    "The actual configuration values can be accessed as basic types (bool, float, int, str), provided the definition is according to the respective data type:"
    ]
   },
   {
@@ -403,7 +405,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 2.C. <a id='ConfDefault'>Default Configuration</a>\n",
+    "### Default Configuration \n",
+    "\n",
     "The conifguration file `climada/conf/climada.conf` contains the default configuration.\\\n",
     "On the top level it has the following attributes:\n",
     "\n",
@@ -446,32 +449,18 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "### Test Configuration \n",
     "\n",
-    "#### Data Initialization\n",
-    "\n",
-    "When `import climada` is executed in a python script or shell, data files from the installation directory are copied to the location specified in the current configuration.\\\n",
-    "This happens only when climada is used for the first time with the current configuration. Subsequent execution will only check for presence of files and won't overwrite existing files."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "<img src=\"img/FileSystem-2.png\" style=\"width:600px;\">"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Thus, the home directory will automatically be populated with a climada directory and several files from the repository when climada is used.\\\n",
-    "To prevent this and keep the home directory clean, create a config file `~/.config/climada.conf` with customized values for `local_data.system` and `local_data.demo`.\\\n",
-    "As an example, a file with the following content would suppress creation of directories and copying of files during execution of CLIMADA code:\n",
+    "The configuration values for unit and integration tests are not part of the [default configuration](#Default-Configuration), since they are irrelevant for the regular CLIMADA user and only aimed for developers.\\\n",
+    "The default test configuration is defined in the `climada.conf` file of the installation directory.\n",
+    "This file contains paths to files that are read during tests. If they are part of the GitHub repository, their path i.g. starts with the `climada` folder within the installation directory:\n",
     "```json\n",
     "{\n",
-    "    \"local_data\": {\n",
-    "        \"system\": \"/path/to/installation-dir/climada/data/system\",\n",
-    "        \"demo\": \"/path/to/installation-dir/climada/data/demo\"\n",
+    "    \"_comment\": \"this is a climada configuration file meant to supersede the default configuration in climada/conf during test\",\n",
+    "    \"test_directory\": \"./climada\",\n",
+    "    \"test_data\": \"{test_directory}/test/data\",\n",
+    "    \"disc_rates\": {\n",
+    "        \"test_data\": \"{test_directory}/entity/disc_rates/test/data\"\n",
     "    }\n",
     "}\n",
     "```"
@@ -481,14 +470,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 2.D. <a id='ConfTest'>Test Configuration</a>\n",
-    "The configuration values for unit and integration tests are not part of the default configuration ([2.C](#ConfDefault)), since they are irrelevant for the regular CLIMADA user and only aimed for developers.\\\n",
-    "The default test configuration is defined in the `climada.conf` file of the installation directory.\n",
-    "This file contains paths to files that are read during tests. If they are part of the GitHub repository, their path i.g. starts with the `climada` folder within the installation directory:\n",
+    "Obviously, the default `test_directory` is given as the relative path to `./climada`. This is fine if (but only if) unit or integration tests are started from the installation directory, which is the case in the automated tests on the CI server.\\\n",
+    "Developers who intend to start a test from another working directory may have to edit this file and replace the relative path with the absolute path to the installation directory:\n",
     "```json\n",
     "{\n",
     "    \"_comment\": \"this is a climada configuration file meant to supersede the default configuration in climada/conf during test\",\n",
-    "    \"test_directory\": \"./climada\",\n",
+    "    \"test_directory\": \"/path/to/installation-dir/climada\",\n",
     "    \"test_data\": \"{test_directory}/test/data\",\n",
     "    \"disc_rates\": {\n",
     "        \"test_data\": \"{test_directory}/entity/disc_rates/test/data\"\n",
@@ -501,15 +488,31 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Obviously, the default `test_directory` is given as the relative path to `./climada`. This is fine if (but only if) unit or integration tests are started from the installation directory, which is the case in the automated tests on the CI server.\\\n",
-    "Developers who intend to start a test from another working directory may have to edit this file and replace the relative path with the absolute path to the installation directory:\n",
+    "### Data Initialization\n",
+    "\n",
+    "When `import climada` is executed in a python script or shell, data files from the installation directory are copied to the location specified in the current configuration.\\\n",
+    "This happens only when climada is used for the first time with the current configuration. Subsequent execution will only check for presence of files and won't overwrite existing files."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<img src=\"img/FileSystem-2.png\" style=\"width:600px;\">"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Thus, the home directory will automatically be populated with a climada directory and several files from the repository when climada is used.\\\n",
+    "To prevent this and keep the home directory clean, create a config file `~/.config/climada.conf` with customized values for `local_data.system` and `local_data.demo`.\\\n",
+    "As an example, a file with the following content would suppress creation of directories and copying of files during execution of CLIMADA code:\n",
     "```json\n",
     "{\n",
-    "    \"_comment\": \"this is a climada configuration file meant to supersede the default configuration in climada/conf during test\",\n",
-    "    \"test_directory\": \"/path/to/installation-dir/climada\",\n",
-    "    \"test_data\": \"{test_directory}/test/data\",\n",
-    "    \"disc_rates\": {\n",
-    "        \"test_data\": \"{test_directory}/entity/disc_rates/test/data\"\n",
+    "    \"local_data\": {\n",
+    "        \"system\": \"/path/to/installation-dir/climada/data/system\",\n",
+    "        \"demo\": \"/path/to/installation-dir/climada/data/demo\"\n",
     "    }\n",
     "}\n",
     "```"