Quickstart: single cast

This guide walks through setting up and running caldip for one calibration dip cast from scratch.

Prerequisites

Install the package (see Installation):

pip install -e ".[dev]"

Directory structure

Each cast needs its own folder containing:

moor/proc_calib/{cruise_id}/cal_dip/cast{ID}/
├── {mooring_id}.caldip.yaml        ← you create this
├── {cast}.cnv                      ← CTD reference cast (1 Hz, SBE processed)
├── {serial}_{date}.hex             ← one file per SBE37 MicroCAT
├── {serial}_{date}.mat             ← one file per RBR thermistor
└── ...

All instrument data files must be in the same folder as the YAML. The directory field in the YAML tells caldip where that folder is.

Step 1 — Generate a stub YAML

Point caldip init at the cast folder and it will scan for recognised instrument files and write a skeleton configuration:

caldip init moor/proc_calib/msm142_2026/cal_dip/castM4/

Open the resulting YAML and fill in any fields left as null or .nan:

  • deployment_time and recovery_time (from the ship’s CTD log)

  • latitude / longitude

  • clock_offset for any instrument whose clock was not set to UTC before deployment

  • ctd_sensors — which CTD sensor pair to use (1 = primary, 2 = secondary)

See the YAML configuration reference for a full field description.

Step 2 — Generate the interactive plot

caldip plot moor/proc_calib/msm142_2026/cal_dip/castM4/castM4.caldip.yaml \
    --output castM4 -o outputs/

This produces a self-contained HTML file (outputs/castM4_plot.html) you can open in any browser. No internet required — the file works at sea.

If you omit --output and -o, the plot opens interactively in your browser instead.

Inspecting a bottle stop in the plot: The plot has three synchronised panels (pressure, temperature, conductivity). To check instrument agreement within a single bottle stop:

  1. Find the bottle stop in the pressure panel — it appears as a flat segment flanked by blue (start) and red (end) vertical lines.

  2. Click and drag across that flat segment in the pressure panel to zoom in. All three panels zoom together on the time axis.

  3. Check that instrument temperatures (and conductivities, if available) lie close to the CTD reference (black) within that window.

  4. Double-click anywhere to zoom back out.

Step 3 — Generate statistics

caldip stats moor/proc_calib/msm142_2026/cal_dip/castM4/castM4.caldip.yaml \
    --ctd-sensor 2 -o outputs/

This writes three files to outputs/:

  • castM4_summary_statistics.csv — one row per instrument (deepest bottle stop)

  • castM4_detailed_statistics.csv — one row per instrument per bottle stop

  • castM4_timing.txt — bottle stop start/end times and pressures

Choosing the CTD sensor (--ctd-sensor)

CTD rosettes typically carry two independent sensor packages (primary=1, and secondary=2). Use --ctd-sensor 2 (secondary) if it is the more accurate sensor package.

Important: --ctd-sensor only applies to caldip stats — the plot always shows both primary and secondary CTD data. Set ctd_sensors: 2 in the YAML to make sensor 2 the default for that cast, so you do not have to pass the flag each time.

Flag

Sensor

--ctd-sensor 1

Primary (default if not set in YAML)

--ctd-sensor 2

Secondary

Rerunning after CTD reprocessing: If the CTD .cnv file is updated (spike removal, pressure correction, salinity calibration, sensor swap), regenerate both the plot and statistics for corrections to be applied to moored instruments.