oceanarray 0.5.1__tar.gz → 0.6.0__tar.gz

{oceanarray-0.5.1 → oceanarray-0.6.0}/.gitattributes

@@ -6,3 +6,7 @@
 # remain tracked/committed (the demo suite is served from _static by Sphinx).
 tests/fixtures/golden/** linguist-generated=true
 docs/source/_static/demo/** linguist-generated=true binary
+
+# The init-template golden is compared byte-for-byte against mooring.save output
+# (which writes LF on every platform); keep it LF so Windows autocrlf cannot flip it.
+tests/fixtures/init_template_golden.yaml text eol=lf

{oceanarray-0.5.1 → oceanarray-0.6.0}/.github/workflows/tests.yml

@@ -25,6 +25,10 @@ jobs:
           # ubuntu-only to keep the job count down.
           - { os: ubuntu-latest, python-version: "3.12" }
           - { os: ubuntu-latest, python-version: "3.13" }
+          # Forward-looking probe for 3.14: allowed to fail (experimental) so a
+          # dependency not yet 3.14-ready does not block the required check. Not
+          # in the supported range / pyproject classifiers yet.
+          - { os: ubuntu-latest, python-version: "3.14", experimental: true }
 
     steps:
       - uses: actions/checkout@v7
@@ -33,6 +37,7 @@ jobs:
         uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
+          allow-prereleases: ${{ matrix.experimental == true }}
           cache: "pip"
 
       - name: Install oceanarray (test extra = runtime + pytest)

oceanarray-0.6.0/CHANGELOG.md

@@ -0,0 +1,384 @@
+# Changelog
+
+All notable changes to oceanarray are documented here.
+
+---
+
+## [Unreleased]
+
+### Added
+
+- `location.parse_coordinate` reads one latitude or longitude value; a non-finite position counts as unknown (#132).
+- Reports for moorings built from imported originator files (OceanSITES/RODB): an imported current meter holding only pressure and velocity no longer crashes the instrument page (its temperature, speed, trajectory and hodograph panels show as not applicable); a `currentmeter` instrument gets the "Current meter" masthead label; the deployment-timing table adapts (all-imported → a trimmed "Record first/last" table; mixed → imported rows marked and not falsely flagged as stopped-early); the array report accepts a mooring entry's `config:` as a path relative to the array description; and the instrument inventory names the directory it searched when no stage file is found.
+- `report_sections` in the mooring YAML turns on optional report sections, keyed by page: `report_sections: {grid: [overflow]}`, resolved by `oceanarray.mooring.resolve_report_sections`.
+- Pressure in `kPa` (converted to dbar, ×0.1) and the OOI ERDDAP unit spellings `decibars`, `m.s-1`, `mS.cm-1` and `1e-3` (practical salinity). A `units_override` entry can be `{units, reason}`; the reason is kept in the variable's `units_override_reason` attribute.
+- Reducing a calibration dip: `oceanarray.pipeline.calibration.reduce_dip(record, variable, scheme=, deployment_pressure=)` gives one dip's correction per variable as a `Reduction` (value, the rule, the stops used, and for a slope its σ and residual). `standard`: temperature at the deepest stop; conductivity as the Sea-Bird AN31 slope through the origin over the stable stops below 500 dbar (200 dbar when fewer than two qualify; never shallower), weighted by `N / cond_std²`; a stop is stable when the CTD's std there is ≤ 0.002 °C (T) or ≤ 0.003 mS/cm (C), when the cast carries it; pressure as the mean offset near the deployment pressure. `rapid`: RAPID's deep-interval average for temperature and conductivity and its interpolation to depth for pressure. In a schema-1 caldip cast, `flagged` stops (reading off by more than caldip's tolerance) are used; `no_data` / `missing` / `unknown` never are. Not yet applied in stage 3.
+- The mooring YAML's `caldip:` block (the cast for each end of the deployment, `scheme: standard | rapid`, a per-variable `override`), checked by `validate` (every shape mistake an ERROR). `oceanarray.pipeline.calibration.caldip_ends` finds each end's `{cast}_caldip.nc` beneath the caldip root (`caldip_dir=`, else the block's `root`); `assign_dip_role` and `cast_time` say whether a cast is an instrument's pre- or post-deployment dip. Not yet applied in stage 3.
+- Reading caldip casts: `oceanarray.pipeline.calibration.read_caldip_cast` opens a `{cast}_caldip.nc`, refuses one with missing provenance, another schema version, an unrecognised units string or a repeated serial, rewrites its temperature, conductivity and pressure units to the registry spelling and its serials to the join key; `instrument_record` returns one instrument's per-stop record. Not yet applied in stage 3.
+- `oceanarray.export(mooring, *, mooring_dir=None, out_dir=None, array=None, grid=True, overwrite=False, dry_run=False)` and `oceanarray export MOORING [--array YAML] [-o DIR] [--no-grid] [--force] [-n]` — write a mooring's stage-3 files and grid as OceanSITES 1.4 files (default `<mooring folder>/oceansites/`); instruments that cannot be exported are listed and left out. The data-format page (`oceanarray_format`) now describes these files, with the earlier departures from OceanSITES (`N_LEVELS`, `contributor_*`, compact times) dropped.
+- `oceanarray.pipeline.oceansites.to_oceansites(ds, mooring, *, array=None, stack=None, source_file=None)` — one instrument's stage-3 dataset as an OceanSITES 1.4 deployment data file: variables on `(TIME, DEPTH)` with `DEPTH` the nominal instrument depth, `<PARAM>_QC` (reference table 2, the same flags), a data mode per variable (`DM_indicator`; `D` only with the calibration-dip correction recorded) and the §2.2 globals. `oceansites_filename` gives `OS_<platform>_<YYYYMM>_<mode>_<type>-<serial>-<depth>m.nc`. An ADCP is one file with its bins on `DEPTH` (nominal transducer depth ± range, by orientation; refused without one), `PRES` the pressure at each bin and `TRANSDUCER_PRES(TIME)` the measured transducer pressure and a failed or suspect `seabed_qc` merged into the velocity flags. A grid becomes a gridded file (`GRD`, §4.2): `OS_<platform>-<YYYYMM>_<start>-<end>_GRD_<interval>-DP<step>.nc`, `DEPTH` the pressure levels converted with `gsw.z_from_p`, `PRES` the levels, and `history` naming the stage files (pass `stack=`); only a provisional (`P`) grid is exported. The mooring description gains `platform_code` and `deployment_code` (default: the month of `deployment_time`); `site_code` comes from the array description and is left out when absent. The OceanSITES reader also reads `CSPD`, `CDIR`, `DOX2` and `TURB`.
+- `oceanarray.pipeline.read_mooring.read_mooring(mooring, *, stage=None, serials=None, allow_missing=False, mooring_dir=None, raw_dir=None)` — reads every instrument of one mooring into a dict of datasets keyed by serial. A mooring's identity is its `name:` field (every file is `<name>_<serial>_stage<N>.nc`); `mooring` may be a dict, a `*.mooring.yaml` path, or a directory holding one. `stage=None` finds and reads each raw file (from `raw_dir`) as stage 1 does — a missing `filename` found by the recovery-file naming convention, the Nortek header (also in a legacy `nortek/` folder), the raw header's calibration metadata — and returns it unmarked; entries marked `skip` are left out; `stage=1|2|3` opens the stage files (from `mooring_dir`) and checks the marker; on every path the description's facts are stamped (per-instrument: serial, instrument, hab, clamp_id, sample_interval_seconds, file_type, source_file; per-mooring: mooring_name, latitude/longitude + source, deployment/recovery window + source, waterdepth, density_reference). A dataset whose `serial` contradicts the description, or whose `mooring_name` differs from `name:` by more than case, raises `MooringError`; a case-only difference is corrected with a `history` line. Position and window keep their placeholders when absent, loudly (`location_source`/`deployment_window_source` = `"none"`, a WARNING). A listed instrument with no file at the requested stage raises unless `allow_missing=True`.
+- `oceanarray.pipeline.write_mooring.write_mooring(datasets, mooring_dir, *, overwrite=False)` — writes a dict of per-instrument datasets to `<mooring_dir>/<instrument>/<name>_<serial>_stage<N>.nc`, taking the name, instrument, serial and stage from each dataset's attributes; refuses a dataset whose `serial` attribute does not match its key.
+- `oceanarray.paths.stage_file(mooring_dir, name, instrument, serial, stage, *, tag="")` and `oceanarray.paths.product_file(mooring_dir, name, product)` (`product` in `paths.PRODUCTS` = `{"stack", "grid"}`) — the full-path builders for a mooring's stage files and products, keyed on the mooring `name`; `read_mooring`/`write_mooring` use them. With them, `paths.stage_suffix`, `stage_glob` and `product_glob` give the filename endings and search patterns; no other module spells `_stageN`, `_stack.nc` or `_grid.nc` (a test enforces it).
+- `oceanarray.readers` — a package reading one raw instrument file to a canonical dataset. `readers.read(path, *, file_type=None)` sniffs the file content (never the suffix) to pick the format, finds the Nortek `.hdr` beside a data file, and dispatches to a per-format module (`sbe`, `nortek`, `rodb`, `oceansites`, `netcdf`). A netCDF is read as OceanSITES when it carries a `TIME` dimension and an OceanSITES parameter code, and returned unchanged otherwise; an unrecognised file with no `file_type=` raises. The per-format reader bodies moved here unchanged from `processors.stage1` and the former `tools.readers`.
+- `oceanarray.pipeline._stage` — the `processing_stage` marker: `stamp(ds, stage, *, source=)` writes the marker, a `history` line and `source_file`; `require(datasets, stage, next_stage)` raises `StageError` when a dataset is at the wrong stage, naming the stage to run first. A file written before the marker existed is tolerated for one release (a missing marker on read is a WARNING).
+- `oceanarray.mooring` — the single seam for reading a mooring description: `load` (path, name + `proc_dir`, or dict; validates and raises `MooringError` on an invalid config), `check` (never raises; adds an unknown-top-level-key warning), `template` and `save`, plus `oceanarray.MooringError`. Every stage, report and CLI path now receives the loaded dict instead of calling `yaml.safe_load` itself; a test (`test_config_sites`) fails if a new mooring-config `safe_load` appears outside the loader. `scripts/survey_mooring_keys.py` lists the top-level keys on a processed-data root that are not yet in `mooring.KNOWN_KEYS`.
+- `oceanarray.pipeline.stage1.stage1(datasets, mooring)`, `oceanarray.pipeline.stage2.stage2(datasets, mooring)`, `oceanarray.pipeline.stage3.stage3(datasets, mooring, *, caldip_dir=None)`, `oceanarray.pipeline.stack.stack(datasets, mooring, *, dt_seconds=None)` and `oceanarray.pipeline.grid.grid(ds_stack, *, pmin, pmax, dp)` — the processing steps as pure functions over datasets, with no file I/O. `MooringProcessor`, `Stage2Processor`, `Stage3Processor`, `MooringStacker` and `MooringGridder` now read, call these, and write; stages 1–3 are unchanged in value, the stack (and so the grid) changes as below. `oceanarray.pipeline.raw_files` holds stage 1's raw-file finding (`resolve_raw_file`, `guess_instrument_filename`) and reading (`read_raw_file`).
+- `oceanarray stamp FILE... --declare N` and `oceanarray.pipeline.stamp.stamp_file(path, stage)` — write the `processing_stage` marker into a stage file written before it existed (`history`: "declared via stamp"). Refuses a stage that contradicts the filename or an existing marker; leaves an already-marked file untouched.
+- `oceanarray.process(mooring, *, stages=(1, 2, 3), serials=None, force=False, keep_going=True, mooring_dir=None, raw_dir=None, caldip_dir=None) -> list[Path]` — runs stages 1–3 for one mooring from its `*.mooring.yaml` path (or a directory holding one, or a loaded description with `mooring_dir=`), writing each stage's files and a log per stage, and returns every stage file of the stages run — written, or kept because it was already there (`force=True` rewrites; stage 1 also rewrites a file older than its raw file); each stage prints how many it wrote and kept. By default it carries on past a failed instrument (see `keep_going` below); `keep_going=False` raises `MooringError` naming the instruments that failed, after the stage has written the rest, and runs nothing after it. Stacking and gridding are not part of it. The previous form, `process(name, stage, proc_dir=…)` (all five stages, returns a bool), still works for one release (see *Deprecated*).
+- `oceanarray.run(mooring, *, stages=None, from_stage=None, serials=None, force=False, keep_going=True, mooring_dir=None, raw_dir=None, caldip_dir=None, dt_seconds=None, pmin=None, pmax=None, dp=None, stack_stage=3, report=False) -> list[Path]` — stages 1–3 (through `process`), then the stack (`<name>_stack.nc`) and the grid (`<name>_grid.nc`), rebuilt on every call; returns the stage files, then the stack and grid. `stages` lists the stages to run (default all); because the stack is rebuilt from the stage-3 files, they must run from the first one given through stage 3, so the stack never takes files older than the ones just written — `stages=(2, 3)` (or `from_stage=2`) re-runs stages 2 and 3 from the stage-1 files without `raw_dir`, while `stages=2` or `(1, 3)` is refused before anything runs. To run one stage on its own, use `process`. `stack_stage=2` (CLI `--stack-stage 2`) is a quick look at sea: it runs through stage 2 only and stacks and grids the stage-2 files (no QC flags, no interpolated pressure, no magnetic declination; every level's `source_stage` is 2). By default it carries on past failures (see `keep_going` below). With `keep_going=False` any failure raises, an instrument with no stage-3 file stops the stack, and a stack that left an instrument out is written but not gridded. The stack and grid settings come from the call, else from new optional `stack:` (`dt_seconds`) and `grid:` (`pmin`, `pmax`, `dp`) blocks in the mooring description, else 3600 s and 200–1000 dbar every 20 dbar; the merged settings are checked before anything runs, and `mooring.check` refuses a malformed block. When a strict run stops after it has rewritten stage files, or its new stack cannot be gridded, the stack and grid that no longer match are renamed `<name>_stack.stale.nc` / `<name>_grid.stale.nc` (a line says so; one stale copy per product, replaced by the next) — whatever the error that stopped it.
+- `keep_going` on `process` and `run`, **on by default** — as much as possible on a first pass, troubleshoot later: a failed instrument is logged and left out and the next stage runs on what has files; a stage-3 failure is logged, not raised; `run` stacks each instrument's stage-3 file, else its stage-2 file. What was taken from stage 2 is recorded in the stack's new per-level `source_stage` variable and in a `stage2_instruments` attribute (the grid inherits it); instruments with neither, or that failed in this run (their older files are not used), are named in `instruments_omitted`; after a stage-3 failure every instrument is stacked from stage 2; what failed is recorded in a `keep_going_failures` attribute on the stack and grid; an instrument that failed in one stage is left out of the later stages of the same run (its older files are neither rebuilt from nor used as another instrument's pressure source); a stack that cannot be gridded (e.g. no pressure left) is kept, with a warning and no grid.
+- `data_mode = "P"` (OceanSITES provisional) on every stage-3, stack and grid file. Nothing earns delayed mode (`D`) yet.
+- A stage-3 instrument whose pressure is interpolated records the stage-2 files it came from: `pressure_source_serials` and `pressure_source_files` (file name, SHA-256, modification time) on its `pressure` variable. When stage 3 keeps or skips such a file and its sources have changed since, a WARNING names it.
+- `oceanarray.reports.report(mooring, *, kind="mooring", pdf=False, ...) -> Path` — builds a mooring's report (summary page and, unless switched off, its instrument, stack and grid pages, plus an A4 PDF with `pdf=True`), the array index (`kind="array"`, from an `*.array.yaml`) or the recovery table (`kind="recovery"`), and returns the main page. Instruments and their files come from the mooring description. A failure raises `MooringError`; a PDF without the `pdf` extra raises rather than skipping. A loaded description is used as given. The mooring's folder is wherever its description is, under any name: the pages are written to its `report/` subfolder and named, and the stage, stack and grid files found, from `name:` (before, the report assumed `<proc-dir>/<name>/` and failed on any other layout). `oceanarray report` calls it; when the mooring report fails, it now stops there (no recovery table or PDF) and exits 1, and a recovery table that cannot be built exits 1 (before: ignored).
+- `oceanarray.reports.report_paths(mooring, *, mooring_dir=None, out_dir=None, report_dir=None, pdf_dir=None)` — where `report` writes each page, without building any (the description is read only for its `name:`, so a half-filled one works); `oceanarray report --dry-run` prints these.
+- `paths.resolve_report_dir(..., mooring_dir=)` — the default report location is `<mooring_dir>/report` when the mooring's folder is given.
+- `oceanarray.reports.summary(mooring)` — the console summary `oceanarray process --report` prints (one line per instrument: records, time span, depth, interval, variables), listing the instruments of the description rather than the files in the folder.
+- `run(..., report=True)` builds the report after the grid and returns its summary page last.
+- `import oceanarray as oa` gives the whole public API: `oa.mooring`, `oa.read`, `oa.read_mooring`, `oa.stage1`, `oa.stage2`, `oa.stage3`, `oa.process`, `oa.stack`, `oa.grid`, `oa.run`, `oa.write`, `oa.write_mooring`, `oa.report`, `oa.MooringError` and `oa.StageError` — every name in `oceanarray.__all__` resolves after a bare import, loaded on first use (importing the package no longer imports xarray).
+- `oceanarray.paths.stale_file(path)` — where a product that no longer matches its stage files is set aside (`<name>_stack.stale.nc`).
+- A migration page, *Upgrading from 0.5 to 0.6* (`docs/source/migrating_0_6_0.rst`), with every renamed name and its replacement; a test keeps it in step with the deprecation table.
+- `oceanarray process`, `run`, `report`, `animate` and `plot` take the mooring as a path — its `*.mooring.yaml` or the folder holding it, under any name — as well as a name with `--proc-dir`.
+- `--only SERIAL ...` on `process`, `run`, `report` and `animate` (was `--serial`, still accepted until 0.7.0 with a note on stderr); `plot --var-y` / `--var-color` (the underscore spellings likewise).
+- `-v` / `--verbose` now does something: each stage names every file it wrote or kept (DEBUG).
+- Stack and grid pages carry an amber note when instruments were stacked from stage 2 (naming them, and that they have no QC flags or interpolated pressure), and a second one above the velocity figures when their velocities have no magnetic declination (magnetic north); the stack records those instruments in a new `stage2_magnetic_north` attribute (the grid inherits it).
+- `oceanarray init` writes the optional `stack:` and `grid:` blocks, commented out with their defaults (`mooring.save(..., optional_blocks=True)`); the `name:` comment no longer says it must match the directory.
+- `oceanarray.instruments.instrument_entries(mooring)` — the one place the `clamp`/legacy-`instruments` fallback and the inline merge live, used by every stage, report and the CLI; it treats a present-but-null `clamp:`/`inline:` as empty (previously a `TypeError`).
+
+### Changed
+
+- Report mastheads (mooring, stack, grid, recovery table) come from one fact list: four cruise/ship fields (recovery `UNK` unless given), positions in degrees and decimal minutes, durations over 6 months in months (`11.2mon`, `1y 10.0mon`), instruments counted by type; the mooring page lists an entry with no `hab` as not stacked; `validate` warns on a position key without its pair, and on a recovered mooring that gives only the legacy `cruise`/`ship` (deployment values only) (#132).
+- Stack: default step 3600 s (was 60 s); each instrument takes its nearest sample within ±dt/2, with no time interpolation, on a time axis of whole steps; instruments slower than the step are named in `instruments_slower_than_step` (#133).
+- The command-line help says, for every subcommand, what it reads and writes, with an `Examples:` block; flags follow the family conventions. Renamed (old spellings accepted until 0.7.0 with a note on stderr): `process --report` → `--summary`, `plot --downsample` → `--downsample-seconds`, `export --overwrite` → `--force`, `stamp --stage` → `--declare`. All deprecated spellings now share one mechanism and message ("… is deprecated and removed in 0.7.0; use …").
+- `oceanarray validate` takes a mooring the way the other commands do (its `*.mooring.yaml`, its folder, or a name with `--proc-dir`) and gains `--strict` (exit 1 on warnings too; the default still exits 0 when there are only warnings).
+- A usage error (a removed flag, a missing `--raw-dir` or `--proc-dir`, an option that does not combine) exits 2 with an `ERROR:` line on stderr; a processing failure still exits 1. A mooring name with `--proc-dir` whose folder does not exist is an error naming the folder.
+- `python -m oceanarray` runs the CLI; `-v` is accepted after the subcommand as well as before it; `export -n/--dry-run` lists the files it would write.
+- `process --stage` help marks `stack` and `grid` as deprecated (use `run`), and their tuning flags are hidden from `process --help`.
+- Private helpers follow one naming table (CONTRIBUTING, "Private helpers"): one verb per job, figure helpers `_draw_<what>` / `_make_<what>_b64` with no `_fig` suffix, 85 renamed; their docstrings are one line, with the reasons the code cannot show kept as comments (≈ −1,400 lines). The three private `_safe_serial` wrappers are gone (`paths.safe_serial`). Four dead helpers deleted, the duplicate `_times_to_float` and the three module `_log`s collapsed (into `oceanarray.logger.log_message`), and four one-line wrappers inlined. No public name or behaviour changes; report `source:` lines name the new helpers.
+- `oceanarray process --dry-run` lists the file every stage would write (new, keep or rewrite) and, for stage 3, which instruments get interpolated pressure; it works by path and needs no `--raw-dir` (before: stage 3 only, by name under `--proc-dir`). The README, the demo notebook and the method pages use the verbs.
+- The report page switches lose their short forms (`-i`, `-s`, `-g`, `-A`; accepted with a note until 0.7.0): the short flags are `-o` (always an output directory), `-n` (`--dry-run`) and `-v`.
+- The CLI is a package, `oceanarray.cli`, with one module per subcommand (as ctdcast's); `oceanarray.cli.build_parser` and `main` are unchanged. `animate -o DIR` is now the output directory, as on `report`, `run` and `plot` (`--output FILE` names a single GIF; an old `-o FILE.gif` is still read as the file, with a note). `process --stage stack|grid` prints that it is removed in 0.7.0 (`oceanarray run` builds the stack and grid).
+- `oceanarray process` runs stages 1–3 through `oceanarray.process`: it carries on past a failed instrument and exits 0 when it finishes (before: exit 1 if any instrument failed); `--strict` stops at the first failure and exits 1, as on `run`; a description error exits 1. `--stage stack` / `grid` still run the pre-0.6 way, with a note, and need `--proc-dir` (`oceanarray run` builds the stack and grid); `--strict` with them is refused.
+- `oceanarray animate` finds each instrument's file from the description (stage 3, else stage 2) instead of searching the folder; `--only` matches a serial exactly (before: any file whose name contained it), and a serial not in the description is named in a warning.
+- `oceanarray plot --colormap` / `--downsample` are passed to the plot instead of overwriting `parameters.DEFAULT_COLORMAP` / `DOWNSAMPLE_SECONDS` for the rest of the process.
+- The stack page's figures are drawn by `plotters` functions instead of inside the page builder: `plotters.timeseries.draw_stack_timeseries` (the P/T/S and U/V/W panels, oxygen, turbidity), `plotters.diagnostic.draw_instrument_spacing` and `plotters.current.draw_aquadopp_tilt_panels`, with the shared per-level line colours in `plotters.helpers.level_line_styles`. The time-series figures now render at the full slot width with the legend inside the canvas (they were cropped to a tight box around an outside legend, so the page rescaled them), and every figure's `source:` caption names its draw function.
+- Stages 1, 2 and 3 return their datasets holding the values their files will hold — float64 stored as float32 (time and position excepted), time rounded to the file's float64-seconds encoding — so a dataset passed on in memory equals the same file read back, and a full run and a later single-stage re-run agree exactly. Written files are unchanged. `oceanarray.writers.netcdf.as_stored(ds)` does the conversion.
+- Stage 3 always reads the whole mooring's stage-2 files and writes only the instruments asked for (`serials=` / `--serials`). Before, a run for one sensorless instrument read only its own file, found no pressure source, and wrote it without pressure.
+- Required mooring-config keys are now `name` and `waterdepth` only; `deployment_time` and `recovery_time` are recommended — absent, they produce a WARNING (Stage 2 can detect the window from the records) rather than the ERROR `validate` used to report.
+- Stage 2 raises `MooringError` on a present-but-unparseable `deployment_time`/`recovery_time` (a log-sheet typo) instead of silently treating it as absent; a genuinely absent value is still tolerated (`NaT`).
+- `stack` raises `MooringError` naming both keys when the config has no deployment window (the common time axis is that window) instead of a bare `KeyError`.
+- Stage 1 names its output files from the description's `name:`, as stages 2 and 3 do (previously from the mooring directory name).
+- Stage 1, 2 and 3 files carry `processing_stage` and the description's stamped facts (instrument, serial, hab, position, deployment window, …).
+- Stacking detects each instrument's sampling interval from its time stamps; `sample_interval_seconds` in the mooring description is no longer read.
+- `oceanarray report --dry-run` previews a half-filled config without raising: it prints the validation issues and lists what parses, and only stops on a file that is not YAML at all.
+- `oceanarray init` builds its stub through `mooring.template` + `mooring.save`; the written file is byte-identical to before.
+- `mooring.KNOWN_KEYS` (the vocabulary the unknown-key warning checks against) gains the position tiers `seabed_*` / `deployment_*` / `planned_*`, `qc_ranges` and `directory`, confirmed against real mooring descriptions.
+- An instrument's `hab` is filled from `hab_bottom` (downward) or `hab_top` (upward) by its `orientation`, for `clamp` and `inline` entries alike (before: `inline` only, `hab_bottom` only); explicit `hab` wins. `validate` ERRORs when an `orientation` lacks its hab key, and names a stacked instrument with no resolvable `hab` in `instruments_omitted` (a strict run stops before the grid) rather than omitting it silently.
+
+### Deprecated
+
+Every old name below still works, warns (`DeprecationWarning`, naming its replacement) and is removed in 0.7.0; the list lives in one table, `oceanarray._deprecated.RENAMED`.
+
+- `oceanarray.parameters` — use `oceanarray.config.parameters`.
+- `MooringProcessor`, `Stage2Processor`, `Stage3Processor`, `MooringStacker`, `MooringGridder` — use `oceanarray.process` / `oceanarray.run`, or the pure `stage1`/`stage2`/`stage3`/`stack`/`grid` on datasets.
+- `oceanarray.inspect.vars` / `attrs` → `inspect.variables` / `inspect.attributes` (the old names shadow the builtin `vars`).
+- Names with a British/American variant spelling: `legacy.process_rodb.normalize_by_middle_percent` / `normalize_dataset_by_middle_percent` → `to_zscore` / `to_zscore_dataset` (they return z-scores over the central `percent`).
+- `oceanarray.process(name, stage, proc_dir=…)` — warns (`DeprecationWarning`) and is removed in 0.7.0. Pass the `*.mooring.yaml`: `oceanarray.process(yaml_path, raw_dir=…)` runs stages 1–3, `oceanarray.run(yaml_path, …)` runs stages 1–3, stack and grid.
+- `plotters.timeseries.draw_grid` — use xarray's `DataArray.plot.pcolormesh` (or `.plot.contourf`) on the grid variable; it had no caller in the package.
+- `config.validation.validate_mooring_yaml(path)` — use `oceanarray.mooring.check`, which reads the file once and adds the unknown-key check. The wrapper warns and is removed in 0.7.0.
+- Stage files without a `processing_stage` marker (written before 0.6) — read with a WARNING and their stage inferred from the filename; refused from 0.7.0. Mark them once with `oceanarray stamp`.
+- `directory:` in a mooring description — a raw-data root belongs to `raw_dir` / `--raw-dir`, not the YAML; `check` warns, and the stage-1 absolute-path override is removed in 0.7.0.
+
+### Breaking changes
+
+- A `clamp` ADCP whose HAB was given only as `hab_bottom`/`hab_top` is now placed in the stack instead of being silently omitted — the `stack`/`grid` files for any such mooring change on rebuild.
+- The grid report's **Overflow** section is off by default; turn it on with a `report_sections` block (`report_sections: {grid: [overflow]}`) in the mooring YAML. An overflow mooring whose YAML does not set it loses the section.
+- A mooring description whose QC override blocks (`qc_ranges`, `qc_spike`, `tilt_qc`, `qc_flat_line`, at mooring or instrument level) hold an unknown field, a span that is not two increasing numbers, a threshold that is not a number, or a new variable without a `fail_span` is now refused by `load` and reported as an ERROR by `oceanarray validate`; before, the mistake was dropped and QC ran with the defaults. A variable outside the registry is a WARNING. `qc_spike`, `tilt_qc` and `qc_flat_line` are no longer reported as unknown top-level keys.
+- `current_direction` is written with `standard_name = "sea_water_velocity_to_direction"`; CF deprecated `direction_of_sea_water_velocity`. Files written before keep the old name.
+- Modules moved to the package layout (no aliases: nothing outside oceanarray imported them). Old → new:
+
+  | old | new |
+  |---|---|
+  | `oceanarray.utilities` (`instrument_entries`, `extract_inline_instruments`) | `oceanarray.instruments` |
+  | `oceanarray.utilities` (`parse_latlon`, `parse_latlon_with_source`, `format_latlon`, …) | `oceanarray.location` |
+  | `oceanarray.utilities` (`find_best_dtype`, `cast_output_dtypes`) | `oceanarray.writers.dtypes` |
+  | `oceanarray.utilities` (`should_skip_regeneration`) | `oceanarray.paths` |
+  | `oceanarray.utilities` (`drop_all_zero_vars`) | `oceanarray.pipeline.dataset` |
+  | `oceanarray.utilities` (`nice_colorbar_ticks`, `period_axis_ticks`; `_nice_colorbar_bounds` → `nice_colorbar_bounds`) | `oceanarray.plotters.primitives` |
+  | `oceanarray.utilities._status`, `_format_rel_path` | `oceanarray.logger.status`, `logger.format_rel_path` |
+  | `oceanarray.tools.rapid_interp` | `oceanarray.pipeline.gridders.rapid_interp` |
+  | `oceanarray.tools.process_dataset`, `analysis.science.process_dataset`, `analysis.temporal.downsample_to_sparse` | `oceanarray.pipeline.gridders.climatology` |
+  | `oceanarray.tools` / `analysis.science` re-exports `calc_psal`, `calc_ds_difference`, `find_cold_entry_exit`, `isopycnal_dataset`, `isopycnal_pressure_series` | `oceanarray.analysis.hydrography` |
+  | `oceanarray.tools` / `analysis.science` re-exports `welch_psd`, `welch_psd_gapaware`, `compute_cwt` | `oceanarray.analysis.spectral` |
+  | `oceanarray.tools` re-exports `lag_correlation`, `split_value`, `downsample_to_sparse` | `oceanarray.pipeline.clock.offsets` (`lag_correlation`, `split_value`), `oceanarray.pipeline.gridders.climatology` (`downsample_to_sparse`) |
+  | `oceanarray.tools` re-exports `flag_salinity_outliers`, `flag_temporal_spikes`, `flag_vertical_inconsistencies`, `run_qc` | `oceanarray.legacy.qc_rodb` |
+  | `oceanarray.pipeline.helpers` (was `processors.helpers`): `STACK_VARS` and the stack helpers | `oceanarray.pipeline.stack`; the QC mask and worst-flag merge → `oceanarray.pipeline.qc` |
+  | `oceanarray.analysis.temporal.filter_sigma_tukey` | `oceanarray.pipeline.gridders.filters` |
+  | `oceanarray.analysis.clock` (`analyze_deployment_timing` → `deployment_timing`; + `analysis.temporal.lag_correlation`, `split_value`) | `oceanarray.pipeline.clock.offsets` |
+  | `oceanarray.analysis.vector.progressive_vector` | `oceanarray.plotters.current.progressive_vector` |
+  | `oceanarray.utilities` (`get_dims`, `check_necessary_variables`, `get_time_key`) | `oceanarray.pipeline.gridders.rapid_interp` |
+  | `oceanarray.utilities` (`concat_with_scalar_vars`) | `oceanarray.legacy.mooring_rodb` |
+  | `oceanarray.utilities` (`iso8601_duration_from_seconds`, `is_iso8601_utc`) | `oceanarray.legacy.convertOS` |
+  | `oceanarray.config.validation.print_validation_report` | removed (`oceanarray validate` prints the report) |
+  | `oceanarray.legacy.find_deployment` | `oceanarray.pipeline.clock.deployment` |
+  | `oceanarray.pipeline.caldip` (`normalize_serial` → `canonical_serial`) | `oceanarray.pipeline.calibration` |
+  | `oceanarray.pipeline.coordinate.apply_adcp_seabed_qc` / `_surface_qc` / `_velocity_qc` | `oceanarray.pipeline.qc.adcp` |
+  | `oceanarray.analysis.hydrographic` | `oceanarray.analysis.hydrography` |
+  | `oceanarray.analysis.science` QC flaggers (`flag_salinity_outliers`, `run_qc`, …) | `oceanarray.legacy.qc_rodb` |
+  | `oceanarray.analysis.vector.xyz_to_enu_2d` | `oceanarray.pipeline.coordinate.xyz_to_enu` (same values; returns `up` too) |
+  | `oceanarray.config.validation.serial_collision_errors` | `oceanarray.mooring.serial_collision_errors` |
+  | `oceanarray.pipeline._resolve_mooring` | `oceanarray.pipeline.resolve_mooring` (public) |
+
+  `oceanarray.tools`, `oceanarray.utilities`, `oceanarray.pipeline.helpers` and `oceanarray.legacy.tools` are gone.
+  `utilities.apply_defaults` is removed (no caller). `plotters.timeseries.draw_grid` is deprecated (see Deprecated).
+- Plotting functions that return a Figure are `draw_<what>`, with no alias: `plotters.diagnostic.plot_knockdown_pressure` / `_hab` / `_anomaly` / `_displacement` / `plot_clock_offset_check`, `plotters.current.plot_temperature_trajectory` / `plot_speed_boxplot` / `plot_multi_aquadopp_trajectories` / `plot_hodograph` / `plot_aquadopp_speed_profile` / `plot_adcp_trajectories`, `plotters.primitives.plot_trajectory` and `plotters.plot_microcat_raw` / `plot_aquadopp_raw` / `plot_mooring_timeseries` → `draw_*`; `draw_isopycnal_ts_fig`, `draw_overflow_temperature_fig`, `draw_grid_fig` → `draw_isopycnal_ts`, `draw_overflow_temperature`, `draw_grid` (itself deprecated, see above). Report `source:` captions name the new functions.
+- Removed, as their 0.5 deprecation warnings said: `pipeline.units.canonicalise_units` (use `to_canonical_units`), `pipeline.units.format_units` (use `config.unit_tables.unit_label`), `config.parameters.UNIT_ALIASES` and `VARIABLE_UNIT_ALIASES` (use `config.unit_tables.TABLES`).
+- `readers.nortek.normalize_nortek_variables` → `to_canonical_nortek`, `readers.sbe.normalize_sbe_ascii` → `repair_sbe_ascii` (no alias: the `readers` package is new in 0.6).
+- `TimeGriddingProcessor`, `time_gridding_mooring` and `process_multiple_moorings_time_gridding` are removed from `oceanarray.pipeline.grid`, with their optional low-pass/de-tiding/band-pass filters. No notebook or CLI verb used them; the stack (`oceanarray.pipeline.stack.stack`) is the one way to put a mooring on a common time axis.
+- `oceanarray run` now calls `oceanarray.run`. It still carries on past failures, as before, and now records what it left out in the products (`instruments_omitted`, `keep_going_failures`, `source_stage`). It exits 0 when it finishes, even with instruments left out (before: 1). `--strict` stops at the first failing stage with exit code 1 and builds no report; `--stage` lists the stages (they must run through stage 3: `--stage 2 3`), `--from N` starts at stage N (`--from 2` runs stages 2 and 3 from the stage-1 files without `--raw-dir`). `--dry-run` lists every stage, stack, grid and report file the run would write; `--skip-existing` keeps report pages that exist. `--dt-seconds` (was `--dt`, accepted until 0.7.0), `--pmin`, `--pmax` and `--dp` on `run` default to the description's `stack:`/`grid:` blocks, and `pmin` / `pmax` are also the Python keywords and YAML keys.
+- `oceanarray.processors` is renamed to `oceanarray.pipeline` (the verbs' bodies). Old → new: every `oceanarray.processors.*` import becomes `oceanarray.pipeline.*` (`stage1`, `stage2`, `stage3`, `stack`, `grid`, `qc`, `coordinate`, `pressure`, `units`, `process`, `run`); `processors.caldip` and `processors.helpers` moved again, see the table above. No deprecation shim.
+- `oceanarray.writers.write(ds, path)` now refuses to replace an existing file by default — pass `overwrite=True` to replace one (the processing stages do). It logs an INFO line (`overwriting <path>`) when it replaces a file, and returns the `Path` written instead of `None`. Previously it overwrote silently.
+- Output filenames are built from the mooring's `name:` field, not its directory name. A directory whose basename differs from `name:` is a WARNING (previously framed as "name must match the directory"); the files are named from `name`.
+- `oceanarray.tools.readers` is removed; its readers moved to the `oceanarray.readers` package. Old → new: `oceanarray.tools.readers.read_oceansites` → `oceanarray.readers.read_oceansites` (or `oceanarray.readers.oceansites.read_oceansites`); `read_rodb` → `oceanarray.readers.read_rodb`; `load_nortek_csv` → `oceanarray.readers.load_nortek_csv`. The dead `load_dataset` and `rodbload_old` are removed with no replacement — use `oceanarray.readers.read` and `read_rodb`.
+
+### Fixed
+
+- Positions no longer print `60.00′` or a hemisphere on zero, a `nan` position reads `—` instead of crashing the report, and the array report pairs latitude and longitude from one key pair and skips `(0, 0)` (#132).
+- `oceanarray report --dry-run` honours `--only` and lists the recovery table with `--cruise-table`; `process --report` on an invalid description prints an ERROR line instead of a traceback; a loaded description passed to `oceanarray.report` rebuilds the summary page even when the page is newer than the YAML file.
+- The stack T–S diagram, the instrument data histograms and the stack pressure range also leave out flag 3 (they left out only 4 and 9).
+- A stack whose Aquadopps carry no east/north velocity (a stage-2 stack of beam-coordinate data) no longer loses its stack page.
+- `oceanarray report --dry-run` lists the instrument pages at the paths they are written to (it printed paths in the processed-data directory).
+- A report whose summary page is newer than its inputs still builds a missing or stale stack, grid or instrument page; before, the fresh summary stopped them all.
+- The summary page is rebuilt when the stack or grid file is newer than it (it lists which instruments they hold), and is no longer rewritten on every run when it is up to date.
+- On phones the report text no longer changes size between full-width and half-width sections: browser text autosizing is turned off (`text-size-adjust: 100%`), so every class renders at the size the stylesheet sets.
+- Every report plot now leaves out only QC flags 3, 4 and 9 (`parameters.QC_BAD_FLAGS`): ADCP/Aquadopp current plots, roses, spectra and the grid velocity panels hid nominal (7) and interpolated (8) values too; the instrument rose's "good" panel (flags ≤ 2) now takes every usable flag (0–2, 7, 8).
+- The stack report's Hydrography and Velocity panels left out values flagged nominal (7) or interpolated (8), so a sensorless instrument's interpolated pressure was missing from the pressure row; they now leave out only flags 3, 4 and 9 (`parameters.QC_BAD_FLAGS`). Both panels now carry their `source:` caption.
+- An extrapolated pressure's `pressure_source` says what it is out of range of: the target's height above bottom against the range the pressure sources span.
+- The netCDF writer stores `bool` attributes as `int8` (0/1) instead of failing: netCDF has no boolean attribute type.
+- A Nortek header whose coordinate system cannot be read is now marked `coordinate_system = "UNK"` instead of being assumed `"ENU"`, and stage 3 refuses to rotate `UNK` velocities (with a WARNING) rather than passing them through as if geographic. Previously a BEAM/XYZ instrument with an unrecognised header was silently labelled ENU, skipping the BEAM→ENU transform and magnetic-declination correction — a silent physical error in the velocity output.
+- Every reader drops records with no time (`NaT`, e.g. an originator's padding of a record that ended early), with a warning naming the file and the count; stage 1 records the count in a new `n_records_without_time` global attribute and a `history` line. A file with no timed record raises `ValueError`. (Before, only the OceanSITES reader dropped them, without a record in the file.)
+- A RODB record with a fill (`-9999`) in `YY`, `MM`, `DD` or `HH` is dropped as having no time; a fill in `HH` could be read as midnight of that day.
+- A RODB file with no data rows after its header raises `ValueError` "no data rows after the RODB header" instead of numpy's column-count error.
+- Stage 2 refuses a stage-1 file with records that have no time (`MooringError` naming the instrument and the count; re-run stage 1), instead of failing in the deployment-window trim.
+- Stage 3 no longer fails on a BEAM/XYZ Aquadopp in a mooring with no position: its `history` says "declination not applied (position unknown)".
+- The stack no longer fails on an instrument whose `magnetic_declination` is `"UNK"`: its level is NaN in the per-level `magnetic_declination`, whose `comment` names the levels with an unknown declination.
+
+## [0.5.1] — 2026-10-23
+
+> The units-display entries — *Units tables come from the shared report layer*, *N² keeps the spelling it arrives with*, *Legacy vocabulary files moved and renamed*, and the two *Deprecated* items — landed as direct-to-main commits (`cdcffc9`/`8982831`/`735adaa`, the units display sweep), not a pull request; [#107](https://github.com/ocean-uhh/oceanarray/pull/107) documented the sweep and added the derived-quantity guard. See `.claude/done/ROADMAP.md`.
+
+### Changed
+
+- **Post-release tidy** ([#105](https://github.com/ocean-uhh/oceanarray/pull/105)): `find_best_dtype` passes `timedelta64` variables through with their native kind instead of miscasting them; the dead `proc_machine` report-context key is removed; the CLI reference page is generated from the argument parser (`sphinx-argparse`); CONTRIBUTING and the README scope line refreshed.
+
+- **Vendored report-design layer adopted** ([#106](https://github.com/ocean-uhh/oceanarray/pull/106)): the report presentation layer moves to `oceanarray/reports/_vendored/`, a directory copied byte-identical from ctdcast `15fa38b` that carries its own `MANIFEST.txt` and self-check (`check.py`). The six scattered vendored files (`config/report_tokens.py`, `config/report.mplstyle`, `reports/_encode.py`, `_css.py`, `_manifest.py`, `templates/_nav.html`), the root `VENDORED.txt`, and `scripts/check_vendored.py` are removed; a new owned `reports/design.py` holds the oceanarray-specific configuration (package accent, QC/sensor predicates, `ATTR_GROUP_EXTRAS`, the per-figure source toggle). `reports/__init__.py` resolves its public names lazily so importing the vendored layer does not pull the page pipeline. No change to the NetCDF outputs or the public API.
+- **NetCDF-inventory tables rendered by the vendored builders** ([#106](https://github.com/ocean-uhh/oceanarray/pull/106)): the coordinates/variables/scalars/globals tables now come from the shared `nc_tables` builders and `_nc_tables.html` macros. Type labels read `string` rather than `str`, each table carries a `source:` caption, the coordinates table gains a Dims column, and the `history` global attribute is shown once (in its dedicated processing-history panel, excluded from the globals table via the builder's `exclude=`). An all-empty Standard/long-name column drops along with units/min-max/attributes (`optional=` includes `stdname`). The QC-companion marker shows the file's real suffix — `(_qc)` for oceanarray's lowercase QC variables, not a hard-coded `(_QC)` — and is coloured with the shared `--qc-mark` token. The local inventory templates and row builders are removed.
+- **Processing-history panel is now tables** ([#106](https://github.com/ocean-uhh/oceanarray/pull/106)): the instrument/grid/stack reports render the processing history as a key/value `properties_table` for the header items plus a sortable Time·Event table for the dated entries (a `|`-joined entry splits into same-time rows), replacing the `dl`-style list that wrapped long entries into orphan rows. The Time·Event table carries a leading `#` column — the row's 1-based position in the `history` attribute — so sorting any column never loses the original sequence (events sharing one timestamp would otherwise be unorderable).
+- **Array page map** ([#106](https://github.com/ocean-uhh/oceanarray/pull/106)): the mooring-position map is the vendored Leaflet `track_map` (a marker per mooring, each carrying a permanent name label in the marker's colour, hover-linked to the mooring list via `data-track-id`, offline bundled assets) behind the `design.ARRAY_MAP_LEAFLET` flag — the interactive map on screen, its matplotlib PNG fallback when printing (never both). The static PNG gains a `source:` caption, a Mercator-square framed extent (a line of moorings no longer renders as a sliver), and family marker colours; the mooring name links to its report and the jump-nav uses the family markup.
+- **Array masthead metadata** ([#106](https://github.com/ocean-uhh/oceanarray/pull/106)): the array summary masthead gains deployment/recovery and duration, position and mooring extent, water-depth range, an instrument by-type breakdown, deployment status, and processed-to counts — all read or derived from the array/mooring YAMLs at render (a missing value is an em-dash).
+- **base.html de-duplicated against the shared stylesheet** ([#106](https://github.com/ocean-uhh/oceanarray/pull/106)): report chrome rules that `emit_css()` already provides are removed from the per-page `<style>` block (only the oceanarray-specific additions remain), guarded by `test_no_base_rule_duplicates_vendored_css`.
+- **Absent figure panels say why** ([#106](https://github.com/ocean-uhh/oceanarray/pull/106)): a figure whose draw raises now renders a short stub with the reason instead of vanishing (`as_panel`, ported from ctdcast).
+- **Coverage floor raised** ([#106](https://github.com/ocean-uhh/oceanarray/pull/106)) from 38% to 58%: `main` and this branch both measure 59% unit coverage, so the CI `--cov-fail-under` gate is ratcheted to one point below.
+- **Units tables come from the shared report layer**: the vendored layer is re-copied from ctdcast `f2af1d8`, where `units_display.py` became `units.py` + `units_tables.py` (canonical spellings, accepted aliases with factors, display labels, keyed by CF `standard_name`). `oceanarray.config.unit_tables` holds oceanarray's differences from those tables (N² stored as `s-2`; the `ml l-1`, `mL/L` and `s⁻²` spellings) and `unit_label()`, the display entry point the plotters now call. The storage pass is `processors.units.to_canonical_units`. It accepts the same spellings as before for every registry quantity (N² aside, below), still takes each variable's canonical spelling from `parameters.VARIABLES`, still raises on a missing units attribute, and still records `units_converted_from` / `units_conversion_factor` on a conversion; the dune2 goldens are byte-identical.
+- **Plot-axis units derived from the registry through the pipeline** ([#107](https://github.com/ocean-uhh/oceanarray/pull/107)): `parameters.vunit`/`vlabel` now format each variable's canonical CF `units` through `unit_label` (`degree_Celsius` → `°C`), so every axis/colorbar label is produced by the one display rule; the duplicate `label_units` column is removed from `VARIABLES`. The attitude/engineering variables `pitch`, `roll`, `heading`, `tilt`, `current_direction`, `bin_pressure` are registered (canonical CF `degree`/`dbar`), and the reader spellings `degrees`/`volts` are accepted as aliases of `degree`/`V`; the storage pass rewrites a stored `degrees` to `degree` at factor 1. Rendered labels are unchanged.
+- **Derived-quantity unit guard** ([#107](https://github.com/ocean-uhh/oceanarray/pull/107)): a plot whose output unit is computed from a source variable (displacement in km from velocity, height-above-seabed in m from pressure, instrument spacing in dbar, temperature PSD) warns via `unit_tables.warn_if_not_canonical` when the source variable does not carry the canonical unit the derivation assumes. Silent on every oceanarray-written file (the storage pass guarantees canonical units); it catches a foreign or hand-edited file the derivation would otherwise mislabel.
+- **N² keeps the spelling it arrives with**: `s-2` and `rad2 s-2` are both accepted and neither is rewritten into the other (`rad2 s-2` used to be refused), so N² is the one quantity whose stored spelling can differ between files.
+- **Legacy vocabulary files moved and renamed**: `config/OS1_var_names.yaml`, `config/OS1_sensor_attrs.yaml` and `legacy/OS1_vocab_attrs.yaml` are now `legacy/OS1_variable_names.yaml`, `legacy/OS1_sensor_attributes.yaml` and `legacy/OS1_variable_attributes.yaml`, beside the legacy `convertOS.py` that takes them as inputs. No other oceanarray code reads them; the wheel no longer ships them.
+- **Report figure layout** ([#110](https://github.com/ocean-uhh/oceanarray/pull/110)): a single-tier current rose (one QC tier, no magnetic panel) renders as a third-slot circle centred in whitespace instead of a full-slot-width square; the knockdown-displacement figure reserves left margin for its pressure y-labels so a deep mooring's four-digit dbar labels no longer clip. The unreachable `GRID_COMBINED_HYDRO` grid profile is removed (T-S stays its own section).
+- **`°` accepted as a degree spelling** ([#110](https://github.com/ocean-uhh/oceanarray/pull/110)): the storage pass accepts the `°` symbol as the canonical `degree` (factor 1) for attitude variables. `deg` is not accepted here — it is scoped to latitude/longitude in the vendored unit tables and arrives, scoped, at the next vendored sync.
+- **Report layer re-vendored from ctdcast v0.4.0** ([#111](https://github.com/ocean-uhh/oceanarray/pull/111)): the `degree`/`degrees`/`°` alias moves into the vendored family tables (the duplicate package-side copy is removed; unit resolution is unchanged). The array-map graticule gains edge labels drawn inside the west/south edges, a bottom-right scale bar, and antimeridian handling for basin-scale tracks.
+- **ADCP bin pressures are tilt-corrected for knock-down** ([#112](https://github.com/ocean-uhh/oceanarray/pull/112)): `compute_adcp_bin_pressure` reduces each bin's vertical range by `cos(θ)` (θ = instrument tilt from pitch/roll, `arccos(cos P_true·cos R)`) before converting to pressure, so a knocked-down profiler's bins are placed at their true depth; `bin_pressure` gains `tilt_correction` / `tilt_definition` attributes. When the firmware recorded earth coordinates with bin mapping on (RDI `EX` command), it has already tilt-placed the bins, so the correction is **not** applied (`tilt_correction = "none (firmware bin mapping)"`). Every current UHH deployment is earth + bin-mapping, so stored outputs are unchanged; the correction is exercised only by beam-coordinate input. Stage 1 surfaces `firmware_coordinate_system` / `firmware_bin_mapping` from the raw metadata for the guard.
+
+### Added
+
+- **Readers for files already processed by their originator** ([#108](https://github.com/ocean-uhh/oceanarray/pull/108)): `file_type: oceansites` (OceanSITES 1.3 netCDF, and the OSNAP variant with variables on `TIME`) and `file_type: rodb` (RAPID/BODC `.microcat`, `.edt`, `.lowedt`), in `oceanarray.tools.readers` (`read_oceansites`, `read_rodb`). Variables are renamed to oceanarray names; the originator's QC flags are kept as `<name>_qc_originator`; the originator's metadata as `originator_*` attributes. Velocities are geographic, so Stage 3 applies no rotation and no second magnetic declination (`originator_magnetic_declination`). New instrument class `currentmeter` for a processed point current meter. Tested on trimmed real OSNAP files (WHOI, GEOMAR, Scripps, RODB) in `tests/fixtures/raw/osnap/`.
+- **`units_override`** ([#108](https://github.com/ocean-uhh/oceanarray/pull/108)) per instrument in the mooring YAML corrects a file whose units attribute is wrong; Stage 1 refuses an imported (`oceansites` / `rodb`) instrument whose values fall outside the registry's valid range for the stated units, naming this key.
+- **`stack: false`** ([#108](https://github.com/ocean-uhh/oceanarray/pull/108)) per instrument in the mooring YAML keeps an instrument out of the stack and grid while it is still processed through stages 1-3 and reported (reference data); the stack names it in an `instruments_excluded` attribute. A low-passed file (`originator_low_passed`, e.g. RODB `.lowedt`) reaching the stack without it is omitted with an error naming the key.
+- Unit spellings accepted: `decibar`, `meter/second`, `meter`, `psu` (practical salinity only), and RODB `cm s-1` (converted ×0.01 to `m s-1`).
+
+### Deprecated
+
+- `oceanarray.processors.units.canonicalise_units` → `to_canonical_units`, and `oceanarray.processors.units.format_units` → `oceanarray.config.unit_tables.unit_label`. The old names warn and are removed in 0.6.0.
+- `oceanarray.parameters.UNIT_ALIASES` and `VARIABLE_UNIT_ALIASES`: the spellings now live in the shared units tables (`oceanarray.config.unit_tables.TABLES`, with `PSU` / `NTU` scoped by CF `standard_name`). Both names still resolve, rebuilt from those tables, with a warning; removed in 0.6.0.
+
+### Breaking changes
+
+- None. The NetCDF outputs and the public API (`oceanarray` CLI, `from oceanarray.reports import MooringReport`) are unchanged. The report HTML changes (masthead nav, inventory-table layout and type labels, `source:` captions); the committed report goldens are rebaselined to match.
+
+## [0.5.0] — 2026-10-12
+
+### Added
+
+- **Serial-uniqueness validation** ([#101](https://github.com/ocean-uhh/oceanarray/pull/101)): `validate` refuses duplicate serials within a mooring, a blank serial, and the reserved names `stack`/`grid` (which would collide the per-instrument report filenames `{mooring}_{serial}_report.html`). A trailing `*` is stripped before every check — `1234` and `1234*` on one mooring are a duplicate, a serial that is only `*` is blank — and stays a diagram-only "pay attention to this sensor" annotation, never carried into filenames or nav labels.
+
+### Changed
+
+- **Report NetCDF-inventory appendix restyled** ([#103](https://github.com/ocean-uhh/oceanarray/pull/103)): the instrument, stack and grid reports share one inventory appendix — a Coordinates table (one row per coordinate variable: type, units, standard/long name, min/max, N valid, attributes), variables grouped by dimension set, QC companions shown inline as a green `(_QC)`, and global attributes split into named groups with a Type column; the per-page variable/scalar/globals templates collapse to one shared set, and the grid page gains a coordinates table it never had. The dune2 test fixture units were canonicalised in place (14 attribute edits, data byte-identical) and the hosted dune2 example suite regenerated. `demo_mooring.ipynb` is ported to `oceanarray.processors.process` and runs on the committed fixture from a clean checkout; `demo_step1.ipynb` is removed, and five old-API demo notebooks move to `notebooks/legacy/`.
+- **Shared masthead nav** ([#100](https://github.com/ocean-uhh/oceanarray/pull/100)): the report masthead navigation is rebuilt from the shared vendored macro, and the six report-design files are re-vendored from ctdcast with a vendoring guard (`scripts/check_vendored.py`).
+- **Canonical units at every stage** ([#102](https://github.com/ocean-uhh/oceanarray/pull/102)): one canonical spelling per quantity is now written to every file — `degree_Celsius`, `mS cm-1`, `dbar`, `m`, `m s-1`, `umol kg-1`, `g kg-1`, `kg m-3`, `1` (practical salinity and turbidity). A registry-scoped pass (`oceanarray.processors.units.canonicalise_units`) runs on the way out of every stage, rewriting the reader spellings (`degC`, `mS/cm`, `meters`, `db`, `S/m`→×10) to the canonical and recording any value conversion in `units_converted_from` / `units_conversion_factor`. Temperature variables carry CF-1.11 `units_metadata = "temperature: on_scale"`. Plot labels are derived from the canonical string by `format_units` (slash form: `mS/cm`, `m/s`, `kg/m³`, `µmol/kg`, `°C`, `PSU`, `NTU`).
+
+- **Single netCDF writer** ([#98](https://github.com/ocean-uhh/oceanarray/pull/98)): the six write paths the processing stages used before now go through one `oceanarray.writers.write` seam. The files that were written uncompressed — the seasenselib-written stage files, whose compression parameters its writer silently discarded, and the bare-`to_netcdf` stage3 output — shrink 58–66% on the dune2 fixtures. The two that were already zlib level-5 compressed — the pressure-gridded and stacked outputs — grow about 1% as they move to the common level-4 setting. Decoded values, dtypes, attributes, and time encoding are unchanged; raw values are byte-identical, verified per stage against the old writer. The private `_get_netcdf_writer_params` methods are removed, including the `quantize` key, which was never a valid netCDF4 encoding parameter and never took effect.
+- **Windows log encoding** ([#98](https://github.com/ocean-uhh/oceanarray/pull/98)): `stage1/2/3` open their per-stage log file as UTF-8. On Windows the default cp1252 encoding raised on the ADCP `BEAM→ENU` log message, which aborted the instrument and silently dropped it from the output.
+- **`oceanarray.writers` exposed** ([#99](https://github.com/ocean-uhh/oceanarray/pull/99)): `import oceanarray as oa; oa.writers.write(ds, path)` now resolves after a bare import.
+- **cftime time coordinates preserved** ([#99](https://github.com/ocean-uhh/oceanarray/pull/99)): a time coordinate decoded with `use_cftime=True` (object dtype, e.g. a non-standard calendar) now keeps its `units` and `calendar` on write instead of letting xarray re-guess the epoch from the data. Numpy `datetime64` time is still pinned to the 1970 epoch; only object-dtype cftime time is affected.
+- **Python 3.13 supported** ([#99](https://github.com/ocean-uhh/oceanarray/pull/99)): added to the classifiers and promoted to a required (no longer allow-failure) CI leg.
+
+### Breaking changes
+
+- **Units spellings in output files changed** ([#102](https://github.com/ocean-uhh/oceanarray/pull/102)): every processed file now carries the canonical units spelling per quantity (above), so a reader matching the old strings (`degC`, `mS/cm`, `meters`, `S/m`, …) must adapt. An unrecognised or missing `units` on a registered variable now **stops that instrument** (`UnitsError`) rather than passing through silently — one bad instrument is logged with its file and skipped, the rest process; the stack still builds but records the omission in an `instruments_omitted` attribute and exits 1. The `dissolved_oxygen` registry entry is corrected to per-mass `umol kg-1` (standard_name `moles_of_oxygen_per_unit_mass_in_sea_water`); turbidity is dimensionless `1` (display label `NTU`). Conductivity in `S/m` is converted ×10 to `mS cm-1` by the units pass, replacing the old `conductivity_normalised_from` attribute with `units_converted_from` / `units_conversion_factor`.
+- **`process` runs stage 3 by default** ([#102](https://github.com/ocean-uhh/oceanarray/pull/102)): `oceanarray process MOORING` with no `--stage` now runs stages 1, 2 and 3 (was 1 and 2). Pass `--stage 1 2` for the old raw→trim-only behaviour. The help text already described "stages 1-3"; the code now matches it.
+- **Oxygen saturation / AOU recomputed on the correct basis** ([#102](https://github.com/ocean-uhh/oceanarray/pull/102)): `derive_oxygen_saturation` previously divided per-mass `dissolved_oxygen` by in-situ density as if it were per-volume, making `oxygen_saturation_pct` and `apparent_oxygen_utilization` ~2.5% low. It now uses a per-mass (`umol kg-1`) input directly and divides only a genuine per-volume (`umol L-1`) variable. Regenerated oxygen products change by the density factor; moorings without an oxygen sensor (the dune2 example) are unaffected.
+- **Minimum Python raised to 3.11** ([#99](https://github.com/ocean-uhh/oceanarray/pull/99)): `requires-python` is now `>=3.11`; the 3.10 classifier and CI leg are dropped. Python 3.10 reached end-of-life, and the core dependencies (xarray, pandas, numpy, matplotlib, gsw, scipy) already require 3.11 — so a 3.10 install silently resolved years-old, untested versions of the whole stack.
+
+- **Dead output helpers removed** ([#99](https://github.com/ocean-uhh/oceanarray/pull/99)): `oceanarray.tools.writers.save_dataset` and `save_OS_instrument` are deleted, and `oceanarray/tools/writers.py` with them. Neither had a working caller (only tests and a dead `if 0:` notebook cell); `save_dataset` also wrote `NETCDF4_CLASSIC`, a format nothing else produced. Use `oceanarray.writers.write`. Two legacy notebooks (`notebooks/legacy/demo_batch_instrument.ipynb`, `notebooks/legacy/demo_instrument_rdb.ipynb`) still reference `save_OS_instrument` and no longer run; they are not CI-executed and are left for the notebook refresh.
+- **`None` attributes dropped, not blanked** ([#99](https://github.com/ocean-uhh/oceanarray/pull/99)): a `None`-valued attribute (global or per-variable) is now dropped with a warning instead of written as `""`. `UNK` belongs where a value is determined, not the write seam. On the dune2 fixtures no attribute is affected (0/84 globals are empty); this is a guardrail.
+- **Time encoding pinned** ([#99](https://github.com/ocean-uhh/oceanarray/pull/99)): every datetime variable is written as `seconds since 1970-01-01` (float64, `proleptic_gregorian`) rather than xarray's per-file guess. Decoded instants change by at most 0.13 µs (float64 seconds have ~238 ns spacing at the 2026 epoch, so ≤119 ns rounding; ~0.5 µs by 2050) — negligible against clock drift, which is corrected in whole seconds. **Raw stored values change**, so a reader using `decode_times=False`/`decode_cf=False` sees different numbers. This also removes a pandas-version dependence in the units string (space vs `T`).
+
+### Known issues
+
+- **Empty-units turbidity files**: a registered variable with an empty `units` fails that one instrument at stage 1 — the handler logs `ERROR: <file>: <reason>`, skips the instrument, and the mooring completes with the others and a non-zero exit (the family rule). Six turbidity files on the drive are affected; the reader fix lands in 0.5.1.
+- **dune2 test fixture stack/grid**: the committed `_stack.nc`/`_grid.nc` fixtures reference instruments not present in the committed raw and YAML — they were built from the full mooring before the fixture was trimmed to two instruments — so running `oceanarray run` on the fixture collapses the stack to those two. A known fixture inconsistency, rebuilt in 0.5.1.
+
+## [0.4.0] — 2026-09-08
+
+### Added
+
+- **caldip calibration-dip stub** ([#92](https://github.com/ocean-uhh/oceanarray/pull/92)): `processors/caldip.py` carries the shared contract (constants, `normalize_serial`, `Offsets`) and a five-function interface for the planned front-of-Stage-3 correction. Stage 3 gains a `caldip_dir` argument that is a null action — it logs a warning and stamps a `caldip_applied` provenance attribute — until the correction lands.
+- **PDF reports**: `report --pdf` renders a merged A4 PDF per mooring ([#69](https://github.com/ocean-uhh/oceanarray/pull/69)); `report --pdf-dir DIR` collects each mooring's PDF into one directory ([#90](https://github.com/ocean-uhh/oceanarray/pull/90)), which also sped up PDF rendering (~50 s → ~6 s).
+- **Manifest-driven report system**: a section-manifest model and resolver ([#78](https://github.com/ocean-uhh/oceanarray/pull/78)) now drive the grid ([#79](https://github.com/ocean-uhh/oceanarray/pull/79)) and stack / instrument / mooring ([#80](https://github.com/ocean-uhh/oceanarray/pull/80)) report pages — per-page registries, automatic panel numbering, generated jump-nav, and defect-visible stubs.
+- **`oceanarray run` report redirection** ([#88](https://github.com/ocean-uhh/oceanarray/pull/88)): `run` accepts `-o/--output-dir`, `--report-dir`, and `--sig-level`, threaded through to the report step, so the full pipeline can write a portable central report tree with custom grid isopycnal targets in one command.
+- **Zenodo DOI** ([#68](https://github.com/ocean-uhh/oceanarray/pull/68)): concept-DOI badge in the README and `CITATION.cff`.
+- A hosted, clickable dune2 example report suite in the docs ([#82](https://github.com/ocean-uhh/oceanarray/pull/82)).
+
+### Changed
+
+- **Report subsystem refactor**: vendored the shared design tokens, encoder, and CSS ([#71](https://github.com/ocean-uhh/oceanarray/pull/71)); added a golden-file regression net ([#72](https://github.com/ocean-uhh/oceanarray/pull/72)); renamed `report/` → `reports/` ([#73](https://github.com/ocean-uhh/oceanarray/pull/73)); reworked page templates ([#74](https://github.com/ocean-uhh/oceanarray/pull/74)); encoder / figure sizing ([#75](https://github.com/ocean-uhh/oceanarray/pull/75)); uniform layout fixes ([#76](https://github.com/ocean-uhh/oceanarray/pull/76), [#77](https://github.com/ocean-uhh/oceanarray/pull/77)); plot polish — colorbar ticks, cyclic current direction, T-S bounds, tilt panels ([#83](https://github.com/ocean-uhh/oceanarray/pull/83)); layout polish — shared title helper, trajectory y-labels, clock legend, rose whitespace ([#84](https://github.com/ocean-uhh/oceanarray/pull/84)); smaller files, updated fonts, and multi-panel pagination ([#70](https://github.com/ocean-uhh/oceanarray/pull/70)).
+- **Packaging**: consolidated configuration into `pyproject.toml`, expanded the CI test matrix, and added a ruff lint gate ([#86](https://github.com/ocean-uhh/oceanarray/pull/86)); moved the dev install to pyproject extras ([#85](https://github.com/ocean-uhh/oceanarray/pull/85)); dropped the unused direct `dolfyn` dependency ([#81](https://github.com/ocean-uhh/oceanarray/pull/81)).
+- **Docs**: PyPI-first install instructions ([#81](https://github.com/ocean-uhh/oceanarray/pull/81)); caldip documented as the planned optional front-of-Stage-3 correction ([#91](https://github.com/ocean-uhh/oceanarray/pull/91)).
+
+### Fixed
+
+- Cross-page links now resolve in the merged PDF — the document is built once and rendered once, with per-page anchor-id namespacing ([#89](https://github.com/ocean-uhh/oceanarray/pull/89)).
+- Conservative QC-flag resampling fix, with unit tests added for the pressure, helpers, and qc paths ([#87](https://github.com/ocean-uhh/oceanarray/pull/87)).
+- `process` / `report` / `run` `--help` no longer crash on Python 3.11 — an argparse usage-formatting `AssertionError` from a single-member mutually-exclusive group around the suppressed `--basedir` flag; the group is removed ([#88](https://github.com/ocean-uhh/oceanarray/pull/88)).
+
+### Breaking changes
+
+- **`oceanarray stack` / `oceanarray grid` removed** ([#88](https://github.com/ocean-uhh/oceanarray/pull/88)): the standalone subcommands (deprecated since 0.2.0) are deleted. Use `oceanarray process MOORING --stage stack grid` — all flags (`--dt`, `--dp`, `--pmin`, `--pmax`, `--force`, `--proc-dir`) carry over; `stack`/`grid` remain available as `--stage` tokens.
+- **`oceanarray logsheet` removed** ([#88](https://github.com/ocean-uhh/oceanarray/pull/88)): the disabled subcommand is deleted (now an argparse "invalid choice" error, not a `DeprecationWarning`). Use the standalone [`logsheet`](https://github.com/eleanorfrajka/logsheet) package.
+- **Python 3.9 dropped** ([#85](https://github.com/ocean-uhh/oceanarray/pull/85)): the minimum supported version is now 3.10.
+- Internal: `oceanarray.cli.cmd_stub` renamed to `cmd_init`; `cmd_stack`, `cmd_grid`, `cmd_logsheet` deleted. Affects only code importing these functions directly; the `oceanarray init` command is unchanged.
+
+---
+
+## [0.3.0] — 2026-08-11
+
+### Breaking changes
+
+- **`oceanarray.logsheet` subpackage deleted** ([#66](https://github.com/ocean-uhh/oceanarray/pull/66)): the deprecated `logsheet` subpackage has been removed from the tree. `oceanarray logsheet` still emits a `DeprecationWarning` and exits 1. Use the standalone [`logsheet`](https://github.com/eleanorfrajka/logsheet) package: `pip install git+https://github.com/eleanorfrajka/logsheet`, then `logsheet build ...`.
+- **`oceanarray run` skips grid when stack fails** ([#65](https://github.com/ocean-uhh/oceanarray/pull/65)): if the stack stage fails, the grid stage is now skipped rather than attempted on incomplete input. This matches `process()` behaviour.
+
+### Bug fixes
+
+- **Grid report N² computed at latitude 0**: the grid report derived buoyancy frequency (N²) at latitude 0° because its `_dms_to_deg` import still pointed at the removed `mooring_level` module and failed silently inside a broad `except`. The import now resolves from `utilities`, so N² uses the mooring's actual latitude.
+
+### Refactoring
+
+- **`STAGES` registry as single source of truth in CLI dispatch** ([#65](https://github.com/ocean-uhh/oceanarray/pull/65)): `process()` accepts a stage list (always applied in `STAGES` order); `cmd_process` and `cmd_run` route through a single `process()` call; argparse `choices` are derived from `STAGES`.
+- **Plot/report hardening** ([#64](https://github.com/ocean-uhh/oceanarray/pull/64)): `render_b64` guard, `plt.style.context`, `vlabel()` helper, `SIGMA_GRID` fix, and a `VARIABLES` registry (21 entries with `valid_min`/`valid_max`).
+
+### Documentation
+
+- Updated developer docs (`project_structure.md`, `methods/standardisation.rst`, `methods/vertical_gridding.rst`, `methods/nortek_coordinate_transform.rst`, `legacy.rst`) to the current `oceanarray.processors.*` module layout after the reorg; fixed broken import examples and API references.
+
+### Tests
+
+- Golden Stage 1 tests, reader and `_array` helper tests, plus associated bug fixes and dead-code removal ([#63](https://github.com/ocean-uhh/oceanarray/pull/63)).
+
+---
+
+## [0.2.0] — 2026-08-07
+
+### Breaking changes
+
+- **`oceanarray logsheet` disabled**: calling `oceanarray logsheet` now emits a `DeprecationWarning` and exits 1. The `logsheet` subpackage remains in the tree but is unused (deleted in v0.3.0). Use the standalone [`logsheet`](https://github.com/eleanorfrajka/logsheet) package: `pip install git+https://github.com/eleanorfrajka/logsheet`, then `logsheet build ...`.
+- **`--basedir` removed** ([#52](https://github.com/ocean-uhh/oceanarray/pull/52)): use `--raw-dir` and `--proc-dir` instead. See the [migration guide](https://ocean-uhh.github.io/oceanarray/migration.html).
+- **`plotter.py` retired** ([#53](https://github.com/ocean-uhh/oceanarray/pull/53)): the monolithic `oceanarray/plotter.py` and all backward-compatibility re-export shims have been removed. Import from canonical modules (`oceanarray.plotters.current`, `oceanarray.plotters.timeseries`, etc.).
+- **Subpackage reorganisation** ([#49](https://github.com/ocean-uhh/oceanarray/pull/49), [#59](https://github.com/ocean-uhh/oceanarray/pull/59)): processing modules moved from `oceanarray/instrument/` and `oceanarray/mooring/` into `oceanarray.processors.*`. Top-level `oceanarray` imports unchanged; internal paths have moved.
+
+### New features
+
+- **`--stage stack grid` in `oceanarray process`**: the `--stage` flag now accepts `stack` and `grid` in addition to `1`, `2`, `3`. Run the full pipeline as `oceanarray process MOORING --stage 1 2 3 stack grid`. New flags `--dt`, `--dp`, `--pmin`, `--pmax` added to `process` (same defaults as `oceanarray run`).
+- **`process()` public API** ([#58](https://github.com/ocean-uhh/oceanarray/pull/58)): `oceanarray.process(mooring_yaml, proc_dir, stages=…)` runs any combination of Stage 1–3, stack, and grid in a single call. `oceanarray.STAGES` is the registry of available stages.
+- **Array report** ([#48](https://github.com/ocean-uhh/oceanarray/pull/48)): `oceanarray report <array.yaml> --array` generates a multi-mooring HTML summary with smart rebuild (only re-renders sections whose NC files are newer than the existing report).
+- **Wave / frequency diagnostics** ([#47](https://github.com/ocean-uhh/oceanarray/pull/47)): rotary power spectra, near-inertial band energy, and wave diagnostics added to ADCP instrument reports.
+- **Release automation** ([#61](https://github.com/ocean-uhh/oceanarray/pull/61)): pushing a `v*` tag now auto-creates a draft GitHub release with PR-based release notes; publishing the draft triggers PyPI upload.
+
+### Bug fixes
+
+- **QC flags unified to OceanSITES table** ([#54](https://github.com/ocean-uhh/oceanarray/pull/54)): all QC flag values now use the standard OceanSITES convention (0 no QC, 1 good, 2 probably good, 3 probably bad, 4 bad, 9 missing). Previously mixed conventions caused flag collisions on merge.
+- **Plot regularisation** ([#50](https://github.com/ocean-uhh/oceanarray/pull/50)): fixed irregular time-axis sampling in instrument report figures.
+- **Turbidity `units=MISSING`** ([#61](https://github.com/ocean-uhh/oceanarray/pull/61)): stage1 now strips placeholder `units` strings (`"MISSING"`, `""`) written by the RBR RSK reader when the instrument database has no units entry, and emits a `UserWarning` so the operator can verify the sensor spec.
+
+### Deprecations
+
+- **`oceanarray stack`**: deprecated in favour of `oceanarray process MOORING --stage stack`. Emits `DeprecationWarning`. Will be removed in v0.3.0.
+- **`oceanarray grid`**: deprecated in favour of `oceanarray process MOORING --stage grid`. Emits `DeprecationWarning`. Will be removed in v0.3.0.
+- `file_type: rbr-hex-oa` remapped automatically to `rbr-hex` with a `DeprecationWarning`; update mooring YAMLs.
+- `file_type: sbe-asc` remapped automatically to `sbe-ascii`.
+
+### Refactoring
+
+- Single-source variable registries in `parameters.py`; `validation.py` derives from it ([#51](https://github.com/ocean-uhh/oceanarray/pull/51)).
+- Figure-returning shape for `report/_plots.py` ([#56](https://github.com/ocean-uhh/oceanarray/pull/56)); `draw_*` helpers relocated to `plotters/` ([#57](https://github.com/ocean-uhh/oceanarray/pull/57)).
+- Type annotations backfilled on `hydrographic.py` and `temporal.py`; two ANN per-file-ignores removed from `pyproject.toml`.
+
+### Tests
+
+- Integration chain tests (stage1 → stage2 → stage3 → stack → grid) over committed `dune2_1_2026` fixtures ([#60](https://github.com/ocean-uhh/oceanarray/pull/60)).
+- CI: integration job now installs seasenselib from PyPI; Windows and macOS unit jobs run seasenselib-free.
+
+---
+
+## [0.1.0] — 2026-07-27
+
+First public release.
+
+### Processing pipeline
+
+- **Stage 1** — raw instrument files → CF-NetCDF: Sea-Bird SBE37 MicroCAT (`sbe-cnv`, `sbe-ascii`), Nortek Aquadopp (`nortek-raw`, `nortek-ascii`, `nortek-csv`), RBR Solo/Duet (`rbr-rsk`, `rbr-dat`), RDI WorkHorse ADCP (`rdi-raw`). Nortek BEAM→XYZ transformation matrix parsed from `.hdr` file and applied at stage 1; matrix stored in output for reproducibility.
+- **Stage 2** — deployment trimming (YAML `deployment_time`/`recovery_time`) and linear clock-drift correction from recovery timestamps.
+- **Stage 3** — QARTOD gross-range and spike QC on T/C/S/P; pressure interpolation (QC flag 8) for instruments without a pressure sensor; Aquadopp XYZ→ENU rotation using heading/pitch/roll + IGRF magnetic declination (`ppigrf`); tilt QC on velocity; potential density via `gsw`.
+
+### Mooring-level commands
+
+- `oceanarray stack` — resample all instruments to a common time axis, stack into a single `(time, N_LEVELS)` dataset ordered deep-first.
+- `oceanarray grid` — linearly interpolate the stacked dataset onto a regular pressure grid (`--pmin`, `--pmax`, `--dp`).
+
+### Reporting
+
+- `oceanarray report` — self-contained HTML reports (all figures base64-embedded, offline-readable):
+  - Mooring summary: deployment metadata, instrument pipeline status, QC flag breakdown, clock corrections, knockdown figures, clock alignment check.
+  - Per-instrument pages (`--instruments`): full time series with QC markers, T-S diagram, current roses, data histograms, QC table, scalar metadata.
+  - Stack report (`--stack`): pressure/T/S/velocity time series, T-S diagram, current roses, spacing histogram.
+  - Grid report (`--grid`): T/S/density pcolormesh, N², velocity sections, T-S diagram, power spectra.
+  - Array report (`--array`): position map, summary table with clickable links to mooring reports.
+
+### CLI
+
+- `oceanarray process` — run stage 1, 2, and/or 3 for a mooring or a single instrument (`--serial`).
+- `oceanarray run` — complete pipeline in one command (process + stack + grid + report).
+- `oceanarray validate` — check mooring YAML for missing fields and unknown instrument types.
+- `oceanarray list` — print accepted `instrument:` names and `file_type:` values.
+- `oceanarray logsheet` — generate PDF logsheets from YAML instrument inventory.
+
+### Logsheets
+
+- `oceanarray logsheet` subcommand generates LaTeX-rendered PDF deployment logsheets from a cruise configuration YAML.
+
+### Notable design choices
+
+- Data provenance: all processing parameters (QC thresholds, declination value, transformation matrix) stored as NetCDF attributes so any file can be reprocessed exactly from itself.
+- Discrete colorbars throughout (≤ 20 levels, `BoundaryNorm`).
+- CF-convention variable names and standard names throughout; OceanSITES QC flag values.
+- `seasenselib` is used for raw file reading but is a separate install (`pip install seasenselib --no-deps` — see installation docs).

{oceanarray-0.5.1 → oceanarray-0.6.0}/CONTRIBUTING.md

@@ -39,7 +39,7 @@ Three separate things.
 
 **Citation authorship** is the author list in `CITATION.cff`, which propagates into the Zenodo DOI for every release and therefore into other people's bibliographies. It reflects *substantial* contribution to the software — its design, a significant body of its implementation, its test suite, or its documentation architecture — and is decided by the maintainer at release time. Funding or supervision alone does not qualify. There is no line count that guarantees it or excludes it. If you believe your contribution crosses that line and it has not been reflected, please say so in an issue — being asked is better than being resented.
 
-Where a contribution is adapted from someone else's work rather than written from scratch, we credit it **in the docstring of the code itself**, so the attribution travels with the code rather than living in a file nobody reads (see the existing examples in `utilities.py` and `plotters/current.py`).
+Where a contribution is adapted from someone else's work rather than written from scratch, we credit it **in the docstring of the code itself**, so the attribution travels with the code rather than living in a file nobody reads (see the existing examples in `pipeline/gridders/rapid_interp.py` and `plotters/current.py`).
 
 ---
 
@@ -81,17 +81,17 @@ For all other bugs:
 
 ### Scope
 
-oceanarray **processes moored-array observations**: raw instrument files from a mooring (MicroCATs, RBRs, Nortek and RDI current meters and ADCPs, SBE 16/56, Seapoint, …) → CF-NetCDF at each stage — stage 1 (raw → NetCDF), stage 2 (deployment window, clock), stage 3 (QC, velocity rotation, calibration-dip offsets applied) — then a stack on a common time axis and a grid on pressure levels, each step documented in an HTML report. The OceanSITES export of the stacked and gridded products is the next in-scope step.
+oceanarray **processes moored-array observations**: raw instrument files from a mooring (MicroCATs, RBRs, Nortek and RDI current meters and ADCPs, SBE 16/56, Seapoint, …) → CF-NetCDF at each stage — stage 1 (raw → NetCDF), stage 2 (deployment window, clock), stage 3 (QC, velocity rotation; calibration-dip offsets once the apply step lands — the interface is in place) — then a stack on a common time axis and a grid on pressure levels, each step documented in an HTML report, and an OceanSITES 1.4 export of the stage-3 files and the grid. Exporting the stack is the next in-scope step.
 
 **Fixed — not open to variation:** the output contract. Variable names, CF standard names and the canonical unit spellings come from one registry (`config/parameters.py`) and are the same in every file the package writes; QC flags follow the QARTOD/OceanSITES vocabulary; every processing parameter is recorded in the output's attributes so a file can be reprocessed from itself. Contributions that change these change every user's files, and are discussed first, as an issue.
 
 **Open — alternative methods welcome, as selectable options with the default unchanged:**
 
-- **Gridding.** The grid step is where the method choices are made — today linear interpolation in pressure onto a fixed `dp` grid, with σ₀ targets for isopycnal products. Alternatives: a **PCHIP spline**; the **RAPID climatological-gradient interpolation** (`tools/rapid_interp.py`, written but **not yet integrated** into `grid.py`); and bounds handling above the shallowest instrument — **extrapolate to the surface**, clip, or mask. All welcome as named methods the user picks in the config, each recording its name and parameters in the output.
+- **Gridding.** The grid step is where the method choices are made — today linear interpolation in pressure onto a fixed `dp` grid, with σ₀ targets for isopycnal products. Alternatives: a **PCHIP spline**; the **RAPID climatological-gradient interpolation** (`pipeline/gridders/rapid_interp.py`, written but **not yet integrated** into `grid.py`); and bounds handling above the shallowest instrument — **extrapolate to the surface**, clip, or mask. All welcome as named methods the user picks in the config, each recording its name and parameters in the output.
 - **Corrections to individual instruments.** How calibration-dip offsets and other per-instrument corrections (drift, pressure-sensor offset) are applied in stage 3 — constant, linear in time, pre/post weighted — is a method choice; the *derivation* of caldip offsets stays in `caldip`, oceanarray applies its output.
 - **QC tests.** New QARTOD-style tests or thresholds, as long as the flags land in the existing `_qc` companions with their thresholds recorded.
 - **Diagnostic figures and report panels.** New figures are welcome, and the report is meant to let a user choose their own selection of panels per page (a config-driven profile); contributions that make that selection easier are in scope.
-- **Readers.** Instrument readers live in `seasenselib`; oceanarray's stage 1 dispatches on the file type (`config/parameters.INSTRUMENT_FILE_TYPES`) and keeps only a small set of its own legacy readers (`tools/readers.py`: RODB and the old Nortek CSV). A reader for an instrument `seasenselib` does not cover is welcome — but write it in `seasenselib` first and add the file type here; a reader that only oceanarray would ever use can live in `tools/readers.py`. (Where exactly that line is drawn is not written down yet — ask.)
+- **Readers.** Instrument readers live in `seasenselib`; oceanarray's stage 1 dispatches on the file type (`config/parameters.INSTRUMENT_FILE_TYPES`) and keeps only a small set of its own readers and helpers (`readers/`: its own netCDF, OceanSITES, RODB, and the Nortek and Sea-Bird header parsers). A reader for an instrument `seasenselib` does not cover is welcome — but write it in `seasenselib` first and add the file type here; a reader that only oceanarray would ever use can live in `readers/`. (Where exactly that line is drawn is not written down yet — ask.)
 
 **Out of scope, because a sibling owns it:** shipboard CTD processing (`ctdcast`); deriving calibration-dip offsets (`caldip`); glider data (`glidertest`, `seagliderOG1`); transport and AMOC estimates from the gridded products (`AMOCatlas`); general-purpose plotting. Also out: features that need cruise-specific raw data in the repository, heavy new dependencies, or that break the CF-NetCDF contract. If you are unsure whether an idea fits, open an issue describing it rather than deciding alone.
 
@@ -103,11 +103,11 @@ oceanarray **processes moored-array observations**: raw instrument files from a
 
 | Layer | Modules | Role |
 |-------|---------|------|
-| Tier 1 | `tools/`, `writers/`, `utilities.py`, `inspect.py` | Low-level I/O and pure functions — raw-file readers, the single netCDF writer, dataset inspection |
-| Tier 2 | `processors/stage1.py` … `processors/grid.py` | Processing orchestrators — read, transform, write CF-NetCDF |
-| Tier 3 | `cli.py` | Entry point — argument parsing, subcommand dispatch |
+| Tier 1 | `readers/`, `writers/`, `instruments.py`, `location.py`, `inspect.py` | Low-level I/O and pure functions — file readers, the single netCDF writer, description parsing, dataset inspection |
+| Tier 2 | `pipeline/stage1.py` … `pipeline/grid.py` | Processing orchestrators — read, transform, write CF-NetCDF |
+| Tier 3 | `cli/` | Entry point — argument parsing, subcommand dispatch |
 | — | `plotters/`, `reports/` | Visualisation and HTML report generation |
-| — | `analysis/` | Science utilities (filtering, isopycnals, QC) |
+| — | `analysis/` | Science analysis (isopycnals, spectra) |
 | — | `config/` | Parameters, variable registry, YAML validation |
 
 Processing flows from raw files → Stage 1 (CF-NetCDF) → Stage 2 (trimming + clock) → Stage 3 (QC + ENU) → stack → grid.
@@ -150,7 +150,26 @@ Co-authored-by: Name <email@example.com>
 - **Type annotations**: all public function arguments and return values.
 - **Lint**: `ruff check .` must be clean. No bare `except:`. No suppressed warnings without a comment explaining why.
 - **Units**: every registered variable carries the registry's canonical spelling (`config/parameters.VARIABLES[var]["units"]`), and that spelling is identical in every file the package writes — except N², kept as `s-2` or `rad2 s-2` as it arrives (`config/unit_tables.UNIT_SPELLINGS_KEPT`). The pipeline rewrites known spellings through the shared units tables (`config/unit_tables.TABLES`) and refuses unknown ones. A new spelling is added **with evidence** — a reader that emits it — never from memory: to `config/unit_tables.UNIT_ALIAS_EXTRAS` if only oceanarray's readers emit it, or upstream in ctdcast's vendored `units_tables.py` if it belongs to the family. A mass↔volume conversion is never a scalar alias. Use `gsw` for all seawater property calculations.
-- **Plot style**: discrete colorbars (`BoundaryNorm`, ≤ 20 levels). Report figures are styled at one choke point — `reports/_encode.render_b64` applies the vendored `report.mplstyle` and `reports/_slots.render` draws each figure at its slot width — so a report plotter does not call `plt.style.use` itself.
+- **Plot style**: discrete colorbars (`BoundaryNorm`, ≤ 20 levels). Report figures are styled at one choke point — `reports/_vendored/figure_png.render_b64` applies the vendored `report.mplstyle` and `reports/_slots.render` draws each figure at its slot width — so a report plotter does not call `plt.style.use` itself.
+- **Private helpers**: a leading underscore keeps a helper out of the public API; it may be shared inside its own subpackage (`reports/`, `cli/`, `pipeline/`). Its docstring is **one line** plus a typed signature; a reason the code cannot show (a units or flag-table detail, a precedence order, an edge case) goes in a `#` comment at the line it explains. The name says what comes back, with one verb per job:
+
+  | verb | returns |
+  |---|---|
+  | `_read_<what>(path)` | an object read from a file |
+  | `_parse_<what>(text)` | a typed value from a string in hand, no I/O |
+  | `_resolve_<what>(…)` | the one value that applies, from several sources by precedence |
+  | `_format_<what>(value)` | a display string |
+  | `_build_<what>(…)` | rows, a dict or a dataset |
+  | `_render_<what>(…)` | an HTML fragment |
+  | `_draw_<what>(…)` | a matplotlib Figure (public: `draw_<what>`; no `_fig` suffix) |
+  | `_make_<what>_b64(…)` | a base64 PNG for a report slot (`_b64s` for a list) |
+  | `_has_<what>` / `_is_<what>` | a bool |
+  | `_apply_<what>(ds, …)` | the dataset after one processing step |
+  | `_add_<what>(…)` | the target with variables, attributes or flags added |
+  | `_rename_<what>(ds)` / `_to_canonical_<form>(ds)` | renamed variables / a foreign layout in ours |
+  | noun (`_time_axis_bounds`) | a computed result |
+
+  Words with a British/American variant are avoided where a neutral word exists (`_rename_`, not `_normalize_`); `color` is the exception. `tests/unit/test_private_names.py` fails on a retired prefix.
 - **Data provenance**: store all processing parameters (thresholds, coefficients) in NC output attributes so any file can be reprocessed exactly from itself.
 - **No silent defaults**: never substitute a default, guess, or approximation when the correct value cannot be determined. Raise, or warn loudly and record what was assumed in the output's metadata. A plausible wrong number is worse than an error, because nothing downstream can detect it.