Developing tutorials

Developers and users of the MESSAGEix framework are welcome to contribute tutorials, according to the following guidelines. Per the license and CLA, tutorials will become part of the message_ix test suite and will be publicly available.

Developers must ensure new features (including message_ix.tools submodules) are fully documented. This can be done via the API documentation (this site) and, optionally, a tutorial. These have complementary purposes:

  • The API documentation (built using Sphinx and ReadTheDocs) must completely, but succinctly, describe the arguments and behaviour of every class and method in the code.

  • Tutorials serve as structured learning exercises for the classroom or self-study. The intended learning outcome for each tutorial is that students understand how the model framework API may be used for scientific research, and can begin to implement their own models or model changes.

Code and writing style

  • Python and R code in notebooks: follow all points of the Code style for message_ix.

  • Only commit ‘bare’ Jupyter notebooks: clear all cell output before committing. Notebooks will be run and rendered when the documentation is generated.

  • Add a line to message_ix/tests/test_tutorials.py, so that the parametrized test function runs the tutorial (as noted at PR #196).

  • Optionally, use Jupyter notebook slide-show features so that the tutorial can be viewed as a presentation.

  • When relevant, provide links to publications or sources that provide greater detail for the methodology, data, or other packages used.

  • Providing the mathematical formulation in the tutorial itself is optional.

  • Framework specific variables and parameters or functions must be in italic.

  • Relevant figures, tables, or diagrams should be added to the tutorial if these can help users to understand concepts.

    • Place rendered versions of graphics in a directory with the tutorial (see Location below). Use SVG, PNG, JPG, or other web-ready formats.

Structure

Generally, a tutorial should have the following elements or sections.

  • Tutorial introduction:

    • The general overview of tutorial.

    • The intended learning outcome.

    • An explanation of which features are covered.

    • Reference and provide links to any tutorials that are interlinked or part of a series.

  • Description of individual steps:

    • A brief explanation of the step.

    • A link to any relevant mathematical documentation.

  • Modeling results and visualizations:

    • Model outputs and post-processing calculations in tutorials should demonstrate usage of the message_ix.report module.

    • Plots to depict results should use pyam.

    • Include a brief discussion of insights from the results, in line with the learning objectives.

  • Exercises: include self-test questions, small activities, and exercises at the end of a tutorial so that users (and instructors, if any) can check their learning.

Location

Place notebooks in an appropriate location:

tutorial/name.ipynb`

Stand-alone tutorial.

tutorial/example/example_baseline.ipynb

Group of tutorials named “example.” Each notebook’s file name begins with the group name, followed by a name beginning with underscores. The group name can refer to a specific RES shared across multiple tutorials. Some example names include:

<group>_baseline.ipynb

<group>_basic.ipynb  # Basic modeling features, e.g.:
<group>_emmission_bounds.ipynb
<group>_emission_taxes.ipynb
<group>_fossil_resources.ipynb

<group>_adv.ipynb  # Advanced modeling features, e.g.:
<group>_addon_technologies.ipynb
<group>_share_constraints.ipynb

<group>_renewables.ipynb  # Features related to renewable energy, e.g.:
<group>_firm_capacity.ipynb
<group>_flexible_generation.ipynb
<group>_renewable_resources.ipynb