Guides

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 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 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 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 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-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 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 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 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 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 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 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 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 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 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 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. Contents Introduction Installation and setup Command-line interface Basic usage Selecting variables Choosing the regrid method The –target-variable flag Weight caching Global source grids Skipping domain subsetting Python API RegridManager .regrid() .subset_to_target_domain() regrid_data() open_with_chunks() Weight caching Regridding methods Coordinate name handling Domain subsetting Unit conversion Troubleshooting 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. ...