CLI reference

All subcommands are available via the ctdcast entry point. Run ctdcast <command> --help for the full flag list at any time.

ctdcast draft

Quick-look pipeline: convert raw CNV files to station pages + index + map in one step. No config.yaml required. Sections and time series are skipped (require profiles.nc).

ctdcast draft <cnv_dir> [out_dir] [options]

positional arguments:
  cnv_dir          Directory of raw SBE CNV files (required)
  out_dir          Output directory (default: ./ctd_draft/)

options:
  --cruise ID      Cruise ID shown in the report header
                   (default: read from nc file attrs, fallback 'draft')
  --ship NAME      Ship name shown in the report header
  --keep-nc DIR    Save converted netCDF files to DIR instead of discarding after the run
  --force          Regenerate existing pages regardless of modification times
  --dry-run        Print what would be done without writing any files

Requires seasenselib (pip install seasenselib) for CNV conversion.

Examples:

ctdcast draft /data/cnv/
ctdcast draft /data/cnv/ ./out/ --cruise odb2026 --ship RRS_Discovery
ctdcast draft /data/cnv/ --keep-nc ./nc_out/ --force
ctdcast draft /data/cnv/ --dry-run

ctdcast init

Write a commented template config.yaml (and optionally auto-detect sections/timeseries groups from profiles.nc) in the target directory.

ctdcast init [dest] [options]

positional arguments:
  dest                  Destination directory or explicit .yaml path (default: .)

options:
  --sections            Also write a template ctd_sections.yaml
  --interactive         Prompt for all data paths and cruise metadata,
                        then offer to auto-detect sections/timeseries
  --auto-section        Re-run section/timeseries detection from an existing
                        config and overwrite ctd_sections_draft.yaml.
                        Reads profiles_nc from the config; does not touch config.yaml.
  --force               Overwrite existing files

detection thresholds (used with --interactive or --auto-section):
  --dx-diameter KM      Max inter-cast distance (km) within a repeat-station cluster (default: 1)
  --dx-section KM       Inter-cast gap (km) that starts a new coarse group (default: 50)
  --max-turn-deg DEG    Max heading change (°) within a directional run (default: 45)
  --min-run-casts N     Min casts for a run to be kept as a section (default: 4, min: 3)
  --max-section-casts N Safety cap: split runs longer than this (default: 25)

Detection algorithm (--interactive / --auto-section):

Coarse gap split on inter-cast distance > --dx-section.
Within each coarse group, find maximal sub-sequences where every consecutive heading change ≤ --max-turn-deg (stable-heading run detection). A backward-extension step adds the “approach station” when the ship arrives at the first section station from the section’s bearing direction.
Remaining unclaimed casts are clustered by proximity: consecutive unclaimed casts within --dx-diameter of each other form a repeat-station cluster.
Classification is by detection method: stable-heading runs → sections; diameter clusters → timeseries.
Runs > --max-section-casts are split into consecutive chunks.

Output is ctd_sections_draft.yaml (alongside section_yaml from the config, or in the config’s directory). Review and rename to ctd_sections.yaml before use.

Examples:

ctdcast init                          # write config.yaml in current directory
ctdcast init /data/cruise/
ctdcast init --sections               # also write a template ctd_sections.yaml
ctdcast init --interactive config.yaml --force   # guided setup with auto-detection
ctdcast init --auto-section config.yaml --force  # re-detect sections only

ctdcast validate

Validate config paths and data before the first run. Does not write any files.

ctdcast validate <config> [options]

positional arguments:
  config           Path to config.yaml

options:
  --strict         Also check that all cast numbers referenced in
                   ctd_sections.yaml are present in nc_dir

Examples:

ctdcast validate config.yaml
ctdcast validate config.yaml --strict

ctdcast process

Run one or more pipeline stages, across every configured data source. A stage runs for whichever sources are configured: with both CTD and LADCP paths set, --stage 1 ingests both (CNV → nc and .mat → nc) and --stage profiles compiles both (profiles.nc and ladcp_profiles.nc). A source whose paths are absent is silently skipped.

ctdcast process <config> --stage {1,2,3,profiles} [more] [options]

positional arguments:
  config           Path to config.yaml

required:
  --stage ...      One or more of: 1, 2, 3, profiles.  Multiple values run in
                   canonical order (1 → 2 → 3 → profiles) regardless of the
                   order given.

options:
  --only N         Restrict cast-scope stages (1, 2, 3) to cast N
  --force          Overwrite existing output files
  --dry-run        Print what would be done without writing any files
  --gebco NC       GEBCO bathymetry for the profiles stage

Stage 1 ingests raw files to per-cast netCDF; stages 2 and 3 apply CTD soak/deck flagging and QC/calibration (LADCP has no stage 2 or 3); profiles compiles the per-cast files into the gridded products.

Examples:

ctdcast process config.yaml --stage 1                # ingest CTD + LADCP
ctdcast process config.yaml --stage 1 2 3 profiles   # full pipeline
ctdcast process config.yaml --stage profiles         # compile products only
ctdcast process config.yaml --stage 1 --only 42      # re-ingest one cast

ctdcast convert (deprecated)

Note

ctdcast convert is deprecated — use ctdcast process --stage .... convert --ctd → process --stage 1; convert --profiles → process --stage profiles; convert --ladcp → process --stage 1 profiles. The command still runs, with a notice.

Convert raw data to netCDF inputs without generating HTML.

ctdcast convert <config> [options]

positional arguments:
  config           Path to config.yaml

step selection (default: --profiles only if data.profiles_nc is configured):
  --ctd            Convert per-cast CNV files to netCDF (requires data.cnv_dir in config)
  --profiles       Compile per-cast netCDF files into profiles.nc

options:
  --backend NAME   CTD conversion backend (currently only 'seasenselib')
  --only N         Convert only cast N (implies --ctd)
  --force          Overwrite existing output files
  --dry-run        Print what would be done without writing any files

(The former ``--cast`` spelling still works as a deprecated alias for ``--only``.)

Examples:

ctdcast convert config.yaml                  # build profiles.nc (default)
ctdcast convert config.yaml --ctd            # CNV → nc, then profiles.nc
ctdcast convert config.yaml --profiles       # rebuild profiles.nc only
ctdcast convert config.yaml --ctd --only 42  # convert one cast
ctdcast convert config.yaml --dry-run

ctdcast report

Generate HTML pages from existing netCDF inputs. Does not run any conversion.

ctdcast report <config> [options]

positional arguments:
  config           Path to config.yaml

page selection (default: all page types enabled in config):
  --casts          Generate per-cast pages
  --sections       Generate section pages (requires profiles.nc and section_yaml)
  --timeseries     Generate timeseries pages (requires profiles.nc and section_yaml)
  --index          Generate index.html and casts.html
  --map            Generate leaflet.html interactive map
  --all            Generate every page type

options:
  --only N [N ...] Regenerate only the pages for cast N (one or more)
  --force          Regenerate all pages regardless of modification times
  --skip-existing  Skip pages whose HTML already exists (fill missing pages only)
  --dry-run        Print what would be done without writing any files

The process exits non-zero if any requested page fails to build.
The former ``--stations`` and ``--cast`` spellings still work as hidden,
deprecated aliases for ``--casts`` and ``--only``; they emit a warning.

Examples:

ctdcast report config.yaml                   # generate all enabled page types
ctdcast report config.yaml --casts           # cast pages only
ctdcast report config.yaml --only 42 --force # rebuild one cast page
ctdcast report config.yaml --skip-existing   # fill any missing pages
ctdcast report config.yaml --dry-run

ctdcast run

Run the processing pipeline then the reports in one step (most common workflow).

ctdcast run <config> [options]

positional arguments:
  config           Path to config.yaml

options:
  --stage ...      Stage(s) to run before reporting, across every configured
                   source (default: all — 1 2 3 profiles). E.g. --stage profiles
                   to only compile and report.
  --only N [N ...] Process only these cast(s): cast-scope stages (1 2 3) run for
                   them and only their pages rebuild; profiles is skipped
  --force          Force regeneration of all outputs regardless of modification times
  --skip-existing  Skip pages whose HTML already exists
  --dry-run        Print what would be done without writing any files

Equivalent to ctdcast process --stage ... then ctdcast report. run is the recommended everyday command: by default it runs every stage (ingest → QC → compile) across every configured source, then builds the HTML — so it works from raw on a fresh checkout. Narrow with --stage when you do not want the full pipeline (--stage profiles compiles and reports without re-ingesting raw). Use report when the compiled products are already current and you only want to regenerate pages. (The former --cast spelling is a deprecated alias for --only; the former --ctd flag is deprecated — run now ingests raw by default.)

Examples:

ctdcast run config.yaml                      # full pipeline (all stages) + reports
ctdcast run config.yaml --stage profiles     # compile + report only (skip ingest)
ctdcast run config.yaml --stage 1 profiles   # ingest + compile + report (skip QC)
ctdcast run config.yaml --force              # rebuild everything
ctdcast run config.yaml --only 42            # reprocess + rebuild one cast page
ctdcast run config.yaml --dry-run