osmose.validation.ices

ICES Stock Assessment Graph (SAG) snapshot validator for OSMOSE outputs.

Reads frozen ICES SAG JSON snapshots (produced by _pull_ices_snapshots.py or fetched live via the ICES MCP server) and compares model run outputs against per-species SSB envelopes.

Snapshot layout (matches data/baltic/reference/ices_snapshots/):

<snapshot_dir>/
    index.json                          # manifest: model_species_to_ices_stocks, units_by_stock
    <stock>.assessment.json             # list of {year, ssb, f, ...} dicts
    <stock>.reference_points.json       # {blim, bpa, fmsy, msy_btrigger, ...}

The validator:

  1. Loads the snapshot manifest + per-stock assessments.

  2. Computes the model’s mean biomass per species over a configurable window (e.g. last 5 years of the run).

  3. Computes the ICES SSB envelope (min, max) over a configurable window of historical SAG data, summed across tonnes-unit stocks linked to the species.

  4. Reports per-species: in-range (model_mean ∈ [ices_min, ices_max]), magnitude factor (model_mean / ices_geomean), excluded index-unit stocks (which can’t be summed with tonnes-unit stocks).

Index-unit stocks are excluded from the envelope sum because relative indices and tonnes can’t be combined. This matches the existing scripts/validate_baltic_vs_ices_sag.py convention.

Functions

compare_outputs_to_ices(results, snapshot, *)

Compare model biomass to ICES SSB envelopes per species.

format_markdown_report(comparisons, *[, ...])

Format comparison results as a markdown report.

load_snapshot(snapshot_dir)

Load an ICES SAG snapshot bundle from disk.

model_biomass_window_mean(results, species)

Mean model biomass for species over the last window_years of the run.

Classes

IcesSnapshot(manifest, assessments, ...)

Loaded ICES SAG snapshot bundle for a model.

SpeciesBiomassComparison(species, ...[, ...])

Result of comparing one species' model mean biomass to its ICES envelope.