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 spawning-stock biomass (the SSB output, which needs output.ssb.enabled) per species over a configurable window (e.g. last 5 years of the run). The biomass output is read alongside as context; quantity=”biomass” compares it instead (explicit opt-in).

  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 the model to ICES SSB envelopes per species.

compare_predation_m2_to_sms(results, snap, *)

Per SMS prey species: biomass-weighted SMS M2 over ices_window beside the model's cod-attributed M2 over its trailing window_years.

format_m2_section(rows, *, window_years, ...)

Markdown lines for the SMS M2 comparison (appended by format_markdown_report).

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

Format comparison results as a markdown report (plus the SMS M2 section when given).

load_sms_m2(snapshot_dir[, scenario])

Load the SMS M2 snapshot described by index.json['sms_m2'].

load_snapshot(snapshot_dir)

Load an ICES SAG snapshot bundle from disk.

model_biomass_window_mean(results, species)

Mean model biomass (biomass output, >= output.cutoff.age) over the trailing window.

model_cod_attributed_m2(results, prey, *[, ...])

Annual tonnes of prey eaten by predators over the prey's mean biomass, per year of the trailing window (biomass-basis M2), summarised as mean/min/max.

model_predation_rate_by_stage(results, ...)

Window statistic ("median" or "mean") over the annual rows of the model's TOTAL predation rate (all predators) per life stage from the mortalityRate output — context for the non-cod residual.

model_ssb_window_mean(results, species[, ...])

Mean model spawning-stock biomass (SSB output, needs output.ssb.enabled) over the window.

sms_m2_weighted_by_year(snap, sms_species, *)

Per-year M2 aggregated over ages: Σ M2(a)·w(a) / Σ w(a) with w = BIO (basis="biomass") or N (basis="numbers") at age from the key run's quarter-1 stock.

Classes

IcesSnapshot(manifest, assessments, ...)

Loaded ICES SAG snapshot bundle for a model.

ModelCodM2(mean, min, max, n_years, ...)

Cod-attributed predation mortality on one prey over the model's trailing window.

PredationM2Comparison(model_species, ...[, ...])

One prey stock: SMS cod-predation M2 beside the model's cod-attributed rate.

SmsM2Snapshot(m2, weights, meta, snapshot_dir)

Loaded WGSAM SMS M2 bundle (one key-run scenario, sentinel rows dropped).

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

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