oceanarray 0.1.0__tar.gz → 0.3.0__tar.gz

{oceanarray-0.1.0 → oceanarray-0.3.0}/.github/ISSUE_TEMPLATE.md

@@ -1,7 +1,7 @@
 ---
 name: "🐛 Bug Report / 💡 Feature Request"
-about: "Report a bug or suggest an improvement for the amocarray project"
-title: "[Bug] <brief description>" or "[Feature] <brief description>"
+about: "Report a bug or suggest an improvement for oceanarray"
+title: "[Bug] <brief description>"
 labels: []
 assignees: []
 ---
@@ -33,24 +33,20 @@ If you can, include a minimal, reproducible example or link to a failing test.
 
 ## Environment
 
-- OS: [e.g., macOS 13.3, Ubuntu 22.04, etc.]
+- OS: [e.g., macOS 13.3, Ubuntu 22.04]
 - Python version: [e.g., 3.11]
-- amocarray version: [if applicable]
+- `oceanarray` version: [`pip show oceanarray`]
+- `seasenselib` version: [`pip show seasenselib`]
 - Virtualenv / Conda / System Python?: [env type]
 
 
 ## Checklist
 
-- [ ] I have checked the existing [issues](https://github.com/AMOCcommunity/amocarray/issues) to avoid duplicates.
+- [ ] I have checked the existing [issues](https://github.com/ocean-uhh/oceanarray/issues) to avoid duplicates.
 - [ ] I have included steps to reproduce the issue, if it's a bug.
 - [ ] I have described the motivation clearly, if it's a feature request.
 
 
 ## Additional context
 
-Add any other context or screenshots about the problem or feature request here.
-
----
-
-*This issue template was prepared with assistance from ChatGPT to support clear and collaborative development.*
-
+Add any other context or screenshots about the problem here.

{oceanarray-0.1.0 → oceanarray-0.3.0}/.github/PULL_REQUEST_TEMPLATE.md

@@ -2,7 +2,7 @@ You can delete unused sections.
 
 ## PR Title Convention
 
-Please prefix your pull request title with one of the following tags for clarity:
+Please prefix your pull request title with one of the following tags:
 
 - `[DOC]` for documentation updates
 - `[FIX]` for bug fixes
@@ -13,7 +13,7 @@ Please prefix your pull request title with one of the following tags for clarity
 - `[CLEANUP]` for general maintenance
 
 Example:
-> `[FIX] Correct dimension handling in OSNAP reader`
+> `[FIX] Correct dimension handling in RBR reader`
 
 **Description:**
 
@@ -25,11 +25,10 @@ Please describe your changes clearly and concisely.
 
 **Checklist:**
 
-- [ ] I have followed the [coding conventions](https://amoccommunity.github.io/amocarray/conventions.html).
+- [ ] I have followed the [code conventions](CONTRIBUTING.md).
 - [ ] I have updated or added tests to cover my changes.
 - [ ] I have updated the documentation if needed.
-- [ ] I have run `pytest` to check that all tests pass.
-- [ ] I have run `pre-commit run --all-files` to lint and format the code.
+- [ ] I have run `ruff check . --fix` and `pytest` — all tests pass.
 
 **Related Issues / Pull Requests:**
 
@@ -41,7 +40,6 @@ Link any related issues, pull requests, or discussions:
 
 Include any additional information reviewers might need:
 
-- Screenshots (if UI/outputs are affected)
+- Screenshots (if outputs are affected)
 - Design decisions or trade-offs
 - Anything reviewers should look at closely
-

{oceanarray-0.1.0 → oceanarray-0.3.0}/.github/workflows/docs.yml

@@ -34,16 +34,16 @@ jobs:
       - name: Install package (editable)
         shell: bash -l {0}
         run: |
-          micromamba run -n TEST python -m pip install --upgrade pip
-          micromamba run -n TEST python -m pip install -e . --no-deps --force-reinstall
+          micromamba run -n oceanarray python -m pip install --upgrade pip
+          micromamba run -n oceanarray python -m pip install -e . --no-deps --force-reinstall
 
       - name: Build documentation
         shell: bash -l {0}
         run: |
           set -e
-          micromamba run -n TEST jupyter nbconvert --to notebook --execute notebooks/demo_instrument.ipynb --output=demo_instrument-output.ipynb --ExecutePreprocessor.allow_errors=True
-          micromamba run -n TEST jupyter nbconvert --to notebook --execute notebooks/demo_mooring.ipynb --output=demo_mooring-output.ipynb --ExecutePreprocessor.allow_errors=True
+          micromamba run -n oceanarray jupyter nbconvert --to notebook --execute notebooks/demo_instrument.ipynb --output=demo_instrument-output.ipynb --ExecutePreprocessor.allow_errors=True
+          micromamba run -n oceanarray jupyter nbconvert --to notebook --execute notebooks/demo_mooring.ipynb --output=demo_mooring-output.ipynb --ExecutePreprocessor.allow_errors=True
           mv notebooks/*output.ipynb docs/source/
           pushd docs
-          micromamba run -n TEST make clean html
+          micromamba run -n oceanarray make clean html
           popd

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

@@ -33,18 +33,18 @@ jobs:
       - name: Install package (editable)
         shell: bash -l {0}
         run: |
-          micromamba run -n TEST python -m pip install --upgrade pip
-          micromamba run -n TEST python -m pip install -e . --no-deps --force-reinstall
+          micromamba run -n oceanarray python -m pip install --upgrade pip
+          micromamba run -n oceanarray python -m pip install -e . --no-deps --force-reinstall
 
       - name: Build documentation
         shell: bash -l {0}
         run: |
           set -e
-          micromamba run -n TEST jupyter nbconvert --to notebook --execute notebooks/demo_instrument.ipynb --output=demo_instrument-output.ipynb --ExecutePreprocessor.allow_errors=True
-          micromamba run -n TEST jupyter nbconvert --to notebook --execute notebooks/demo_mooring.ipynb --output=demo_mooring-output.ipynb --ExecutePreprocessor.allow_errors=True
+          micromamba run -n oceanarray jupyter nbconvert --to notebook --execute notebooks/demo_instrument.ipynb --output=demo_instrument-output.ipynb --ExecutePreprocessor.allow_errors=True
+          micromamba run -n oceanarray jupyter nbconvert --to notebook --execute notebooks/demo_mooring.ipynb --output=demo_mooring-output.ipynb --ExecutePreprocessor.allow_errors=True
           mv notebooks/*output.ipynb docs/source/
           pushd docs
-          micromamba run -n TEST make clean html
+          micromamba run -n oceanarray make clean html
           popd
 
       - name: Deploy to GitHub Pages
@@ -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.3.0/.github/workflows/tests.yml

@@ -0,0 +1,63 @@
+name: Run tests
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  unit:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11"]
+      fail-fast: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.txt
+
+      - name: Install oceanarray
+        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
+          ${{ matrix.os == 'ubuntu-latest' && '--cov=oceanarray --cov-report=term-missing --cov-fail-under=38' || '--no-cov' }}
+
+  integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install dependencies
+        # requirements-test.txt = requirements-dev.txt + the PyPI seasenselib
+        # release, so the golden integration tests (stage2/stage3/grid) run for
+        # real here rather than skipping.
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-test.txt
+
+      - name: Install oceanarray
+        run: pip install -e . --no-deps --force-reinstall
+
+      - name: Run integration tests
+        # needs_seasenselib is NOT excluded here: seasenselib is installed above.
+        run: pytest tests/integration -m "not local" -q

{oceanarray-0.1.0 → oceanarray-0.3.0}/.gitignore

@@ -31,8 +31,6 @@ matlab_calibration/
 
 logs/*log
 
-# Claude Code configuration
-.claude/
 
 # VSCode settings
 .vscode/*

oceanarray-0.3.0/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+All notable changes to oceanarray are documented here.
+
+---
+
+## [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.3.0/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata below."
+authors:
+- family-names: Frajka-Williams
+  given-names: Eleanor
+  orcid: https://orcid.org/0000-0001-8773-7838
+  affiliation: University of Hamburg, Bundesstraße 53, 20146 Hamburg, Germany
+title: oceanarray
+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.
+keywords:
+  - oceanography
+  - mooring
+  - ADCP
+  - CTD
+  - NetCDF
+  - quality-control

oceanarray-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Contributing to oceanarray
+
+Thanks for taking the time to contribute.
+
+All contributions are welcome: bug reports, feature suggestions, documentation improvements, and code.
+
+## Table of Contents
+
+- [I Have a Question](#i-have-a-question)
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Enhancements](#suggesting-enhancements)
+- [Your First Code Contribution](#your-first-code-contribution)
+- [Improving The Documentation](#improving-the-documentation)
+
+---
+
+## I Have a Question
+
+Read the [documentation](https://ocean-uhh.github.io/oceanarray/) first.
+Then search [existing issues](https://github.com/ocean-uhh/oceanarray/issues) — your question may already be answered.
+
+If you still need help, [open an issue](https://github.com/ocean-uhh/oceanarray/issues/new) and include:
+
+- What you were trying to do and what you expected to happen.
+- A minimal reproducible example (e.g. a short script or notebook cell).
+- Your platform, Python version, and `pip show oceanarray seasenselib` output.
+
+---
+
+## Reporting Bugs
+
+Security vulnerabilities must be reported by email to [eleanorfrajka@gmail.com](mailto:eleanorfrajka@gmail.com) — do not use the public issue tracker.
+
+For all other bugs:
+
+1. Confirm you are on the latest release (`pip show oceanarray`).
+2. [Open an issue](https://github.com/ocean-uhh/oceanarray/issues/new) with:
+   - Steps to reproduce (minimal script if possible).
+   - Expected vs. actual behaviour.
+   - Full traceback.
+   - OS, Python version, `oceanarray` and `seasenselib` versions.
+
+---
+
+## Suggesting Enhancements
+
+[Open an issue](https://github.com/ocean-uhh/oceanarray/issues/new) describing:
+
+- What you want to do that is currently impossible or inconvenient.
+- Why it would be useful to other users (not just your specific cruise).
+- Whether you are willing to implement it yourself.
+
+Keep in mind that oceanarray is designed for reproducible processing of moored array data. Features that require cruise-specific raw data, add heavy new dependencies, or break the CF-NetCDF output contract are unlikely to be merged.
+
+---
+
+## Your First Code Contribution
+
+### Architecture overview
+
+| Layer | Modules | Role |
+|-------|---------|------|
+| Tier 1 | `tools/`, `utilities.py` | Pure functions, no side effects |
+| 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 |
+| — | `plotters/`, `report/` | Visualisation and HTML report generation |
+| — | `analysis/` | Science utilities (filtering, isopycnals, QC) |
+| — | `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.
+
+### Development setup
+
+```bash
+git clone https://github.com/ocean-uhh/oceanarray.git
+cd oceanarray
+python -m venv venv && source venv/bin/activate
+pip install -e .
+pip install -r requirements-dev.txt
+# seasenselib (needed for raw file reading):
+pip install pyrsktools pycnv
+pip install seasenselib --no-deps
+```
+
+### Workflow
+
+1. Fork the repository and create a feature branch from `main`.
+2. Make your changes, following the conventions below.
+3. Run `ruff check . --fix` and then `pytest` — all tests must pass.
+4. Open a pull request against `main`. Use a title prefixed with `[FEAT]`, `[FIX]`, `[REFACTOR]`, `[DOC]`, `[TEST]`, or `[CLEANUP]`.
+
+### Code conventions
+
+- **Docstrings**: NumPy style on every public function and class. Include `Parameters`, `Returns`, and `Raises` sections. Period at the end.
+- **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**: never strip or assume units. Use `gsw` for all seawater property calculations.
+- **Plot style**: discrete colorbars (`BoundaryNorm`, ≤ 20 levels); call `plt.style.use(str(P.MPLSTYLE))` at the start of every plot function.
+- **Data provenance**: store all processing parameters (thresholds, coefficients) in NC output attributes so any file can be reprocessed exactly from itself.
+
+### Testing
+
+Tests live in `tests/unit/` and `tests/integration/`. Run the full suite:
+
+```bash
+pytest                                                # all tests
+pytest tests/unit -m "not slow and not needs_seasenselib"  # without seasenselib
+pytest --cov=oceanarray --cov-report=term-missing -q  # with coverage
+```
+
+New or changed code must have test coverage. Integration tests use committed NetCDF fixtures in `tests/fixtures/`.
+
+---
+
+## Improving The Documentation
+
+Documentation is built with Sphinx from `docs/source/`. To build locally:
+
+```bash
+pip install -r requirements-dev.txt
+cd docs && make clean html
+open build/html/index.html
+```
+
+Docstring changes are picked up automatically. For narrative docs, edit `.rst` files in `docs/source/`. The API reference is auto-generated from docstrings via `autodoc`.

{oceanarray-0.1.0 → oceanarray-0.3.0}/MIGRATION-BASEDIR.md

@@ -1,9 +1,9 @@
 # Migrating from --basedir to --raw-dir / --proc-dir
 
-The `--basedir` flag is deprecated.  All subcommands now accept
-`--raw-dir` and `--proc-dir` instead.  `--basedir` still works and
-will continue to work indefinitely, but it prints a `DeprecationWarning`
-on every invocation.
+The `--basedir` flag has been **removed**.  All subcommands now require
+`--raw-dir` and `--proc-dir` instead.  Passing `--basedir` prints a migration
+message naming the replacement and exits without processing.  This document
+explains how to convert an old `--basedir` layout to the current one.
 
 ---
 
@@ -166,3 +166,25 @@ The old `--basedir DIR` resolved paths as:
 The new `--raw-dir`/`--proc-dir` flags give you explicit control over
 each root, support mooring-first raw layout, and put logs in a
 `processing_logs/` subdirectory.
+
+---
+
+## If you call the Python API directly (notebooks / scripts)
+
+The same removal touched the Python entry points:
+
+- **Processor constructors are keyword-only and required.** Replace
+  `MooringProcessor(basedir)` with
+  `MooringProcessor(raw_dir=RAW, proc_dir=PROC)`, and
+  `Stage2Processor(basedir)` / `Stage3Processor` / `MooringStacker` /
+  `MooringGridder` / `MooringReport` / `TimeGriddingProcessor` with
+  `proc_dir=PROC` (add `raw_dir=RAW` for stage 1 and the report). A positional
+  or `base_dir=` call now raises `TypeError`.
+- **Removed convenience functions:** `stage1_mooring`,
+  `process_multiple_moorings`, `stage2_mooring`,
+  `process_multiple_moorings_stage2`. Use the `oceanarray` CLI, or loop over
+  moorings yourself constructing the processor directly.
+- **`time_gridding_mooring(mooring, proc_dir, ...)`** and
+  `process_multiple_moorings_time_gridding` — the second positional argument is
+  now the **proc root**, not a cruise base dir. Update call sites; a positional
+  `basedir` value will be silently misused as `proc_dir`.

oceanarray-0.3.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: oceanarray
+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
+        
+        Copyright (c) 2025 Eleanor Frajka-Williams
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Documentation, https://ocean-uhh.github.io/oceanarray
+Project-URL: Homepage, https://github.com/ocean-uhh/oceanarray
+Project-URL: Repository, https://github.com/ocean-uhh/oceanarray
+Project-URL: Issue Tracker, https://github.com/ocean-uhh/oceanarray/issues
+Keywords: oceanography,mooring,ADCP,CTD,NetCDF,QC,oceanographic-data,AMOC
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Oceanography
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=2.0
+Requires-Dist: xarray>=2023.12.0
+Requires-Dist: netcdf4>=1.6
+Requires-Dist: scipy>=1.10
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: gsw>=3.6.16
+Requires-Dist: ppigrf
+Requires-Dist: ioos_qc
+Requires-Dist: dolfyn
+Requires-Dist: pycwt
+Requires-Dist: jinja2>=3.0
+Requires-Dist: packaging>=21.0
+Requires-Dist: ruamel.yaml>=0.18
+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/
+
+## Installation
+
+```bash
+pip install oceanarray
+```
+
+`seasenselib` is required for reading raw instrument files (available on PyPI but needs `--no-deps`):
+
+```bash
+pip install pyrsktools pycnv
+pip install seasenselib --no-deps
+```
+
+Python 3.9–3.12 is supported.
+
+## Quick start
+
+Create a skeleton YAML, fill in the deployment metadata, then process:
+
+```bash
+oceanarray init dsG3_1_2026 --proc-dir /data/proc
+# edit /data/proc/dsG3_1_2026/dsG3_1_2026.mooring.yaml
+oceanarray validate /data/proc/dsG3_1_2026/dsG3_1_2026.mooring.yaml
+oceanarray process dsG3_1_2026 --raw-dir /data/raw --proc-dir /data/proc --stage 1 2 3 stack grid
+oceanarray report  dsG3_1_2026 --raw-dir /data/raw --proc-dir /data/proc --all
+```
+
+See the [documentation](https://ocean-uhh.github.io/oceanarray/) for the recommended first-processing workflow, YAML reference, and CLI reference.
+
+## Python API
+
+```python
+import oceanarray
+
+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