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: read CNV files (stage 1), compile profiles.nc, and build the cast pages, index,
map, sensors and processing pages in one step. No config.yaml required. No section or
time-series pages are built (their index pages are empty): they need a groupings file saying
which casts belong together.
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: the files' cruise attribute, else UNKCRUISE)
--ship NAME Ship name shown in the report header
--keep-nc DIR Save converted netCDF files to DIR instead of discarding after the run
--pattern GLOB Filename glob selecting CNV files within cnv_dir (default: '*.cnv')
--sal MIN MAX Salinity range for plot trimming: records whose salinity
(ctd_salinity, else ctd_salinity_1) is outside it are left out
of the cast-page plots
--trim-soak Leave the surface soak and back-on-deck records out of the
cast-page plots, with stage 2's default rules (last scan above
10 dbar before the descent, searched back 20 s; the deck from
the pressure of the last 20 s; processing.trim is not read)
(both plotting filters only; the netCDF files are not changed)
--force Regenerate existing pages regardless of modification times
--dry-run Print what would be done without writing any files
Requires seasenselib for CNV conversion (pip install "ctdcast[cnv]").
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 inspect
Render a data-inventory page for a single netCDF file — every variable with its
dimensions, units and attributes — or print a Sea-Bird CNV’s processing steps (below). No config.yaml required. Useful for checking
what a stage actually wrote — which QC flags are present, whether an attribute
survived a stage, what the compiled product contains.
ctdcast inspect <nc_file> [options]
positional arguments:
nc_file The netCDF file to inventory, or a .cnv
options:
-o, --out PATH Output HTML path
(default: <nc_file stem>_inventory.html, beside the input)
--title TEXT Page title (default: the file name)
Unlike ctdcast clock, which is cruise-scope and reads every stage-1 file, this
looks at one file and writes one page.
Examples:
ctdcast inspect /data/ctd_nc/stage1/msm_142_1_001_stage1.nc
ctdcast inspect /data/ctd_nc/profiles.nc -o profiles_inventory.html
ctdcast inspect /data/ctd_nc/profiles.nc --title "MSM142 compiled product"
A Sea-Bird CNV. Given a .cnv, inspect reads the SBE Data Processing steps from
its header instead and prints the equivalent data_processing: block: the modules in the
order they ran, each with its parameters and ctdcast’s variable names, ready to paste into
config.yaml. Modules that are not ctdcast steps (datcnv, Derive) are listed as
comments. Nothing is written beside the CNV; with -o, the block is also written as a page
with a copy button, followed by each module’s fields as the header records them:
ctdcast inspect /data/cnv_24Hz/mixsed2_017.cnv
ctdcast inspect /data/cnv_24Hz/mixsed2_017.cnv -o mixsed2_017_processing.html
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_groupings.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 write ctd_groupings_draft.yaml (an existing
draft is overwritten with --force, or after asking in a
terminal). Reads
<ctd_root>/profiles.nc, or data.profiles_nc when set;
does not touch config.yaml.
--force Overwrite existing files
detection thresholds (used only with --interactive or --auto-section; ignored otherwise):
--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-diameterof each other form a repeat-station cluster.Classification is by detection method: stable-heading runs → sections; diameter clusters → timeseries.
Runs >
--max-section-castsare split into consecutive chunks.
Output is ctd_groupings_draft.yaml (alongside groupings_yaml from the
config, or in the config’s directory). Review and rename to
ctd_groupings.yaml before use.
Examples:
ctdcast init # write config.yaml in current directory
ctdcast init /data/cruise/
ctdcast init --sections # also write a template ctd_groupings.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
Check a config and the files it names before the first run: the YAML, the output folder
(created if missing), the stage root and profiles.nc (warnings when absent), and the
groupings file. It does not check the raw input folders (hex_dir, cnv_dir,
ladcp_dir).
ctdcast validate <config> [options]
positional arguments:
config Path to config.yaml
options:
--strict Also check that every cast number the sections in
ctd_groupings.yaml name is present in ctd_root
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 (.hex or 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 [N ...] Restrict cast-scope stages (1, 2, 3) to these casts
--force Rebuild every stage file, even when it is up to date
--dry-run Print what would be done without writing any files
--gebco NC GEBCO netCDF for the water depth at each cast in profiles.nc
(data.gebco_nc is not read by this stage)
--backend NAME CNV reader (default: seasenselib); a hex_dir cruise reads .hex
--pattern GLOB Filename glob for CNV files (default: from config, else '*.cnv');
not used for .hex
(The former --cast spelling still works as a deprecated alias for --only.)
stage 2 trim tuning (all optional; the defaults are the documented behaviour):
--near-surface-dbar D Pressure threshold for the last near-surface crossing
(default: 10 dbar)
--search-seconds S Backward-crawl window for the pre-descent surface minimum
(default: 20 s)
--deck-window-seconds S Tail window for the on-deck reference pressure estimate
(default: 20 s)
--margin-dbar D Added to the on-deck median to form the cut threshold
(default: 0.5 dbar)
--max-deck-dbar D If the on-deck median exceeds this, no end-trim is applied
(default: 20 dbar)
A trim flag overrides the corresponding processing.trim key in the config for that
run only; nothing is written back. Use them to test a threshold before committing it
to the config.
Stage 1 reads the raw .hex or CNV files to per-cast netCDF; stage 2 flags the soak and
deck records and applies the clock block; stage 3 applies the conductivity slope and offset,
the data_processing steps, salinity, SBE 43 oxygen and QC, then makes the products (LADCP
has no stage 2 or 3); profiles compiles the per-cast files into the gridded files. A
stage-1 file is read only when it is missing (--force reads a replaced raw file again); a
stage-2 or stage-3 file, or profiles.nc, is rebuilt when its input is newer.
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 and will be removed in 0.5.0 — 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, but it is not
the same: on a config with only ctd_root (no data.profiles_nc) it may do
nothing, and --ctd does not stamp cruise_info or the sensor overrides.
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
--ladcp Convert LADCP .mat files and compile ladcp_profiles.nc
options:
--backend NAME CTD conversion backend (currently only 'seasenselib')
--pattern GLOB Filename glob for CNV files (default: '*.cnv'); --ctd only
--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 (no 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 groupings_yaml)
--timeseries Generate timeseries pages (requires profiles.nc and groupings_yaml)
--index Generate the cruise-wide pages: index, casts, sections and
timeseries index pages, each compiled file's inventory, SBE
sensors, processing, and T/S corrections when fits.nc exists
--map Generate leaflet.html interactive map
--all Generate every page type
options:
--only N [N ...] Regenerate only these casts' pages (no other page type)
--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
plotting (affect the figures only; no netCDF file is modified):
--sal MIN MAX Salinity range for plot trimming: records whose salinity
(ctd_salinity, else ctd_salinity_1) is outside it are left out
of the cast-page plots
--trim-soak Leave the surface soak and back-on-deck records out of the
cast-page plots, with stage 2's default rules (last scan above
10 dbar before the descent, searched back 20 s; the deck from
the pressure of the last 20 s; processing.trim is not read)
--dbar-step N Plot every Nth pressure level from profiles.nc in section and
timeseries figures (default: 1, every level). This thins the
plot, not the data; the grid is set by processing.profiles_dbar
--drop-stub Drop cast-page sections whose figures all failed to render.
By default such a section stays visible as a warning, so a
failed figure is noticed rather than silently absent
A cast, section or time-series page is rebuilt only when the files it is drawn
from are newer, so --sal, --trim-soak and --drop-stub change an up-to-date page
only with --force; the cruise-wide pages are rebuilt on every run. A top-level
force: true in the config does the same as --force.
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
--trim-soak Leave the soak and deck records out of the cast-page plots (see
``report --trim-soak``)
Runs ctdcast process --stage ... and 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
ctdcast clock
Diagnose the acquisition-clock error for a cruise. Each SBE cast records two
clocks in its header — the acquisition PC’s System clock and the GPS-derived NMEA
clock — and their difference is the offset by which the recorded time may be
wrong. clock reads that pair off every stage-1 cast, classifies the cruise,
and prints a verdict, the coordinate-source line, a per-segment table, and a
paste-ready clock block. It writes nothing — applying a correction
is a separate stage-2 step.
ctdcast clock <config> [options]
positional arguments:
config Path to config.yaml (the CTD root is read from data.ctd_root)
options:
-f, --figure PNG Also write the offset-vs-cast figure to this path
The verdict is one of constant, step (one row per level, a changepoint at
each boundary), drift (only when a rate positively fits — the note quotes
slope, R² and residual sd), no_clock_pair or insufficient. The
coordinate-source line is orthogonal to the verdict: a cruise can show a real
offset yet need no correction because its time coordinate was already anchored
to GPS. The suggested block is shown only when the coordinate is on the System
clock, and its sign is emitted as a comment so it is copied, never hand-computed.
Examples:
ctdcast clock config.yaml # print the verdict + suggested config
ctdcast clock config.yaml --figure clock.png # also write the offset-vs-cast figure
ctdcast fit
Suggest conductivity-alignment and cell-thermal-mass parameters for a cruise. fit reads every
native-rate stage-2 cast, scores each conductivity line’s salinity-spike cost (alignment) and
down/up salinity-mismatch cost (cell thermal mass), writes the per-cast cost surfaces to
<ctd_root>/fits.nc, and prints a paste-ready data_processing: block with the recommended
alignctd and celltm values. It writes no stage file — the values reach stage 3 only when
you paste them into the config. ctdcast report draws the T/S corrections page from
fits.nc.
ctdcast fit <config> [options]
positional arguments:
config Path to config.yaml (the CTD root is read from data.ctd_root, or data.nc_dir)
options:
--only N [N ...] Fit only these cast number(s)
--dry-run List the casts that would be fitted, write nothing
The recommended (alpha, tau) is the grid point within fit.ctm_tolerance (default
2%) of the cost minimum closest to Sea-Bird’s default (0.03, 7 s); any value within the tolerance is
equivalent. A cast at a non-native scan rate, or one Sea-Bird already aligned or ran cell thermal
mass on, is reported as not fitted and left out. Tune the finder (cost windows, tolerance, block
size) with the fit block (see config.yaml).
Examples:
ctdcast fit config.yaml # print the suggested data_processing: block
ctdcast fit config.yaml --only 11 12 # just two casts
ctdcast fit config.yaml --dry-run # list what would be fitted
ctdcast list
Show what the institution, platform and role registries hold, so you do not have to
open a YAML file inside site-packages to find a slug.
ctdcast list {institutions|platforms|roles} [CONFIG] [options]
positional arguments:
registry Which registry to list; omit to see the three names.
config Optional config.yaml — also shows what this cruise adds.
options:
--search TEXT Case-insensitive filter across slug and name.
--vocabulary N For `roles`: show one vocabulary only (C89, G04, C59, W08).
Give a CONFIG to see what your cruise adds on top of the shipped defaults: a
cruise_info.institutions_file and inline cruise_info.institutions entries, and an
inline cruise_info.platform vessel. The Source column says where each entry came
from (packaged, user, the config file, or inline), so you can tell “my entry did
not load” from “you did not give me a config”. list platforms also prints the
ambiguous_slugs and forbidden_codes traps with the reason each is refused; list
roles groups the four vocabularies by axis (person vs institution) and marks each axis’s
default.
Examples:
ctdcast list # the three registries
ctdcast list institutions config.yaml # shipped + user + this config's entries
ctdcast list platforms --search meteor # filter by slug or name
ctdcast list roles --vocabulary W08 # one vocabulary