CLIMADA Tutorial Template

Content

  1. Why tutorials

  2. Basic structure

  3. Good examples

1. Why tutorials

Main goal: The main goal of the tutorials is it to give a complete overview on: * essential CLIMADA components * introduce newly developed modules and features

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.

Important: A tutorial needs to be included with the final pull request for every new feature.

2. Basic structure

Every tutorial should cover the following main points. Additional features characteristic to the modules presented can and should be added as see fit.

Introduction

  • What is the feature presented? Briefly describe the feature and introduce how it’s presented in the CLIMADA framework.

  • What is its data structure? 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.

  • Table of content: How is this tutorial structured?

Illustration of feature functionality and application

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. A few core points should be considered when creating the tutorial: * SIZE MATTERS! * each notebook as a total should not exceed the critical (yet vague) size of “a couple MB” * keep the size of data you use as examples in the tutorial in mind * we aim for computational efficiency * a lean, well-organized, concise notebook is more informative than a long, messy all-encompassing one.

  • follow the general CLIMADA naming convention for the notebook. For example: “climada_hazard_TropCyclone.ipynb” image-2.png

3. Good examples

The following examples can be used as templates and inspiration for your tutorial: * https://github.com/CLIMADA-project/climada_python/blob/tutorial_update/doc/tutorial/climada_entity_Exposures.ipynb * https://github.com/CLIMADA-project/climada_python/blob/tutorial_update/doc/tutorial/climada_hazard_Hazard.ipynb