[eleanorfrajka]

Summary

Writes one instrument's stage-3 dataset as an OceanSITES 1.4 deployment data file (manual §4.1), and a mooring's grid as a gridded file (§4.2), so the processed mooring data can be shared in the OceanSITES format.

What's changed

• oceanarray.writers.oceansites.to_oceansites(ds, mooring, *, array=None): variables on (TIME, DEPTH) with DEPTH the nominal instrument depth and PRES the measured (or interpolated) pressure; <PARAM>_QC from the stage-3 flags (reference table 2, unchanged); DM_indicator per variable and the global data_mode (M when mixed); sensor_* attributes; the §2.2 globals, TIME in days since 1950-01-01.
• An ADCP is one file with its bins on DEPTH (nominal transducer depth ± range, by orientation; refused without an orientation), PRES the pressure at each bin, TRANSDUCER_PRES(TIME) the measured transducer pressure it is computed from, sensor_orientation on every ADCP variable, and seabed_qc merged into the velocity flags.
• A grid becomes a gridded file (GRD): DEPTH the pressure levels converted with gsw.z_from_p (no re-interpolation), PRES the levels, and history naming the stage files the stack was built from; a grid that is not provisional (P) is refused, since it records no per-input data modes.
• oceansites_filename: OS_<platform>_<YYYYMM>_<mode>_<type>-<serial>-<depth>m.nc, type CTD, CT, CTDO, O, T, CM or ADCP.
• oceanarray.export(mooring, ...) and oceanarray export MOORING [--array YAML] [-o DIR] [--no-grid] [--overwrite]: writes every instrument's stage-3 file and the grid to <mooring folder>/oceansites/; an instrument that cannot be exported is listed and left out.
• Mooring description: platform_code and deployment_code (the month of deployment_time); oceanarray validate warns on a _ in the platform code or a deployment code that is not that month; oceanarray init writes both keys.
• D (delayed mode) only where the stage-3 file records the calibration-dip correction; site_code only from the array description, never invented.
• The OceanSITES reader also reads CSPD, CDIR, DOX2 and TURB.
• Docs: methods/oceansites_export.rst replaces the AC1 conversion page; oceanarray_format.rst describes the files written, without its earlier departures from OceanSITES (N_LEVELS, contributor_*, compact times).

Breaking changes

None.

Tests

The two dune2 stage-3 fixtures are written, read back with read_oceansites and compared variable by variable (TIME to 1 µs); file names, required globals, data-mode rules and refusals are tested on the same fixtures; the verb and the command run on a copy of the dune2 mooring folder.

[Copilot]

🟡 Changes recommended

Several moderate correctness issues remain in validation and OceanSITES export behavior, including invalid deployment codes, incorrect ADCP QC propagation, missing sensor metadata, and improper platform-code handling, while the documentation also promises unsupported outputs and metadata.

8 open issues

• Validate deployment-code month ranges · New
• Apply seabed QC only to velocity variables · New
• Reject impossible months in explicit deployment codes · New
• Reject non-string platform codes instead of coercing · New
• Use pressure QC for exported ADCP bin pressure · New
• Add sensor metadata to TRANSDUCER_PRES · New
• Remove unsupported stack file from OceanSITES product list · New
• Document that mixed-mode grids lack DM metadata · New

What changed in this PR

Adds OceanSITES 1.4 export support for instrument stage-3 datasets and mooring grid products, with Python and CLI interfaces, ADCP handling, metadata/QC support, naming validation, documentation, and tests.

Changes:

• Adds deployment and gridded OceanSITES conversion, filenames, metadata, data modes, QC flags, and ADCP support.
• Adds the oceanarray.export API and oceanarray export CLI command.
• Adds OceanSITES identity fields, validation, reader mappings, fixtures, documentation, and changelog updates.

File	Description
tests/​unit/​test_writers_oceansites.py	Tests deployment, ADCP, gridded exports, metadata, QC, modes, naming, and refusals.
tests/​unit/​test_mooring.py	Tests validation of OceanSITES platform and deployment codes.
tests/​unit/​test_export.py	Tests the export API and CLI behavior.
tests/​unit/​test_config_sites.py	Updates the allowed configuration-module list.
tests/​fixtures/​init_template_golden.yaml	Adds OceanSITES identity fields to the initialization fixture.
oceanarray/​writers/​oceansites.py	Implements OceanSITES 1.4 dataset conversion and filename generation.
oceanarray/​readers/​oceansites.py	Adds mappings for current, oxygen, and turbidity parameters.
oceanarray/​pipeline/​export.py	Implements mooring-level export orchestration.
oceanarray/​mooring.py	Adds platform/deployment fields, validation, and template support.
oceanarray/​cli/​export.py	Adds the oceanarray export command.
oceanarray/​cli/​__init__.py	Registers the export CLI command.
oceanarray/​__init__.py	Exposes the export API at package level.
docs/​source/​processing_framework.rst	Points processing documentation to the new export method.
docs/​source/​oceanarray.rst	Documents the OceanSITES writer module.
docs/​source/​oceanarray_format.rst	Documents the OceanSITES-based output format.
docs/​source/​methods/​oceansites_export.rst	Documents OceanSITES products, naming, ADCP behavior, grids, and data modes.
docs/​source/​methods/​conversion.rst	Removes the obsolete AC1 conversion page.
docs/​source/​index.rst	Updates the documentation index link.
CHANGELOG.md	Records the new export API, CLI, format, and metadata behavior.

_{Review effort: Lite}