config.yaml
data block
Every path in this block is either an input ctdcast only reads, or an output root ctdcast owns and writes into. The distinction is worth holding onto, because only the second kind is safe to delete and regenerate:
Inputs — read, never written |
|
|---|---|
Output roots — created and written by ctdcast |
|
A cruise’s raw CTD input is either its CNV files (cnv_dir) or its raw SBE 911plus
.hex files (hex_dir), never both: ctd_raw_format names which one stage 1
reads, so a stray directory never changes what a cruise is read from.
Key |
Required |
Description |
|---|---|---|
|
yes |
The CTD root ctdcast owns. It holds |
|
no |
The same for LADCP: |
|
no |
Directory of calibrated CNV files, one per cast — an input ctdcast only
reads. Stage 1 needs |
|
no |
Directory of raw SBE 911plus |
|
no |
|
|
no |
Directory of processed LADCP |
|
no |
Path to the cast-groupings file (conventionally |
|
no |
Override for the compiled profiles path. Derived as
|
|
no |
Override for the compiled LADCP path, derived as
|
|
no |
LADCP file names when they are not |
|
no |
Path to a GEBCO NetCDF bathymetry file, for the report maps. Maps render without
bathymetry if this is omitted or the file is not found — not an error. The
profiles compile reads bathymetry only from |
|
no |
A ship-track netCDF, drawn as the background line on the interactive map. |
|
no |
Superseded spelling of |
|
no |
Superseded spelling of |
output block
Key |
Required |
Description |
|---|---|---|
|
yes |
Directory where all HTML output is written. Created if it does not exist. |
generate block
Key |
Default |
Description |
|---|---|---|
|
|
Generate per-cast station pages. |
|
|
Generate transect section pages. Requires a compiled |
|
|
Generate a time-series page per group in |
|
|
Generate the cruise-wide pages: |
|
|
Generate the interactive Leaflet map page. |
force (rebuild every page even when it is up to date) is a top-level config
key, not part of the generate block; it defaults to false, and --force on the
command line turns it on.
display block
How the report figures look. Every key is optional.
Key |
Default |
Description |
|---|---|---|
|
|
Section fields drawn as cells ( |
|
|
The same for the time-series pages. |
|
from the data |
Colorbar limits per variable, for when an outlier dominates the auto-scale. Keyed
by the variable the panel draws: |
|
per variable |
Colormap per variable (a matplotlib or cmocean name), merged over the defaults:
|
|
|
Shape of the summary page’s overview panels, |
|
|
Hide the top and right axis lines on the profile, section, time-series and LADCP panels. |
display:
section_style: contourf
vmin:
ctd_oxygen: 200.0 # umol/kg
conservative_temperature: 3.0
vmax:
ctd_oxygen: 300.0
conservative_temperature: 10.0
var_cmaps:
ctd_turbidity: cmo.turbid
Map extent is set in cruise_info (map_lat_min, map_lat_max, map_lon_min,
map_lon_max); see Cruise metadata (cruise_info).
Processing settings (optional)
Five top-level blocks set how the pipeline treats the data, each by what it does, plus a small
processing: block for the stage-2 trim and the profiles grid. Every key is optional and falls
back to a built-in default.
preferred_sensor: # which sensor the plain ctd_temperature / ctd_salinity / ctd_oxygen use
tc: primary
oxygen: primary
clock: {...} # stage-2 acquisition-clock correction, from `ctdcast clock`
qc: {...} # stage-3 gross-range and spike tests
fit: {...} # how `ctdcast fit` searches; nothing here is applied
data_processing: # what ctdcast applies to the data at stage 3
slope_offset: {...}
oxygen: {...}
steps: [...]
processing:
trim: {...}
profiles_dbar: 1
From the 0.4 layout. Everything used to sit under processing:. processing.preferred_pair /
preferred_oxygen, processing.clock, processing.qc and
processing.calibration.conductivity_slope are still read, with a deprecation warning, until the
release after this one; the slope then applies to both sensors with offset 0. Ranges in a
preferred-sensor declaration now take value: (use: is read with a warning).
data_processing block
What stage 3 applies, after stage 2’s soak and deck flags. ctdcast inspect <file>.cnv prints the
block that reproduces a cruise’s own Sea-Bird processing; ctdcast fit suggests the alignctd and
celltm values.
Key |
Description |
|---|---|
|
Per conductivity sensor, |
|
Window (s) for the SBE 43 tau correction’s dV/dt when stage 3 derives |
|
The processing steps, run in the order listed; a step may appear more than once. Each entry is one step name with its parameters. A step is applied only if it is listed. |
|
Files made from the stage-3 data by further steps, each |
The steps, as Sea-Bird names its modules:
Step |
Parameters |
|---|---|
|
|
|
Seconds to advance a channel relative to pressure, as Sea-Bird’s Align CTD. Channels:
|
|
Cell thermal mass correction of conductivity, |
|
Sea-Bird’s low-pass filter, run forward and backward (no lag): |
|
|
|
Marks whole scans where the package reversed, moved slower than |
|
Product only: |
|
Product only, and last: |
Alignment, cell thermal mass, Filter, Window Filter, Loop Edit and the oxygen derivation act scan
by scan, so they run only on a cast at its instrument’s native scan rate (24 Hz on a 911plus) that
Sea-Bird has not already processed the same way. Any other cast skips them with a warning and a
history note, and still gets the slope, salinity and QC. Wild Edit skips a cast Sea-Bird’s own
Wild Edit already ran on, but does not yet check the scan rate.
The stage-3 file records the order the steps ran in (data_processing_steps) and, on each
variable, what each step did to it.
data_processing:
slope_offset:
conductivity_1: {slope: 1.0000452, offset: 0.0}
conductivity_2: # a sensor swapped at cast 7
default: {slope: 0.9999368}
ranges:
- casts: [[1, 6]]
value: {slope: 1.0000120}
steps:
- wildedit:
pass1_nstd: 2.0
pass2_nstd: 20.0
scans_per_block: 100
variables: [pressure, ctd_temperature_1, conductivity_1, ctd_temperature_2, conductivity_2]
- alignctd:
conductivity: -0.015 # bare value: seconds for every cast (the usual case)
conductivity_2: # a sensor swapped at cast 7: its own value from there on
default: -0.040
ranges:
- casts: [[1, 6]]
value: -0.015
- celltm:
conductivity: {alpha: 0.0275, tau: 6.5}
- loopedit: {min_velocity: 0.25, surface_soak: {min_depth: 5, max_depth: 20, deck_pressure: true}}
products:
- name: 1dbar_down
steps:
- split: down
- binavg: {bin: decibars, size: 1}
- name: 1sec
steps:
- binavg: {bin: seconds, size: 1}
qc, clock and fit blocks
Key |
Description |
|---|---|
|
Stage-3 gross-range bounds |
|
Stage-3 spike thresholds on |
|
Stage-2 acquisition-clock correction: a list of
|
|
|
qc:
gross_range:
suspect: { ctd_salinity_1: [30.0, 38.0] } # tighten for a cruise
fail: { ctd_salinity_1: [0.0, 42.0] }
spike:
suspect: { pressure: 10.0 } # dbar
fail: { pressure: 50.0 }
clock: # from `ctdcast clock config.yaml`
segments: # one entry per segment found
- casts: [[1, 3]]
clock_offset_seconds: 4.33
n_casts: 3 # the evidence for the offset
clock_offset_sd_seconds: 0.47
- casts: [[4, 182]]
clock_offset_seconds: 7.76
n_casts: 179
clock_offset_sd_seconds: 0.57
processing block
Key |
Description |
|---|---|
|
Vertical bin size (dbar) for the compiled |
|
Pressure threshold for stage-2 soak detection (dbar). Default |
|
Stage-2 curated drop: the list of SeaBird-derived |
Preferred sensor
A dual-sensor cast records both a primary (_1) and a secondary (_2) channel; which is the
better one is a judgement about noise that only the operator can make. Declare it cruise-wide with
per-cast exceptions. tc is the temperature/conductivity pair (and the salinity derived from it);
stage 3 builds the plain ctd_temperature / ctd_salinity / conductivity (and, for
oxygen, ctd_oxygen) as a per-cast copy of the selected channel and records the chosen sensor in
sensor_<role>_preferred.
preferred_sensor:
tc: # temperature + conductivity + salinity move together
default: primary # cruise-wide; "primary" | "secondary"
ranges: # exceptions by cast number; [[first, last]] inclusive
- casts: [[31, 60]]
value: secondary
oxygen: # independent oxygen choice, same grammar
default: primary
ranges:
- casts: [[15, 15]] # a single-cast range is valid
value: secondary
Notes:
Values are exactly
primary/secondary— a digit or any other spelling is refused at stage 3 (a clear error, not a silent guess). A single-sensor cast has no choice and is left untouched; an undeclared dual cast gets no plain name (never a silent_1).castsneeds an explicit last number (no open-ended range). So declare the latest / ongoing configuration as the unboundeddefaultand the earlier casts as explicitranges— then the config need not be edited as new casts are added.Declaring one, both, or neither is valid, and
oxygenmay differ fromtc. An explicit range naming a channel a single-sensor cast lacks is an error; a default that lands on a single-sensor cast is silently skipped.Where the per-cast serials of a declared range do not match where the hardware actually changed, the compile and
ctdcast validatewarn (never block) — reconcile the range with the sensor-change log on the cast page.
sensors block (optional)
Per-cruise sensor provenance that the CNV header cannot supply: sensors it cannot
identify (the altimeter and user-polynomial channels carry no make/model) and
model refinements (a combined FLNTU(RT)D reads as a generic fluorometer plus
turbidity from its SensorID alone). The universal SensorID → model table ships
in ctdcast/config/sbe_sensors.yaml; this block adds only what is
cruise-specific. Overrides are keyed by role (not SensorID, which the newer
Sea-Bird XML drops); use role:serial only to disambiguate two different-model
devices in one role.
sensors:
overrides:
altimeter: # SensorID 0 records no make/model
sensor_model: "Benthos PSA-916T"
sensor_model_vocabulary: "https://vocab.nerc.ac.uk/collection/L22/current/TOOL0134/"
sensor_maker: "Teledyne Benthos"
model_source: operator
fluorometer: # sharpen the generic default to the combined unit
sensor_model: "WET Labs ECO FLNTU(RT)D"
sensor_model_vocabulary: "https://vocab.nerc.ac.uk/collection/L22/current/TOOL1531/"
model_source: operator
turbidity:
sensor_model: "WET Labs ECO FLNTU(RT)D"
sensor_model_vocabulary: "https://vocab.nerc.ac.uk/collection/L22/current/TOOL1531/"
model_source: operator
aliases:
# the value is the canonical serial spelling and becomes the catalog entry
# name, so both recorded spellings fold onto SENSOR_FLUOROMETER_3508 /
# SENSOR_TURBIDITY_3508 rather than the long ..._FLNTURTD_3508 names
"FLNTURTD-3508": "3508"
Roles: temperature_1/_2, conductivity_1/_2, oxygen_1/_2,
pressure, fluorometer, turbidity, transmissometer, ph,
altimeter. A sensor left unresolved (no override, and the SensorID gives no
model) is recorded with sensor_model: "UNK" and a build-time warning —
ctdcast never guesses a model.
Example
data:
ctd_root: /data/cruise/CTD/ctd_nc # stage1/…stage3/, products/, profiles.nc
ladcp_root: /data/cruise/LADCP/ladcp_nc
hex_dir: /data/cruise/CTD/raw # input: .hex + .xmlcon
ladcp_dir: /data/cruise/LADCP/mat # input: processed .mat
groupings_yaml: /data/cruise/config/ctd_groupings.yaml
gebco_nc: /data/GEBCO_2025.nc
output:
dir: /data/cruise/report
generate:
stations: true
sections: true
timeseries: true
force: false # top level, not under generate