Quickstart guide
This guide takes a cruise’s CTD data from the raw files to a report.
Two workflows are available: a quick look that needs only CNV files and no configuration,
and the full workflow — raw .hex or .cnv through every processing stage, with
sections, time series, LADCP panels and the processing record.
Quick look (no config file needed)
If you have SBE CNV files and want cast pages, an index and a map immediately:
pip install "ctdcast[cnv]"
ctdcast draft /path/to/cnv/ # output → ./ctd_draft/
ctdcast draft /path/to/cnv/ ./out/ --cruise odb2026 # with cruise ID and output dir
ctdcast draft /path/to/cnv/ --dry-run # preview without writing
ctdcast draft reads the CNV files to netCDF (stage 1), compiles profiles.nc and
builds the cast pages, the index, the map, the sensors page and the processing page in one
step. No config.yaml is needed. It builds no section or time-series pages (their index
pages are empty): those need a groupings file that says which casts belong together; for
those, use the full workflow below.
Full workflow prerequisites
Python 3.11–3.14 is required. Install from PyPI into a virtual environment:
python -m venv venv
source venv/bin/activate # macOS / Linux
pip install ctdcast # reads .hex; add [cnv] to read .cnv
or from source, which also gives you the demo:
git clone https://github.com/ocean-uhh/ctdcast
cd ctdcast
python -m venv venv
source venv/bin/activate # macOS / Linux
pip install -e .
Land coastlines on the interactive maps need the optional maps extra (cartopy and
shapely): pip install -e ".[maps]". Without it the maps draw over a lat/lon graticule.
To check a source checkout, build a demo report from the committed fixture casts. They are
stage-1 files: --stage profiles compiles and reports them without running stages 2 and 3
(which would write into the fixtures), and the compiled file goes to a work folder
(demo_work/):
ctdcast run config_demo.yaml --stage profiles
Then open demo_report/index.html in a browser.
See About the demo report for a preview of what the output looks like.
Prepare your input files
ctdcast starts from the raw files, one per cast: Sea-Bird .hex files with the
.xmlcon beside each (hex_dir), or .cnv files (cnv_dir). It never writes
there. LADCP profiles come as processed .mat files, one per cast (ladcp_dir).
Each instrument gets one root that ctdcast owns and fills. Inside it, one directory per processing stage, products, and the compiled file at the top:
/data/cruise/CTD/ctd_nc/ # ctd_root
stage1/
MIXSED2_001_stage1.nc # the raw file read to netCDF (named after it)
MIXSED2_002_stage1.nc
stage2/
MIXSED2_001_stage2.nc # + soak / back-on-deck flags
stage3/
MIXSED2_001_stage3.nc # + Sea-Bird's steps, calibration and QC
products/
1dbar_down/
MIXSED2_001_1dbar_down.nc # a product, as configured
profiles.nc # the compiled casts
/data/cruise/LADCP/ladcp_nc/ # ladcp_root
stage1/
ladcp_profiles.nc
A directory of unsuffixed per-cast files written before the stage layout is still read, as stage 1.
See Data files (netCDF) for what each file contains.
Edit config.yaml
Generate a template with ctdcast init (it writes a commented config.yaml in
the current directory), then adjust the paths:
data:
ctd_root: /data/cruise/CTD/ctd_nc # ctdcast's; profiles.nc goes at its top
hex_dir: /data/cruise/CTD/raw # .hex + .xmlcon, read only
# cnv_dir: /data/cruise/CTD/cnv # or .cnv instead (needs ctdcast[cnv])
groupings_yaml: /data/cruise/config/ctd_groupings.yaml
gebco_nc: /data/GEBCO_2025.nc # optional
output:
dir: /data/cruise/report
generate:
stations: true
sections: true # requires profiles.nc and groupings_yaml
timeseries: true # requires profiles.nc
Leave gebco_nc blank or omit it entirely if you do not have a GEBCO file — maps will
render without bathymetry. Sea-Bird’s processing steps (Wild Edit, filters, alignment, cell
thermal mass, Loop Edit) and the products go in a data_processing block;
ctdcast inspect cast.cnv prints that block from a CNV’s own header, so you can start from
the steps used at sea. See config.yaml.
Define your sections
If generate.sections is true, create a ctd_groupings.yaml file that groups
casts into named transects:
sections:
KTout:
description: "Kögur Transect outflow"
color: "#e41a1c"
cast_numbers: [[1, 12], 15] # ranges and/or individual cast numbers
FARDWO:
description: "FARDWO mooring array"
color: "#377eb8"
cast_numbers: [[20, 35]]
See ctd_groupings.yaml for the full groupings YAML specification.
Process and report
ctdcast run config.yaml
run runs every stage from the raw files (1, 2, 3, then the compile) and builds the
report. To work a step at a time, use ctdcast process config.yaml --stage … and
ctdcast report config.yaml (see CLI reference).
To force every stage and page to be rebuilt (including ones that are up to date):
ctdcast run config.yaml --force
Open the report
Open <output.dir>/index.html in any browser. The file is fully self-contained —
copy the entire output directory anywhere and it works offline.
<output.dir>/
index.html summary — map, overview panels, navigation
casts.html map and sortable table of all casts
sections.html section cards with links
timeseries.html time-series groups with links
leaflet.html interactive map
sbe_sensors.html sensors by cast and device
processing.html every processing step, by run of casts
profiles_inventory.html variables and attributes of profiles.nc
casts/
cast_001.html
...
sections/
section_KTout.html
...
timeseries/
timeseries_<name>.html
...
See Report output for a description of what each page contains.
Updating mid-cruise
run is incremental. 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 is rebuilt when its input is newer;
profiles.nc when a cast file is newer; a cast, section or time-series page when the files
it is drawn from are newer. The cruise-wide pages (summary, casts, sensors, processing, …)
are rebuilt on every run. After new casts arrive, run it again:
ctdcast run config.yaml
The new casts are processed and get their pages; profiles.nc is recompiled, so the
section, time series and summary pages are rebuilt with them. A config change is not a newer
file: after changing the processing steps or thresholds, add --force (with --only to
limit it to a few casts).
Where to go next
config.yaml — every
config.yamlfield.ctdcast processing framework — the stages and what each one does.
Cruise metadata (cruise_info) — the
cruise_infoblock: identity, platform, people, embargo.ctd_groupings.yaml — every
ctd_groupings.yamlfield.Data files (netCDF) — the netCDF files ctdcast reads and writes.
Report output — what each report page contains.
Python API — Python API for calling ctdcast from your own scripts.