Guides on Ocean Model Validation

Tidal Analysis

Mon, 01 Jan 0001 00:00:00 +0000

Tidal Analysis Guide

Overview

tidal-analysis extracts tidal harmonic constituents from model output and validates them against satellite tidal atlases (FES2014, TPXO9) or tide gauge records from the GESLA database.

The harmonic analysis uses utide to fit sinusoidal components at each grid point or station location. Model amplitudes and phases are then compared to the reference atlas or gauge data.

Analysis modes

Mode	Flag	Description
`gesla`	`--mode gesla`	Harmonic analysis at GESLA tide gauge locations (fast; recommended; config default)
`spatial`	`--mode spatial`	Harmonic analysis on the full model grid, compared to a tidal atlas
`both`	`--mode both`	Run spatial and GESLA together
`stations`	`--mode stations`	Named stations listed under `stations:` in config

Model source: `--source` / `--experiment`

The model file to read no longer lives in the per-run config. It comes from config/sources.yaml, keyed by --source, with --experiment naming the run folder under that source:

Gridded 2D Validation

Mon, 01 Jan 0001 00:00:00 +0000

Gridded 2D Validation Guide

Overview

gridded-2d-validation compares any horizontal 2-D model field against a gridded observation product. Three layer modes are supported:

Layer	Description	Typical use
`surface`	2-D field or top of 3-D output	SST, SSS, SSH
`bottom`	Deepest wet cell of 3-D output	Bottom temperature / salinity
`<depth_m>`	Horizontal slice at a fixed depth (m)	Depth-layer climatology

Multiple layers can be run in a single invocation.

There are four shipped configs: gridded_2d_validation.yaml is the generic one, with any combination of layers via --layers. gridded_2d_validation_surface.yaml, _bottom.yaml and _depths.yaml are the dedicated single-purpose variants used for NSe.

Gridded 3D Validation

Mon, 01 Jan 0001 00:00:00 +0000

Gridded 3D Validation Guide

Overview

gridded-3d-validation validates model temperature and salinity (or any 3-D variable) against a gridded observation product — WOA23 climatology, CMIP6 ensembles, Copernicus reanalysis, or any dataset that provides values at every horizontal grid point and a set of depth levels.

The observations are regridded onto the model grid and compared cell-by-cell, enabling:

Spatial statistics maps (RMSE, bias, MAE, correlation per grid point)
Time-mean comparison maps at selected depth levels
Monthly statistics bar charts
Statistics text file (overall + monthly breakdown)

When to use this tool vs profile validation: Use gridded-3d-validation for climatologies or reanalyses that cover the full model domain at all depths. Use argo-profiles, cruise-ctd-profiles, or fixed-platform for sparse in-situ observations scattered in space and time.

Profile Validation

Mon, 01 Jan 0001 00:00:00 +0000

Profile Validation Guide

Overview

Five scripts share the same profile validation workflow:

Command	Observation source
`argo-profiles`	Argo floats (Ifremer ERDDAP)
`glodap-profiles`	GLODAP v2.2023 bottle data
`wod-profiles`	World Ocean Database (NOAA ERDDAP)
`cruise-ctd-profiles`	ICES / EMODnet cruise CTD casts
`ices-profiles`	ICES/ECOVAL profiles (local Feather files)
`fixed-platform`	EMODnet fixed-platform (mooring/buoy) profiles

All six follow the same config structure, output layout, and command-line flags.

Config structure

Annotated example configs: config/argo_profiles.yaml · config/glodap_profiles.yaml · config/cruise_ctd_profiles.yaml · config/wod_profiles.yaml · config/ices_profiles.yaml · config/fixed_platform.yaml

MLE Comparison

Mon, 01 Jan 0001 00:00:00 +0000

MLE Cross-Experiment Comparison Guide

Overview

Standard validation metrics (RMSE, bias, correlation) compare each experiment against observations in isolation. When you have three or more experiments that share the same observation dataset — sensitivity runs, ensemble members, or physics variants — a scalar metric gives no information about the joint structure of the errors.

MLE comparison in reduced-rank (SVD) space addresses this. The joint residual matrix across all experiments is decomposed with SVD, and each experiment is ranked by its Gaussian log-likelihood in the leading modes. This is the same “optimal fingerprinting” framework used in climate attribution (Allen & Tett 1999): the leading SVD modes capture the dominant joint variance pattern, and the log-likelihood in that low-dimensional space is a principled, multi-dimensional distance from perfect.

Run Validation

Mon, 01 Jan 0001 00:00:00 +0000

run-analyses Guide

This guide used to document a run-validation command. That command no longer exists — it was replaced by run-analyses (cli/run_analyses.py), which has a different config layout and CLI. This page now documents the current tool; the title and URL are unchanged.

Overview

run-analyses is the master orchestrator. It calls each step’s own CLI entry point as a subprocess, reusing one YAML config per step (config/run_analyses.yaml maps step names to those per-step config files).

Scenario Analysis

Mon, 01 Jan 0001 00:00:00 +0000

Scenario Analysis Guide

Overview

The scenario workflow has three stages:

CMIP6 forcing  ──► bc correct ──► bias-corrected forcing
                                        │
                               ocean model (future run)
                                        │
                         ┌─────────────┴─────────────┐
                   single-scenario              multi-scenario
                  (trends, changes)       (SSP comparison)

Bias-correct CMIP6 atmospheric forcing against ERA5 (or equivalent) so its statistical properties match the observational reference over the calibration period.
Run the ocean model with the corrected forcing for each SSP scenario.
Analyse the ocean output — trend maps, time series, regional means — for one scenario at a time or across multiple scenarios simultaneously.

Step 1 — Bias correction

Note: bc correct, bc diagnostics, and bc check have moved to ocean-prep. Install and run them from the ocean-prep repo. Config and guides are at ocean-prep/config/bc_correct_example.yaml and ocean-prep/guides/.

Push To Remote

Mon, 01 Jan 0001 00:00:00 +0000

push-to-remote Guide

Overview

push-to-remote is the other half of the post-simulation handoff, alongside update-from-remote. Run it on the simulation server (e.g. an HPC login node) right after a batch of analyses finishes there, to send the results to the machine that actually generates and deploys the Hugo site (the “analysis server”, e.g. bb-server1).

It exists because the two machines are not symmetrically reachable: the simulation server typically has outgoing network access only, and the analysis server has no route back to it at all. Any transfer must be initiated from the simulation server, pushing out — never initiated from the analysis server trying to pull in. push-to-remote wraps manage-analyses sync ... --put, which is exactly that: an rsync, run from here, pushing local files out.

River Flow and Nutrient Load Projection

Mon, 01 Jan 0001 00:00:00 +0000

River Flow and Nutrient Load Projection Guide

river-projection (stage 1, below) lives in ocean-prep, alongside bc-correct/bc-diagnostics — install and run it from the ocean-prep repo (cli/river_projection.py), with its config at ocean-prep/config/river_projection_example.yaml. river-diagnostics (stage 2) stays in ocean-post. Confirmed 2026-10-07; this page previously referenced a config/river_projection.yaml in ocean-post that was never there, and the real tool and config were found in ocean-prep instead. No project-specific copy of the config exists yet in this checkout — the only one found is ocean-prep’s own example.

Update From Remote

Mon, 01 Jan 0001 00:00:00 +0000

update-from-remote Guide

Overview

update-from-remote is a one-command post-simulation pipeline. After a model run finishes on a remote machine and the analysis scripts have written their outputs there, this command:

sync — rsyncs the remote analyses/ tree to the local machine
merge — flushes staging YAML records into simulation_list.db
scan — registers any experiments found on the filesystem but not yet in the DB
report — regenerates all Hugo pages via ocean-reporting
deploy — builds and pushes the Hugo site to gh-pages (only with --deploy)

Both REMOTE and LOCAL_ANALYSES are required positional arguments. There are no defaults, which prevents accidentally syncing into the wrong directory.

Manage Analyses

Mon, 01 Jan 0001 00:00:00 +0000

manage-analyses Guide

Overview

manage-analyses is the housekeeping tool for the analyses/ output tree. All subcommands default to a dry run — add --apply to actually execute.

Subcommand	Purpose
`clean`	Remove files at the wrong directory depth (non-canonical layout)
`wipe`	Remove all regeneratable outputs so scripts can be re-run from scratch
`sync`	Rsync the remote analyses tree to a local directory
`import-stats`	Import existing CSV statistics files into `statistics.db`

clean

Removes files that do not conform to the canonical layout — for example, plots written directly under validations/<experiment>/plots/ instead of the correct plots/<domain>/<model>/<period>/<type>/ path. Canonical files are left untouched.

Simulation List

Mon, 01 Jan 0001 00:00:00 +0000

Simulation List Guide

Overview

simulation-list manages the experiment registry — a SQLite database that tracks every analysis run, its parameters, and its status. The registry is used by ocean-reporting to populate the Hugo site and by update-from-remote after each sync.

The registry uses a two-step write pattern to avoid race conditions when multiple analysis scripts run in parallel:

Each script writes a small staging YAML file under analyses/staging/.
simulation-list merge atomically flushes all staging files into the DB.

Subcommands

# Show DB contents and pending staging files
simulation-list status [--base-dir DIR]

# Flush staging → DB
simulation-list merge  [--base-dir DIR]

# Export DB to a human-readable YAML snapshot
simulation-list to-yaml out.yaml [--base-dir DIR]

# Migrate a legacy YAML registry into the DB
simulation-list to-sqlite old_registry.yaml [--base-dir DIR]

--base-dir defaults to ./analyses.

Statistics Database

Mon, 01 Jan 0001 00:00:00 +0000

Statistics Database Guide

Overview

Every analysis script writes its results to human-readable TXT/CSV files inside the analyses/ tree and records the same numbers in a SQLite database at analyses/statistics.db. The database makes it easy to compare experiments, track how metrics change over time, and query across areas and variables without parsing text files.

The database is managed by lib/stats_db.py.

Tables

Table	Purpose
`statistics`	Core metrics from 2-D gridded, 3-D, and profile analyses
`monthly_statistics`	Month-by-month breakdown (child of `statistics`)
`tidal_statistics`	Tidal constituent summary aggregated across stations
`mle_rankings`	MLE cross-experiment ranking rows
`bc_statistics`	Bias-correction calibration and future-period metrics

statistics

One row per (area, experiment, variable, period, layer, model, obs_source, depth_label) combination. A UNIQUE constraint on those eight columns means re-running an analysis upserts the row rather than duplicating it.

Reporting

Mon, 01 Jan 0001 00:00:00 +0000

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:

Hugo Deployment

Mon, 01 Jan 0001 00:00:00 +0000

Hugo Deployment Guide

Overview

Reporting explains ocean-reporting’s options and the analyses/ tree it reads. This guide is about what happens after that: getting the generated Hugo content actually live, and the real mistakes that have already happened doing it.

There are two entry points to the exact same underlying code — pick whichever fits the situation:

update-from-remote — sync a remote cluster’s analyses/ down, merge/scan into the DB, then report + deploy, all in one command. Right when there’s fresh data to pull in first.
Manual two-step (used directly against data that’s already local, e.g. on the reporting host itself): the calling project’s own regenerate_hugo.py --apply, then this repo’s own deploy_ghpages.py --apply. Both relay over ssh to the reporting host automatically if run from elsewhere. regenerate_hugo.py isn’t part of this repo — it lives in the site’s own repo (e.g. oceanicu_3d/regenerate_hugo.py), and its own docs/web-regeneration.md has the full detail for that side.

Either path ends up calling cli.reporting:main (as ocean-reporting in one case, python3 -m cli.reporting in the other) and this repo’s own deploy_ghpages.py directly. A bug or fix in lib/reporting.py affects both equally.

Regridding

Sat, 10 Oct 2026 00:00:00 +0000

Regridding User Guide

ocean_data.regridding provides xESMF-based regridding with automatic weight-file caching, domain subsetting, and coordinate name normalisation. The regrid command (cli/regrid.py) exposes the same functionality as a command-line tool. ocean-post re-exports the same API from ocean_post.regridding for backward compatibility; import from ocean_data.regridding in new code.

1. Introduction

Regridding maps data from one spatial grid to another — for example interpolating a global 0.25° satellite observation product onto a regional 1 km model grid, or the other way round, before computing validation statistics.

Guides on Ocean Model Validation

Tidal Analysis

Tidal Analysis Guide

Overview

Analysis modes

Model source: --source / --experiment

Gridded 2D Validation

Gridded 2D Validation Guide

Overview

Gridded 3D Validation

Gridded 3D Validation Guide

Overview

Profile Validation

Profile Validation Guide

Overview

Config structure

MLE Comparison

MLE Cross-Experiment Comparison Guide

Overview

Run Validation

run-analyses Guide

Overview

Scenario Analysis

Scenario Analysis Guide

Overview

Step 1 — Bias correction

Push To Remote

push-to-remote Guide

Overview

River Flow and Nutrient Load Projection

River Flow and Nutrient Load Projection Guide

Update From Remote

update-from-remote Guide

Overview

Manage Analyses

manage-analyses Guide

Overview

clean

Simulation List

Simulation List Guide

Overview

Subcommands

Statistics Database

Statistics Database Guide

Overview

Tables

statistics

Reporting

Reporting Guide

Overview

Prerequisite: the analyses/ tree

Hugo Deployment

Hugo Deployment Guide

Overview

Regridding

Regridding User Guide

Contents

1. Introduction

Model source: `--source` / `--experiment`