Best practices

Content creation¶

The SWUMP criteria¶

All training material destined for CDS/ADS/CADS portals must satisfy the SWUMP criteria:

• Self-explanatory: Steps are clearly, correctly and succinctly explained.

• Well structured: Logical flow and aesthetically pleasing layout with a balanced mix of Markdown and code.

• Usable: Notebook runs to completion without errors and uses only outputs/widgets compatible with JupyterBook.

• Meaningful: Provides an authentic, value-adding use-case for CDS/ADS/CADS data.

• Proficient: Passes the code-standards tests (see quality assurance).

Filenames¶

Filenames should use human-readable slugs that capture the notebook’s key themes, particularly those that distinguish it from other notebooks in the repository.

• Do not include contract numbers or version identifiers in filenames.

• Contract numbers, where required, may be referenced in the Pull Request that introduces or modifies the notebook.

• File versioning is managed automatically through GitHub and should not be duplicated in filenames.

Scope¶

Focus on one topic / visualisation / processing routine. Consider separate notebooks if multiple parts or topics are included.

Pedagogical ordering¶

Within a single notebook, present material in increasing order of complexity:

• Introduce context, prerequisites, and the workflow before the analysis.

• Place the simplest, most representative example first; build up to more advanced cases.

• Place caveats, edge cases, and advanced extensions after the core demonstration, not interleaved with it.

Diátaxis governs which kind of notebook you are writing; pedagogical ordering governs the order of material within it.

Titles¶

When selecting titles for your notebooks, consider the needs of a broad and diverse audience.

Training notebooks serve as entry points to the subject matter and should therefore be titled in a way that is clear, accurate, and accessible. Titles must be:

• Concise – easy to read and limited to fewer than 80 characters.

• Accurate – clearly reflect the notebook’s content and purpose.

• Accessible – avoid acronyms, abbreviations, or technical jargon that may not be widely understood.

Section headings¶

• Keep headings in separate cells

• Use # for first level headings, ## for second level, and so on. Do not skip a level (e.g. do not follow a 1st level heading with a third level, without a second level in between).

TOC¶

Keep the table of contents (TOC) clear and intuitive, that is, avoid long lists that clutter the view. See the official MyST Markdown documentation for details on how to structure the table of contents.

Scientific terminology¶

Define acronyms and domain-specific terminology on first use in the prose. Where a term has an authoritative definition elsewhere, link to that source instead of redefining it in the notebook.

• Example: “...the climatology (the long-term average of a variable over a 30-year reference period) of 2 m temperature...”

• For unfamiliar acronyms, write the expansion at first use: “ECMWF (European Centre for Medium-Range Weather Forecasts)”.

A standalone ## Definitions section is optional in the notebook template and should be used only when the notebook introduces several novel terms; otherwise, defining on first use is preferred.

Figures and visualisation¶

Every figure in a notebook must be self-interpretable without reference to surrounding prose:

• Title that names what the figure shows.

• Axis labels with units on every axis (Temperature [°C], Time [UTC], etc.).

• Legend whenever more than one series, mask, or category is plotted.

• Caption stating the data source, the time/region covered, and the attribution string for any reused image. DOIs or stable URLs preferred.

• Honest scaling. Do not crop or truncate axes in ways that exaggerate or hide effects; if a non-linear scale (log, symlog) is used, label it as such.

• Sufficient image quality. Save raster outputs at a resolution that remains legible when the book is rendered (typically ≥ 150 dpi); prefer vector formats (SVG, PDF) where appropriate.

Storage and reuse:

• Store notebook-specific images in ./content/img/.

• For images reused across repositories (e.g. logos), link to an external URL such as https://climate.copernicus.eu/branding-guidelines#Logolines. Images not already online can be uploaded to a dedicated repository for training. In that case, please contact chris.stewart@ecmwf.int.

• Refer to the MyST documentation for how to include figures.

Visual style and ECMWF guidelines¶

For visual styling decisions in plots and figures, consult the ECMWF visual style guide (link to be added by the maintainer once the canonical URL is confirmed). The guide governs plot-level rules: typography, colour usage, gridlines, and chart conventions.

You do not need to manually embed ECMWF or service logos in individual notebooks: the book-level branding (branding/c3s.yml, cams.yml, ecmwf.yml) and myst.yml configuration take care of logo placement at the rendered-book level.

Colour-vision-deficiency-safe palettes¶

Colour choice is the single most common visualisation issue flagged in expert review. ECMWF acknowledges the gap (Hewson, 2022) but has not yet published a normative palette specification, so the rules below cite community standards that meet or exceed any plausible future guideline.

Universal rule. “If a colour palette is readable in black and white after being desaturated, it is universally accessible to all viewers.” (Crameri et al., 2020) Authors should also simulate colour-vision deficiency (CVD) on every published figure using the Coblis colour-blindness simulator — the same tool referenced in Hewson (2022).

Choose the palette by data type. Sequential, diverging, categorical, and cyclic data each require a different palette family; using the wrong family is as serious as using a CVD-unsafe one.

ColorBrewer for maps. ColorBrewer 2.0 remains a useful source for cartographic sequential, diverging, and qualitative palettes, especially for choropleth and classified maps. Use the colorblind safe filter on the ColorBrewer website, then still check the rendered figure with desaturation or a CVD simulator. Not every ColorBrewer scheme is suitable for every data type, class count, or continuous field.

Default Python recipe (zero install cost). matplotlib built-ins are sufficient for most training notebooks:

import matplotlib.pyplot as plt
plt.imshow(data, cmap="viridis")     # sequential
plt.imshow(anomaly, cmap="RdBu_r")   # diverging

For richer palettes, install on demand and add to environment.yml:

pip install cmcrameri    # Crameri scientific colour maps
pip install cmweather    # radar/meteorology, CVD-friendly (Sherman et al., 2024)
pip install cmocean      # oceanographic / atmospheric
pip install colorbrewer  # ColorBrewer map palettes

import cmcrameri.cm as cmc
plt.imshow(data, cmap=cmc.batlow)

Authority references. Cite at least one of these when a notebook applies a non-default palette, so reviewers can verify the choice against a stated source:

• Crameri F., Shephard G. E., Heron P. J. (2020). The misuse of colour in science communication. Nature Communications 11, 5444. Crameri et al. (2020)

• ColorBrewer 2.0. Color Advice for Cartography. https://colorbrewer2.org

• Sherman Z. et al. (2024). Effective Visualization of Radar Data for Users Impacted by Color Vision Deficiency. BAMS 105(8). Sherman et al. (2024)

• Rocchini D. et al. (2023). Scientific maps should reach everyone: The cblindplot R package to let colour blind people visualise spatial patterns. Ecological Informatics 76, 102045. Rocchini et al. (2023)

• Hewson, T. (2022). Creative Use of Colour to Satisfy Different User Needs. UEF 2022, ECMWF.

Data files¶

Data files should not be stored in the GitHub repository, but hosted externally and linked to, or downloaded from the original source (e.g. CDS/ADS).

Trusted data sources¶

Cite each dataset using a DOI, an equivalent persistent identifier, or a stable URL with named authoritative provenance. Acceptable provenance includes:

• Copernicus services (CDS, ADS, CAMS, CADS) and their dataset DOIs.

• Peer-reviewed datasets accompanied by a DOI.

• Official agency products (ECMWF, NOAA, NASA, ESA, national meteorological services) accessed via their official URLs.

• Other authoritative sources where provenance can be unambiguously named.

DOI-only is not the only acceptable form: a stable, versioned URL from a recognised authority is also acceptable when no DOI exists.

Code¶

Code commenting and annotation¶

For code logic to remain clear to a non-technical audience:

• Add a one-line inline comment at the top of each non-trivial code block stating what it does and why.

• Provide a docstring for any custom function (purpose, arguments, return value).

• Worked example:

# Compute the monthly climatology over the reference period
# (mean across years for each calendar month).
def monthly_climatology(da, period=("1991", "2020")):
    """Return the monthly climatology of a DataArray.

    Parameters
    ----------
    da : xarray.DataArray
        Time-indexed input data.
    period : tuple of str
        (start_year, end_year) reference period, inclusive.

    Returns
    -------
    xarray.DataArray
        12-element climatology indexed by month.
    """
    return da.sel(time=slice(*period)).groupby("time.month").mean("time")

References and attribution¶

Every notebook must list its underlying datasets, publications, and reused figures in the ## References section of the notebook template. Use the formats below.

Datasets¶

Cite by DOI where available; otherwise by a stable URL plus the named authoritative provider.

• Example (DOI): Hersbach, H., Bell, B., Berrisford, P., et al. (2023). ERA5 monthly averaged data on single levels from 1940 to present. Copernicus Climate Change Service Climate Data Store. Copernicus Climate Change Service (2019)

Publications¶

Use a consistent citation style (APA is the default for ECMWF training material). For reproducibility-sensitive material, also provide a BibTeX entry.

• APA example: Author, A. B., & Author, C. D. (Year). Title of the article. Journal Name, vol(issue), pages. https://doi.org/...

• BibTeX:

@article{author2024title,
  author  = {Author, A. B. and Author, C. D.},
  title   = {Title of the article},
  journal = {Journal Name},
  year    = {2024},
  volume  = {12},
  number  = {3},
  pages   = {45--67},
  doi     = {10.xxxx/xxxxx}
}

Reused figures¶

State the source URL and the licence string under which the figure is reused (e.g. CC-BY-4.0, Crown Copyright, © ECMWF). Match the licence to the original publication.

Tools¶

MyST markdown¶

Use enhanced markdown features (e.g. colored cells, icons) provided by MyST markdown to enhance your notebooks.

Cross-references & placeholder links¶

Avoid HTML <a> tags without href and notebook cross-references built with plain HTML; they render poorly and flood the build with warnings.

Metadata¶

Apply metadata at the notebook level and at the cell level according to a metadata-schema described here: https://github.com/ecmwf-training/jn-metadata-schema.