oceanarray 0.2.0__tar.gz → 0.3.0__tar.gz

{oceanarray-0.2.0 → oceanarray-0.3.0}/.github/workflows/docs_deploy.yml

@@ -54,3 +54,10 @@ jobs:
           publish_dir: docs/build/html
           # Optional: publish_branch: gh-pages
           # Optional: cname: docs.example.org
+          # Replace gh-pages with a single commit each deploy. The built site is
+          # regenerable, so its history has no value. The saving is smaller than it
+          # looks: git deltas near-identical HTML well, and squashing 70-120 deploys
+          # shrinks a fresh clone by only 4-18%. What it does bound is the growth from
+          # re-executed demo notebooks, whose embedded PNGs differ every build and so
+          # never delta. Current site size dominates, not history - keep _static small.
+          force_orphan: true

{oceanarray-0.2.0 → oceanarray-0.3.0}/.github/workflows/tests.yml

@@ -32,7 +32,9 @@ jobs:
         run: pip install -e . --no-deps --force-reinstall
 
       - name: Run unit tests
-        run: pytest tests/unit -m "not slow and not local and not needs_seasenselib" -q
+        run: >
+          pytest tests/unit -m "not slow and not local and not needs_seasenselib" -q
+          ${{ matrix.os == 'ubuntu-latest' && '--cov=oceanarray --cov-report=term-missing --cov-fail-under=38' || '--no-cov' }}
 
   integration:
     runs-on: ubuntu-latest

{oceanarray-0.2.0 → oceanarray-0.3.0}/CHANGELOG.md

@@ -4,10 +4,37 @@ All notable changes to oceanarray are documented here.
 
 ---
 
-## [0.2.0] — unreleased
+## [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.

{oceanarray-0.2.0 → oceanarray-0.3.0}/CITATION.cff

@@ -6,15 +6,13 @@ authors:
   orcid: https://orcid.org/0000-0001-8773-7838
   affiliation: University of Hamburg, Bundesstraße 53, 20146 Hamburg, Germany
 title: oceanarray
-version: 0.2.0
-date-released: 2026-07-27
+version: 0.3.0
+date-released: 2026-08-11
 url: https://github.com/ocean-uhh/oceanarray
 repository-code: https://github.com/ocean-uhh/oceanarray
 license: MIT
 abstract: >
-  Multi-stage processing pipeline for moored oceanographic array observations:
-  converts raw instrument files (Sea-Bird, RBR, Nortek, RDI) to QC-flagged,
-  CF-compliant NetCDF and generates self-contained HTML mooring recovery reports.
+  Multi-stage processing pipeline for moored oceanographic array observations: converts raw instrument files (Sea-Bird, RBR, Nortek, RDI) to QC-flagged, CF-compliant NetCDF and generates self-contained HTML mooring recovery reports.
 keywords:
   - oceanography
   - mooring

{oceanarray-0.2.0/oceanarray.egg-info → oceanarray-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oceanarray
-Version: 0.2.0
+Version: 0.3.0
 Summary: Multi-stage processing pipeline for moored oceanographic observations: raw instrument files to QC-flagged CF-compliant NetCDF with automated HTML reports.
 Maintainer-email: Eleanor Frajka-Williams <eleanorfrajka@gmail.com>
 License: MIT License
@@ -60,6 +60,12 @@ Dynamic: license-file
 
 # OceanArray
 
+[![PyPI](https://img.shields.io/pypi/v/oceanarray.svg)](https://pypi.org/project/oceanarray/)
+[![Python versions](https://img.shields.io/pypi/pyversions/oceanarray.svg)](https://pypi.org/project/oceanarray/)
+[![License: MIT](https://img.shields.io/pypi/l/oceanarray.svg)](https://github.com/ocean-uhh/oceanarray/blob/main/LICENSE)
+[![Tests](https://github.com/ocean-uhh/oceanarray/actions/workflows/tests.yml/badge.svg)](https://github.com/ocean-uhh/oceanarray/actions/workflows/tests.yml)
+[![Documentation](https://img.shields.io/badge/docs-ocean--uhh.github.io-blue.svg)](https://ocean-uhh.github.io/oceanarray/)
+
 Python tools for processing moored oceanographic array observations from raw instrument files to quality-controlled, CF-compliant NetCDF.
 
 **Documentation**: https://ocean-uhh.github.io/oceanarray/
@@ -103,6 +109,12 @@ oceanarray.process('dsG3_1_2026', raw_dir='/data/raw', proc_dir='/data/proc')
 
 See the [API reference](https://ocean-uhh.github.io/oceanarray/oceanarray.html) for the full interface.
 
+## Acknowledgements
+
+Development was assisted by Claude Code (Anthropic) and GitHub Copilot code review.
+
+The data-processing approach draws on methods developed for the RAPID mooring array programme (UK/US funded). `oceanarray` is developed toward the DFG Ocean Array infrastructure project (DFG project number 571027118), from which it takes its name, and was first applied in the AEI–DFG MIXSED project (DFG project number 541914507).
+
 ## License
 
 MIT License

{oceanarray-0.2.0 → oceanarray-0.3.0}/README.md

@@ -1,5 +1,11 @@
 # OceanArray
 
+[![PyPI](https://img.shields.io/pypi/v/oceanarray.svg)](https://pypi.org/project/oceanarray/)
+[![Python versions](https://img.shields.io/pypi/pyversions/oceanarray.svg)](https://pypi.org/project/oceanarray/)
+[![License: MIT](https://img.shields.io/pypi/l/oceanarray.svg)](https://github.com/ocean-uhh/oceanarray/blob/main/LICENSE)
+[![Tests](https://github.com/ocean-uhh/oceanarray/actions/workflows/tests.yml/badge.svg)](https://github.com/ocean-uhh/oceanarray/actions/workflows/tests.yml)
+[![Documentation](https://img.shields.io/badge/docs-ocean--uhh.github.io-blue.svg)](https://ocean-uhh.github.io/oceanarray/)
+
 Python tools for processing moored oceanographic array observations from raw instrument files to quality-controlled, CF-compliant NetCDF.
 
 **Documentation**: https://ocean-uhh.github.io/oceanarray/
@@ -43,6 +49,12 @@ oceanarray.process('dsG3_1_2026', raw_dir='/data/raw', proc_dir='/data/proc')
 
 See the [API reference](https://ocean-uhh.github.io/oceanarray/oceanarray.html) for the full interface.
 
+## Acknowledgements
+
+Development was assisted by Claude Code (Anthropic) and GitHub Copilot code review.
+
+The data-processing approach draws on methods developed for the RAPID mooring array programme (UK/US funded). `oceanarray` is developed toward the DFG Ocean Array infrastructure project (DFG project number 571027118), from which it takes its name, and was first applied in the AEI–DFG MIXSED project (DFG project number 541914507).
+
 ## License
 
 MIT License

{oceanarray-0.2.0 → oceanarray-0.3.0}/docs/source/cli_reference.rst

@@ -7,8 +7,7 @@ CLI Reference
 The typical workflow is: validate the YAML, run ``oceanarray process`` stage by
 stage, inspect with ``oceanarray report``, combine with ``oceanarray stack`` and
 ``oceanarray grid``, then use ``oceanarray run`` to reproduce the full pipeline
-in one command.  ``oceanarray logsheet`` covers fieldwork logistics and is
-independent of the processing pipeline.
+in one command.
 
 All processing subcommands accept a mooring name as the first positional
 argument.  The mooring name is used to locate the YAML file at
@@ -555,102 +554,6 @@ reports.
 
 ----
 
-``oceanarray logsheet``
-------------------------
-
-Generate PDF logsheets for mooring fieldwork and calibration-dip casts.
-See :doc:`logsheets` for a full description of sheet types and configuration.
-
-**Synopsis**
-
-.. code-block:: text
-
-   oceanarray logsheet [--type TYPE] [--mooring MOORING] [--cast CAST]
-                       [--config-dir DIR] [--inventory PATH]
-                       [--logsheet-config PATH]
-                       [--output-dir DIR] [--format {pdf,tex}]
-                       [--all]
-                       [--proc-dir DIR]
-
-**Flags**
-
-.. list-table::
-   :header-rows: 1
-   :widths: 28 10 12 50
-
-   * - Flag
-     - Type
-     - Default
-     - Description
-   * - ``--type TYPE``
-     - string
-     - (required)
-     - Sheet type: ``caldip-setup``, ``caldip-download``, ``mooring-download``,
-       ``mooring-recovery``, or ``mooring-setup``.
-   * - ``--mooring MOORING``
-     - string
-     - —
-     - Mooring name (required for mooring sheet types).
-   * - ``--cast CAST``
-     - string
-     - —
-     - Cast name, e.g. ``B1`` (required for caldip sheet types).
-   * - ``--config-dir DIR``
-     - path
-     - ``$LOGSHEETS_CONFIG_DIR`` or ``./``
-     - Directory containing ``logsheet_config.yaml`` and
-       ``instrument_inventory.csv``.
-   * - ``--inventory PATH``
-     - path
-     - ``{config-dir}/instrument_inventory.csv``
-     - Explicit path to the instrument inventory CSV (overrides ``--config-dir``).
-   * - ``--logsheet-config PATH``
-     - path
-     - ``{config-dir}/logsheet_config.yaml``
-     - Explicit path to the logsheet YAML (overrides ``--config-dir``).
-   * - ``--output-dir DIR``
-     - path
-     - ``./logsheets/``
-     - Directory where PDF (or TeX) files are written.
-   * - ``--format {pdf,tex}``
-     - string
-     - ``pdf``
-     - Output format: compile to PDF (requires ``pdflatex``) or write LaTeX
-       source only.
-   * - ``--all``
-     - flag
-     - off
-     - Generate all sheet types for every cast and mooring listed in
-       ``logsheet_config.yaml``.
-   * - ``--proc-dir DIR``
-     - path
-     - (required for mooring sheets)
-     - Cruise-level processed data directory (used to locate mooring YAMLs).
-
-**Examples**
-
-Caldip setup sheet for cast B1:
-
-.. code-block:: bash
-
-   oceanarray logsheet --type caldip-setup --cast B1 \
-       --config-dir config/ --proc-dir /data/proc
-
-Mooring recovery log:
-
-.. code-block:: bash
-
-   oceanarray logsheet --type mooring-recovery --mooring dsG3_1_2026 \
-       --config-dir config/ --proc-dir /data/proc
-
-All sheets for every cast and mooring:
-
-.. code-block:: bash
-
-   oceanarray logsheet --all --config-dir config/ --proc-dir /data/proc
-
-----
-
 ``oceanarray list``
 --------------------
 

{oceanarray-0.2.0 → oceanarray-0.3.0}/docs/source/file_naming_conventions.rst

@@ -63,7 +63,8 @@ the instrument type and firmware:
      - binary raw files; ``filename:`` points to the first file
 
 These conventions are recorded in the ``filename_conventions:`` section of
-``logsheet_config.yaml`` and are used by ``oceanarray logsheet`` to pre-fill
+``logsheet_config.yaml`` and are used by the standalone
+`logsheet <https://github.com/ocean-uhh/logsheet>`_ package to pre-fill
 expected filenames on the download logsheets.
 
 ----
@@ -122,5 +123,5 @@ See also
 - :doc:`directory_structure` — where these files live on disk
 - :doc:`yaml_configuration` — YAML fields that control filenames (``name:``,
   ``serial:``, ``filename:``)
-- :doc:`logsheets` — how ``logsheet_config.yaml`` filename conventions connect
-  raw-file naming to the logsheet workflow
+- `logsheet package <https://github.com/ocean-uhh/logsheet>`_ — how ``logsheet_config.yaml``
+  filename conventions connect raw-file naming to the logsheet workflow

{oceanarray-0.2.0 → oceanarray-0.3.0}/docs/source/index.rst

@@ -59,13 +59,6 @@ Contents
    Stack into one NetCDF <methods/time_gridding>
    Grid onto pressure <methods/vertical_gridding>
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Logsheets
-
-   Fieldwork Logsheets <logsheets>
-
-
 .. toctree::
    :maxdepth: 1
    :caption: Caldips

{oceanarray-0.2.0 → oceanarray-0.3.0}/docs/source/legacy.rst

@@ -34,7 +34,7 @@ active processing code:
 
 ``mooring_rodb.py``
    Mooring-level stacking and filtering for RODB data — superseded by
-   :mod:`oceanarray.mooring_level`.
+   :mod:`oceanarray.processors.stack` and :mod:`oceanarray.processors.grid`.
 
 ``convertOS.py``
    OceanSites format conversion from RODB — superseded by the Stage 1–3 pipeline.

{oceanarray-0.2.0 → oceanarray-0.3.0}/docs/source/methods/nortek_coordinate_transform.rst

@@ -249,7 +249,7 @@ The reference Python script from Nortek Support is reproduced at
 
    R = H @ P
 
-The ``oceanarray`` implementation in ``stage3._xyz_to_enu()`` expands this
+The ``oceanarray`` implementation in ``processors.coordinate.xyz_to_enu()`` expands this
 product analytically (vectorised over the time dimension) and adds the magnetic
 declination offset to the heading before computing :math:`h`.
 
@@ -286,6 +286,6 @@ See also
 - `Nortek Support: How do I transform a coordinate system manually?
   <https://support.nortekgroup.com/hc/en-us/articles/26048113914652-How-do-I-transform-a-coordinate-system-manually>`_
 - :doc:`auto_qc` — QARTOD flags applied to velocity after tilt QC
-- :py:func:`oceanarray.stage3._xyz_to_enu` — vectorised ENU rotation
-- :py:func:`oceanarray.stage3._apply_beam_to_enu` — full BEAM/XYZ → ENU pipeline
-- :py:func:`oceanarray.stage1.Stage1Processor._parse_nortek_T_matrix_hdr` — header parsing
+- :py:func:`oceanarray.processors.coordinate.xyz_to_enu` — vectorised ENU rotation
+- :py:func:`oceanarray.processors.coordinate.apply_beam_to_enu` — full BEAM/XYZ → ENU pipeline
+- :py:func:`oceanarray.processors.stage1._parse_nortek_T_matrix_hdr` — header parsing

{oceanarray-0.2.0 → oceanarray-0.3.0}/docs/source/methods/standardisation.rst

@@ -28,12 +28,12 @@ This creates a uniform structure suitable for later trimming, filtering, and con
 3. Current Implementation (Stage 1)
 -----------------------------------
 
-The standardisation process is implemented in the :mod:`oceanarray.stage1` module, which provides automated conversion from native instrument formats to standardised NetCDF files.
+The standardisation process is implemented in the :mod:`oceanarray.processors.stage1` module, which provides automated conversion from native instrument formats to standardised NetCDF files.
 
 3.1. Input Formats Supported
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The :class:`oceanarray.stage1.MooringProcessor` class supports multiple instrument formats:
+The :class:`oceanarray.processors.stage1.MooringProcessor` class supports multiple instrument formats:
 
 - **Sea-Bird CNV files** (`sbe-cnv`): Standard SBE 37 MicroCAT output
 - **Sea-Bird ASCII files** (`sbe-ascii`): Alternative SBE ASCII format
@@ -136,15 +136,16 @@ The ``instruments`` list contains one entry per instrument on the mooring, with:
 
 .. code-block:: python
 
-   from oceanarray.stage1 import MooringProcessor, process_multiple_moorings
+   import oceanarray
 
-   # Process a single mooring
-   processor = MooringProcessor('/path/to/data/')
-   success = processor.process_mooring('mooring_name')
+   # Process a single mooring through Stage 1
+   oceanarray.process('mooring_name', stage=1,
+                      raw_dir='/path/to/raw/', proc_dir='/path/to/proc/')
 
    # Process multiple moorings
-   moorings = ['mooring1', 'mooring2', 'mooring3']
-   results = process_multiple_moorings(moorings, '/path/to/data/')
+   for mooring in ['mooring1', 'mooring2', 'mooring3']:
+       oceanarray.process(mooring, stage=1,
+                          raw_dir='/path/to/raw/', proc_dir='/path/to/proc/')
 
 4. Output Format
 ----------------
@@ -238,7 +239,7 @@ This script performed similar functions to the current Python implementation:
    :linenos:
    :caption: Excerpt from `microcat2rodb_3.m`
 
-The modern Python implementation in :mod:`oceanarray.stage1` provides equivalent functionality with improved:
+The modern Python implementation in :mod:`oceanarray.processors.stage1` provides equivalent functionality with improved:
 
 - **Error handling**: Comprehensive logging and graceful failure modes
 - **Format support**: Multiple instrument types through pluggable readers

{oceanarray-0.2.0 → oceanarray-0.3.0}/docs/source/methods/vertical_gridding.rst

@@ -25,9 +25,9 @@ Python API
 
 .. code-block:: python
 
-   from oceanarray.mooring_level import MooringGridder
+   from oceanarray.processors.grid import MooringGridder
 
-   MooringGridder(proc_dir).grid(mooring_name, p_start=200.0, p_end=1000.0, dp=20.0, force=False)
+   MooringGridder(proc_dir=proc_dir).grid(mooring_name, p_start=200.0, p_end=1000.0, dp=20.0, force=False)
 
 Purpose
 -------

{oceanarray-0.2.0 → oceanarray-0.3.0}/docs/source/oceanarray.rst

@@ -60,15 +60,6 @@ Path resolution helpers for raw and processed directory trees.
    :members:
    :undoc-members:
 
-logsheet
-^^^^^^^^
-Generate fieldwork logsheet PDFs for mooring deployments/recoveries and
-calibration-dip casts.
-
-.. automodule:: oceanarray.logsheet
-   :members:
-   :undoc-members:
-
 Instrument processing
 ----------------------
 

oceanarray-0.3.0/docs/source/project_structure.md

@@ -0,0 +1,211 @@
+# OceanArray Project Structure
+
+This document provides an overview of the oceanarray codebase structure and organisation.
+
+---
+
+## Project Structure Overview
+
+```
+oceanarray/
+├── oceanarray/                    # Main Python package
+│   ├── __init__.py                # Public API: process(), STAGES, parameters
+│   ├── _version.py                # Package version (auto-generated by setuptools-scm)
+│   ├── cli.py                     # [core] Command-line interface (oceanarray init/process/run/report/validate/…)
+│   ├── utilities.py               # [core] Shared utility helpers used across the pipeline
+│   ├── inspect.py                 # [core] Quick dataset inspection helpers for interactive use
+│   ├── logger.py                  # [core] Logging configuration and helpers
+│   ├── paths.py                   # [core] Filesystem path and filename conventions
+│   │
+│   ├── processors/                # [core] Processing stages + pipeline registry
+│   │   ├── __init__.py            # Pipeline stage registry and public process() entry point
+│   │   ├── stage1.py              # Stage 1: raw data → CF-NetCDF (*_stage1.nc)
+│   │   ├── stage2.py              # Stage 2: clock correction + deployment trim (*_stage2.nc)
+│   │   ├── stage3.py              # Stage 3: pressure interpolation + QARTOD QC (*_stage3.nc)
+│   │   ├── pressure.py            # Pressure interpolation helpers for stage 3
+│   │   ├── qc.py                  # QARTOD QC tests and CTD derivations for stage 3
+│   │   ├── coordinate.py          # BEAM→ENU transforms and ADCP QC for stage 3
+│   │   ├── caldip.py              # CalDip calibration-dip corrections (not yet implemented)
+│   │   ├── stack.py               # MooringStacker: instruments → common time grid (*_stack.nc)
+│   │   ├── grid.py                # MooringGridder: stack → regular pressure grid (*_grid.nc)
+│   │   └── helpers.py             # Internal helpers for stack and grid operations
+│   │
+│   ├── analysis/                  # [analysis] Science utilities
+│   │   ├── clock.py               # Clock-offset analysis functions
+│   │   ├── hydrographic.py        # Hydrographic analysis utilities
+│   │   ├── science.py             # QC and dataset processing functions
+│   │   ├── spectral.py            # Spectral analysis of time series
+│   │   ├── temporal.py            # Time-series analysis utilities
+│   │   └── vector.py              # Vector rotation and progressive-vector utilities
+│   │
+│   ├── plotters/                  # [viz] Three-tier plotting package
+│   │   ├── __init__.py            # Public API
+│   │   ├── primitives.py          # Tier 1: data-agnostic plotting primitives
+│   │   ├── current.py             # Tier 2: current/velocity domain plots
+│   │   ├── diagnostic.py          # Tier 2: T-S, histogram, spectrum, QC diagnostic plots
+│   │   ├── hydrography.py         # Tier 2: hydrographic section and isopycnal plots
+│   │   ├── timeseries.py          # Tier 2: time-series and gridded-section plots
+│   │   ├── spectrum.py            # Tier 2: spectral diagnostics
+│   │   ├── ts.py                  # T-S diagram and thermohaline structure plots
+│   │   ├── animation.py           # Animated plot functions
+│   │   ├── helpers.py             # Shared colormap/style helpers
+│   │   └── _cli_legacy.py         # Legacy CLI plots (pending `oceanarray plot <file>` redesign)
+│   │
+│   ├── report/                    # [report] HTML report generation
+│   │   ├── __init__.py            # Public entry-points (MooringReport, etc.)
+│   │   ├── _mooring.py            # Mooring summary template + MooringReport orchestrator
+│   │   ├── _instrument.py         # Per-instrument report ({mooring}_{serial}_report.html)
+│   │   ├── _stack.py              # Stack report (multi-instrument timeseries, tilt panels)
+│   │   ├── _grid.py               # Grid report (vertical section, spectra, N²)
+│   │   ├── _array.py              # Array-level multi-mooring summary report
+│   │   ├── _plots.py              # Tier 3: report-level figure wrappers (base64 PNGs)
+│   │   ├── _html_helpers.py       # HTML/QC constants, base64 helpers, NC metadata readers
+│   │   └── _recovery_table.py     # Per-mooring cruise-report recovery table
+│   │
+│   ├── tools/                     # [core] Shared I/O infrastructure
+│   │   ├── readers.py             # NetCDF and legacy-format instrument readers
+│   │   ├── writers.py             # NetCDF write helpers (OceanSITES-compliant)
+│   │   └── rapid_interp.py        # Physics-informed vertical interpolation for sparse profiles
+│   │
+│   ├── config/                    # Configuration
+│   │   ├── parameters.py          # Package-level defaults (VARIABLES, QC ranges, style)
+│   │   ├── validation.py          # Mooring YAML validation
+│   │   ├── OS1_var_names.yaml     # OceanSITES variable name mappings
+│   │   ├── OS1_sensor_attrs.yaml  # OceanSITES sensor attributes
+│   │   ├── logging.yaml           # Logging configuration
+│   │   └── legacy/                # Legacy RAPID/RODB configuration files
+│   │
+│   └── legacy/                    # Legacy RODB/RAPID processing (deprecated; excluded from lint)
+│
+├── tests/                         # pytest test suite
+│   ├── unit/                      # seasenselib-free unit tests
+│   ├── integration/               # Golden + pipeline tests (needs_seasenselib)
+│   ├── fixtures/                  # Committed raw + processed dune2_1_2026 fixtures
+│   └── legacy/                    # Tests for legacy RODB/RAPID processing
+│
+├── notebooks/                     # Demo notebooks
+├── docs/                          # Sphinx documentation
+│   └── source/
+│       ├── methods/               # Method documentation (one page per processing step)
+│       └── _static/               # Static files, code examples, CSS
+│
+├── CLAUDE.md                      # Claude Code guidance (local-only)
+├── CITATION.cff                   # Citation metadata
+├── CHANGELOG.md
+├── pyproject.toml                 # Build system and project metadata
+├── requirements.txt
+└── README.md
+```
+
+---
+
+## Processing Stages
+
+The pipeline processes raw instrument data through sequential stages, each
+producing a CF-NetCDF output file. `oceanarray.STAGES` is the registry of stages,
+and `oceanarray.process(mooring, stage=…, proc_dir=…, raw_dir=…)` runs any subset.
+
+### Stage 1 — Standardisation (`processors/stage1.py`)
+- **Input**: raw instrument files (`.cnv`, `.rsk`, `.dat`, `.hex`, RDI raw)
+- **Output**: `{proc_dir}/{mooring}/{mooring}_{serial}_stage1.nc`
+- Faithful to the raw data — no QC, no trimming. Stores the transformation matrix
+  and coordinate system so later stages can rotate correctly.
+
+### Stage 2 — Clock correction + trimming (`processors/stage2.py`)
+- **Input**: `*_stage1.nc` + mooring YAML (clock offsets, deployment window)
+- **Output**: `*_stage2.nc`
+- Applies linear clock-offset correction; trims to the deployment window.
+
+### Stage 3 — QC, rotation, derived variables (`processors/stage3.py`)
+- **Input**: `*_stage2.nc`
+- **Output**: `*_stage3.nc`
+- Gross-range and tilt QC flags, BEAM→ENU rotation (Aquadopp), magnetic declination
+  correction, salinity, density.
+
+### Stack — multi-instrument coordination (`processors/stack.py`)
+- **Input**: `*_stage3.nc` files for all instruments on a mooring
+- **Output**: `{mooring}_stack.nc`  — `(N_LEVELS, time)` Dataset
+- Aligns instruments onto a common time axis; HAB-ordered deepest-first (index 0).
+
+### Grid — vertical gridding (`processors/grid.py`)
+- **Input**: `*_stack.nc`
+- **Output**: `{mooring}_grid.nc` — `(N_LEVELS, time)` on uniform pressure levels
+- Simple 1-D linear interpolation at each time step (preliminary; no objective mapping).
+
+---
+
+## Data Flow
+
+```
+Raw files
+   │
+   ▼ oceanarray process --stage 1
+*_stage1.nc   (faithful copy, CF-NetCDF)
+   │
+   ▼ oceanarray process --stage 2
+*_stage2.nc   (clock-corrected, trimmed)
+   │
+   ▼ oceanarray process --stage 3
+*_stage3.nc   (QC flagged, ENU velocities, salinity/density)
+   │
+   ▼ oceanarray process --stage stack
+{mooring}_stack.nc   (N_LEVELS × time)
+   │
+   ├──▶ oceanarray report  →  HTML reports
+   │
+   ▼ oceanarray process --stage grid
+{mooring}_grid.nc   (uniform pressure × time)
+   │
+   └──▶ oceanarray report  →  grid HTML report
+```
+
+The full pipeline runs in one command: `oceanarray process MOORING --stage 1 2 3 stack grid`
+(or `oceanarray run MOORING`).
+
+---
+
+## Plotters Package Architecture
+
+Three-tier architecture (see `.claude/plotters_update-20260718.md` for the rules):
+
+- **Tier 1** (`plotters/primitives.py`): low-level axes primitives, no domain knowledge
+- **Tier 2** (`plotters/current.py`, `timeseries.py`, `hydrography.py`, etc.): domain
+  functions that know about oceanographic variables
+- **Tier 3** (`report/_plots.py`): report wrappers that call Tier-2 functions and return
+  base64 PNG strings for embedding in HTML
+
+---
+
+## Report Package
+
+Report types, each in its own module:
+
+| Report | Module | Output file |
+|--------|--------|-------------|
+| Mooring summary | `report/_mooring.py` | `{mooring}_report.html` |
+| Per-instrument | `report/_instrument.py` | `{mooring}_{serial}_report.html` |
+| Stack | `report/_stack.py` | `{mooring}_stack_report.html` |
+| Grid | `report/_grid.py` | `{mooring}_grid_report.html` |
+| Array | `report/_array.py` | `{array}_array_report.html` |
+
+All figures are generated by `report/_plots.py` (Tier 3) and embedded as base64 PNGs.
+
+---
+
+## Key Design Principles
+
+- **Data provenance**: never silently substitute defaults; store all processing
+  parameters in NetCDF global attributes so treatment can be reconstructed from the file.
+- **CF-compliant**: CF conventions for metadata and variable naming throughout.
+- **xarray-based**: `xr.Dataset` is the primary data structure in all stages.
+- **Discrete colorbars**: all figures use `_nice_colorbar_bounds` + `BoundaryNorm`;
+  continuous colorbars are not used.
+- **Configurable**: YAML-driven configuration for QC ranges, clock offsets, deployment
+  windows, and instrument metadata.
+
+---
+
+## Legacy Modules
+
+`legacy/` contains the RODB/RAPID-format processing path, kept for backward
+compatibility with older datasets.  New projects use the stage 1–3 pipeline above.

oceanarray-0.3.0/oceanarray/_version.py

@@ -0,0 +1 @@
+__version__ = '0.3.0'