CLI Reference

The typical workflow is: validate the YAML, run oceanarray process stage by stage (including the stack and grid stages), inspect with oceanarray report, then use oceanarray run to reproduce the full 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 {proc_dir}/{mooring}/{mooring}.mooring.yaml.

Without --force, every subcommand skips any output file that already exists. Add --force to overwrite.

The flag lists below are generated from the argument parser (oceanarray.cli.build_parser()), so they cannot drift from the code.

`oceanarray validate`

Check one or more YAML configuration files for missing required fields, unrecognised values, and structural errors. Does not require --raw-dir or --proc-dir. Run this before any processing to catch typos in file_type, missing hab, or malformed serial numbers.

usage: oceanarray validate [-h] yaml [yaml ...]

Positional Arguments

yaml: Path(s) to .mooring.yaml file(s)

Example

oceanarray validate /data/proc/dsG3_1_2026/dsG3_1_2026.mooring.yaml

Prints errors and warnings to the console. Exits with a non-zero status if any errors are found.

`oceanarray init`

Create a skeleton mooring YAML file with commented template fields for all mandatory metadata and one example entry per instrument type. Edit the file to fill in real values and delete unused instrument blocks. Typically run once, before oceanarray validate.

usage: oceanarray init [-h] --proc-dir DIR mooring

Positional Arguments

mooring: Mooring name, e.g. dsG3_1_2026

Named Arguments

--proc-dir: Cruise-level processed output directory (stub is written to {proc_dir}/{mooring}/).

Example

oceanarray init dsG3_1_2026 --proc-dir /data/proc

Creates /data/proc/dsG3_1_2026/dsG3_1_2026.mooring.yaml (the directory is created if it does not exist).

`oceanarray process`

Run one or more per-instrument processing stages. Stage 2 requires that stage 1 has already run; stage 3 requires stage 2.

The recommended sequence for a new mooring is:

--stage 1: verify that all raw files are reachable.
--stage 2: check that trimming looks right; adjust deployment_time / recovery_time in the YAML if needed.
--stage 3: apply QC and velocity rotation once stages 1 and 2 are confirmed.

usage: oceanarray process [-h] [--raw-dir DIR] [--proc-dir DIR]
                          [--stage {1,2,3,stack,grid} [{1,2,3,stack,grid} ...]]
                          [--dt SECONDS] [--dp DBAR] [--pmin DBAR]
                          [--pmax DBAR] [--plot] [--report]
                          [--serial SERIAL [SERIAL ...]] [--force] [-n]
                          mooring

Positional Arguments

mooring: Mooring name, e.g. dsG3_1_2026

Named Arguments

--raw-dir

Cruise-level raw data directory (pipeline appends /{mooring}/). Required for stage 1.

--proc-dir

Cruise-level processed output directory (pipeline appends /{mooring}/).

--stage

Possible choices: 1, 2, 3, stack, grid

Stage(s) to run (default: 1 2 3). Use ‘stack’ and ‘grid’ for mooring-level steps.

--dt

Stack time-grid interval in seconds (default: 60)

Default: 60

--dp

Pressure grid spacing in dbar (default: 20)

Default: 20.0

--pmin

Shallowest pressure level for grid (default: 200)

Default: 200.0

--pmax

Deepest pressure level for grid (default: 1000)

Default: 1000.0

--plot

Generate plots of processed microcat data after stage 2

Default: False

--report

Print a summary of processed records per instrument and serial number

Default: False

--serial

Process only instrument(s) with these serial number(s), e.g. –serial 14321 400118

Default: []

--force

Overwrite existing output files (both stages skip existing files by default)

Default: False

-n, --dry-run

Do not actually modify any files; show what would be done (stage 3 only)

Default: False

Stage descriptions

Stage 1: reads raw instrument files via seasenselib and writes {mooring}_{serial}_stage1.nc. Data are stored as-is — no QC, no trimming.
Stage 2: trims to deployment_time / recovery_time from the YAML and applies clock drift correction. Writes {mooring}_{serial}_stage2.nc.
Stage 3: applies QARTOD gross-range QC flags, derives salinity, interpolates pressure for instruments without a pressure port, rotates Aquadopp velocities to earth coordinates, and applies magnetic declination correction. Writes {mooring}_{serial}_stage3.nc.
stack: interpolates all instruments onto a common time axis and writes {mooring}_stack.nc. Instruments sampling faster than --dt are subsampled by nearest-neighbour; slower instruments are interpolated linearly. The 60-second default suits most mooring data; for high-frequency analysis (e.g. internal waves from fast thermistors) work from the _stage3.nc files or build a finer stack with --dt.
grid: interpolates the stack onto a regular pressure grid and writes {mooring}_grid.nc. Values outside the instrument depth range at each time step are set to NaN. QC flags from stage 3 are not consulted — data flagged suspect or bad are treated the same as good unless already NaN.

Output created

Per-instrument: {mooring}_{serial}_stage{N}.nc in {proc_dir}/{mooring}/{instrument}/. Mooring-level: {mooring}_stack.nc and {mooring}_grid.nc in {proc_dir}/{mooring}/.

Examples

Run stage 1 for all instruments:

oceanarray process dsG3_1_2026 --raw-dir /data/raw --proc-dir /data/proc --stage 1

Rerun stage 2 for a single instrument after updating the YAML:

oceanarray process dsG3_1_2026 --raw-dir /data/raw --proc-dir /data/proc --stage 2 --serial 26261 --force

Full pipeline — all instrument stages plus stack and grid:

oceanarray process dsG3_1_2026 --raw-dir /data/raw --proc-dir /data/proc --stage 1 2 3 stack grid

Stack and grid only (after stages 1–3 already ran), non-default grid spacing:

oceanarray process dsG3_1_2026 --proc-dir /data/proc --stage stack grid --dp 10 --pmin 100 --pmax 2000

`oceanarray report`

Generate HTML reports for a mooring. Without any report-type flags, generates only the mooring summary page. See HTML Reports for a description of what each report page contains.

usage: oceanarray report [-h] [--raw-dir DIR] [--proc-dir DIR] [-o DIR]
                         [--report-dir DIR] [--sig-level SIG [SIG ...]]
                         [--force] [--instruments] [--grid] [--stack]
                         [--serial SN [SN ...]] [--all] [--pdf]
                         [--pdf-dir DIR] [--array] [--cruise-table] [-n]
                         [--skip-existing]
                         mooring

Positional Arguments

mooring: Mooring name, e.g. dsG3_1_2026

Named Arguments

--raw-dir

Cruise-level raw data directory (pipeline appends /{mooring}/). Required for stage 1.

--proc-dir

Cruise-level processed output directory (pipeline appends /{mooring}/).

-o, --output-dir

Directory for the HTML report (default: {proc-dir}/{mooring}/report/)

--report-dir

Central directory for all mooring reports. Each mooring’s pages are written to DIR/{mooring}/ instead of proc/{mooring}/report/, making the whole report tree portable.

--sig-level

σ₀ target values (kg m⁻³, referenced to 0 dbar) for isopycnal height-above-seabed tracking in the grid report. Pass one or more values; they are sorted before use. Example: –sig-level 27.5 27.7 27.9 (default: 27.7).

--force

Overwrite existing report

Default: False

--instruments, -i

Also generate per-instrument HTML pages (slow; skipped by default)

Default: False

--grid, -g

Also generate the gridded-data report page (requires _grid.nc)

Default: False

--stack, -s

Also generate the stacked-data report page with pressure and T time series (requires _stack.nc)

Default: False

--serial

Generate per-instrument page(s) for these serial number(s) only (implies –instruments for the listed serials)

--all, -A

Generate all report pages: equivalent to –stack –grid –instruments –pdf (also builds the combined PDF)

Default: False

--pdf

Combine the generated HTML report pages into a single A4 PDF ({mooring}_report.pdf), in reading order summary → instruments → stack → grid. Requires the ‘pdf’ extra: pip install oceanarray[pdf]. Implied by –all.

Default: False

--pdf-dir

Write the combined PDF to DIR/{mooring}_report.pdf instead of beside the HTML pages, so every mooring’s PDF collects in one shareable directory (created if needed). Only affects PDF placement; still needs –pdf or –all to build the PDF at all.

--array

Treat the positional argument as an array YAML path (name ending .array.yaml) and generate an array-level HTML index linking all mooring reports. –report-dir is the output root for the index.

Default: False

--cruise-table

Generate a standalone, print-optimised HTML recovery table for use in cruise reports (one per mooring: {mooring}_recovery_table.html).

Default: False

-n, --dry-run

Show which report files would be generated (no files written).

Default: False

--skip-existing

Skip any output file that already exists, regardless of source mtime (old behaviour; use –force to always regenerate).

Default: False

Output created

{mooring}_report.html (always), plus optional {mooring}_stack_report.html, {mooring}_grid_report.html, and report/instrument/{mooring}_{serial}_report.html.

Examples

Summary and per-instrument pages:

oceanarray report dsG3_1_2026 --raw-dir /data/raw --proc-dir /data/proc --instruments

All report types (equivalent to --stack --grid --instruments --pdf):

oceanarray report dsG3_1_2026 --raw-dir /data/raw --proc-dir /data/proc --all

Array-level index across all moorings:

oceanarray report cruise.array.yaml --array --report-dir /data/reports

Cruise recovery table:

oceanarray report dsG3_1_2026 --raw-dir /data/raw --proc-dir /data/proc --cruise-table

`oceanarray run`

Run the complete processing pipeline in one command: stages 1, 2, and 3, followed by stack, grid, and all report pages. Continues past individual instrument failures — check the processing logs in {proc_dir}/{mooring}/processing_logs/ for details.

Use oceanarray run only after confirming that stage 1 can read all raw files and that the deployment_time / recovery_time values in the YAML produce the correct trim (verified with oceanarray process --stage 2 and a quick report inspection).

usage: oceanarray run [-h] [--raw-dir DIR] [--proc-dir DIR] [--force]
                      [--serial SN [SN ...]] [--dt SECONDS] [--dp DBAR]
                      [--pmin DBAR] [--pmax DBAR] [-o DIR] [--report-dir DIR]
                      [--sig-level SIG [SIG ...]]
                      mooring

Positional Arguments

mooring: Mooring name, e.g. dsG3_1_2026

Named Arguments

--raw-dir

Cruise-level raw data directory (pipeline appends /{mooring}/). Required for stage 1.

--proc-dir

Cruise-level processed output directory (pipeline appends /{mooring}/).

--force

Overwrite existing files at every stage

Default: False

--serial

Restrict to these serial number(s) for processing and per-instrument reports

Default: []

--dt

Stack time-grid interval in seconds (default: 60)

Default: 60

--dp

Pressure grid spacing in dbar (default: 20)

Default: 20.0

--pmin

Shallowest pressure level for grid (default: 200)

Default: 200.0

--pmax

Deepest pressure level for grid (default: 1000)

Default: 1000.0

-o, --output-dir

Directory for the HTML report (default: {proc-dir}/{mooring}/report/)

--report-dir

Central directory for all mooring reports. Each mooring’s pages are written to DIR/{mooring}/ instead of proc/{mooring}/report/, making the whole report tree portable.

--sig-level

σ₀ target values (kg m⁻³, referenced to 0 dbar) for isopycnal height-above-seabed tracking in the grid report. Pass one or more values; they are sorted before use. Example: –sig-level 27.5 27.7 27.9 (default: 27.7).

Output created

All stage NC files, {mooring}_stack.nc, {mooring}_grid.nc, mooring summary report, stack report, grid report, and per-instrument reports.

Example

oceanarray run dsG3_1_2026 --raw-dir /data/raw --proc-dir /data/proc --force

`oceanarray list`

Print a reference table of allowed instrument: and file_type: values for mooring YAML configuration. Use this to look up the correct reader name for a given instrument type, or to check which instrument: values are recognised.

Does not require a mooring name, --raw-dir, or --proc-dir.

usage: oceanarray list [-h] [{instruments,file-types}]

Positional Arguments

topic

Possible choices: instruments, file-types

Filter output: ‘instruments’ or ‘file-types’ (default: show both).

Example

oceanarray list

Preliminary visualisation commands

The following commands produce standalone plots and animations. They are available for quick inspection but are considered preliminary — the output style, variable names, and flag set may change in a future release.

`oceanarray plot`

Show an interactive overview plot of processed data, or save it to a file.

usage: oceanarray plot [-h] [--proc-dir DIR] [--var_y VAR_Y]
                       [--var_color VAR_COLOR] [--colormap COLORMAP]
                       [--markersize PTS2] [--downsample SECONDS]
                       [--output FILENAME] [-o DIR] [--show]
                       mooring

Positional Arguments

mooring: Mooring name, e.g. dsG3_1_2026

Named Arguments

--proc-dir

Cruise-level processed output directory (pipeline appends /{mooring}/).

--var_y

Variable on y-axis (default: temperature)

Default: 'temperature'

--var_color

Variable for scatter colour; omit for line plot

--colormap

Matplotlib colormap (default: RdBu_r)

--markersize

Scatter marker size in points² (default 4). Only used in scatter mode.

--downsample

Resample interval in seconds (default: 120)

--output

Base filename for saved figure (e.g. overview.png); combined with –output-dir if given

-o, --output-dir

Directory for saved figure (default: mooring proc dir)

--show

Display the figure interactively (works alongside –output)

Default: False

Example

oceanarray plot dsG3_1_2026 --proc-dir /data/proc --var_y pressure --var_color temperature --output overview.png

`oceanarray animate`

Generate an animated hodograph (tip of the velocity vector tracing a path over time) for Aquadopp or ADCP instruments. Requires east_velocity and north_velocity in the stage 3 output. The Pillow library must be installed for GIF output.

usage: oceanarray animate [-h] [--proc-dir DIR] [--serial SN [SN ...]]
                          [-o FILE] [--u-var VAR] [--v-var VAR]
                          [--lp-days DAYS] [--smooth-hours HOURS]
                          [--frame-hours HOURS] [--fps FPS] [--dpi DPI]
                          mooring

Positional Arguments

mooring: Mooring name, e.g. dsG2_1_2026

Named Arguments

--proc-dir

Cruise-level processed output directory (pipeline appends /{mooring}/).

--serial

Serial number(s) to animate (default: all instruments with velocity data)

Default: []

-o, --output

Output GIF path (only used when a single –serial is given; default: {stem}_hodograph.gif next to the NC file)

--u-var

Eastward velocity variable name (default: east_velocity)

Default: 'east_velocity'

--v-var

Northward velocity variable name (default: north_velocity)

Default: 'north_velocity'

--lp-days

Low-pass window for eddy-component removal in days (default: 4.0)

Default: 4.0

--smooth-hours

Tukey smoothing window in hours applied to both panels (default: 3.0)

Default: 3.0

--frame-hours

Time step between frames in hours (default: 6.0 → one frame per quarter-day of deployment)

Default: 6.0

--fps

Frames per second in the output GIF (default: 20)

Default: 20

--dpi

Resolution of each frame in dots per inch (default: 100)

Default: 100

Example

oceanarray animate dsG3_1_2026 --proc-dir /data/proc --serial 400115 -o dsG3_400115_hodograph.gif

Deprecated flags

`--basedir DIR` (removed)

The --basedir flag has been removed. Passing it prints a migration message naming the replacement and exits without processing. Use --raw-dir and --proc-dir with the mooring-first layout instead.

See Migrating from the --basedir Layout for step-by-step migration instructions.

CLI Reference

oceanarray validate

Positional Arguments

oceanarray init

Positional Arguments

Named Arguments

oceanarray process

Positional Arguments

Named Arguments

oceanarray report

Positional Arguments

Named Arguments

oceanarray run

Positional Arguments

Named Arguments

oceanarray list

Positional Arguments

Preliminary visualisation commands

oceanarray plot

Positional Arguments

Named Arguments

oceanarray animate

Positional Arguments

Named Arguments

Deprecated flags

--basedir DIR (removed)

`oceanarray validate`

`oceanarray init`

`oceanarray process`

`oceanarray report`

`oceanarray run`

`oceanarray list`

`oceanarray plot`

`oceanarray animate`

`--basedir DIR` (removed)