Reporting Guide

Overview

ocean-reporting reads the analyses/ directory tree produced by the validation scripts and generates two types of output:

• Hugo Markdown pages — a structured static website showing plots, statistics tables, and summary text for every area and experiment.
• PDF report — a self-contained document with the same content, built with reportlab.

Both outputs can be produced in a single run by combining --hugo and --pdf.

Prerequisite: the analyses/ tree

All validation scripts write to a canonical tree under output.analyses_dir (resolved from OCEANICU_ANALYSES_FOLDER — see the tidal/gridded guides). The exact layout is defined in lib/layout.py:

<analyses_dir>/
├── areas/
│   └── <AREA>/
│       ├── *.md                              ← hand-written prose, merged onto the area page
│       └── validations/
│           └── <EXPERIMENT>/
│               ├── plots/
│               │   └── <domain>/               ← physics | bio
│               │       └── <model>/            ← e.g. pyGETM
│               │           └── <period>/       ← e.g. 2016 | 2016-2023
│               │               └── <type>/     ← surface | argo | tidal | wod | ices | …
│               │                   └── *.png
│               └── tables/
│                   └── <domain>/
│                       └── <model>/
│                           └── <type>/
│                               └── *_statistics.txt
└── experiments/experiment_registry.sqlite     ← simulation registry (optional)

<EXPERIMENT> is either a single name (the legacy layout, still used by NS and AMM7) or <SOURCE>/<experiment> — NSe’s layout, produced by running the validation scripts with --source. Both are discovered the same way.

Recognised <type> values: surface, bottom, 3d, argo, glodap, wod, cruise, ices, platform, tidal, scenario, and depth-slice names like 0050m.

The reporter discovers areas and experiments by walking this tree, and classifies each experiment by its <type> directory name into one of four buckets: tidal, scenario, mle_comparison (a flat mle_comparison/ folder by name), or validation (everything else — surface, bottom, 3d, argo, wod, cruise, ices, platform). No additional config is needed.

Basic usage

# All areas → Hugo
ocean-reporting --analyses-dir ./analyses --recursive \
    --hugo /path/to/hugo/

# Single area → Hugo
ocean-reporting --analyses-dir ./analyses --area NS \
    --hugo /path/to/hugo/

# Single experiment → Hugo
ocean-reporting --analyses-dir ./analyses --area NS \
    --experiment Baseline --hugo /path/to/hugo/

# All areas → PDF
ocean-reporting --analyses-dir ./analyses --recursive \
    --pdf report.pdf

# Single area → PDF
ocean-reporting --analyses-dir ./analyses --area NS \
    --pdf NS_report.pdf

# Both outputs in one run
ocean-reporting --analyses-dir ./analyses --recursive \
    --hugo /path/to/hugo/ --pdf report.pdf

Options

--area on a --recursive run is a publish allowlist, not just a filter. Any area not named prunes its already-published content//static/ pages — it is removed, not merely skipped. This is how regenerate_hugo.py’s enabled_areas list (in regen_hosts.yaml) controls which areas are actually live on the site; see the Hugo deployment guide.

Hugo output structure

Pages are written flat under the Hugo content directory, one Markdown file per experiment, named <area>-<experiment> with / and _ in the experiment label turned into - (see validation_slug() in lib/layout.py):

hugo/content/
├── _index.md
├── areas/
│   ├── _index.md
│   ├── nse-boundaries.md
│   └── amm7.md
├── validations/
│   ├── _index.md
│   ├── nse-overview.md
│   ├── nse-cmems-tidal.md               ← area=NSe, experiment=CMEMS/tidal
│   ├── nse-woa-tidal.md
│   └── ns-baseline.md                   ← legacy, flat experiment name
└── scenarios/
    └── simulations/
        └── nse-cmip6-raw-gfdl-esm4-ssp126-run01/
            └── _index.md

Static assets (PNG plots, tables) are served from the Hugo static/ tree and linked from the Markdown pages automatically.

PDF output

The PDF contains a table of contents, one section per area and experiment, with embedded figures and statistics tables. It uses the reportlab library. If reportlab is not installed the --pdf flag raises an error with install instructions.

How experiment type is detected

FlexibleReportingManager._detect_experiment_type() walks the experiment directory via AnalysesLayout.iter_table_dirs/iter_plot_dirs — it reads known layout positions, not filenames — and returns the first match:

If an experiment directory contains results of multiple <type>s under validation (e.g. surface and 3d), all of them are reported on the one experiment page.

Area-level .md files — geographic description

Each area directory (<analyses_dir>/areas/<AREA>/) may contain one or more hand-written .md files with a description of the geographic domain. The reporter includes this text verbatim at the top of the area’s Hugo page and PDF section. Example:

---
title: North Sea
coordinates: [lon_min: -5, lon_max: 12, lat_min: 50, lat_max: 62]
---

The North Sea is a shallow shelf sea bounded by the British Isles to the west,
Scandinavia to the east, and the English Channel to the south.  It is strongly
influenced by Atlantic inflow through the Norwegian Trench and by riverine input
from the Rhine and Elbe.

Automating the full pipeline

update-from-remote wraps the reporting step as part of a larger pipeline: sync → merge → report → deploy. See guides/update-from-remote.md.