Python API

The public entry points are importable from ctdcast itself: ctdcast.process() runs processing stages, ctdcast.report() builds the HTML report, and ctdcast.stage1 / ctdcast.profiles run stage 1 and the profiles compile on their own.


Main entry points

ctdcast.processors.process(stage: int | str | list[int | str] | None = None, *, cnv_dir: Path | str | None = None, ctd_root: Path | str | None = None, hex_dir: Path | str | None = None, ctd_raw_format: str | None = None, ladcp_dir: Path | str | None = None, ladcp_root: Path | str | None = None, nc_dir: Path | str | None = None, profiles_path: Path | str | None = None, ladcp_nc_dir: Path | str | None = None, ladcp_profiles_path: Path | str | None = None, force: bool = False, dry_run: bool = False, cast_tags: set[str] | None = None, **kw: object) → object[source]

Run one or more pipeline stages across every configured source.

A stage runs for whichever sources are configured: with both CTD and LADCP paths supplied, stage="stage1" ingests both, and stage="profiles" compiles both. A source whose paths are absent is silently skipped, so a cruise without LADCP is not an error.

Parameters:
  • stage – Which stage(s) to run — 1, 2, 3, a name such as "stage1" or "profiles", or a list of these. A list runs its subset in STAGES order regardless of the order requested. None (the default) runs every stage in order.

  • cnv_dir – CTD pipeline paths. cnv_dir is the external CNV input; ctd_root is the directory ctdcast owns, holding stage1/ … stage3/ and the compiled product. Present → CTD participates in the relevant stages.

  • ctd_root – CTD pipeline paths. cnv_dir is the external CNV input; ctd_root is the directory ctdcast owns, holding stage1/ … stage3/ and the compiled product. Present → CTD participates in the relevant stages.

  • hex_dir – Raw SBE 911plus .hex input and the switch between it and cnv_dir ("cnv" or "hex"; see StagePaths.from_config()).

  • ctd_raw_format – Raw SBE 911plus .hex input and the switch between it and cnv_dir ("cnv" or "hex"; see StagePaths.from_config()).

  • ladcp_dir – LADCP equivalents. Present → LADCP participates in stage 1 (convert) and profiles (compile).

  • ladcp_root – LADCP equivalents. Present → LADCP participates in stage 1 (convert) and profiles (compile).

  • nc_dir – Superseded. nc_dir/ladcp_nc_dir are read as the roots when the root arguments are absent, and the two product paths as explicit overrides of the derived ones. Accepted so an existing caller keeps working; prefer the roots.

  • profiles_path – Superseded. nc_dir/ladcp_nc_dir are read as the roots when the root arguments are absent, and the two product paths as explicit overrides of the derived ones. Accepted so an existing caller keeps working; prefer the roots.

  • ladcp_nc_dir – Superseded. nc_dir/ladcp_nc_dir are read as the roots when the root arguments are absent, and the two product paths as explicit overrides of the derived ones. Accepted so an existing caller keeps working; prefer the roots.

  • ladcp_profiles_path – Superseded. nc_dir/ladcp_nc_dir are read as the roots when the root arguments are absent, and the two product paths as explicit overrides of the derived ones. Accepted so an existing caller keeps working; prefer the roots.

  • force – Re-run even when outputs already exist.

  • dry_run – Print what would run without writing any files.

  • cast_tags – If given, process only files whose stem contains one of the zero-padded cast numbers (e.g. {"042", "043"}). Cruise-scope stages ignore it.

  • **kw – Tuning forwarded to the stage wrappers (e.g. backend, pattern, near_surface_dbar, cruise_cfg, gebco_path, ladcp_pattern). Each wrapper names the kwargs it uses and ignores the rest.

Returns:

A list of per-stage return values when stage is None or a list; the single stage’s return value for a scalar stage.

Return type:

object

ctdcast.reports.index.report(nc_dir: Path, out_dir: Path, *, profiles_path: Path | None = None, groupings_yaml: Path | None = None, section_yaml: Path | None = None, ladcp_dir: Path | None = None, ladcp_profiles_path: Path | None = None, ladcp_pattern: str | None = None, ship_track_nc: Path | None = None, generate: dict[str, bool] | None = None, force: bool = False, skip_existing: bool = False, section_style: str = 'pcolormesh', timeseries_style: str = 'pcolormesh', vmin_override: dict[str, float] | None = None, vmax_override: dict[str, float] | None = None, cruise_info: dict[str, Any] | None = None, config: ReportConfig | None = None, cast_filter: int | list[int] | None = None, sal_range: tuple[float, float] | None = None, trim_soak: bool = False, dbar_step: int = 1, drop_stub: bool = False, generated_at: str | None = None) → int[source]

Generate the full ctdcast HTML report suite.

Parameters:
  • nc_dir – Directory containing per-cast .nc files.

  • out_dir – Root output directory.

  • profiles_path – Path to compiled profiles.nc. Required for section and time series pages.

  • groupings_yaml – Cast groupings — sections: and timeseries:. Conventionally ctd_groupings.yaml.

  • section_yaml – Superseded spelling of groupings_yaml; accepted, and used only when groupings_yaml is absent.

  • ladcp_dir – Directory containing processed LADCP .mat files named NNN.mat or NNNb.mat (letter-suffix variants supported).

  • ladcp_profiles_path – Path to compiled ladcp_profiles.nc. When present, the summary page gains a Velocity section (cruise-wide U/V overview panels) and a data-inventory pill for the file.

  • ladcp_pattern – Optional filename glob for non-standard LADCP naming, e.g. "msm_142_1_*.mat". The * is replaced with the zero-padded cast number. See find_ladcp_file().

  • ship_track_nc – Path to a ship-track netCDF for the Leaflet map background line.

  • generate – Dict of booleans controlling which page types to build. Keys: "stations", "sections", "timeseries", "index", "map". Missing keys default to True.

  • force – Regenerate all pages regardless of file modification times.

  • skip_existing – If True, skip any page whose output HTML already exists, regardless of whether the source files are newer. Use this to fill in only missing pages without touching anything already generated. Takes precedence over the mtime check but is overridden by force.

  • section_style – "pcolormesh" or "contourf" for section figures.

  • timeseries_style – "pcolormesh" or "contourf" for time series figures.

  • vmin_override – Per-variable colormap limit overrides (e.g. {"SA": 34.5}).

  • vmax_override – Per-variable colormap limit overrides (e.g. {"SA": 34.5}).

  • cruise_info – Cruise metadata dict (from the cruise_info: block in config.yaml).

  • config – Frozen display configuration (GEBCO path, figsizes, map bounds, colormaps). Defaults to DEFAULT_REPORT_CONFIG.

  • cast_filter – If set, rebuild only the station page for this cast number (implies generate={"stations": True, rest False}).

  • sal_range – (sal_min, sal_max) — records with ctd_salinity_1 outside this range are excluded from all station page plots. The NC files are not modified. Excluded record count is shown in each page header.

  • trim_soak – If True, apply pre-soak detection on each cast: cut the first 60 s (pump activation) and any records up to the last near-surface record after pump-on. Passed through to generate_station_page().

  • dbar_step – Subsample the pressure axis by this step for section and timeseries plots (default 1, full 1-dbar resolution). build_profiles() always stores 1-dbar data; this controls plot-time resolution only.

  • drop_stub – If True, a cast-page section that applies but whose figures all failed to render is dropped and the survivors renumber over it, instead of keeping the heading with an “unavailable” placeholder. Passed through to generate_station_page().

  • generated_at – Page build stamp written to every page; None (the normal run) uses the current UTC time. Set to a fixed string for a reproducible build (the demo pins it so regenerating does not churn the committed HTML).

Returns:

The number of pages that failed to build (0 on full success), so the CLI can exit non-zero when a requested page could not be generated.

Return type:

int

ctdcast.stage1 is ctdcast.processors.stage1.stage1() and ctdcast.profiles is ctdcast.processors.profiles.build_profiles(), both documented below.

The stage registry: one entry per stage token, read by the CLI’s --stage and by ctdcast.process().

ctdcast.processors.STAGES: tuple[Stage, ...]

Pipeline stages in execution order. Single source of truth for process(), the CLI (--stage choices, help, dispatch), and the re-run rule. Adding a stage — a new CTD step, a cruise-level export, another source — is one row here; everything user-facing derives from this tuple. Each stage fans out over all configured sources inside its run wrapper, so there is no per-source token: --stage 1 ingests CTD and LADCP, --stage profiles compiles both.


Best-available file selection

The supported entry point for consumers outside ctdcast (e.g. caldip) to read the best available ctdcast file per cast — stage 3 if present, else stage 2, else stage 1 — without reimplementing the precedence ladder. Import it as ctdcast.select_best_available.

ctdcast.select_best_available(root: Path | str) → list[tuple[tuple[int, str], Path, int]][source]

Return (cast_id, best_path, source_stage) per cast, sorted by identity.

The one place the best-available precedence lives for every consumer (the report, build_profiles, the LADCP compile). best_path is the highest-stage file present (3 > 2 > 1); source_stage is that stage, or 0 when the best file is a flat/suffix-less file that does not state its own stage (the compatibility shim only assumes stage 1, so 0 = “unknown, guessed stage 1” stays distinct from a stated stage 1).

Parameters:

root (Path or str) – The instrument stage root.

Returns:

One ((cast_num, cast_suffix), path, source_stage) per cast, sorted by cast identity.

Return type:

list of (tuple(int, str), Path, int)


Cast identity

Cast identity: cast-number parsing, expansion, and compact formatting.

Single home for the cast-identity operations shared across the package: parse a cast number and letter suffix from a filename (cast_id_from_name()), expand a cast_numbers config spec to order-preserving pairs or ints (expand_cast_ids() / expand_cast_numbers()), format a single cast id as a zero-padded string (format_cast_id()), and format a list of cast numbers compactly with collapsed ranges (compact_cast_list()).

ctdcast.identity.cast_id_from_name(name: str) → tuple[int, str] | None[source]

Extract (cast_num, cast_suffix) from a cast filename stem.

Uses the last 3+-digit group in the stem as the cast number, so cruise or leg numbers earlier in the name (e.g. the 142 in msm_142_1_001_1sec) are not mistaken for the cast number. Letter suffixes are recognised whether directly appended (mixsed2_004b) or underscore-separated (mixsed2_004_b). Returns None when no 3+-digit group is present.

A per-cast file may carry a stage suffix (_stage1 … _stage3; see ctdcast.processors.stage_layout). It is stripped first, so a lettered cast like mixsed2_029_b_stage1 parses to (29, "b") — otherwise the trailing _stage1 defeats the end-anchored letter-suffix match below and the cast collapses to (29, ""), colliding with plain cast 29.

ctdcast.identity.compact_cast_list(nums: list[int]) → str[source]

Format a cast number list compactly, collapsing consecutive runs into ranges.

Example: [131, 133, 134, 136, 163] → “131, 133–134, 136, 163”.

ctdcast.identity.expand_cast_ids(cast_numbers: list) → list[tuple[int, str]][source]

Expand a cast_numbers spec to (number, suffix) pairs, preserving order.

A plain cast NNN and its lettered sibling NNNb are distinct events, so identity is the pair, not the bare number. A bare int or range names plain events only (suffix ""); a “NNNb” string names the lettered event. Input order is preserved and duplicates are kept — section ordering relies on the author’s given order, so sorting and de-duplication are not applied.

Raises ValueError on a malformed entry, so a bad config fails loudly rather than silently dropping or coercing casts.

ctdcast.identity.expand_cast_numbers(cast_numbers: list) → list[int][source]

Expand a cast_numbers spec to a flat list of station numbers, in order.

The integer view of expand_cast_ids() — the letter suffix is dropped, so a “10b” entry contributes station 10. Use this where callers key on the integer station (LADCP files, map positions, membership); use expand_cast_ids() where a plain cast must be distinguished from its lettered sibling (section and timeseries profile selection).

ctdcast.identity.format_cast_id(cast_num: int, cast_suffix: str = '') → str[source]

Format a cast identity as a zero-padded id string, e.g. (10, "b") -> "010b".

The single formatter for the NNN/NNNb convention used in output filenames (cast_010b.html), page labels, and cast pills. Changing the pad width or suffix rule here changes it everywhere.


Figure builders

draw_*_fig functions build and return a matplotlib Figure (or None when the dataset lacks the required variables). They are grouped by subject.

Maps

Map figure builders and the shared map scaffolding (limits, layout, GEBCO panel, ticks).

ctdcast.plotters.maps.GEBCO_RENDER_PAD: float = 0.5

Extra margin (degrees) added when loading GEBCO for map rendering, so downsampled pcolormesh edge cells extend past the axis limits and no white gap shows at the map border.

ctdcast.plotters.maps.draw_all_sections_map_fig(sections_data: list[dict[str, Any]], all_lats: list[float], all_lons: list[float], legend_outside: bool = False, *, target_h: float = 4.5, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 4.5) → Figure | None[source]

Return a GEBCO map Figure showing every section track in its own colour.

Parameters:
  • sections_data (list of dict) – One dict per section with name, color, lats and lons.

  • all_lats (list of float) – Positions of all casts, drawn as a grey background scatter.

  • all_lons (list of float) – Positions of all casts, drawn as a grey background scatter.

  • legend_outside (bool) – Accepted for call-site compatibility and ignored; the legend sits in a reserved row below the map.

  • target_h (float) – Accepted for call-site compatibility and ignored; the layout sets the height.

  • cfg (ReportConfig) – Report configuration; gebco_path supplies the bathymetry and map_bounds can fix the extent.

  • width_in (float, default W_HALF) – Figure width in inches (half slot); the height follows at a fixed aspect.

Returns:

The figure, or None when sections_data is empty or no position is finite.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.maps.draw_cruise_map_fig(all_meta: list[dict], *, target_h: float = 4.0, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 4.5) → Figure | None[source]

Return a GEBCO map Figure of all cast positions, without a highlighted cast.

Parameters:
  • all_meta (list of dict) – Every cast of the cruise, each with lat, lon and cast_num; non-finite positions are skipped.

  • target_h (float) – Accepted for call-site compatibility and ignored; the layout sets the height.

  • cfg (ReportConfig) – Report configuration; gebco_path supplies the bathymetry and map_bounds can fix the extent.

  • width_in (float, default W_HALF) – Figure width in inches (half slot); the height follows at a fixed aspect.

Returns:

The figure, or None when no cast in all_meta has a finite position.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.maps.draw_section_map_fig(lats: list[float], lons: list[float], cast_nums: list[int], title: str = '', min_margin: float = 0.03, min_margin_lon: float | None = None, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float | None = None, fig_w: float | None = None) → Figure | None[source]

Return a GEBCO map Figure with the section track.

Parameters:
  • lats (list of float) – Cast positions along the section; non-finite positions are skipped.

  • lons (list of float) – Cast positions along the section; non-finite positions are skipped.

  • cast_nums (list of int) – Cast numbers, same length as lats.

  • title (str) – Accepted for call-site compatibility and ignored.

  • min_margin (float, default 0.03) – Minimum margin (degrees) around the track; the margin is otherwise a fraction of the track extent.

  • min_margin_lon (float, optional) – Separate minimum longitude margin (degrees). When given, latitude and longitude margins are set independently and a minimum 0.2° latitude span is enforced — used for the co-located time-series location map.

  • cfg (ReportConfig) – Report configuration; gebco_path supplies the bathymetry and map_bounds can fix the extent.

  • width_in (float, optional) – Figure width in inches; None means W_HALF (the half slot). The height follows from the map extent.

  • fig_w (float, optional) – Deprecated alias of width_in, removed in 0.7.0; passing both raises TypeError.

Returns:

The figure, or None when no position is finite.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.maps.draw_station_map_fig(lat: float, lon: float, all_meta: list[dict], target_h: float = 4.5, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 3.6) → Figure | None[source]

Return a GEBCO map Figure with all casts and this cast highlighted.

Parameters:
  • lat (float) – Position of this cast (degrees north, degrees east).

  • lon (float) – Position of this cast (degrees north, degrees east).

  • all_meta (list of dict) – Every cast of the cruise, each with lat and lon; non-finite positions are skipped.

  • target_h (float) – Accepted for call-site compatibility and ignored; the layout sets the height.

  • cfg (ReportConfig) – Report configuration; gebco_path supplies the bathymetry and map_bounds can fix the extent.

  • width_in (float, default W_TWO_FIFTHS) – Figure width in inches (two-fifths slot); the height follows at a fixed aspect.

Returns:

The figure, or None when no cast in all_meta has a finite position.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.maps.map_panel(ax: Axes, cax: Axes, xl0: float, xl1: float, yl0: float, yl1: float, *, cfg: ReportConfig) → None[source]

Draw the GEBCO depth field into ax and its ‘Depth (m)’ colorbar into cax.

Parameters:
  • ax (matplotlib.axes.Axes) – Map axes to draw the depth field into.

  • cax (matplotlib.axes.Axes) – Pre-placed colorbar axes from the map layout; hidden when there is no GEBCO to draw, so no empty box remains.

  • xl0 (float) – Western and eastern longitude limits (degrees east).

  • xl1 (float) – Western and eastern longitude limits (degrees east).

  • yl0 (float) – Southern and northern latitude limits (degrees north).

  • yl1 (float) – Southern and northern latitude limits (degrees north).

  • cfg (ReportConfig) – Report configuration; gebco_path supplies the bathymetry.

ctdcast.plotters.maps.square_map_limits(yl0: float, yl1: float, xl0: float, xl1: float, cos_lat: float) → tuple[float, float, float, float][source]

Widen longitude so the map is ~square in Mercator proportion.

Mercator-equivalent width is lon_span * cos(lat); if the map would be taller than wide, longitude is expanded symmetrically to make it roughly square. Shared aspect principle for all cruise maps.

Parameters:
  • yl0 (float) – Southern and northern latitude limits (degrees north).

  • yl1 (float) – Southern and northern latitude limits (degrees north).

  • xl0 (float) – Western and eastern longitude limits (degrees east).

  • xl1 (float) – Western and eastern longitude limits (degrees east).

  • cos_lat (float) – Cosine of the map’s central latitude.

Returns:

(yl0, yl1, xl0, xl1); latitudes unchanged, longitudes widened if needed.

Return type:

tuple of float

Profiles

Per-cast profile figure builders: T–S diagrams, stability, auxiliary profiles, QC histograms.

ctdcast.plotters.profiles.draw_aux_profiles_fig(ds: Dataset, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 9.0) → Figure | None[source]

Return side-by-side profiles of oxygen saturation, fluorescence and turbidity.

Parameters:
  • ds (xarray.Dataset) – Per-cast dataset; each of oxygen_saturation, ctd_fluor and ctd_turbidity (or their old names) found in it gets a panel.

  • cfg (ReportConfig) – Report configuration; clean_spines sets the despine.

  • width_in (float, default W_FULL) – Figure width in inches (full slot); the height follows at a fixed aspect.

Returns:

The figure, or None when none of the three variables is present.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.profiles.draw_ct_sa_sigma0_fig(ds: Dataset, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 9.0) → Figure | None[source]

Return side-by-side CT, SA and σ₀ profiles (downcast, with the upcast in grey).

Parameters:
  • ds (xarray.Dataset) – Per-cast dataset with pressure and the T/S channels; CT, SA and σ₀ are derived here (TEOS-10) and the downcast is selected.

  • cfg (ReportConfig) – Report configuration; clean_spines sets the despine.

  • width_in (float, default W_FULL) – Figure width in inches (full slot); the height follows at a fixed aspect.

Returns:

The figure, or None when none of CT, SA, σ₀ is available.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.profiles.draw_qc_histogram_fig(nc_path: Path, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 9.0) → Figure | None[source]

Return a per-variable data-value distribution Figure, or None.

One histogram panel per science variable that carries a {var}_qc companion. Grey bars are all finite data; coloured bars are the good data (QARTOD pass, flag 1 only — so suspect, fail and missing all show as grey above the colour), on shared bin edges so the two are directly comparable. The gross-range suspect and fail thresholds recorded on the _qc companion are drawn as dashed/dotted lines when they fall within the plotted range. Reads nc_path directly, so the distribution is the file’s own — untrimmed — data and flags. Ports the logic of oceanarray’s draw_data_histogram.

Parameters:
  • nc_path – Path to a per-cast stage file (stage 2 or 3, i.e. one carrying _qc).

  • cfg – The frozen report configuration; clean_spines drives the despine.

  • width_in – Figure width in inches; each panel row’s height scales with it.

ctdcast.plotters.profiles.draw_stability_fig(ds: Dataset, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 6.0) → Figure | None[source]

Return downcast profiles of buoyancy frequency squared (N²) and the Turner angle.

Parameters:
  • ds (xarray.Dataset) – Per-cast dataset with pressure and the T/S channels; CT, SA and σ₀ are derived here (TEOS-10) and the downcast is selected.

  • cfg (ReportConfig) – Report configuration; clean_spines sets the despine.

  • width_in (float, default W_TWOTHIRDS) – Figure width in inches (two-thirds slot); the height follows at a fixed aspect.

Returns:

The figure, or None when the downcast has fewer than three levels.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.profiles.draw_ts_density_fig(ds: Dataset, ladcp_path: Path | None = None, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'}))) → Figure | None[source]

Return a CT/SA/σ₀ profile Figure, optionally alongside LADCP U/V.

Parameters:
  • ds (xarray.Dataset) – Per-cast dataset with pressure and the T/S channels; CT, SA and σ₀ are derived here (TEOS-10) and the downcast is selected.

  • ladcp_path (pathlib.Path, optional) – LADCP .mat file for this cast. A path draws a second column with U/V, or a placeholder when the file does not exist. None keeps the same two-column layout and leaves the LADCP column empty, so the CTD panel has the same width either way.

  • cfg (ReportConfig) – Report configuration; clean_spines is used.

Returns:

The figure.

Return type:

matplotlib.figure.Figure

ctdcast.plotters.profiles.draw_ts_diagram_fig(ds: Dataset, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 3.0) → Figure | None[source]

Return a T–S diagram Figure coloured by oxygen saturation, or plain without oxygen.

Parameters:
  • ds (xarray.Dataset) – Per-cast dataset with pressure and the T/S channels; CT, SA and σ₀ are derived here (TEOS-10) and the downcast is selected. With oxygen_saturation (or the old oxsat_1) the points are coloured by it; without, they are drawn in one colour and the figure has no colour bar.

  • cfg (ReportConfig) – Report configuration; clean_spines sets the despine.

  • width_in (float, default W_THIRD) – Figure width in inches (third slot); the height follows at a fixed aspect.

Returns:

The figure, or None when there are fewer than five valid points.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.profiles.draw_ts_updown_fig(ds: Dataset, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 3.6) → Figure | None[source]

Return a T–S diagram Figure overlaying the downcast and the upcast.

Parameters:
  • ds (xarray.Dataset) – Per-cast dataset with pressure and the T/S channels; CT, SA and σ₀ are derived here (TEOS-10) and the downcast is selected.

  • cfg (ReportConfig) – Report configuration; clean_spines sets the despine.

  • width_in (float, default W_TWO_FIFTHS) – Figure width in inches (two-fifths slot); the height follows at a fixed aspect.

Returns:

The figure, or None when the downcast has no valid CT/SA pair.

Return type:

matplotlib.figure.Figure or None

Sections

Section figure builders: depth–distance sections, section T–S panels and the overview panel.

ctdcast.plotters.sections.draw_overview_panel_fig(ds_prof: Dataset, var: str, label: str, bathy_depths: ndarray | None = None, style: str = 'pcolormesh', vmin: float | None = None, vmax: float | None = None, cast_groups: dict[str, list[int]] | None = None, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float | None = None) → Figure | None[source]

Return a Figure of var vs pressure × cast number (cruise overview panel).

Parameters:
  • ds_prof (xarray.Dataset) – Downcast profiles sorted by cast_number; casts are evenly spaced along x with cast numbers as tick labels.

  • var (str) – Variable to plot from ds_prof.

  • label (str) – Accepted for call-site compatibility; the colorbar shows units only.

  • bathy_depths (numpy.ndarray, optional) – Water depth (m) at each cast (length N_PROF), drawn as a black fill.

  • style ({"pcolormesh", "contourf"}) – Field rendering.

  • vmin (float, optional) – Colour limits; each defaults to the 2nd / 98th percentile of the data.

  • vmax (float, optional) – Colour limits; each defaults to the 2nd / 98th percentile of the data.

  • cast_groups (dict of str to list of int, optional) – Section colour → cast numbers, drawn as coloured markers above the axes.

  • cfg (ReportConfig) – Report configuration; var_cmaps is used, and overview_figsize sets the size (its aspect ratio only, when width_in is given).

  • width_in (float, optional) – Figure width in inches (the slot the panel is shown in); the height follows overview_figsize’s aspect. None uses overview_figsize as is.

Returns:

The figure, or None when var is absent or has no finite values.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.sections.draw_section_fig(ds_prof: Dataset, var: str, label: str, x_vals: ndarray, x_label: str, title: str = '', style: str = 'pcolormesh', bathy_depths: ndarray | None = None, bathy_x: ndarray | None = None, cast_labels: list | None = None, vmin: float | None = None, vmax: float | None = None, figsize: tuple[float, float] | None = None, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'}))) → Figure | None[source]

Return a Figure of var vs pressure × along-track distance.

Parameters:
  • ds_prof (xarray.Dataset) – Profiles gridded on pressure × profile, one profile per x_vals entry.

  • var (str) – Variable to plot from ds_prof.

  • label (str) – Accepted for call-site compatibility; the colorbar shows units only.

  • x_vals (numpy.ndarray) – Along-track position of each profile.

  • x_label (str) – x-axis label.

  • title (str) – Accepted for call-site compatibility and ignored.

  • style ({"pcolormesh", "contourf"}) – Field rendering.

  • bathy_depths (numpy.ndarray, optional) – Water depth (m) for the bathymetry fill, at bathy_x when given, else at x_vals.

  • bathy_x (numpy.ndarray, optional) – Denser along-track positions (km) for bathy_depths; used only when its length matches, otherwise the fill falls back to x_vals.

  • cast_labels (list, optional) – Cast numbers drawn as markers along the top edge (same length as x_vals).

  • vmin (float, optional) – Colour limits; each defaults to the 2nd / 98th percentile of the data.

  • vmax (float, optional) – Colour limits; each defaults to the 2nd / 98th percentile of the data.

  • figsize (tuple of float, optional) – (width, height) in inches, used unchanged so a caller can keep the PNG and its slot consistent; when None, section_figsize_and_slot() sets it from the data’s depth and along-track extent.

  • cfg (ReportConfig) – Report configuration; var_cmaps gives the colormap for var.

Returns:

The figure, or None when var is absent or has no finite values.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.sections.draw_section_ts_histogram_fig(ds_prof: Dataset, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 3.0) → Figure | None[source]

Return a CT–SA two-dimensional count histogram Figure (log₁₀ colour) for section profiles.

Parameters:
  • ds_prof (xarray.Dataset) – Profiles with absolute_salinity and conservative_temperature.

  • cfg (ReportConfig) – Report configuration; clean_spines sets the despine.

  • width_in (float, default W_THIRD) – Figure width in inches (third slot); the height follows at a fixed aspect.

Returns:

The figure, or None when SA or CT is absent or fewer than ten valid points remain.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.sections.draw_section_ts_o2_fig(ds_prof: Dataset, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 3.0) → Figure | None[source]

Return a CT–SA Figure coloured by the median oxygen in each T–S bin (bins with at least two points).

Parameters:
  • ds_prof (xarray.Dataset) – Profiles with absolute_salinity, conservative_temperature and an oxygen variable.

  • cfg (ReportConfig) – Report configuration; clean_spines sets the despine.

  • width_in (float, default W_THIRD) – Figure width in inches (third slot); the height follows at a fixed aspect.

Returns:

The figure, or None when SA, CT or oxygen is absent or fewer than ten valid points remain.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.sections.draw_section_ts_profiles_fig(ds_prof: Dataset, x_vals: ndarray, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 3.0) → Figure | None[source]

Return a Figure of per-cast CT–SA profiles coloured by along-track distance.

Parameters:
  • ds_prof (xarray.Dataset) – Section profiles with absolute_salinity and conservative_temperature.

  • x_vals (numpy.ndarray) – Along-track position (km) of each profile; sets the colour.

  • cfg (ReportConfig) – Report configuration; clean_spines sets the despine.

  • width_in (float, default W_THIRD) – Figure width in inches (third slot); the height follows at a fixed aspect.

Returns:

The figure, or None when SA or CT is absent or has no finite values.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.sections.draw_ts_diagram_timeseries_fig(ds_ts: Dataset, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 3.0) → Figure | None[source]

Return a CT–SA diagram Figure for all time-series profiles, coloured by time.

Parameters:
  • ds_ts (xarray.Dataset) – Profiles (N_PROF × pressure) with absolute_salinity, conservative_temperature and time_start.

  • cfg (ReportConfig) – Report configuration; clean_spines sets the despine.

  • width_in (float, default W_THIRD) – Figure width in inches (third slot); the height follows at a fixed aspect.

Returns:

The figure, or None when SA or CT is absent, fewer than two profiles exist, or no value is finite.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.sections.overview_figsize(overview_size: tuple[float, float], width_in: float | None) → tuple[float, float][source]

Return the overview-panel figure size: width_in wide at overview_size’s aspect.

Parameters:
  • overview_size (tuple of float) – (width, height) in inches from the report configuration; only its aspect ratio is used when width_in is given.

  • width_in (float or None) – Figure width in inches (the slot the panel is shown in); None keeps overview_size unchanged.

Returns:

(width, height) in inches.

Return type:

tuple of float

ctdcast.plotters.sections.section_figsize_and_slot(p_max_dbar: float, dist_km: float) → tuple[tuple[float, float], str][source]

Return figure size and CSS slot class for a section pcolormesh plot.

The figure width is always a canonical slot width (one of SLOTS), so the rendered PNG fills its slot at the same oversample as every other figure and the browser never rescales it — otherwise a section rendered at a between-slots width is squeezed into the nearest slot box, shrinking its baked-in fonts.

Aspect is calibrated (_SECTION_STRETCH) so KTout (416 dbar, 94 km) is short at full width. The widest slot whose resulting height stays within _MAX_SECTION_H is chosen; height then follows the data aspect (floored at _MIN_SECTION_H). A section too deep for even the narrowest slot keeps that slot’s width and accepts the height cap.

Parameters:
  • p_max_dbar – Maximum pressure in the section (dbar).

  • dist_km – Total along-track distance of the section (km).

Returns:

  • tuple of ((fig_w, fig_h), css_slot) where fig_w equals the slot’s

  • canonical inch width and css_slot is one of "slot-full",

  • "slot-twothirds", "slot-half", or "slot-third".

Time series

Time-series figure builders: repeat-station series, pressure–time, clock offset, sensor and up/down differences.

ctdcast.plotters.timeseries.draw_clock_offset_fig(series: list[CastClock], verdict: ClockVerdict, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 9.0) → plt.Figure | None[source]

Return a Figure of per-cast clock offset vs cast number, with segment means and changepoints.

Points, not a line — the offsets are whole-second-quantised, so a line would imply a precision that is not there. Each segment mean is drawn as a horizontal rule over its cast range and each changepoint as a vertical rule. Returns None when there is nothing to plot (no segments — a no_clock_pair or insufficient verdict).

Parameters:
  • series (list of CastClock) – Per-cast clock offsets, in cast order.

  • verdict (ClockVerdict) – Segmentation of series (segment means and changepoints).

  • cfg (ReportConfig) – Report configuration; clean_spines sets the despine.

  • width_in (float, default W_FULL) – Figure width in inches (full slot); the height follows at a fixed aspect.

Returns:

The figure, or None when there is nothing to plot (no segments).

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.timeseries.draw_pressure_time_fig(ds: Dataset, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 3.0) → Figure | None[source]

Return a pressure vs elapsed time Figure (cast trajectory and bottle stops).

Parameters:
  • ds (xarray.Dataset) – Per-cast dataset with pressure and time.

  • cfg (ReportConfig) – Report configuration; clean_spines sets the despine.

  • width_in (float, default W_THIRD) – Figure width in inches (third slot); the height follows at a fixed aspect.

Returns:

The figure.

Return type:

matplotlib.figure.Figure

ctdcast.plotters.timeseries.draw_sensor_diff_fig(ds: Dataset, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 6.0) → Figure | None[source]

Return primary-minus-secondary sensor difference profiles (T₁−T₂, S₁−S₂).

Parameters:
  • ds (xarray.Dataset) – Per-cast dataset with a primary and a secondary temperature and/or salinity channel.

  • cfg (ReportConfig) – Report configuration; clean_spines sets the despine.

  • width_in (float, default W_TWOTHIRDS) – Figure width in inches (two-thirds slot); the height follows at a fixed aspect.

Returns:

The figure, or None when neither a temperature nor a salinity pair is present.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.timeseries.draw_timeseries_fig(ds_prof: Dataset, var: str, label: str, style: str = 'pcolormesh', vmin: float | None = None, vmax: float | None = None, width_in: float | None = None, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), figw: float | None = None) → Figure | None[source]

Return a Figure of var vs cast time × pressure, downcasts and upcasts.

Parameters:
  • ds_prof (xarray.Dataset) – Profiles with time_start, time_end, cast_number and cast_type.

  • var (str) – Variable to plot from ds_prof.

  • label (str) – Accepted for call-site compatibility; the colorbar shows units only.

  • style ({"pcolormesh", "contourf"}) – Field rendering.

  • vmin (float, optional) – Colour limits; each defaults to the 2nd / 98th percentile of the data.

  • vmax (float, optional) – Colour limits; each defaults to the 2nd / 98th percentile of the data.

  • width_in (float, optional) – Figure width in inches. When None it follows the profile count: full width for 30 or more, half for 15 or more, else third.

  • cfg (ReportConfig) – Report configuration; var_cmaps gives the colormap for var.

  • figw (float, optional) – Deprecated alias of width_in, removed in 0.7.0; passing both raises TypeError.

Returns:

The figure, or None when var or time_start is absent or no value is finite.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.timeseries.draw_updown_diff_fig(ds: Dataset, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 9.0) → Figure | None[source]

Return downcast-minus-upcast profiles of ΔCT, ΔSA and Δσ₀ on a shared 1 dbar grid.

Parameters:
  • ds (xarray.Dataset) – Per-cast dataset with pressure and the T/S channels; CT, SA and σ₀ are derived here (TEOS-10), and the cast is split at the turnaround.

  • cfg (ReportConfig) – Report configuration; clean_spines sets the despine.

  • width_in (float, default W_FULL) – Figure width in inches (full slot); the height follows at a fixed aspect.

Returns:

The figure, or None when either half has fewer than five levels, the down/up overlap is under 10 dbar, or no difference can be formed.

Return type:

matplotlib.figure.Figure or None

LADCP

LADCP figure builders: velocity sections and bottom-track panels.

class ctdcast.plotters.ladcp.LadcpOverviewGrid(cast_nums: np.ndarray, x_pos: np.ndarray, depth: np.ndarray, u: np.ndarray, v: np.ndarray, bounds: np.ndarray, bathy: np.ndarray | None, y_bottom: float)[source]

Cruise-wide LADCP velocity on a cast-index × depth grid, shared by the U and V panels.

Built once per page by ladcp_overview_grid() so the two panels share one colour scale and one GEBCO lookup.

bathy: ndarray | None

GEBCO water depth (m) at each cast, or None without bathymetry.

bounds: ndarray

Symmetric discrete colour boundaries shared by both components.

cast_nums: ndarray

Cast numbers in ascending order, one per column.

depth: ndarray

Depth axis (m), trimmed to the deepest level with finite velocity.

u: ndarray

Eastward velocity, shape (cast, depth).

v: ndarray

Northward velocity, shape (cast, depth).

x_pos: ndarray

Evenly spaced column positions (0, 1, 2, …), one per cast.

y_bottom: float

5 % below the deeper of the data and the bathymetry.

Type:

Lower plot limit (m)

class ctdcast.plotters.ladcp.LadcpSectionGrid(x: np.ndarray, cast_nums: list[int], z_grid: np.ndarray, u: np.ndarray, v: np.ndarray, bounds: np.ndarray, z_max: float, dense_bathy_x: np.ndarray | None, dense_bathy_d: np.ndarray | None, bathy_coarse: np.ndarray | None, y_bottom: float)[source]

LADCP velocity along a section on a common 10 m depth grid, shared by U and V.

Built once per section by ladcp_section_grid() so the two panels share one read of the .mat files, one colour scale and one GEBCO lookup.

bathy_coarse: ndarray | None

GEBCO water depth (m) at each cast, or None.

bounds: ndarray

Symmetric discrete colour boundaries shared by both components.

cast_nums: list[int]

Cast numbers of those casts, in the same order.

dense_bathy_d: ndarray | None

Water depth (m) of the dense GEBCO profile, or None.

dense_bathy_x: ndarray | None

Along-track x of the dense GEBCO profile, or None.

u: ndarray

Eastward velocity, shape (cast, depth).

v: ndarray

Northward velocity, shape (cast, depth).

x: ndarray

Along-track x position of each cast that has LADCP data.

y_bottom: float

5 % below the deeper of the data and the bathymetry.

Type:

Lower plot limit (m)

z_grid: ndarray

Depth axis (m), 0 to the deepest cast in 10 m steps.

z_max: float

Deepest LADCP depth (m).

ctdcast.plotters.ladcp.draw_ladcp_bottomtrack_fig(ladcp_path: Path | None, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float = 3.0) → Figure | None[source]

Return LADCP bottom-track U and V vs depth.

Parameters:
  • ladcp_path (pathlib.Path or None) – LADCP .mat file for this cast.

  • cfg (ReportConfig) – Report configuration; clean_spines sets the despine.

  • width_in (float, default W_THIRD) – Figure width in inches (third slot); the height follows at a fixed aspect.

Returns:

The figure, or None when ladcp_path is None or the file has no bottom-track solution.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.ladcp.draw_ladcp_overview_fig(grid: LadcpOverviewGrid, component: str, cast_groups: dict[str, list[int]] | None = None, style: str = 'pcolormesh', *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), width_in: float | None = None) → Figure[source]

Return one full-width LADCP velocity panel versus cast number × depth.

The LADCP parallel of ctdcast.plotters.sections.draw_overview_panel_fig(): casts are evenly spaced along x, with a symmetric RdBu_r colorbar (positive = east/north) shared with the other component through grid.

Parameters:
  • grid (LadcpOverviewGrid) – The shared grid from ladcp_overview_grid().

  • component ({"U", "V"}) – Which velocity component to draw.

  • cast_groups (dict of str to list of int, optional) – Section colour → cast numbers; drawn as coloured markers above the axes.

  • style ({"pcolormesh", "contourf"}) – Field rendering.

  • cfg (ReportConfig) – Report configuration; clean_spines is used, and overview_figsize sets the size (its aspect ratio only, when width_in is given).

  • width_in (float, optional) – Figure width in inches (the slot the panel is shown in); the height follows overview_figsize’s aspect. None uses overview_figsize as is.

Returns:

The panel.

Return type:

matplotlib.figure.Figure

ctdcast.plotters.ladcp.draw_ladcp_section_fig(cast_nums: list[int], x_vals: ndarray, x_label: str, ladcp_dir: Path, *, component: str, lats: list[float] | None = None, lons: list[float] | None = None, figsize: tuple[float, float] | None = None, ladcp_pattern: str | None = None, style: str = 'pcolormesh', cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'})), grid: LadcpSectionGrid | None = None) → Figure | None[source]

Return one LADCP velocity-section panel (U or V) vs depth × along-track x.

Parameters:
  • cast_nums (list of int) – Cast numbers along the section, in along-track order.

  • x_vals (numpy.ndarray) – Along-track x position of each cast (same length as cast_nums).

  • x_label (str) – Axis label for the x coordinate.

  • ladcp_dir (pathlib.Path) – Directory holding the LADCP .mat files.

  • component (str) – "U" for the eastward panel or "V" for the northward panel. Both components are gridded either way, so the symmetric RdBu_r colorbar is matched across the two panels regardless of which one is drawn.

  • lats (list of float, optional) – Cast latitudes/longitudes, used for the GEBCO bathymetry fill.

  • lons (list of float, optional) – Cast latitudes/longitudes, used for the GEBCO bathymetry fill.

  • figsize (tuple of float, optional) – Panel (width, height) in inches; when None the aspect-ratio formula section_figsize_and_slot() sets it from the depth and along-track extent.

  • ladcp_pattern (str, optional) – Filename glob (e.g. "msm_142_1_*.mat") with * replaced by the zero-padded cast number; falls back to NNN.mat.

  • style (str) – "pcolormesh" (default) or "contourf".

  • cfg (ReportConfig) – Report configuration (GEBCO path, spine style) threaded to the renderer.

  • grid (LadcpSectionGrid, optional) – A grid already built by ladcp_section_grid() for these casts. Pass it when drawing both components so the files are read once; when None it is built here from the arguments above. When given, cast_nums, x_vals, ladcp_dir, lats, lons and ladcp_pattern are not read: the grid must have been built from the same casts.

Returns:

The panel, or None when fewer than two casts carry LADCP data or no finite velocity remains after gridding.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.ladcp.ladcp_overview_grid(ds_ladcp: Dataset, *, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'}))) → LadcpOverviewGrid | None[source]

Sort, trim and scale a compiled ladcp_profiles.nc for the overview panels.

Parameters:
  • ds_ladcp (xarray.Dataset) – Compiled LADCP profiles (dims N_PROF × depth) with u, v, cast_number, latitude and longitude.

  • cfg (ReportConfig) – Report configuration; gebco_path supplies the bathymetry.

Returns:

The shared grid, or None when u/v are missing, fewer than two casts are present, or no velocity is finite.

Return type:

LadcpOverviewGrid or None

ctdcast.plotters.ladcp.ladcp_section_grid(cast_nums: list[int], x_vals: ndarray, ladcp_dir: Path, *, lats: list[float] | None = None, lons: list[float] | None = None, ladcp_pattern: str | None = None, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'}))) → LadcpSectionGrid | None[source]

Read and grid the LADCP casts of one section for the U and V panels.

Parameters:
  • cast_nums (list of int) – Cast numbers along the section, in along-track order.

  • x_vals (numpy.ndarray) – Along-track x position of each cast (same length as cast_nums).

  • ladcp_dir (pathlib.Path) – Directory holding the LADCP .mat files.

  • lats (list of float, optional) – Cast latitudes/longitudes, used for the GEBCO bathymetry.

  • lons (list of float, optional) – Cast latitudes/longitudes, used for the GEBCO bathymetry.

  • ladcp_pattern (str, optional) – Filename glob (e.g. "msm_142_1_*.mat") with * replaced by the zero-padded cast number; falls back to NNN.mat.

  • cfg (ReportConfig) – Report configuration; gebco_path supplies the bathymetry.

Returns:

The shared grid, or None when fewer than two casts carry LADCP data or no finite velocity remains after gridding.

Return type:

LadcpSectionGrid or None

Corrections (alignment and cell thermal mass)

The figures on the T/S corrections page, drawn from the fits.nc file ctdcast fit writes.

Figures for the corrections page: alignment and cell thermal mass fits over a cruise.

Each draw function takes the fits.nc dataset written by ctdcast fit and the slot width, and returns a Figure at a fixed aspect. Primary is drawn with circles and solid lines, secondary with triangles and dashed lines, throughout. Downcast blue, upcast vermillion (Okabe–Ito, colour-blind safe).

ctdcast.plotters.corrections.alignment_at_edge(fits: Dataset, li: int) → ndarray[source]

Return a mask of the casts with a downcast alignment cost but no estimate from it.

The minimum is at an end of the search, or the cost has no well (ctdcast.analysis.fits.has_well()).

Parameters:
  • fits (xarray.Dataset) – The fits.nc dataset.

  • li (int) – Line index (0 primary, 1 secondary).

Returns:

True where the cast has a cost but no estimate.

Return type:

numpy.ndarray of bool

ctdcast.plotters.corrections.draw_alignment_fig(fits: Dataset, *, width_in: float = 9.0) → Figure | None[source]

Return per-cast total conductivity advance, primary and secondary, with their medians.

The total is the deck unit’s advance plus the residual at each cast’s downcast minimum. A solid line marks the primary median and a dashed line the secondary, each with its value printed.

Parameters:
  • fits (xarray.Dataset) – The fits.nc dataset.

  • width_in (float, default W_FULL) – Figure width in inches; the height follows at a fixed aspect.

Returns:

None when no cast has an alignment fit.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.corrections.draw_alignment_hist_fig(fits: Dataset, *, width_in: float = 4.5) → Figure | None[source]

Return a histogram of each cast’s total conductivity advance, primary and secondary.

One panel per line: the deck unit’s advance plus the residual at each cast’s downcast minimum, with the median drawn.

Parameters:
  • fits (xarray.Dataset) – The fits.nc dataset.

  • width_in (float, default W_HALF) – Figure width in inches; the height follows at a fixed aspect.

Returns:

None when no cast has an alignment fit.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.corrections.draw_alignment_legs_fig(fits: Dataset, *, width_in: float = 9.0) → Figure | None[source]

Return each cast’s downcast minus upcast best advance, primary and secondary.

Not on the corrections page: for looking into why the legs differ. Casts where either leg has no minimum inside the search are left out.

Parameters:
  • fits (xarray.Dataset) – The fits.nc dataset.

  • width_in (float, default W_FULL) – Figure width in inches; the height follows at a fixed aspect.

Returns:

None when no cast has both legs.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.corrections.draw_alignment_wells_fig(fits: Dataset, *, width_in: float = 9.0) → Figure | None[source]

Return the cruise alignment cost against total advance: the downcast and upcast wells.

One panel per line. Each cast’s cost is divided by its own minimum and the curve drawn is the median across casts (ctdcast.analysis.fits.median_curve()), the 25–75th percentiles shaded. Downcast blue, upcast vermillion, each minimum dashed; the downcast’s, the value suggested, is bold in the legend. A grey line marks the deck unit’s advance; the top axis counts scans.

Parameters:
  • fits (xarray.Dataset) – The fits.nc dataset.

  • width_in (float, default W_FULL) – Figure width in inches; the height follows at a fixed aspect.

Returns:

None when no line has a downcast curve.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.corrections.draw_blocks_fig(fits: Dataset, *, cruise: list[LineSummary] | None = None, width_in: float = 9.0) → Figure | None[source]

Return the fits for blocks of consecutive casts: advance, alpha at 7 s, tau at 0.03.

Parameters:
  • fits (xarray.Dataset) – The fits.nc dataset; its block attribute sets the casts per block.

  • cruise (list of LineSummary, optional) – The whole-cruise summaries (ctdcast.processors.fit.summarise()), drawn as the reference advance per line; computed here when the caller does not pass them.

  • width_in (float, default W_FULL) – Figure width in inches; the height follows at a fixed aspect.

Returns:

None when the cruise has fewer than two blocks.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.corrections.draw_ctm_casts_fig(fits: Dataset, *, width_in: float = 9.0) → Figure | None[source]

Return the three-panel cell thermal mass figure, x = cast.

(1) |ΔT| between the bottom and the top of the window, downcast and upcast; (2) maximum pressure, with the window marked for casts that were fitted; (3) one-parameter fits, alpha at tau = 7 s (black, left) and tau at alpha = 0.03 (right), filled where the cast’s |ΔT| is above the cruise median and open below.

Parameters:
  • fits (xarray.Dataset) – The fits.nc dataset.

  • width_in (float, default W_FULL) – Figure width in inches; the height follows at a fixed aspect.

Returns:

None when no cast has a cell thermal mass fit.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.corrections.draw_ctm_param_hist_fig(fits: Dataset, *, width_in: float = 4.5) → Figure | None[source]

Return histograms of the per-cast one-parameter fits: α (at τ=7 s) and τ (at α=0.03).

Two columns (α, τ) and one row per conductivity line; each bar split by whether the cast’s |ΔT| across the window is above (dark) or below (light) the cruise median — the same cut as draw_ctm_casts_fig()’s filled/open markers — with Sea-Bird’s value dotted. A clearer count summary than the per-cast scatter.

Parameters:
  • fits (xarray.Dataset) – The fits.nc dataset.

  • width_in (float, default W_HALF) – Figure width in inches; the height follows at a fixed aspect.

Returns:

None when no cast has a cell thermal mass fit.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.corrections.draw_ctm_surface_fig(fits: Dataset, *, width_in: float = 9.0) → Figure | None[source]

Return the cruise cell thermal mass cost surface per line, as labelled line contours.

The surface is the |ΔT|-weighted mean of each cast’s cost divided by its cost with no correction; contours are labelled as multiples of the minimum, the region within the tolerance (ctm_tolerance, default 2%) of the minimum is shaded, and three points are marked: the global minimum (dot), Sea-Bird’s (0.03, 7 s) (cross) and the recommended value (square).

Parameters:
  • fits (xarray.Dataset) – The fits.nc dataset.

  • width_in (float, default W_FULL) – Figure width in inches; the height follows at a fixed aspect.

Returns:

None when no line has a cell thermal mass fit.

Return type:

matplotlib.figure.Figure or None

ctdcast.plotters.corrections.per_cast_alignment(fits: Dataset, li: int, leg: int = 0) → ndarray[source]

Return each cast’s residual advance at the minimum of one leg’s cost.

NaN where the cast has no alignment cost, where the minimum is at either end of the search (the cost still falling there), or where the cost has no well (ctdcast.analysis.fits.has_well()): no estimate.

Parameters:
  • fits (xarray.Dataset) – The fits.nc dataset.

  • li (int) – Line index (0 primary, 1 secondary).

  • leg (int, default 0) – 0 downcast (the leg fitted), 1 upcast.

Returns:

One value per cast, seconds.

Return type:

numpy.ndarray

ctdcast.plotters.corrections.per_cast_one_parameter(fits: Dataset, li: int) → tuple[ndarray, ndarray][source]

Return each cast’s alpha at tau = 7 s and tau at alpha = 0.03 (NaN where not fitted).

Parameters:
  • fits (xarray.Dataset) – The fits.nc dataset.

  • li (int) – Line index (0 primary, 1 secondary).

Returns:

(alpha, tau), one value per cast.

Return type:

tuple of numpy.ndarray

The figure of a processing setting against cast number, for the processing page.

Figure for the cruise processing page: a setting that changes cast to cast.

ctdcast.plotters.processing.draw_setting_by_cast_fig(casts: Sequence[int], values: Sequence[float], label: str, *, width_in: float = 4.5) → Figure | None[source]

Return the value a step used on each cast, against cast number.

Parameters:
  • casts (sequence of int) – Cast numbers.

  • values (sequence of float) – The step’s value on each cast (NaN where the step did not run).

  • label (str) – The y-axis label: the step and the quantity.

  • width_in (float, default W_HALF) – Figure width in inches; the height follows at a fixed aspect.

Returns:

None when no cast has a value.

Return type:

matplotlib.figure.Figure or None

The figure for a ctdcast-versus-Sea-Bird comparison: the difference in each variable against pressure.

Figure for a ctdcast-versus-Sea-Bird comparison: the difference in each variable against pressure.

One panel per variable, ctdcast minus the CNV at every scan neither side flags, downcast blue and upcast vermillion (Okabe–Ito), with zero drawn. A step reproduced exactly is a vertical line at zero; a step missing or different shows as structure where the profile changes fastest.

ctdcast.plotters.sbe_compare.draw_sbe_compare_fig(ours: Dataset, ref: Dataset, variables: list[str], *, title: str | None = None, width_in: float = 9.0) → Figure | None[source]

Return ctdcast minus Sea-Bird against pressure, one panel per variable.

Parameters:
  • ours (xarray.Dataset) – A ctdcast stage file read from the .hex.

  • ref (xarray.Dataset) – The same cast’s CNV, from ctdcast.analysis.sbe_compare.read_reference().

  • variables (list of str) – The variables to draw, each present in both.

  • title (str, optional) – A figure title, e.g. the cast and the step compared.

  • width_in (float, default W_FULL) – Figure width in inches; the height follows at a fixed aspect.

Returns:

None when no variable has a scan to compare or the scan counts differ.

Return type:

matplotlib.figure.Figure or None

Layer-1 primitives

ax-taking primitives that draw into a caller-supplied axes and create no Figure, so a panel shared by more than one page type has a single implementation.

Layer-1 ax-taking primitives that draw into a provided axes and create no Figure.

ctdcast.plotters.primitives.hide_outer_spines(*axes: Axes, clean: bool) → None[source]

Hide the top and right spines of each axes when clean is True.

Parameters:
  • *axes (matplotlib.axes.Axes) – The axes to despine.

  • clean (bool) – Despine only when True (ReportConfig.clean_spines); otherwise a no-op.

ctdcast.plotters.primitives.mesh_field(ax: Axes, fig: Figure, x: np.ndarray, y: np.ndarray, data2d: np.ndarray, *, cmap: Colormap, norm: Normalize, cmap_name: str, bounds: np.ndarray, style: str, cbar_label: str = '') → Colorbar[source]

Draw a pcolormesh/contourf field with a matched discrete colorbar into ax; return the colorbar.

The colorbar has a fixed inch width (not a fraction of the host axes), so its thickness and the resulting right margin are identical on every field figure regardless of slot width, and its labels are ~6 round values (nice_colorbar_ticks()) rather than one per discretisation boundary, with cbar_label written as a title on top (unit_colorbar()) so it does not widen the figure.

make_axes_locatable (via unit_colorbar(reserve=True)) is used only because this axes is free-aspect. It attaches the colorbar to the divider of the axes’ box at layout time; if something resizes that box afterwards — set_aspect("equal", adjustable="box"), or a hand-placed map layout — the cax tracks the pre-resize box and ends up the wrong size. The rule: make_axes_locatable for free-aspect axes; hand-reserved inches whenever the aspect is locked or the axes are hand-placed. Do not add set_aspect("equal") to a figure that colorbars through here without switching to the reserved-inches path.

ctdcast.plotters.primitives.nice_colorbar_bounds(vmin: float, vmax: float, n: int = 20, hard_min: float | None = None, hard_max: float | None = None) → ndarray[source]

Return a boundary array for a discrete colorbar with approximately n levels.

Steps are chosen from the “nice” ladder [1, 2, 2.5, 5, 10] scaled to the appropriate decade, so ticks land on clean values (e.g. 1.0 rather than 0.8, 0.5 rather than 0.4). The range is centred on the midpoint of [vmin, vmax].

If hard_min or hard_max are given, the returned bounds are clipped to those values so user-specified colormap limits are honoured exactly.

Parameters:
  • vmin (float) – Data range to cover.

  • vmax (float) – Data range to cover.

  • n (int, default 20) – Approximate number of colour levels.

  • hard_min (float or None, optional) – Exact limits to clip to and include as end bounds.

  • hard_max (float or None, optional) – Exact limits to clip to and include as end bounds.

Returns:

Monotonic level boundaries, for BoundaryNorm and the colorbar ticks.

Return type:

numpy.ndarray

ctdcast.plotters.primitives.nice_colorbar_ticks(vmin: float, vmax: float, *, max_ticks: int = 6) → ndarray[source]

Return at most max_ticks nicely-rounded tick positions in [vmin, vmax].

Decoupled from the colorbar’s colour discretisation: a 20-level BoundaryNorm bar can still show ~6 round labels (e.g. 34.8, 34.9, … 35.2) instead of one label per boundary. Uses MaxNLocator with round step multiples so labels land on clean values.

Parameters:
  • vmin (float) – Data range of the colorbar.

  • vmax (float) – Data range of the colorbar.

  • max_ticks (int) – Maximum number of ticks (approximate; the locator may return a few fewer).

Returns:

Tick positions, clipped to [vmin, vmax].

Return type:

numpy.ndarray

ctdcast.plotters.primitives.sigma0_isopycnals(ax: Axes, x: np.ndarray, y: np.ndarray, data2d: np.ndarray) → None[source]

Overlay the 27.7 and 27.8 σ₀ isopycnal contours (labelled) on ax, swallowing contour failures.

ctdcast.plotters.primitives.unit_colorbar(target: Axes, mappable: ScalarMappable, *, unit: str = '', ticks: np.ndarray | None = None, extend: str = 'neither', reserve: bool = False, title_loc: str = 'center') → Colorbar[source]

Draw the report-standard colorbar with the unit as a title on top.

One entry point, two placement strategies so the appearance (bar width, gap, tick choice, unit-on-top) is set in a single place regardless of how the axes was laid out.

Parameters:
  • target (matplotlib Axes) – When reserve is False, a colorbar axes already reserved by a hand layout. When reserve is True, the host plot axes, into which a fixed-inch cax is appended — allowed only for free-aspect axes (see mesh_field()).

  • mappable (matplotlib ScalarMappable) – The artist to map (pcolormesh, contourf set, …).

  • unit (str) – Text placed above the bar (cax.set_title) rather than as a rotated side label — reads cleanly and, unlike a side label, does not widen the figure. A unit ("m/s") or a full label ("CT (°C)"); empty renders no title.

  • ticks (numpy.ndarray, optional) – Explicit tick positions (e.g. from nice_colorbar_ticks()).

  • extend (str) – "neither"/"both"/"min"/"max" — pointed ends for out-of-range.

  • reserve (bool) – Append a fixed-inch cax to target instead of treating it as the cax.

  • title_loc (str) – Horizontal anchor for the on-top title — "center" (default), "left" or "right". "left" anchors the title at the thin bar’s left edge so it extends right into the margin, clear of a figure’s top-left annotations (e.g. the cast-marker strip on field figures); centering it over the thin bar would instead overhang the plot.

Return type:

matplotlib.colorbar.Colorbar

Plotting parameters

Package-wide constants: plotting parameters, CNV aliases, variable metadata, CCHDO conventions.

Compile-time constants only — the per-run display settings (GEBCO path, clean_spines, figsizes, map bounds, colormap overrides) live in the frozen ctdcast.config.report_config.ReportConfig, built once and threaded down.

Section headers mark what kind of constant each block holds, because that determines who may change it and what breaks when they do:

Contract

Changing it makes output wrong or non-conformant. Requires a code review and a version bump.

Science

Changing it gives a different but equally valid answer. Per-cruise overrides go in display.variables: in the cruise config.yaml; use ctdcast.config.loader.load_display_config().

Derived

Computed from another constant; must live here to avoid drift.

Deferred

Belongs in oceanvis once that package exists.

ctdcast.config.parameters.SBE_PREFIX: str = 'sbe_'

Prefix marking a SeaBird-derived channel — quantities ctdcast recomputes (density → sigma0) or does not use. Stage 1 keeps them under this prefix (faithful translation); stage 2 drops them by default; build_profiles never bins them; CCHDO export excludes them. The contract lives here, not as a bare "sbe_" literal scattered across those sites.

ctdcast.config.parameters.SECTION_BIOGEO_VARS: tuple[str, ...] = ('ctd_oxygen', 'ctd_fluor', 'ctd_turbidity')

Biogeochemical variables drawn on section, overview, and timeseries pages, in order. Oxygen is named by its plain (preferred-composite) form: resolve_sensor_var picks the composite when the cast declared preferred_oxygen, and falls back to ctd_oxygen_1 on an undeclared dual-oxygen cast.

ctdcast.config.parameters.SECTION_PHYSICS_VARS: tuple[str, ...] = ('conservative_temperature', 'absolute_salinity', 'sigma0')

Physics variables drawn on section, overview, and timeseries pages, in order. Use vlabel(var) for the axis/panel label and VARIABLES[var]["label"] for the short caption. Defined here so the three report modules share one source of truth and cannot silently diverge from each other or from VARIABLES.

ctdcast.config.parameters.color_limit_override(overrides: dict[str, float], var: str, resolved: str) → float | None[source]

Look up a colour-limit override for a sensor variable under any of its names.

A cruise config may key an override by the name actually drawn (resolved), by the registry name (var), or by the other form of var — plain ctd_oxygen and line-1 ctd_oxygen_1 stand for each other, as in resolve_sensor_var(). A line-2 name (ctd_oxygen_2) has no alternate, so an override set for the plain composite never lands on line 2. The first non-None hit wins, in that order.

Parameters:
  • overrides (dict of str to float) – The vmin or vmax override mapping.

  • var (str) – The registry name the page asked for.

  • resolved (str) – The name present in the dataset (resolve_sensor_var()).

Returns:

The override value, or None when no name carries one.

Return type:

float or None

ctdcast.config.parameters.is_sbe_channel(name: str) → bool[source]

Return whether name is a SeaBird-derived channel (carries SBE_PREFIX).

ctdcast.config.parameters.is_unflagged_channel(name: str) → bool[source]

Return whether name is a channel that carries no QARTOD flag.

Status words (STATUS_CHANNELS) are bits and counters, and a raw voltage volt<N>_raw with no sensor conversion is kept for the record, not used; neither is a measurement a _qc flag could describe. An SBE 43 voltage (oxygen_raw_<N>) is not in this set: stage 3 derives oxygen from it.

Parameters:

name (str) – Variable name.

Returns:

True for a status word or an unconverted raw voltage.

Return type:

bool

ctdcast.config.parameters.resolve_sensor_var(ds: xr.Dataset, var: str) → str[source]

Return the name to use for var in ds, applying the single/dual-sensor rule.

A variable may be stored plain (single sensor, e.g. ctd_oxygen) or suffixed (dual sensor, e.g. ctd_oxygen_1). This resolves whichever form ds actually holds: a suffixed var falls back to its plain form, and a plain var falls back to the _1 form. Returns var unchanged when neither is present, so the caller’s draw function then returns None for the missing variable.

Parameters:
  • ds – The dataset whose variables to resolve against.

  • var – The requested variable name (plain or _1/_2 suffixed).

Returns:

The name present in ds, or var unchanged if neither form is found.

Return type:

str

ctdcast.config.parameters.vlabel(var: str, prefix: str = '') → str[source]

Return a matplotlib axis label for var using the VARIABLES registry.

Format is "Label (units)" when the entry has a non-empty units, or just "Label" when it is dimensionless. The display unit is derived from the CF units string by ctdcast.config.unit_tables.unit_label() (the vendored format_units against ctdcast’s TABLES), never the ASCII-safe units string itself.

Parameters:
  • var – VARIABLES key (e.g. "conservative_temperature").

  • prefix – Optional prefix prepended to the label component only, not the units. Use "Δ" to produce difference labels such as "ΔCT (°C)".

Returns:

Ready-to-use axis label string. Falls back to var itself when var is not in VARIABLES.

Return type:

str

ctdcast.config.parameters.vlabel_html(var: str, prefix: str = '') → str[source]

Return vlabel() as HTML-ready text — mathtext subscripts as Unicode.

Use this wherever a variable label is written into HTML (a figure caption, a table cell): matplotlib needs the mathtext form, but HTML must show σ₀, not the literal $\sigma_0$. One helper so the label-form choice lives in one place.

ctdcast.config.parameters.vunit(var: str) → str[source]

Return the Unicode display unit for var, or "" when dimensionless.

The unit half of vlabel(), for field colorbars that place the unit as a title on top of the bar rather than a "Label (units)" side label. Derives the display unit from the CF units string via ctdcast.config.unit_tables.unit_label(), so it is defined for every entry with units and agrees with vlabel().

Declare and resolve the preferred sensor per cast — one mechanism, two groups.

A dual-sensor cast carries a primary and a secondary measurement for each role; which is better is a human judgement made on noise, not derivable from calibration. The cruise config declares the choice as a cruise-wide default plus per-cast-range exceptions, in channel terms (primary / secondary); ctdcast resolves it per cast and (elsewhere) stamps it.

The same resolve → derive-segments → validate logic serves two independent groups — the T/C pair (which governs temperature, salinity and conductivity together, because salinity needs a matched pair) and oxygen — so every function here takes a SensorGroup descriptor and never branches on which group. PREFERRED_PAIR and PREFERRED_OXYGEN are the only group-specific data.

Primary vs secondary is the sensor role index (temperature_1 / temperature_2), which matches the variable suffix (ctd_temperature_1 / _2) — not the sensor_channel field, which is the CNV wiring position (primary conductivity sits on channel 2). The declaration is by that index; the physical sensor is an independent, verification-only record stamped at write time (the catalog variable name per role), so a later mismatch is detectable. Serials never enter the config a human types.

ctdcast.config.preferred_sensors.GROUPS: tuple[SensorGroup, ...] = (SensorGroup(config_key='preferred_pair', members=('ctd_temperature', 'ctd_salinity', 'conductivity'), preferred_roles=('temperature', 'conductivity'), segment_roles=('temperature_1', 'conductivity_1', 'temperature_2', 'conductivity_2')), SensorGroup(config_key='preferred_oxygen', members=('ctd_oxygen',), preferred_roles=('oxygen',), segment_roles=('oxygen_1', 'oxygen_2', 'temperature_1', 'conductivity_1', 'temperature_2', 'conductivity_2')))

Every group ctdcast resolves.

ctdcast.config.preferred_sensors.PREFERRED_OXYGEN = SensorGroup(config_key='preferred_oxygen', members=('ctd_oxygen',), preferred_roles=('oxygen',), segment_roles=('oxygen_1', 'oxygen_2', 'temperature_1', 'conductivity_1', 'temperature_2', 'conductivity_2'))

independent hardware, its own choice. Its derivation uses its line’s T/S, so a T/C swap on that line is a segment boundary for oxygen too.

Type:

Oxygen

ctdcast.config.preferred_sensors.PREFERRED_PAIR = SensorGroup(config_key='preferred_pair', members=('ctd_temperature', 'ctd_salinity', 'conductivity'), preferred_roles=('temperature', 'conductivity'), segment_roles=('temperature_1', 'conductivity_1', 'temperature_2', 'conductivity_2'))

one choice governs temperature, salinity and conductivity (matched for the salinity computation); segments break on any of the four T/C serials.

Type:

The T/C pair

class ctdcast.config.preferred_sensors.SensorGroup(config_key: str, members: tuple[str, ...], preferred_roles: tuple[str, ...], segment_roles: tuple[str, ...])[source]

A set of channels governed by one preferred-choice declaration.

Parameters:
  • config_key (str) – The settings key carrying the declaration (from preferred_sensor.tc / .oxygen) — "preferred_pair" or "preferred_oxygen". Also the attribute name stamped on the output.

  • members (tuple of str) – The composite (plain, unsuffixed) variables this one choice governs, built from the preferred channel per cast — e.g. ("ctd_temperature", "ctd_salinity", "conductivity") for the pair, ("ctd_oxygen",) for oxygen.

  • preferred_roles (tuple of str) – The base roles whose physical sensor the choice selects (for the sensor_<role>_preferred stamp and the single-sensor presence test) — ("temperature", "conductivity") for the pair, ("oxygen",) for oxygen. The chosen indexed role is f"{base}_{index}" with index from the use word.

  • segment_roles (tuple of str) – The indexed catalog roles whose serial defines a hardware segment; a change in any of them starts a new segment. The T/C pair uses all four (temperature_1/2, conductivity_1/2); oxygen adds its line’s T/C, because the O₂ saturation/AOU derivation uses that line’s temperature and salinity.

config_key: str
members: tuple[str, ...]
preferred_roles: tuple[str, ...]
segment_roles: tuple[str, ...]
ctdcast.config.preferred_sensors.USE_VALUES: frozenset[str] = frozenset({'primary', 'secondary'})

The closed set of declaration values; the 0/1 CNV-vs-ctdcast ambiguity is why a digit is refused rather than mapped — the declaration is words (“primary”/”secondary”), not numbers.

ctdcast.config.preferred_sensors.derive_segments(group: SensorGroup, catalog_by_cast: dict[int, list[dict]]) → list[tuple[int, int, tuple[str | None, ...], frozenset[int]]][source]

Derive runs of consecutive casts sharing one hardware configuration.

A boundary is any cast where the segment_key() (the catalog names of the group’s segment_roles) changes — never a hardcoded cast count.

Parameters:
  • group (SensorGroup) – The group whose serials define the segments.

  • catalog_by_cast (dict of {int: list of dict}) – Per-cast SENSOR_* catalog records (from processors.sensor_catalog.read_cast_sensor_catalog), keyed by cast number.

Returns:

(first_cast, last_cast, segment_key, casts) for each run, in cast order. casts is the set of cast numbers actually in the run — not every integer in [first, last], so reconciliation stays correct when cast numbering has gaps.

Return type:

list of tuple(int, int, tuple, frozenset of int)

ctdcast.config.preferred_sensors.has_choice(group: SensorGroup, records: list[dict]) → bool[source]

Return True if this cast has a genuine primary-vs-secondary choice for group.

A choice exists only when both channels are present (e.g. oxygen_1 and oxygen_2). A single-sensor cast has no choice: its one sensor is already the plain composite (stage-1 promotes a lone sensor to the unsuffixed name), so no preferred declaration applies and nothing is stamped.

Parameters:
  • group (SensorGroup) – The group to test.

  • records (list of dict) – The cast’s SENSOR_* catalog records.

Returns:

True only when both primary and secondary sensors are present for every preferred role of group.

Return type:

bool

ctdcast.config.preferred_sensors.has_use(group: SensorGroup, records: list[dict], use: str) → bool[source]

Return True if every preferred role of group has a sensor for use on this cast.

Parameters:
  • group (SensorGroup) – The group whose preferred_roles must all be present.

  • records (list of dict) – The cast’s SENSOR_* catalog records.

  • use (str) – "primary" or "secondary".

Returns:

False on a single-sensor cast asked for its missing channel (e.g. secondary where only temperature_1 / conductivity_1 exist).

Return type:

bool

ctdcast.config.preferred_sensors.index_of(use: str) → int[source]

Return the role/variable index suffix for a use word.

Parameters:

use (str) – "primary" or "secondary".

Returns:

1 for "primary", 2 for "secondary" — the suffix on the indexed role (temperature_1) and variable (ctd_temperature_1).

Return type:

int

ctdcast.config.preferred_sensors.preferred_sensor_names(group: SensorGroup, records: list[dict], use: str) → dict[str, str][source]

Return {base role: catalog variable name} for the chosen sensors on this cast.

For each of group.preferred_roles, resolves the indexed role f"{role}_{index}" (index from use) to its SENSOR_* catalog name. A role with no such entry is omitted — the caller decides whether that absence is a refusal (explicit choice) or a silent skip (cruise-wide default).

Parameters:
  • group (SensorGroup) – The group whose preferred_roles to resolve.

  • records (list of dict) – The cast’s SENSOR_* catalog records (name / role / channel / attrs).

  • use (str) – "primary" or "secondary" — which indexed sensor to select.

Returns:

dict of {str – {base role: catalog variable name} for the roles present on this cast; roles the cast lacks are omitted.

Return type:

str}

ctdcast.config.preferred_sensors.resolve_preferred(group: SensorGroup, cruise_cfg: dict, cast_number: int) → tuple[str | None, str | None][source]

Resolve the declared choice for one cast, from config alone.

Parameters:
  • group (SensorGroup) – The group whose declaration to read (group.config_key in cruise_cfg).

  • cruise_cfg (dict) – The settings from ctdcast.config.layout.processing_view() (cruise_cfg[group.config_key] is the nested {default, ranges} declaration, or absent).

  • cast_number (int) – The cast’s integer number (a lettered cast resolves by its number).

Returns:

(use, source) where use is "primary" / "secondary" / None (undeclared for this cast) and source is "range" / "default" / None. The caller (the stamp step) needs source to tell an explicit declaration (refuse when impossible) from a cruise-wide default (skip silently).

Return type:

tuple of (str or None, str or None)

Raises:

ValueError – On a declaration that is not a mapping, a range missing its casts key, a value outside USE_VALUES, or two ranges covering this cast with different use (a conflicting overlap).

ctdcast.config.preferred_sensors.segment_key(group: SensorGroup, records: list[dict]) → tuple[str | None, ...][source]

Return the catalog-name tuple identifying a cast’s hardware for group.

One entry per group.segment_roles member, in order: the SENSOR_* catalog variable name for that indexed role, or None when the cast has no such sensor. Two casts with equal keys share a hardware configuration; a change between consecutive casts is a hardware boundary, used both here (derive_segments()) and by ctdcast fit to mark hardware changes on the corrections figures.

Parameters:
  • group (SensorGroup) – The group whose indexed roles define the key.

  • records (list of dict) – The cast’s SENSOR_* catalog records (from processors.sensor_catalog.read_cast_sensor_catalog).

Returns:

One catalog name (or None) per group.segment_roles member, in order.

Return type:

tuple of (str or None)

ctdcast.config.preferred_sensors.validate_preferred(group: SensorGroup, cruise_cfg: dict, catalog_by_cast: dict[int, list[dict]]) → list[str][source]

Return advisory warnings reconciling the declaration against derived segments.

Warnings only, and never raises — a partially declared cruise is a normal mid-processing state, and reconciliation runs at compile time where it must not block. A group with no declaration at all is silent (declaring one group, both, or neither is valid). A malformed declaration (a scalar shorthand, a range missing casts), out-of-set values, and conflicting overlaps are all resolve_preferred()’s job to refuse loudly at stamp time — here they are skipped, not re-raised. For a well-formed declared group, two conditions warn: a declared range that crosses a hardware segment boundary (the human’s cast range does not match where sensors actually changed), and a derived segment the declaration does not cover at all.

Parameters:
Returns:

Human-readable warning strings naming the casts; empty when coherent.

Return type:

list of str

Sensor-provenance registry and per-cruise override resolution.

Records each CTD sensor’s identity — model, maker, serial, calibration date, controlled-vocabulary URIs — so a cruise’s sensor configuration is reconstructable from the output alone. Attribute names follow the OceanGliders OG1 conventions where they apply (sensor_model, sensor_maker, the L05/L22/L35 vocabularies, the SENSOR_* variable form) for interoperability, but this is shipboard CTD data, not a glider mission: the per-profile sensor linkage ctdcast adds has no OG1 equivalent, and nothing here claims OG1 conformance.

Two layers feed a sensor’s attributes:

  1. The universal sbe_sensors.yaml shipped in this package, keyed on the numeric SeaBird SensorID from the CNV header (SensorRegistry).

  2. The operator’s cruise config.yaml sensors: block, keyed on role, supplying what the header cannot — sensors the header can’t identify (altimeter, user-polynomial channels) and model refinements (SensorOverrides).

resolve_sensor() merges them in the fixed order SensorID default -> role override -> serial alias and never invents a model: an unresolved sensor is recorded as UNK with an actionable warning, or (strict=True) raises.

ctdcast.config.sensors.FREQUENCY_ROLES: frozenset[str] = frozenset({'conductivity', 'pressure', 'temperature'})

their datcnv Slope/Offset is a drift knob applied to the derived value, so they carry sensor_calibration_slope/_offset. Voltage sensors (oxygen, fluorometer, …) have a native Slope/Offset that is not a drift knob and is excluded (see ctdcast.config.cnv_header.sensor_calibrations()).

Type:

Frequency-sensor role bases

ctdcast.config.sensors.INDEXED_ROLES: frozenset[str] = frozenset({'conductivity', 'oxygen', 'temperature'})

Roles that carry a primary/secondary index (dual sensors); others are bare.

ctdcast.config.sensors.ROLE_ORDER: tuple[str, ...] = ('temperature_1', 'temperature_2', 'conductivity_1', 'conductivity_2', 'oxygen_1', 'oxygen_2', 'pressure', 'fluorometer', 'turbidity', 'transmissometer', 'ph', 'altimeter', 'spar', 'par', 'user_polynomial')

Canonical sensor roles in display order (roles not listed sort last).

ctdcast.config.sensors.ROLE_QUANTITY: dict[str, str] = {'Altimeter': 'altimeter', 'Conductivity': 'conductivity', 'Fluorometer': 'fluorometer', 'Oxygen': 'oxygen', 'PAR': 'par', 'Pressure': 'pressure', 'SPAR': 'spar', 'Temperature': 'temperature', 'Transmissometer': 'transmissometer', 'Turbidity Meter': 'turbidity', 'User Polynomial': 'user_polynomial', 'pH': 'ph'}

CNV sensor-block comment quantity word -> canonical role base. The comment is the authoritative per-channel role statement (see readers/metadata.py).

ctdcast.config.sensors.ROLE_RAW_VARIABLE: dict[str, str] = {'oxygen': 'oxygen_raw'}

Role base -> the raw-signal variable base to link when the role’s measured variable is absent: a cast read from a .hex carries the SBE 43 voltage (oxygen_raw_N) at stage 1, and ctd_oxygen only once stage 3 derives it.

ctdcast.config.sensors.ROLE_VARIABLE: dict[str, str] = {'altimeter': 'ctd_altimeter', 'conductivity': 'conductivity', 'fluorometer': 'ctd_fluor', 'oxygen': 'ctd_oxygen', 'pressure': 'pressure', 'temperature': 'ctd_temperature', 'turbidity': 'ctd_turbidity'}

Role base -> the canonical data-variable base it measures. Roles are the header’s vocabulary (a device’s job); variables are ctdcast’s (a stored quantity), so the two legitimately differ – fluorometer is the instrument, ctd_fluor the fluorescence. A role absent here (transmissometer, pH, SPAR/PAR, a user polynomial today) still gets a catalog entry. On a .hex cast it links by .xmlcon channel instead: to the converted variable the reader made from that channel (transmissometer), else its raw voltage. A CNV cast has no channel tags, so such a role stays unlinked, silently. The single source of truth for the sensor->variable join; nothing else re-derives a variable name from a role.

ctdcast.config.sensors.SENSOR_ATTR_FIELDS: tuple[str, ...] = ('long_name', 'sensor_type', 'sensor_type_vocabulary', 'sensor_model', 'sensor_model_vocabulary', 'sensor_maker', 'sensor_maker_vocabulary')

Sensor attribute fields a resolved sensor carries, in write order (names follow OG1 conventions for interoperability).

class ctdcast.config.sensors.SensorOverrides(overrides: dict[str, dict[str, str]]=<factory>, aliases: dict[str, str]=<factory>)[source]

Cruise-level, role-keyed sensor overrides and serial aliases.

overrides is keyed by role ("altimeter") or, to disambiguate two different-model devices in one role, "role:serial" ("altimeter:42299"). aliases maps a serial spelling to its canonical form so one physical device recorded two ways yields one catalog entry.

aliases: dict[str, str]
canonical_serial(serial: str) → str[source]

Return the canonical spelling of serial after alias resolution.

for_role(role: str, serial: str) → dict[str, str][source]

Return the override for role, most specific first, or {}.

Tries role:serial (raw then canonical), then bare role.

classmethod from_cruise_config(cruise_cfg: dict[str, Any] | None) → SensorOverrides[source]

Build from a cruise config.yaml mapping (its sensors: block).

overrides: dict[str, dict[str, str]]
class ctdcast.config.sensors.SensorRegistry(by_sensor_id: dict[str, dict[str, str]]=<factory>)[source]

Universal SensorID -> sensor attribute table, from the package YAML.

by_sensor_id: dict[str, dict[str, str]]
default_for(sensor_id: str) → dict[str, str] | None[source]

Return a copy of the registry entry for sensor_id, or None.

classmethod load(path: Path | str | None = None) → SensorRegistry[source]

Load the registry from sbe_sensors.yaml (package default if None).

ctdcast.config.sensors.catalog_var_name(role: str, serial: str) → str[source]

Return the sensor-catalog variable name SENSOR_<TYPE>_<SERIAL>.

role is a canonical ctdcast role (temperature_1, fluorometer); any trailing primary/secondary index (_1/_2) is dropped, because the serial alone identifies the physical device. Primary-vs-secondary is a role fact carried by the linkage variables, not a hardware fact — so one device serving two roles of the same type (e.g. a conductivity cell used as primary on some casts and secondary on others) is a single catalog entry.

ctdcast.config.sensors.is_sensor_catalog_var(name: Hashable) → bool[source]

Return whether name is a sensor-catalog entry (SENSOR_<TYPE>_<SERIAL>).

The catalog entries are the uppercase dimensionless SENSOR_* scalars. A SENSOR_*_qc companion is not an entry, and neither are the lowercase sensor_<role> linkage or sensor_channel_<role> variables.

Parameters:

name (hashable) – The variable name, as Dataset.variables yields it.

Returns:

True when name starts with SENSOR_ and does not end with _qc.

Return type:

bool

ctdcast.config.sensors.resolve_sensor(*, sensor_id: str, serial: str, role: str, calibration_date: str = '', element: str = '', cast: int | str | None = None, registry: SensorRegistry, overrides: SensorOverrides | None = None, strict: bool = False) → dict[str, str][source]

Resolve one sensor’s attributes: SensorID default -> override -> alias.

sensor_id is the numeric SeaBird SensorID (as a string); serial the verbatim serial number (a string — leading zeros are significant); role a canonical ctdcast role; element the CNV element name for cross-checking against the registry; cast an optional label used only in warnings.

Returns a dict of sensor attributes plus provenance (sensor_serial_number, sensor_calibration_date, sbe_sensor_id, sbe_sensor_element, model_source). Never invents a model: an unresolved sensor is returned with sensor_model="UNK" and a loud, actionable warning; with strict=True it raises ValueError instead.

Raises:
  • TypeError – if serial is not a str (guards YAML octal coercion of leading-zero serials).

  • ValueError – if strict and the model cannot be resolved.

ctdcast.config.sensors.role_base(role: str) → str[source]

Strip a dual-sensor index from role (temperature_1 -> temperature).

Only an INDEXED_ROLES role carries the index, so a non-indexed role (pressure, user_polynomial) is returned unchanged.

ctdcast.config.sensors.role_label(role: str) → str[source]

Render a role as a short human label (temperature_1 -> Temperature 1).

ctdcast.config.sensors.role_sort_key(role: str) → tuple[int, str][source]

Sort roles by ROLE_ORDER, unlisted ones last (alphabetical).

ctdcast.config.sensors.sanitize_serial(serial: str) → str[source]

Return serial_slug() of serial; deprecated alias, removed in 0.5.0.

sanitize/sanitise is a British/American variant word, so the family uses one spelling-neutral name (serial_slug) for the filename/variable-safe form.

ctdcast.config.sensors.serial_slug(serial: str) → str[source]

Apply OG1’s rule — non-alphanumerics become underscores — to serial.

File-level metadata

Cruise-level metadata written into the compiled files as ACDD-1.3 global attributes. global_attrs composes the derived coverage bounds, provenance, embargo licence, people, and platform attributes; platforms resolves the vessel registry and derives the EXPOCODE; people turns the structured contributors list into the semicolon-delimited ACDD strings.

Assemble a compiled file’s global attributes from config + derived bounds.

Three layers, kept apart on purpose (see the file-level-metadata design note):

  • derived — geospatial_* and time_coverage_* bounds, date_created. Computed from the data at write time, never authored and never copied up from a per-cast file. Copying the first cast’s latitude up into the cruise file states a bounding box containing one station; the fix is to compute.

  • authored — title, project, acknowledgement, people, embargo. Taken from cruise_info: in the cruise config, once, at the level it is true.

  • identity — cruise, platform_* and expocode. Constant for a ctdcast file, so all three are globals. (CCHDO’s exchange format stores expocode per profile, because a file there may span cruises; a ctdcast file never does, so that per-profile projection belongs with a CCHDO exporter, not here.)

The one rule that decides where a fact goes: a global attribute must be true of the entire file. Anything that varies within the file (cast lat/lon, station name, sensor serial) is a variable, not an attribute.

Conformance target is ACDD-1.3 (with CF). We take OG1’s vocabularies (C89 roles, EDMO institutions, L06 platform, L08 access policy) without adopting OG1’s glider-mission entity model.

ctdcast.config.global_attrs.ATTR_GROUPS: tuple[tuple[str, tuple[str, ...]], ...] = (('Identity & discovery', ('title', 'cruise', 'cast_id', 'platform', 'platform_name', 'platform_ices_code', 'platform_vocabulary', 'expocode', 'id', 'naming_authority', 'project', 'internal_mission_identifier', 'summary', 'program', 'references')), ('Spatiotemporal coverage', ('geospatial_lat_min', 'geospatial_lat_max', 'geospatial_lat_units', 'geospatial_lon_min', 'geospatial_lon_max', 'geospatial_lon_units', 'geospatial_vertical_min', 'geospatial_vertical_max', 'geospatial_vertical_units', 'geospatial_vertical_positive', 'time_coverage_start', 'time_coverage_end', 'time_coverage_duration', 'time_coverage_resolution')), ('People & institutions', ('contributor_name', 'contributor_role', 'contributor_role_vocabulary', 'contributor_id', 'contributor_email', 'contributing_institutions', 'contributing_institutions_id', 'contributing_institutions_role', 'contributing_institutions_role_vocabulary', 'institution', 'publisher_name', 'publisher_email', 'publisher_url')), ('Rights & access', ('acknowledgement', 'license', 'access_constraint', 'date_available', 'license_after_embargo', 'citation', 'doi')), ('Provenance & processing', ('date_created', 'date_modified', 'tracking_id', 'source_tracking_id', 'source_cnv', 'source_hex', 'source_xmlcon', 'source_mat', 'processing_stage', 'history', 'creator_name', 'creator_type', 'creator_id', 'source', 'processing_level', 'data_mode', 'data_mode_meaning', 'Conventions', 'featureType', 'cdm_data_type', 'pressure_units', 'pressure_spacing_dbar', 'cchdo_software_version', 'cchdo_parameters_version')))

Canonical grouping + order of the compiled-file global attributes. Single source of truth for both the on-disk write order (order_attrs()) and the inventory page’s grouped tables (group_attrs()). The order within each group is the canonical order; the group titles are the HTML section headings.

ctdcast.config.global_attrs.CREATION_NOTE = 'file created by ctdcast (https://github.com/ocean-uhh/ctdcast)'

The note recording what wrote this file, appended by each builder through ctdcast.processors.history.append_history() – which already stamps the time and the ctdcast version, so this carries only the part that helper does not: where to find the software.

ctdcast.config.global_attrs.DATA_MODES: dict[str, str] = {'D': 'delayed-mode', 'M': 'mixed', 'P': 'provisional', 'R': 'real-time'}

OceanSITES Reference Table 4 data modes. Single letters rather than OG1’s spelled-out forms because OG1’s own examples are inconsistent — it shows both sea008_..._delayed and sp032_..._R — and oceanarray already uses the OceanSITES letters, so one convention serves both packages.

ctdcast.config.global_attrs.EXPOCODE_PLACEHOLDER_ICES = '{ICES}'

Stand-ins for the two halves of an EXPOCODE when config cannot supply them. Braces are not legal in an EXPOCODE (it is ICES code + YYYYMMDD, both alphanumeric), so a placeholder can never be mistaken for a real code by a reader or a regex — the same reasoning as UNKCRUISE in ctdcast.config.parameters: conspicuous beats plausible. [Contract — a file carrying one of these is provisional. Do not publish it.]

ctdcast.config.global_attrs.OTHER_GROUP = 'Other'

Title for attributes not named in ATTR_GROUPS (never dropped).

ctdcast.config.global_attrs.aggregate_identity(per_cast: list[dict[str, str]], cruise_info: dict[str, Any] | None = None) → dict[str, str][source]

Lift identity attributes from the per-cast files being compiled.

The compiled product describes one cruise, so every per-cast file should agree about which cruise it is. Rather than trusting config and hoping, the inputs are compared:

  • constant across every cast that states it → lifted;

  • a cruise-defining attribute (cruise, expocode) varying → ValueError. Two cruises in one directory is a mistake, not a merge. The previous behaviour (combine_attrs="drop_conflicts") silently discarded the attribute, so a stray cast from another cruise made cruise vanish rather than fail;

  • a ship-describing attribute (the platform_* block) varying → warn, and take cruise_info’s value if it has one, else omit the attribute. Disagreement here is usually registry drift — a platform_vocabulary URI edited between two stage-1 runs, a vessel renamed — which says nothing about whether these casts are one cruise. Failing the whole compile over it, with a message about legs sharing a root, misdirects the reader towards a problem they do not have;

  • absent from every cast → fall back to cruise_info and warn, which is the pre-stage-2 path and the case for files written before identity was recorded at stage 1.

The key set is _IDENTITY_KEYS, which identity_attrs() filters its own output through, so the two cannot drift apart.

Parameters:
  • per_cast (list of dict) – Each per-cast file’s global attributes.

  • cruise_info (dict or None) – Fallback for attributes no cast states.

Return type:

dict of str to str

Raises:

ValueError – If a cruise-defining attribute (cruise, expocode) takes more than one value across the inputs.

ctdcast.config.global_attrs.canonical_attr_order() → list[str][source]

Return the flat canonical order of all named global attributes.

ctdcast.config.global_attrs.coverage_attrs(*, lats: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], lons: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], vertical_min: float | None = None, vertical_max: float | None = None, vertical_units: str = 'dbar', time_starts: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, time_ends: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None) → dict[str, str][source]

Return the derived ACDD coverage attributes.

Every value here is computed from the data, so a multi-station file states a bounding box that brackets all its stations — the property the accompanying test asserts.

Parameters:
  • lats (array-like) – Per-profile latitudes/longitudes (NaNs ignored).

  • lons (array-like) – Per-profile latitudes/longitudes (NaNs ignored).

  • vertical_min (float, optional) – Shallowest and deepest levels, in vertical_units. Omitted when None.

  • vertical_max (float, optional) – Shallowest and deepest levels, in vertical_units. Omitted when None.

  • vertical_units (str) – Units of the vertical bounds. "dbar" for a pressure grid (the honest label — the profiles are gridded on pressure, not converted to metres).

  • time_starts (array-like of datetime64, optional) – Per-profile start and end times. time_coverage_start is the earliest start and time_coverage_end the latest end — the two are taken from separate arrays so the end bound is a real end, never the start of the last profile. Both must be given for any time coverage to be written; a source with a single time per profile passes that one array as both.

  • time_ends (array-like of datetime64, optional) – Per-profile start and end times. time_coverage_start is the earliest start and time_coverage_end the latest end — the two are taken from separate arrays so the end bound is a real end, never the start of the last profile. Both must be given for any time coverage to be written; a source with a single time per profile passes that one array as both.

Returns:

ACDD geospatial_* and time_coverage_* attributes.

Return type:

dict of str to str

ctdcast.config.global_attrs.cruise_expocode(cruise_info: dict[str, Any] | None) → str | None[source]

Return the cruise EXPOCODE, with placeholders for what config omits.

A present but unusable slug (ambiguous, no ICES code, or a forbidden code) is a config error that ctdcast.config.platforms.derive_expocode() raises on — but at build time a wrong EXPOCODE is worse than none and a hard crash mid-pipeline is worse still, so here it is downgraded to a loud warning and None. The resolver keeps its strict raising contract for direct callers; this is the lenient wrapper the file builders use.

A missing platform/ship_slug or start_date is different: the cruise is mid-processing and has simply not settled that value yet. Returning None there meant the compiled file carried no cruise identifier at all, and — because the departure date appears nowhere else (see the CCHDO exemplar, which encodes it only inside the EXPOCODE) — the fact was lost rather than merely deferred. So the shape is kept and the missing half is filled with a conspicuous placeholder:

29OD{YYYYMMDD}      departure date not yet set
{ICES}20260709      ship not yet resolved to an ICES code

With neither half given there is nothing to defer — no cruise is being described — so that returns None as before rather than a placeholder on every profile.

The file can therefore be generated and read, and states plainly which fact is absent. Callers that must not see a placeholder — the filename builder above all — test with is_placeholder_expocode().

Parameters:

cruise_info (dict or None) – The cruise_info: mapping.

Returns:

The EXPOCODE, possibly containing placeholders; None only when the slug is present but unusable.

Return type:

str or None

ctdcast.config.global_attrs.cruise_global_attrs(cruise_info: dict[str, Any] | None, *, lats: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, lons: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, vertical_min: float | None = None, vertical_max: float | None = None, vertical_units: str = 'dbar', time_starts: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, time_ends: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, source: str | None = None, config: dict[str, Any] | None = None, now: datetime | None = None) → dict[str, str][source]

Compose the full global-attribute set for a compiled cruise file.

Merges, in order: authored discovery fields (title/summary/project/ program/cruise_id/acknowledgement), derived coverage bounds, provenance/conformance tags, licence/embargo, people (creator + contributors), and platform attributes. The expocode is not here — the caller emits it as an N_PROF coordinate.

Parameters:
  • cruise_info (dict or None) – The cruise_info: mapping. None or empty yields only derived + provenance attributes.

  • lats – Passed to coverage_attrs().

  • lons – Passed to coverage_attrs().

  • vertical_min – Passed to coverage_attrs().

  • vertical_max – Passed to coverage_attrs().

  • vertical_units – Passed to coverage_attrs().

  • time_starts – Passed to coverage_attrs().

  • time_ends – Passed to coverage_attrs().

  • source (str, optional) – Product key ("ctd", "ladcp"). Passed to ctdcast.config.people.contributor_attrs(), which writes only the roles each contributor scoped to this product (their roles: {all, ctd, ladcp} mapping) plus their unscoped roles — so a product’s own processing personnel are credited on that file alone.

  • config (dict, optional) – The whole cruise config. Only used to read processing.profiles_dbar for the grid token in dataset_identity(); without it a CTD file is identified at the 1 dbar default.

  • now (datetime, optional) – Creation timestamp (injectable for tests).

Returns:

Ready to merge into the dataset’s attrs.

Return type:

dict of str to str

ctdcast.config.global_attrs.cruise_name(cruise_info: dict[str, Any] | None) → str | None[source]

Return the cruise identifier from config, accepting either spelling.

cruise is the attribute written to the file, and is the preferred config key: for every other authored field – title, summary, project, program – the key and the attribute are the same word, and making this one an exception is what let a cruise_id attribute leak into every file. cruise_id stays accepted, because configs are written by hand and both spellings are already in use.

One resolver rather than the precedence repeated at each of the six call sites, so a config cannot be read one way by the compiler and another by the report.

Parameters:

cruise_info (dict or None) – The cruise_info: mapping.

Returns:

The identifier, or None when neither key is set.

Return type:

str or None

ctdcast.config.global_attrs.data_mode_with_meaning(mode: str | None, *, warn: bool = True) → tuple[str, str][source]

Return a validated OceanSITES data_mode and its data_mode_meaning.

The single place the mode-to-meaning pairing is made, so the two attributes can never drift. An unset or out-of-vocabulary mode falls back to "P" (provisional) — the honest default for a file nobody has declared finished — optionally warning.

Parameters:
  • mode – The candidate mode (e.g. from cruise_info.data_mode or an existing attribute).

  • warn – Emit a warning when mode is present but not an OceanSITES data mode.

Returns:

The validated mode and its meaning, both drawn from DATA_MODES.

Return type:

tuple of str

ctdcast.config.global_attrs.dataset_filename(cruise_info: dict[str, Any] | None, product: str, *, config: dict[str, Any] | None = None, grid: str | None = None) → str | None[source]

Return <id>.nc for a compiled product, or None when no id exists.

ACDD notes that the id may be the file name without its suffix, which is what this enforces, so the file on disk and the identifier inside it cannot drift apart.

ctdcast.config.global_attrs.dataset_identity(cruise_info: dict[str, Any] | None, product: str, *, config: dict[str, Any] | None = None, grid: str | None = None) → dict[str, str][source]

Build the ACDD identity attributes for one compiled product.

Two identifiers, sharing a tail:

id                          29OD20260709_R_ctd_2dbar
internal_mission_identifier mixsed2_20260709_R_ctd_2dbar

id follows OG1’s <platform_serial>_<start_date>_<data_mode> shape, with the EXPOCODE standing in for platform-plus-date — it already is the ICES ship code followed by the departure date, so repeating the date would be redundant. internal_mission_identifier is the institution’s own name for the cruise and carries the date explicitly, since a project short name like mixsed2 has none. The product and grid then distinguish the files within one cruise.

The leading <expocode>_ctd is exactly CCHDO’s own file name (740H20200119_ctd.nc), so a ctdcast identifier is a strict extension of the convention ctdcast already reads.

_ separates fields and must not occur inside one — the OceanSITES rule, adopted so the identifier can be split back apart.

Parameters:
  • cruise_info (dict or None) – The cruise_info: mapping. Reads data_mode, naming_authority and internal_id.

  • product (str) – "ctd" or "ladcp".

  • config (dict, optional) – The whole cruise config, for the grid lookup.

  • grid (str, optional) – Overrides the derived grid token.

Returns:

id, naming_authority, internal_mission_identifier, data_mode and data_mode_meaning — only those that can be built.

Return type:

dict of str to str

ctdcast.config.global_attrs.grid_token(product: str, config: dict[str, Any] | None = None) → str | None[source]

Return the vertical-grid token for a product, e.g. "2dbar" or "10m".

The grid belongs in the identifier because it is part of what the file is, not a parameter of how it was made: regridding the same casts at 1 dbar and at 3 dbar yields two products that a user may legitimately want to keep side by side, and nothing else in the name would tell them apart.

Parameters:
  • product (str) – "ctd" or "ladcp".

  • config (dict, optional) – The whole cruise config, read for processing.profiles_dbar.

Returns:

A token safe for an identifier field (no _), or None if unknown.

Return type:

str or None

ctdcast.config.global_attrs.group_attrs(attrs: dict[str, Any]) → list[dict[str, Any]][source]

Split attrs into the canonical groups for display.

Groups appear in ATTR_GROUPS order; within each group the attributes keep the order they appear in attrs (i.e. the file order), so the rendered page can be checked visually against the canonical spec. Unnamed attributes fall into a trailing OTHER_GROUP. Empty groups are omitted.

Returns:

[{"title": str, "rows": [(key, value), ...]}, ...]. The key is rows (not items) so a Jinja template’s group.rows does not collide with the dict .items() method.

Return type:

list of dict

ctdcast.config.global_attrs.identity_attrs(cruise_info: dict[str, Any] | None, *, include_expocode: bool = True) → dict[str, str][source]

Return the attributes that identify which cruise and ship this is.

cruise, the platform_* block, and expocode. These are the facts fixed the moment a cast is taken, so they are written at stage 1 onto each per-cast file and lifted unchanged into the compiled products — unlike coverage (computed per file) or people and rights (authored, and revisable for years afterwards).

Parameters:
  • cruise_info (dict or None) – The cruise_info: mapping. None or empty returns {}, which is what keeps a call path supplying no config unchanged.

  • include_expocode (bool, default True) – Emit expocode. This switch exists for a caller that wants the rest of the identity without it.

Returns:

Only the attributes that could be resolved.

Return type:

dict of str to str

ctdcast.config.global_attrs.is_placeholder_expocode(expocode: str | None) → bool[source]

Return True when expocode carries a placeholder for a missing config value.

ctdcast.config.global_attrs.license_attrs(cruise_info: dict[str, Any]) → dict[str, str][source]

Return the license (and embargo companions) for a cruise.

An embargo is not a licence: a CC BY grant is irrevocable and takes effect the instant it is written, so an embargoed file must carry a self-describing restriction statement, not CC-BY-4.0. This function writes:

  • a moratorium free-text license citing NERC L08 and COAR when cruise_info.embargo is present. The release date is embargo.until when set, otherwise end_date + 2 years. Machine readers also get date_available and access_constraint;

  • a bare CC BY statement when cruise_info.license names it and there is no embargo;

  • nothing when neither is configured — an absent license asserts nothing, which is safer mid-cruise than a wrong claim.

Parameters:

cruise_info (dict) – The cruise_info: mapping.

Returns:

license and, under embargo, date_available / access_constraint.

Return type:

dict of str to str

ctdcast.config.global_attrs.order_attrs(attrs: dict[str, Any]) → dict[str, Any][source]

Return attrs in canonical order.

Named attributes come first in canonical_attr_order(); any remaining ones keep their original relative order and follow (so nothing is dropped and an unrecognised attribute stays visible rather than being silently reordered away).

ctdcast.config.global_attrs.provenance_attrs(now: datetime | None = None) → dict[str, str][source]

Return date_created / date_modified and CF/ACDD conformance tags.

Deliberately not history. Every other writer appends to that attribute through ctdcast.processors.history.append_history(), so a layer that returns it in a dict merged with .update() silently replaces whatever the caller had already recorded – the ordering of the merge becomes load-bearing. The software-provenance note lives in CREATION_NOTE and is appended, like every other line.

Parameters:

now (datetime, optional) – Creation timestamp; defaults to the current UTC time. Injectable so a test can assert an exact value.

Return type:

dict of str to str

Research-vessel registry: config slug → identity, ICES code, and EXPOCODE.

A cruise’s EXPOCODE is derived, not allocated:

EXPOCODE = <4-character ICES ship code> + <departure date YYYYMMDD>

where the departure date is the day the ship left port (cruise_info.start_date), which is not necessarily the first cast. The only piece that must be looked up is the ICES ship code, and looking it up by vessel name is unsafe: names carry accents, punctuation, and generational ambiguity (four hulls have been called Meteor; two live C17 entries are called Odon de Buen). A wrong code yields a well-formed EXPOCODE filed against somebody else’s cruise — a silent, permanent error.

So the registry is keyed on a short ASCII slug (odb, msm, meteor3), and this module refuses to guess:

  • an unknown slug raises;

  • a slug listed in ambiguous_slugs (e.g. bare meteor) raises with the message naming the alternatives;

  • a slug whose ices_code is null (a vessel with no code yet) raises rather than emitting a malformed EXPOCODE;

  • a derived code appearing in forbidden_codes raises — each is a real trap (deprecated codes, same-name different-ship) that a name lookup would fall into.

Source registry: ctdcast.config.platforms platforms.yaml.

exception ctdcast.config.platforms.PlatformError[source]

A platform slug could not be resolved, or its ICES code is unusable.

Raised rather than returning a sentinel because every caller of this module is about to write an EXPOCODE into a file, and a wrong or missing code there is worse than a hard failure at build time.

ctdcast.config.platforms.ambiguous_slugs() → dict[str, str][source]

Return the ambiguous_slugs traps (slug → why it is refused), for ctdcast list.

ctdcast.config.platforms.derive_expocode(platform: str | dict[str, Any], start_date: str | date) → str[source]

Derive the CCHDO/GO-SHIP EXPOCODE for a cruise.

EXPOCODE = <ICES ship code> + <departure date YYYYMMDD>.

Parameters:
  • platform (str or dict) – A platforms.yaml slug, or an inline platform record carrying at least ices_code (see resolve_platform_spec()).

  • start_date (str or datetime.date) – The departure date from port (cruise_info.start_date). Not the first cast; the two can differ (MSM142 departs 2026-03-27, first cast 2026-03-29).

Returns:

e.g. "29OD20260709" for odb departing 2026-07-09.

Return type:

str

Raises:

PlatformError – If a slug is unknown/ambiguous, the platform has no ICES code, the derived code is in forbidden_codes, or start_date is unparseable.

ctdcast.config.platforms.expocode_from_cruise_info(cruise_info: dict[str, Any]) → str | None[source]

Derive the EXPOCODE from a cruise config, or None when not derivable.

Returns None (rather than raising) when the config supplies no ship_slug or no start_date — a cruise mid-processing may not have settled its departure date, and that is not an error. A present slug that is ambiguous, unknown, or lacks an ICES code still raises via derive_expocode(), because those are authoring mistakes.

Parameters:

cruise_info (dict) – The cruise_info: mapping from the cruise config.

Returns:

The EXPOCODE, or None when the slug/start_date is absent.

Return type:

str or None

Notes

The slug is read from cruise_info["platform"], falling back to cruise_info["ship_slug"]. ship (the free-text display name) is never used as a slug — name lookup is exactly the ambiguity this registry avoids.

ctdcast.config.platforms.forbidden_codes() → dict[str, str][source]

Return the forbidden_codes traps (ICES code → why it is refused), for ctdcast list.

ctdcast.config.platforms.load_platforms() → dict[str, dict[str, Any]][source]

Return the platform registry keyed by slug.

Returns an empty mapping when the registry file is absent, so a config that supplies no ship_slug still works (EXPOCODE is simply not derived).

ctdcast.config.platforms.parse_config_date(value: Any) → date | None[source]

Coerce a config date value to a datetime.date, or None.

Accepts a date/datetime (YAML parses a bare 2026-03-27 as a date), an ISO "YYYY-MM-DD" string, or a compact "YYYYMMDD" string. Returns None for None or any value it cannot parse, leaving the caller to decide whether that is an error. Shared by the EXPOCODE derivation and the embargo-date logic so both accept exactly the same date forms.

ctdcast.config.platforms.platform_attrs(platform: str | dict[str, Any]) → dict[str, str][source]

Return ACDD platform global attributes for a slug or inline platform.

Emits platform, platform_vocabulary, platform_name and platform_ices_code from the resolved record, skipping any it omits. Returns an empty mapping when a slug does not resolve to a usable record (the caller decides whether that is fatal).

Parameters:

platform (str or dict) – A platforms.yaml slug, or an inline platform record (see resolve_platform_spec()).

Returns:

Platform attributes ready to merge into a dataset.

Return type:

dict of str to str

ctdcast.config.platforms.platform_display_name(platform: str | dict[str, Any]) → str | None[source]

Return the registry display name for a slug or inline platform, or None.

Uses the plain name (not native_name), for the report masthead and for defaulting the free-text ship in ctdcast init from the chosen slug — deriving the name from the ICES code (unambiguous) rather than resolving a typed name into a code (ambiguous). Returns None when a slug does not resolve.

ctdcast.config.platforms.resolve_platform(slug: str) → dict[str, Any][source]

Return the registry record for slug.

Parameters:

slug (str) – The cruise_info.ship_slug value — a key in platforms.yaml.

Returns:

The platform’s fields (name, ices_code, platform, …).

Return type:

dict

Raises:

PlatformError – If slug is listed in ambiguous_slugs (quoting its message) or is not a key in the registry.

ctdcast.config.platforms.resolve_platform_spec(platform: str | dict[str, Any]) → dict[str, Any][source]

Resolve a config platform value (a registry slug or an inline dict).

A string is a slug looked up in platforms.yaml. A mapping is used inline — for a vessel not (yet) in the shared registry — and should carry at least ices_code (for the EXPOCODE) and name, plus optional platform (L06 category) and platform_vocabulary. This mirrors the inline institution form, so a user can name a new vessel in their own config without first editing platforms.yaml.

Parameters:

platform (str or dict) – A platforms.yaml slug, or an inline platform record.

Returns:

The platform record (registry entry, or the inline mapping as given).

Return type:

dict

Contributors and institutions: config → validated records → netCDF attributes.

The conventions store people as parallel delimited strings aligned by position — contributor_name, contributor_email, contributor_role and contributor_id are separate attributes whose n-th elements describe the same person. That representation has two silent failure modes, and this module exists to make both impossible:

  • A delimiter inside a value. OG1 specifies comma-separated, OceanSITES semicolon-separated. Comma is unsafe — "A. Sanchez Franks, NOC" is a real string from a CCHDO header, and splitting it yields two people. ctdcast writes semicolon-separated (per OceanSITES) and refuses any person-level value containing ; or ,, so the output survives a reader that assumes either.

    Institution names are the exception and are checked for ; only: EDMO’s official names contain commas unavoidably — “University of Hamburg, Institute of Oceanography” — which is itself the demonstration that comma cannot serve as the delimiter for contributing_institutions.

  • Lists of unequal length. Four names and three emails parses cleanly and attributes the wrong address to the wrong person. The strings are generated from one structured list here, so they cannot drift.

Note the direction of travel. amocatlas.contributors parses delimited strings out of other people’s files and is deliberately lenient — it splits on both delimiters and warns heuristically. ctdcast writes its own files and controls the delimiter, so it can be strict instead, which is the stronger guarantee.

Roles come from NERC C89 (BODC data/cruise roles) — the vocabulary that fits a research-cruise dataset (Cruise principal scientist, Project principal investigator, Project collaborator, …). It is the only NVS collection with cruise-scoped terms, and so the only one able to record a chief scientist — PS, whose definition explicitly allows the role to be shared. A role may be given in config as its full prefLabel or its short C89 code (PS, PI, CO); it is normalised to the prefLabel on write, and contributor_role_vocabulary names C89.

ctdcast.config.people.ALL_SCOPE = 'all'

Scope keys accepted inside a contributor’s roles: mapping. all means every compiled file; the others name one product, so a role listed there is written only when that file is built.

ctdcast.config.people.C89_ROLES: dict[str, str] = {'CI': 'Project co-investigator', 'CO': 'Project collaborator', 'CP': 'Cruise participant', 'DC': 'Dataset supply contact', 'DI': 'Cruise dataset principal investigator', 'DM': 'Data manager', 'DP': 'Project dataset principal investigator', 'MC': 'Cruise data manager', 'MP': 'Project data manager', 'PA': 'Project administrator', 'PD': 'Project research assistant', 'PG': 'Project research student', 'PI': 'Project principal investigator', 'PM': 'Project manager', 'PS': 'Cruise principal scientist', 'RA': 'Project technician', 'TC': 'Cruise technical contact', 'TS': 'Cruise technician'}

Convenience alias for the default vocabulary’s terms (code → prefLabel).

ctdcast.config.people.CREATOR_TYPES = ('person', 'group', 'institution', 'position')

ACDD 1.3 creator_type values.

ctdcast.config.people.DEFAULT_INSTITUTION_ROLE = 'CONMEM'

Applied to an institution entry that names no role.

ctdcast.config.people.DEFAULT_INSTITUTION_ROLE_VOCABULARY = 'C59'

Used when cruise_info.institution_role_vocabulary is absent.

ctdcast.config.people.DEFAULT_ROLE_VOCABULARY = 'C89'

Used when cruise_info.role_vocabulary is absent.

ctdcast.config.people.FORBIDDEN_IN_VALUE = (';', ',')

Characters that may never appear inside a field value, because a reader assuming either convention’s delimiter would mis-split the string.

ctdcast.config.people.INSTITUTION_ROLE_VOCABULARIES: dict[str, dict[str, Any]] = {'C59': {'terms': {'CONLEAD': 'Project Lead', 'CONMEM': 'Project Member', 'DATM': 'Project Data Management', 'FUND': 'Project Funding body'}, 'title': 'BODC organisation roles within activities and projects', 'uri': 'https://vocab.nerc.ac.uk/collection/C59/current/'}, 'W08': {'terms': {'CONT0001': 'Manufacturer', 'CONT0002': 'Owner', 'CONT0003': 'Operator', 'CONT0004': 'PI', 'CONT0005': 'Technical Coordinator', 'CONT0006': 'Data scientist', 'CONT0007': 'Service Provider'}, 'title': 'SensorML Contact Section Terms', 'uri': 'https://vocab.nerc.ac.uk/collection/W08/current/'}}

Vocabularies for INSTITUTION roles — a different question from a person’s role, and a different list. OG1 names W08 for this (contributing_institutions_role_vocabulary), and W08’s organisational terms (Operator, Owner, Manufacturer, Service Provider) genuinely are organisation roles, which is why W08 belongs here even though it was the wrong list for people. C59 is the default because it is project-shaped — lead, member, data management, funding body — which is what an institution is to a funded cruise, and because it can name a funder, which W08 cannot.

ctdcast.config.people.ROLE_VOCABULARIES: dict[str, dict[str, Any]] = {'C89': {'terms': {'CI': 'Project co-investigator', 'CO': 'Project collaborator', 'CP': 'Cruise participant', 'DC': 'Dataset supply contact', 'DI': 'Cruise dataset principal investigator', 'DM': 'Data manager', 'DP': 'Project dataset principal investigator', 'MC': 'Cruise data manager', 'MP': 'Project data manager', 'PA': 'Project administrator', 'PD': 'Project research assistant', 'PG': 'Project research student', 'PI': 'Project principal investigator', 'PM': 'Project manager', 'PS': 'Cruise principal scientist', 'RA': 'Project technician', 'TC': 'Cruise technical contact', 'TS': 'Cruise technician'}, 'title': 'BODC dataset roles', 'uri': 'https://vocab.nerc.ac.uk/collection/C89/current/'}, 'G04': {'terms': {'001': 'resourceProvider', '002': 'custodian', '003': 'owner', '004': 'user', '005': 'distributor', '006': 'originator', '007': 'pointOfContact', '008': 'principalInvestigator', '009': 'processor', '010': 'publisher', '011': 'author', '012': 'sponsor', '013': 'coAuthor', '014': 'collaborator', '015': 'editor', '016': 'mediator', '017': 'rightsHolder', '018': 'contributor', '019': 'funder', '020': 'stakeholder'}, 'title': 'ISO 19115 CI_RoleCode', 'uri': 'https://vocab.nerc.ac.uk/collection/G04/current/'}}

The role vocabularies ctdcast can author in, keyed by short name. Each maps concept id → prefLabel, and each uri is what goes into contributor_role_vocabulary.

These are alternatives to CHOOSE BETWEEN, never things to convert between. A mapping from one to another is necessarily lossy — C89 distinguishes the chief scientist from the funded PI, G04 cannot — and a converted file has no way to record that the detail was dropped. So ctdcast validates and writes in whichever vocabulary the config declares, and does not translate. A consumer needing a different vocabulary can map it themselves, knowing their own tolerance for the loss; that judgement is not ours to make.

ctdcast.config.people.SEPARATOR = '; '

Separator written between entries in the parallel attribute strings. OceanSITES mandates ;; OG1 says ,. Semicolon is the safe choice because personal names and “Name, Institution” strings contain commas.

ctdcast.config.people.check_contributors(cruise_info: dict[str, Any]) → tuple[list[str], list[str]][source]

Validate the contributors/creator block of a cruise config.

Returns (errors, warnings). Errors are conditions that would produce a misleading file — a value containing a delimiter, an unknown role, an unresolvable institution. Warnings are omissions that are legitimate while a cruise is in progress but should be settled before publication.

Parameters:

cruise_info (dict) – The cruise_info: mapping from the cruise config.

Returns:

  • errors (list of str)

  • warnings (list of str)

ctdcast.config.people.contributor_attrs(cruise_info: dict[str, Any], source: str | None = None) → dict[str, str][source]

Build the netCDF global attributes describing people and institutions.

Generates the parallel strings from one structured list, so they cannot fall out of alignment. An attribute whose every entry would be empty is omitted entirely rather than written as "; ; ; " — an empty delimited string asserts four empty values, whereas an absent attribute asserts nothing was recorded.

contributing_institutions comes from cruise_info.institutions, a list independent of the people: one person may sit at several institutions and one institution may send several people, so the two must never be zipped together.

Parameters:
  • cruise_info (dict) – The cruise_info: mapping from the cruise config.

  • source (str or None, optional) – Provenance hint forwarded to entry_roles() when resolving each entry’s roles; None uses the default resolution.

Returns:

Global attributes, ready to merge into the dataset.

Return type:

dict of str to str

ctdcast.config.people.entry_roles(entry: dict[str, Any], source: str | None = None) → list[str][source]

Return the roles a contributor holds on one product file, in order.

A contributor states their roles once, in any of three forms:

role: PI                      # one role, every file
roles: [PS, PI]               # several roles, every file
roles:                        # scoped: some roles only on one product
  all: [PI]
  ctd: [DC]
  ladcp: [DI]

The scoped form is what lets one person be a project PI everywhere but the supply contact for the CTD file only, without repeating their name and ORCID and without a second contributor list.

Parameters:
  • entry (dict) – One contributor mapping.

  • source (str or None) – Product key being written ("ctd", "ladcp"). None returns the union across every scope, which is what validation wants.

Returns:

Role tokens as written in config (codes or prefLabels), all first then the product’s own, with duplicates removed and order preserved.

Return type:

list of str

ctdcast.config.people.institution_registry_paths(extra: Path | str | None = None) → list[Path][source]

Return the registry files to merge, lowest precedence first.

Institutions are looked up in three places so that a user who installed ctdcast from PyPI never has to edit package data — which lives in site-packages and is overwritten on upgrade:

  1. the packaged ctdcast/config/institutions.yaml (the shipped defaults);

  2. ~/.config/ctdcast/institutions.yaml (or $CTDCAST_CONFIG_DIR), for institutions an individual or lab uses across cruises;

  3. a path given by cruise_info.institutions_file, for a registry kept beside the cruise config and version-controlled with it.

Later files win key-by-key. A fourth route needs no registry at all: an entry in cruise_info.institutions may be written inline with its own name and id — see resolve_institution(). Inline is the most reproducible option, since the config then carries everything the file asserts.

Parameters:

extra (Path or str, optional) – The institutions_file from the cruise config.

Returns:

Existing files only, in merge order.

Return type:

list of Path

ctdcast.config.people.institution_role_vocabulary(cruise_info: dict[str, Any]) → tuple[str, dict[str, Any]][source]

Return (name, spec) for the institution-role vocabulary in use.

Parameters:

cruise_info (dict) – The cruise_info: mapping; institution_role_vocabulary selects by short name and defaults to DEFAULT_INSTITUTION_ROLE_VOCABULARY.

Returns:

  • name (str)

  • spec (dict)

Raises:

KeyError – If the named vocabulary is unknown.

ctdcast.config.people.institutions_with_source(extra: Path | str | None = None, inline: list[Any] | None = None) → list[dict[str, str]][source]

Return every resolvable institution with the source that supplies it, for ctdcast list.

Follows load_institutions()’ merge order (packaged < user directory < config file, later winning slug by slug) but keeps the winning source per slug instead of discarding it, then appends the inline cruise_info.institutions entries that carry their own name/id and bypass the registry entirely. Keeping the merge here rather than re-walking the paths in the CLI means the precedence lives in one place.

Each item is {slug, name, id, source}; source is "packaged", "user", the config file’s path, or "inline". Inline entries have an empty slug — they are named, not keyed.

ctdcast.config.people.load_institutions(extra: Path | str | None = None) → dict[str, dict[str, Any]][source]

Return the merged institution registry, keyed by slug.

Merges every file from institution_registry_paths(), later files overriding earlier ones slug by slug. Returns an empty mapping when no registry exists, so a config that defines its institutions inline still works.

Parameters:

extra (Path or str, optional) – The institutions_file from the cruise config.

Returns:

Slug → institution entry.

Return type:

dict

ctdcast.config.people.orcid_uri(orcid: str) → str[source]

Return the resolvable URI for an ORCID given in either accepted form.

Accepts a bare identifier (0000-0001-8773-7838) or a URL (https://orcid.org/0000-0001-8773-7838) and always returns the URL, so the value written to contributor_id is canonical regardless of how it was typed.

Parameters:

orcid (str) – Bare identifier or orcid.org URL.

Returns:

https://orcid.org/<identifier>.

Return type:

str

Raises:

ValueError – If orcid matches neither form.

ctdcast.config.people.resolve_institution(item: Any, registry: dict[str, dict[str, Any]]) → dict[str, Any] | None[source]

Resolve one institutions: entry to {name, id, role}.

An entry may be written three ways, so that a user who installed ctdcast from PyPI — and therefore cannot edit the packaged registry — can still name an institution the registry does not know:

institutions:
  - uhh                                   # a registry slug
  - slug: ulpgc                           # a slug, with a role
    role: CONLEAD
  - name: "Agencia Estatal de Investigación"   # inline, no registry
    id: "https://ror.org/003x0zc53"
    role: FUND
Parameters:
  • item (str or dict) – One entry from cruise_info.institutions.

  • registry (dict) – The loaded institution registry, keyed by slug.

Returns:

{"name": str, "id": str, "role": str}, or None when a slug does not resolve.

Return type:

dict or None

ctdcast.config.people.role_choices(vocabulary: str | None = None) → list[str][source]

Return the prefLabels of a role vocabulary, in definition order.

Intended for interactive prompting, where a numbered list of human-readable roles is wanted rather than concept codes.

Parameters:

vocabulary (str, optional) – Short name from ROLE_VOCABULARIES; defaults to DEFAULT_ROLE_VOCABULARY.

Returns:

prefLabels, ordered as the vocabulary defines them (cruise-scoped terms first, for C89).

Return type:

list of str

ctdcast.config.people.role_vocabulary(cruise_info: dict[str, Any]) → tuple[str, dict[str, Any]][source]

Return (name, spec) for the vocabulary this config authors in.

Parameters:

cruise_info (dict) – The cruise_info: mapping; role_vocabulary selects the vocabulary by short name and defaults to DEFAULT_ROLE_VOCABULARY.

Returns:

  • name (str)

  • spec (dict) – uri, title and terms for the selected vocabulary.

Raises:

KeyError – If the named vocabulary is not one of ROLE_VOCABULARIES.

cnv_header is the counterpart that reads inwards rather than composing outwards: pure functions over a CNV header’s text, recovering what the deck unit and SBE Data Processing did to a cast before ctdcast saw it. It opens no files — the header travels on every stage-1 file in raw_metadata.

Parse the acquisition (*) and start-time (#) header of an SBE CNV/HEX file.

These are pure functions over header text — no file I/O, no xarray. They recover what a Sea-Bird deck unit and Seasave did to a cast before ctdcast ever read it: the deck-unit conductivity advance (applied in hardware at acquisition and recorded nowhere ctdcast previously looked), the system/NMEA clock pair, and which clock the start_time coordinate is anchored to.

The two verbatim blocks are ground truth; every typed field is a best-effort read on top of them. A line the classifier does not recognise is kept in verbatim and skipped — never dropped, never fatal. Absence of a deck-unit line means a different instrument class, not “unaligned”: it yields an empty DeckUnit, not an error.

Header lines are matched with str.splitlines(), which handles the CRLF endings these Windows-written files carry, and whitespace inside a value is collapsed before a timestamp is parsed (some writers emit NMEA UTC with a double space).

The header text is not read from a CNV file: it is already carried on every stage-1 file in the raw_metadata global attribute. header_from_raw_metadata() extracts it from that JSON envelope, so nothing here opens a file.

class ctdcast.config.cnv_header.Acquisition(deck_unit: DeckUnit, clocks: Clocks, seasave_version: str | None, verbatim: str)[source]

Everything recovered from the * acquisition block of a CNV/HEX header.

clocks: Clocks
deck_unit: DeckUnit
seasave_version: str | None
verbatim: str
ctdcast.config.cnv_header.CONFORMANCE_MATCH = 'match'

Conformance-tick states for the “Matches reference” column. Three states, never two: a dash (no reference) must never read as a cross (differs).

class ctdcast.config.cnv_header.Clocks(system_upload: str | None = None, system_utc: str | None = None, nmea_utc: str | None = None, offset_seconds: float | None = None, system_dt: datetime | None = None, nmea_dt: datetime | None = None, system_upload_dt: datetime | None = None)[source]

The two acquisition clocks and their offset.

offset_seconds is nmea_utc - system_utc (positive when the system clock is slow relative to GPS), or None if either timestamp is absent or unparseable. system_dt / nmea_dt are the same two clocks already parsed to datetime while computing the offset, exposed so callers need not re-parse the verbatim strings; system_upload_dt is system_upload parsed the same way (the PC clock at the first scan of a .hex).

nmea_dt: datetime | None = None
nmea_utc: str | None = None
offset_seconds: float | None = None
system_dt: datetime | None = None
system_upload: str | None = None
system_upload_dt: datetime | None = None
system_utc: str | None = None
class ctdcast.config.cnv_header.ConformanceTick(key: str, label: str, state: str, reference: str, source: str, detail: str, variables: str = '')[source]

One correction row’s agreement with a documented reference value.

state is CONFORMANCE_MATCH / CONFORMANCE_DIFFER / CONFORMANCE_NO_REFERENCE, rendered ✓ / ✗ / — and never conflated: a dash means “no reference to check against”, not “differs”. A match means the value equals a documented typical value, NOT that it is “correct”; a differ is a deviation to judge, NOT “wrong” — every reference is configuration-dependent, so source names where the reference came from and the tick is a match indicator, not a verdict. key aligns the tick to the Correction it belongs to ("celltm", "align", a suffixed "wildedit_2"); several ticks share one key when a correction expands per sensor/channel (label disambiguates the sub-rows). detail is the parsed-vs-reference text; variables names the variable(s) the step modified, for a display column (conductivity_1 for a cell-thermal-mass row, the smoothed channels for a filter row, all channels: raw→physical for datcnv). The comparison is producer-agnostic: it checks the parameters, not who applied them, so the same references serve a future stage-3 correction ledger.

detail: str
key: str
label: str
reference: str
source: str
state: str
variables: str = ''
class ctdcast.config.cnv_header.Correction(label: str, key: str, producer: str, version: str, parameters: str)[source]

One correction in the ledger, split into producer, version and parameters.

The deck-unit alignment and each Sea-Bird Data Processing module become a record. label is the display name ("align (deck)", "celltm", "celltm (2)" for a repeat); key is the attribute suffix ("align", "celltm", "celltm_2"). parameters is the salient parameter string, possibly empty.

key: str
label: str
parameters: str
producer: str
version: str
class ctdcast.config.cnv_header.DeckUnit(model: str | None = None, firmware: str | None = None, advance: dict[str, float]=<factory>, scans_averaged: int | None = None)[source]

The SBE 11plus deck unit’s acquisition-time configuration.

advance maps a channel name exactly as the header spells it ("primary conductivity", "voltage 0") to its advance in seconds. It is a per-channel map, not a boolean or single value: a V 5.0 unit advances the two conductivity channels by different amounts, and that asymmetry is the whole reason this parse exists. An empty map with model None means no deck-unit line was found.

advance: dict[str, float]
firmware: str | None = None
model: str | None = None
scans_averaged: int | None = None
class ctdcast.config.cnv_header.ProcessingChain(steps: list[ProcessingStep] = <factory>, verbatim: str = '')[source]

The SBE Data Processing module chain, in file order.

steps is one entry per contiguous run of a module’s lines, so a module that runs twice (SBE sanctions running Wild Edit more than once) yields two steps and is never deduplicated. verbatim is the # processing region exactly as read, so an unrecognised line is preserved there even when it contributes no step.

steps: list[ProcessingStep]
verbatim: str = ''
class ctdcast.config.cnv_header.ProcessingStep(module: str, params: dict[str, str]=<factory>)[source]

One SBE Data Processing module in the # chain.

module is the name exactly as the header spells it (datcnv, wildedit, Derive). params maps each field to its verbatim value in file order — keys keep the SBE channel names the header uses (low_pass_A_vars, action t090C); values are never split, so a comma-collection such as no, min = 0.000, ... and a date’s trailing [datcnv_vars = 15] stay intact.

module: str
params: dict[str, str]
class ctdcast.config.cnv_header.SbeHistoryNote(timestamp: str, version: str, stage: str, note: str)[source]

One SBE Data Processing module rendered as a history line’s components.

timestamp is the module’s verbatim SBE stamp (no Z); stage is the module name as spelled; note is its salient-parameter body. The deck-unit align has no timestamp and is not a history note (it is correction_align).

note: str
stage: str
timestamp: str
version: str
class ctdcast.config.cnv_header.SensorCalibration(kind: str, label: str, serial: str, slope: str, offset: str, slope_nondefault: bool, offset_nondefault: bool)[source]

A frequency sensor’s drift Slope/Offset, read from the CNV <Sensors> config.

Answers “was a calibration correction already applied before ctdcast read the cast?” Sea-Bird applies corrected = slope * computed + offset at datcnv to the derived physical value (not the raw frequency), so a non-identity slope/offset means a drift or span correction is already baked into the data. kind is "temperature"/"conductivity"/"pressure"; label disambiguates dual sensors ("temperature_1", "temperature_2"), or is the bare kind when a sensor is single. slope and offset are kept verbatim as the config spells them, so no precision is lost. slope_nondefault / offset_nondefault flag each value that departs from its identity (slope 1.0, offset 0.0) independently, so the display can mark exactly which one carries a correction; drift_applied is True when either does. Only the frequency sensors are read: a voltage sensor’s Slope/Offset (pH, transmissometer) is a native calibration, not a drift knob.

property drift_applied: bool

True when a drift or span correction is baked into either value.

kind: str
label: str
offset: str
offset_nondefault: bool
serial: str
slope: str
slope_nondefault: bool
class ctdcast.config.cnv_header.StackedAdvance(channel: str, deck: float, software: float)[source]

A software conductivity advance applied on top of the deck unit’s advance of the same channel.

channel is the SBE column (c0S/m); deck and software are the two advances in seconds and total their sum, which is what the data carry.

channel: str
deck: float
sentence() → str[source]

Return the finding as one sentence.

software: float
property total: float

the deck unit’s plus the software one.

Type:

The advance the data carry

class ctdcast.config.cnv_header.StartTime(value: str | None, clock: str, anchor: str, source: str = '')[source]

The # start_time value and the provenance named in its bracket.

source is the verbatim bracket text ("System UTC, first data scan."); clock and anchor are its resolved halves. source is "" when the line carries no bracket.

anchor: str
clock: str
source: str = ''
value: str | None
ctdcast.config.cnv_header.applied_sbe_corrections(header_text: str) → dict[str, object][source]

Return what Sea-Bird already did to the data that ctdcast’s stage 3 might also do.

Parameters:

header_text (str) – The verbatim CNV or .hex header.

Returns:

"modules": the set of SBE Data Processing modules in the chain, lower-cased ({"datcnv", "celltm", "binavg", …}); "aligned": {variable: seconds} for each channel an alignctd step advanced, named conductivity_1, oxygen_2, temperature_1 …; "align_unparsed": alignctd channels ctdcast could not name (a caller should treat these as “every channel may be aligned”); "deck_advance": the deck unit’s hardware advances ({"primary conductivity": 0.073, …}), which are in the raw data and are not a software alignment.

Return type:

dict

ctdcast.config.cnv_header.build_correction_ledger(header_text: str) → dict[str, str | float][source]

Build the stage-1 correction ledger from an SBE header.

Records what was done to the cast before ctdcast read it, so a later stage does not re-apply a correction already made. Two verbatim blocks (sbe_acquisition, sbe_processing) are the ground truth; the structured attributes are convenience summaries over them: the module order, the deck-unit alignment, one correction_<module> per step in the chain (a repeat suffixed _2, _3…), and the time coordinate’s source and offset. Every module gets a summary — deciding which “count” as corrections would require predicting them. An attribute is written only when the header supports it; an absent correction_<name> means “not recorded”, never “not done”. Returns an empty mapping for an empty or missing header (e.g. a LADCP file), so the caller can update attributes unconditionally.

ctdcast.config.cnv_header.cal_value_nondefault(value: str, default: float) → bool[source]

Return whether a calibration value departs from its default beyond tolerance.

Decides whether a stored slope (default 1.0) or offset (default 0.0) carries a drift/span correction, so the cast page can amber-tint and bold it — used both on the sensor_calibrations header parse and, since the sensor catalog, on the per-cast SENSOR_* attributes.

Parameters:
  • value (str) – The stored slope or offset, verbatim as read from the SBE header or a SENSOR_* catalog attribute.

  • default (float) – The identity value it is compared against — 1.0 for a slope, 0.0 for an offset.

Returns:

True when value parses and lies more than the identity tolerance (_CAL_IDENTITY_TOL, 5e-7) from default; False when it is within tolerance or cannot be parsed — a drift that cannot be read is not claimed.

Return type:

bool

ctdcast.config.cnv_header.celltm_reference_tick(key: str, label: str, alpha: float, tau: float, variables: str = '') → ConformanceTick[source]

Compare one cell thermal mass (alpha, tau) pair with SBE’s documented reference.

The same reference and tolerances as the Sea-Bird celltm rows, so a correction made in ctdcast stage 3 is judged exactly as one made by SBE Data Processing.

Parameters:
  • key (str) – The row’s key and display label.

  • label (str) – The row’s key and display label.

  • alpha (float) – The applied amplitude and time constant (s).

  • tau (float) – The applied amplitude and time constant (s).

  • variables (str, optional) – The variable the step modified, for the display column.

Returns:

A match (✓) or differ (✗) tick citing SBE manual p.92.

Return type:

ConformanceTick

ctdcast.config.cnv_header.conductivity_advance_reference_tick(key: str, label: str, total_seconds: float, variables: str = '') → ConformanceTick[source]

Compare a conductivity channel’s total advance (deck unit + software) with SBE’s 0.073 s.

Parameters:
  • key (str) – The row’s key and display label.

  • label (str) – The row’s key and display label.

  • total_seconds (float) – The deck unit’s advance plus any software alignment, in seconds.

  • variables (str, optional) – The variable the step modified, for the display column.

Returns:

A match (✓) or differ (✗) tick citing SBE manual p.85, with the same tolerance as the deck-unit rows.

Return type:

ConformanceTick

ctdcast.config.cnv_header.conformance_advisories(header_text: str) → list[str][source]

Where a cast’s processing deviates from a documented reference, as hedged prose.

A sibling of provenance_advisories() (which reports structural facts); this reports comparisons to a recommendation. Two sources, one list: every parameter tick that CONFORMANCE_DIFFER`s becomes a sentence, plus three structural checks — oxygen present but not aligned (SBE p.86), a temperature/conductivity channel low-pass smoothed when SBE smooths pressure only (p.100), and Bin Average without a preceding Loop Edit. Every string cites its source and hedges: a deviation is a value to judge, never asserted "wrong", because each reference is configuration-dependent. Empty header, or an instrument outside the SBE 9 family (see :func:`conformance_supported) → [].

ctdcast.config.cnv_header.conformance_supported(header_text: str) → bool[source]

Return True when documented references exist for this cast’s instrument (the SBE 9 family).

The values in _CONFORMANCE_REFS (celltm α/τ, filter-pressure tc, deck conductivity advance) are the SBE 9 / 11plus defaults. Other instruments (SBE 19plus, 25, …) have different documented defaults that are not yet encoded, so conformance is reported only for the SBE 9 family; every other instrument yields no ticks and, on the report, a note naming it. An unrecognised header is unsupported.

ctdcast.config.cnv_header.conformance_ticks(header_text: str, rename_map: dict[str, str] | None = None) → list[ConformanceTick][source]

Compare a cast’s processing parameters against documented references, one tick per row.

A sibling of correction_records(): the ticks align to those records by key, and a correction whose parameters are per-sensor/per-channel lists (deck align, cell thermal mass) expands into one tick per channel/cell. Modules with no documented reference (datcnv, binavg, loop edit, wfilter, Derive, …) get a single CONFORMANCE_NO_REFERENCE tick — a dash, never a cross. The comparison reads the structured ProcessingStep parameters and is producer-agnostic, so the same references serve a future stage-3 ledger. rename_map is the cast’s {sbe_column_name: variable_name} (from each variable’s original_name), used to canonicalise the Variables column to the names the reader actually applied — see _canonical_var(). Returns an empty list for an empty header, or for an instrument outside the SBE 9 family (see conformance_supported()).

ctdcast.config.cnv_header.correction_records(header_text: str) → list[Correction][source]

Return the structured corrections (deck-unit align + each module) in file order.

The display counterpart of the flat correction_<key> ledger attributes: same records, split into producer / version / parameters instead of one string.

ctdcast.config.cnv_header.detect_instrument(header_text: str) → str | None[source]

Return the CTD model from the header’s first * Sea-Bird … line, or None.

The spelling’s spacing is inconsistent across firmware (SBE 9 vs SBE19plus), so it is normalised to a single space after SBE (SBE19plus → SBE 19plus). Returns None for a header with no such line (a bare hex, a LADCP file, an empty header).

ctdcast.config.cnv_header.header_from_raw_metadata(raw_metadata: str | None) → str | None[source]

Extract the verbatim SBE header text from a stage-1 file’s raw_metadata attr.

raw_metadata is the JSON envelope seasenselib writes and stage 1 carries through: {"schema": ..., "raw_format": "sbe-cnv", "blocks": {"header": "<* and # lines>", ...}}. Returns the blocks.header string, or None if the attribute is absent, is not JSON, or does not carry a header string. The schema string is not required to match, so a schema bump degrades gracefully rather than raising — only a change to the envelope shape yields None.

ctdcast.config.cnv_header.no_reference_tick(key: str, label: str, variables: str = '') → ConformanceTick[source]

Return a dash tick (no documented reference) for a display row.

Parameters:
  • key (str) – The row’s key and display label.

  • label (str) – The row’s key and display label.

  • variables (str, optional) – The variable the step modified, for the display column.

Returns:

A CONFORMANCE_NO_REFERENCE tick.

Return type:

ConformanceTick

ctdcast.config.cnv_header.parse_processing_chain(header_text: str) → ProcessingChain[source]

Parse the # SBE Data Processing module chain into ordered steps.

Module identity is the token before the first _ (datcnv_date -> datcnv), which is correct for every SBE #-block module — they are all single tokens.

A new step starts when the module changes or when a field reappears within the current run. The second rule catches a module run twice as adjacent blocks — the case SBE’s manual explicitly sanctions for Wild Edit — where the module name never changes: the repeat of wildedit_date (or any field already seen) opens a fresh step, so the first run’s parameters are never overwritten. This works even for a dialect that emits no _date line at all, unlike splitting on _date. Repeats are therefore kept, never deduplicated.

Values are split on the first = only, leaving comma-collections and bracketed second fields verbatim. A line that is not key = value is preserved in ProcessingChain.verbatim but adds no step, so an unrecognised dialect degrades to verbatim rather than to an empty chain.

ctdcast.config.cnv_header.parse_sample_interval(header_text: str) → tuple[str | None, float | None][source]

Return the CNV # interval line as (kind, value), or (None, None).

kind is the word Sea-Bird writes, lower-cased: "seconds" for scan-rate or time-averaged data (seconds: 0.0416667 at 24 Hz, seconds: 1 after a 1 s average), "decibars" for pressure-binned data. A .hex header has no such line.

Parameters:

header_text (str) – The verbatim CNV header.

Returns:

The interval’s kind and its value in that kind’s unit.

Return type:

tuple of (str or None, float or None)

ctdcast.config.cnv_header.parse_sensor_block(header_text: str) → list[dict][source]

Parse the CNV <Sensors> config block into one raw record per channel.

The single reader of the block. Each record has channel (int), element (the type tag, e.g. "TemperatureSensor"), sensor_id, serial, calibration_date (verbatim), slope and offset (defaulting "1.0" / "0.0" when absent), comment (the sensor-comment body, e.g. "Temperature, 2" or "Free") for the caller to resolve to a role, and raw_block (the whole <sensor> element verbatim, for provenance). Returns [] for an empty header or one with no <Sensors> block. Role interpretation and calibration-date normalisation are the reader’s concern (see ctdcast.readers.metadata.parse_sensor_channels()), so they stay out of here to keep the parser free of the sensor-role vocabulary.

ctdcast.config.cnv_header.parse_star_block(header_text: str) → Acquisition[source]

Parse the * acquisition block of an SBE CNV/HEX header.

Recognised lines populate the typed fields; every * line (bar the sensor XML) is preserved in Acquisition.verbatim. Unrecognised lines are not fatal. Absence of the deck-unit line yields an empty DeckUnit.

ctdcast.config.cnv_header.parse_start_time(header_text: str) → StartTime[source]

Parse # start_time and resolve its bracket to a (clock, anchor) pair.

The provenance bracket is optional: a start_time line without one still yields its timestamp value, with clock/anchor "unknown". A file with no start_time line at all (e.g. a raw HEX, which carries no # block) returns value=None.

ctdcast.config.cnv_header.pressure_filter_reference_tick(key: str, label: str, time_constant: float, variables: str = '') → ConformanceTick[source]

Compare a low-pass time constant applied to pressure with SBE’s documented 0.15 s.

The same reference and tolerance as the Sea-Bird filter rows.

Parameters:
  • key (str) – The row’s key and display label.

  • label (str) – The row’s key and display label.

  • time_constant (float) – The applied time constant (s).

  • variables (str, optional) – The variables the filter changed, for the display column.

Returns:

A match (✓) or differ (✗) tick citing SBE manual p.100.

Return type:

ConformanceTick

ctdcast.config.cnv_header.provenance_advisories(header_text: str) → list[str][source]

Structural implications of the SBE ledger — what the file is and what was done.

Each is a fact about the cast and its consequence, not a comparison to any recommendation. The single source for both a stage-1 warning and the note under the cast-page provenance table, so the two never drift. (The SBE-conformance check — where a cast deviates from Sea-Bird’s published recommendation — is a separate, later concern and deliberately not here.)

ctdcast.config.cnv_header.raw_metadata_block(raw_metadata: str | None, name: str) → str | None[source]

Return one named text block of a stage-1 raw_metadata envelope, or None.

Parameters:
  • raw_metadata (str or None) – The raw_metadata attribute (JSON).

  • name (str) – The block: "header" (CNV or .hex header) or "xmlcon" (a .hex cast’s .xmlcon).

Returns:

The block’s text; None if the attribute is absent, not JSON, or has no non-empty string under blocks.<name>.

Return type:

str or None

ctdcast.config.cnv_header.sbe_history_notes(header_text: str) → list[SbeHistoryNote][source]

Return one history note per timestamped SBE Data Processing module, file order.

Attributed to Sea-Bird so a stage-1 file’s history shows what SBE did before ctdcast, oldest-first. A module with no _date line — the third-party dialect that emits none — is skipped, because a history line needs a stamp and it has none: such a module still appears in correction_<module> and sbe_processing_order but not in history. The deck-unit align has no timestamp either and is recorded only as correction_align. The note body is the same summary the ledger uses.

ctdcast.config.cnv_header.sensor_calibrations(header_text: str) → list[SensorCalibration][source]

Read each frequency sensor’s drift Slope/Offset from the CNV <Sensors> config.

Surfaces whether a drift or span correction is already baked into the data before ctdcast read it (see SensorCalibration). A projection over parse_sensor_block(): only temperature, conductivity and pressure sensors are returned, in config order; voltage sensors are skipped because their Slope/Offset is a native calibration rather than a datcnv drift knob. Dual sensors are labelled <kind>_1/<kind>_2 and a lone sensor keeps the bare kind. Returns an empty list for an empty header or a header with no <Sensors> block.

ctdcast.config.cnv_header.stacked_advances(header_text: str) → list[StackedAdvance][source]

Return each conductivity that Align CTD advanced again after the deck unit advanced it.

The SBE 11plus deck unit advances primary and secondary conductivity in hardware (0.073 s by default), so the advance is already in the raw scans. An alignctd advance of the same channel adds to it. That can be deliberate (a residual found from the data), but more often the deck unit’s advance has been applied twice.

Parameters:

header_text (str) – The verbatim CNV header.

Returns:

In the order the channels appear in the alignctd step; empty when nothing stacks.

Return type:

list of StackedAdvance

ctdcast.config.cnv_header.start_time_clock(bracket: str) → str[source]

Classify a time_coordinate_source bracket to its clock: system/nmea/unknown.

The public single point of truth for “which clock is the time coordinate anchored to”, used by the stage-2 clock applier’s gate so it does not re-parse the bracket with a fragile substring. An empty or unrecognised bracket resolves to "unknown".

sbe_steps turns the SBE Data Processing steps recorded in a CNV header into the equivalent data_processing: steps, in the order they ran, with each step’s parameters and ctdcast’s variable names — the starting point for reproducing a cruise’s own CNVs from its .hex files.

Translate a CNV header’s SBE Data Processing steps into ctdcast data_processing steps.

A Sea-Bird CNV records every module that ran on it (# wildedit_date, # filter_low_pass_tc_A, …). processing_steps() turns that record into the list of steps ctdcast’s stage 3 understands, in the order the modules ran, with the parameters each used and SBE channel names replaced by ctdcast’s variable names. It is how a cruise’s own processing is reproduced from the .hex: read the CNV the cruise made, write the equivalent data_processing: block, run it, compare.

Each step is a one-key mapping {module: parameters}; a module that ran twice gives two steps. Sea-Bird’s Filter, which applies two time constants (A and B) in one run, becomes two filter steps. Modules that are not steps in ctdcast are reported in skipped with the reason: datcnv (stage 1), Derive (ctdcast derives salinity, density and oxygen itself), strip (a product’s variable list) and bottlesum (bottle files). One CNV header shows only the processing that produced that file; a cruise’s other products have their own headers.

ctdcast.config.sbe_steps.SKIPPED_MODULES: dict[str, str] = {'asciiout': 'file format only', 'bottlesum': 'bottle files, not the profile', 'datcnv': 'conversion to engineering units: stage 1', 'derive': 'ctdcast derives salinity, density and oxygen itself after every change', 'rossum': 'bottle files, not the profile', 'seaplot': 'plotting only', 'strip': "a product's variable list, not a processing step", 'translate': 'file format only'}

SBE modules with no ctdcast step, and why.

ctdcast.config.sbe_steps.header_text_of(path: str | Path) → str[source]

Return a CNV file’s header, everything before *END*.

Parameters:

path (str or os.PathLike) – The CNV file.

Returns:

The header lines, joined.

Return type:

str

ctdcast.config.sbe_steps.processing_steps(header_text: str, rename_map: dict[str, str] | None = None) → dict[str, list][source]

Return the ctdcast processing steps equivalent to a CNV header’s SBE Data Processing steps.

Parameters:
  • header_text (str) – The CNV header (everything up to *END*).

  • rename_map (dict of str to str, optional) – {sbe_column_name: variable_name} for this file, when known; otherwise the static aliases are used and an unmapped channel keeps its SBE name.

Returns:

{"steps": [...], "products": [{"name": ..., "steps": [...]}, ...], "skipped": [...]}: the steps in run order up to the file’s first Split or Bin Average, the rest as a product (two, one per leg, after a Split), and the modules that are not steps, each {"module": ..., "reason": ...}. An SBE module ctdcast has no translation for is listed in skipped with the reason "not translated".

Return type:

dict

ctdcast.config.sbe_steps.processing_yaml(header_text: str, rename_map: dict[str, str] | None = None) → str[source]

Return processing_steps() as a paste-ready data_processing: YAML block.

Parameters:
  • header_text (str) – The CNV header.

  • rename_map (dict of str to str, optional) – As for processing_steps().

Returns:

YAML with the steps under data_processing.steps, the skipped modules as comments.

Return type:

str

layout reads a config.yaml into the settings the stages use, from the current layout or, for one release, the 0.4 one.

Read a cruise config.yaml into the settings the stages use, whichever layout it is in.

The config is split by what each block does:

preferred_sensor:          # which sensor the plain ctd_temperature / ctd_salinity / ctd_oxygen use
  tc: primary              # the temperature/conductivity pair; bare value or {default:, ranges:}
  oxygen: primary
clock: {...}               # the acquisition-clock correction (stage 2)
qc: {gross_range: {...}, spike: {...}}
fit: {...}                 # how ``ctdcast fit`` searches; nothing here is applied
data_processing:           # what ctdcast applies to the data
  slope_offset: {...}      # per conductivity sensor: C' = slope * C + offset
  oxygen: {tau_window_seconds: 2.0}
  steps:                   # in the order they run
    - wildedit: {...}
    - alignctd: {...}
    - celltm: {...}
processing:                # stage-2 trim and the profiles grid, unchanged
  trim: {...}
  profiles_dbar: 1

Ranges in preferred_sensor take value:, as every other range does.

processing_view() turns this into the one dict the stages read. The 0.4 layout (everything under processing:) is read for one more release, with a DeprecationWarning per key: processing.preferred_pair / preferred_oxygen, processing.clock, processing.qc and processing.calibration.conductivity_slope (one slope for both sensors, offset 0). Blocks that never shipped in a release (processing.alignctd, celltm, oxygen, fit) are refused with the place they moved to.

ctdcast.config.layout.processing_view(cfg: dict | None) → dict[source]

Return the settings the stages read, from a config file of either layout.

Parameters:

cfg (dict or None) – The whole parsed config.yaml.

Returns:

processing: (trim, profiles_dbar) plus preferred_pair, preferred_oxygen, clock, qc, fit and data_processing from wherever the file declares them. The input is not changed.

Return type:

dict

Raises:

ValueError – For a processing: key that moved before it was ever released, naming its new place; or a key given in both layouts.


Acquisition-clock diagnostic

clock reads each cast’s System/NMEA clock pair off the header and classifies the cruise’s clock error (constant, step, drift, or too little to tell), recursively segmenting the whole-second offsets into levels and claiming a drift only when a rate positively fits. It is read-only — it finds the error and generates a paste-ready clock block; applying the correction is a stage-2 step.

Cruise-scale acquisition-clock diagnostic: per-cast NMEA-vs-System offsets, changepoints, verdict.

Reads the acquisition (System) and GPS (NMEA) clock pair off each cast’s raw Sea-Bird header — already on every stage-1 file in raw_metadata — and classifies the cruise’s clock error as a constant offset, a drift, or one or more step changes. Read-only: this finds the error; whether a correction is applied is a separate stage-2 decision, and turns not only on the kind here but on whether the time coordinate is already on GPS (start_time sourced from NMEA) — the two are orthogonal.

Sign convention, stated once because a sign error here is silent and catastrophic: offset = NMEA - System — the seconds added to acquisition time to obtain corrected (GPS) time. Positive means the acquisition clock ran behind GPS. This matches oceanarray’s _apply_clock_offset, so the value transfers without a flip.

The offsets are whole seconds, so structure is read as a histogram of levels, not a fitted line: three contiguous casts at one value are a level, not scatter. classify_offsets() recurses, splitting at each detected step until every segment is flat (sd below the quantisation). A segment that will not flatten is a drift only if a rate positively fits it — otherwise it is a noisy level, reported as a constant/step with a resolution caveat rather than a drift. classify_offsets() is pure; clock_offsets() reads the cast files.

class ctdcast.analysis.clock.CastClock(cast_id: str, system_utc: datetime, nmea_utc: datetime, offset_seconds: float)[source]

One cast’s acquisition/GPS clock pair, with both raw times so the sign is checkable.

Carries both times and the cast id (not just the derived offset): the per-cast table shows both so a reader can confirm the sign, and segments are labelled by cast range.

cast_id: str
nmea_utc: datetime
offset_seconds: float
system_utc: datetime
class ctdcast.analysis.clock.ClockSegment(first_cast: str, last_cast: str, start: datetime, end: datetime, offset_seconds: float, sd_seconds: float, n_casts: int)[source]

A run of casts sharing one clock offset, between changepoints — one row of the segment table.

property cast_range: str

Cast-id span as "001-003" (or just "001" for a single-cast segment).

end: datetime
first_cast: str
last_cast: str
n_casts: int
offset_seconds: float
sd_seconds: float
start: datetime
class ctdcast.analysis.clock.ClockVerdict(kind: str, segments: list[ClockSegment], note: str, resolution_caveat: str = '')[source]

The cruise’s clock classification: kind, level segments and a plain-language note.

kind is "constant", "drift", "step", "no_clock_pair" or "insufficient". "drift" is claimed only when a rate is measured (the note quotes slope, R² and residual sd) — failing to resolve into flat segments is not evidence of a rate, so a merely noisy cruise is a "constant" (or "step") with a resolution caveat, never a drift. "no_clock_pair" (files scanned, none carrying a pair) is distinct from "insufficient" (too few casts, or no files) so a renderer selects on kind alone, never on the note prose. resolution_caveat is non-empty when a segment’s sd exceeds the quantisation: a statement about resolution (per-cast comparison noise, or possibly-hidden structure), carried beside the verdict rather than as a verdict of its own. Changepoints are exposed via changepoints.

property changepoints: list[datetime]

Acquisition times of the segment boundaries (empty unless the verdict is a step).

kind: str
note: str
resolution_caveat: str = ''
segments: list[ClockSegment]
ctdcast.analysis.clock.cast_number(cast_id: str) → int[source]

Integer cast number from a formatted cast id ("001" -> 1, "029b" -> 29).

ctdcast.analysis.clock.classify_offsets(series: list[CastClock], *, n_scanned: int | None = None) → ClockVerdict[source]

Classify a cruise’s offset series (sorted by acquisition time) into a ClockVerdict.

Recursively segments the series and reads the result: one segment is a constant, several are a step. A segment that will not flatten triggers a rate test — only a rate that positively fits is a drift; otherwise the segments stand and the non-flat sd becomes a resolution caveat (per-cast comparison noise, or possibly-hidden structure). n_scanned, when given, is reported in the too-few message so a reader can tell “no clocks in these headers” from “few casts present”; the cause of an empty result is not asserted here.

ctdcast.analysis.clock.clock_offsets(root: Path | str) → tuple[list[CastClock], int, dict[str, int]][source]

Return the casts carrying both clocks, the number of casts scanned, and a coordinate census.

Discovers casts with group_by_cast(), the same best-available machinery the report uses, so it works across the nested stageN/ layout, a flat nc_dir, or a tree processed only to stage 2/3 — and skips compiled products and unnumbered files. The header (raw_metadata) rides every stage, so the raw clock pair is read from each cast’s stage-1 file when present, else its lowest available stage. A cast whose clock is missing/unparseable is skipped and counted in a single warning. The census counts which clock each cast’s start_time bracket anchors the coordinate to (system vs nmea) — the fact the stage-2 gate keys on, orthogonal to the offset structure. Only determined sources are counted; a bracketless header ("unknown") is left out rather than tallied as a source it never named.

ctdcast.analysis.clock.coordinate_summary(coordinate_counts: dict[str, int], scanned: int) → str[source]

One line stating which clock the time coordinate is anchored to, and the correction consequence.

Orthogonal to the offset verdict: a cruise can show a real offset yet need no correction because its coordinate was already on GPS (OdB). Reports the count, not a single answer — mixed values across a cruise are themselves a finding. nmea needs no correction; system is where a non-zero offset would be applied.

ctdcast.analysis.clock.correction_status(coordinate_counts: dict[str, int]) → str[source]

Whether a clock correction applies, from the coordinate census: apply/on_gps/undetermined.

The single source of truth for the gate both the CLI and the report read, so they cannot disagree. Any cast on the System clock means a correction is relevant (apply); a coordinate only ever on GPS needs none (on_gps); an empty census means no start_time bracket was parsed, so whether a correction applies is undetermined — which must NOT be reported as “already on GPS”, a source that was never measured.

ctdcast.analysis.clock.suggested_config_yaml(verdict: ClockVerdict) → str | None[source]

Paste-ready clock YAML for a step/constant verdict, or None if inapplicable.

One segments entry per segment, keyed on inclusive cast-number ranges (the ctd_groupings.yaml idiom). Returns None for drift (no applier), no_clock_pair and insufficient. The sign is emitted so it is copied, never hand-computed — that is the one thing here that is silently catastrophic to get backwards. A [[lo, hi]] range expands to plain casts only, so a segment holding lettered casts (029b) or gaps gets a warning comment to verify by hand rather than silently mis-scoping the correction.

Each segment also carries n_casts and clock_offset_sd_seconds — the evidence that justified the offset. The applier records these with the correction so the number’s uncertainty travels with it; sourcing them here (not from a re-measurement at apply time) keeps the recorded statistics describing the population that actually produced the number.


Section manifest

Each report page is described by a Profile of Section and Panel entries, resolved by resolve() into a numbered, rendered report. The model is package-neutral; each page’s concrete registry lives in its own generator module.

Section-manifest model and resolver for report pages.

A report page is described by a Profile: an ordered sequence of Section (and Expand) entries, each naming Panel ids that render figures or tables. resolve() walks a profile once against a render context and returns a ResolvedReport whose sections are numbered over the rendered subset — absent sections leave no gap, and identity is the section id (a stable slug), not the integer.

This module holds only the model and the resolution algorithm — it is package-neutral (names no variable, page, or science) and is vendored byte-identical to the sister repos. Each page’s concrete registry (its Ctx builder, panels, sections, and profiles) lives in that page’s own module — grid’s in reports/_grid.py, and so on — never in a plural _manifests.py companion.

class ctdcast.reports._vendored.page_model.Expand(over: Callable[[Any], Sequence[Any]], section: Callable[[Any], Section])[source]

A single manifest entry that becomes N sections at resolution time.

Parameters:
  • over (Callable) – Returns the sequence of items to expand over (e.g. the variables present on the page, in display order).

  • section (Callable) – Builds one Section per item yielded by over.

over: Callable[[Any], Sequence[Any]]
section: Callable[[Any], Section]
class ctdcast.reports._vendored.page_model.Panel(id: str, render: ~collections.abc.Callable[[~typing.Any], str | ~ctdcast.reports._vendored.page_model.Stub | None], kind: ~typing.Literal['figure', 'html', 'table'] = 'figure', slot: str | ~collections.abc.Callable[[~typing.Any], str] | None = 'full', caption: str | None = None, applies_to: ~collections.abc.Callable[[~typing.Any], bool] = <function _always>, unavailable_if: ~collections.abc.Callable[[~typing.Any], str | None] = <function _unavailable_never>)[source]

One figure or table, addressable by id.

Parameters:
  • id (str) – Unique panel identifier, e.g. "temperature_field". Also the anchor a caption or cross-reference can point at.

  • render (Callable) – Adapter that returns the panel’s payload — a base64 PNG string for a "figure", or ready-to-emit markup for "html"/"table" — or None when the panel applies but no output could be produced (a plot raised, or the variable is absent), which the resolver turns into a .warn stub. May instead return a Stub to carry the reason the panel is empty, so the stub says why. Figure adapters wrap the existing _make_*_b64 functions unchanged.

  • kind ({"figure", "html", "table"}, optional) – Content discriminator. The template macro branches on it so that only "html"/"table" payloads are emitted |safe; a "figure" payload is always escaped into an image src.

  • slot (str or Callable or None, optional) – SLOTS key giving the panel’s display width, or a callable ctx -> slot that computes it (e.g. from a section’s aspect ratio). Belongs to the panel, not the section, so a panel is the same width wherever it is placed. The resolver calls it when callable. None marks a figure that is not rendered through the slot system: it is emitted as a bare .fig that fills the content column (no slot-* class, so no rendered-width contract).

  • caption (str, optional) – Caption text rendered beneath the panel.

  • applies_to (Callable, optional) – Predicate deciding whether the panel is attempted at all. False omits the panel silently (it is excluded, not merely unavailable).

  • unavailable_if (Callable, optional) – Precondition checked before render: given the context, return a reason string when the panel applies but cannot be produced (e.g. a required metadata field is missing), or None to proceed. A returned reason becomes a .warn stub with that reason and render is not called. This is the channel for defects knowable from context; a render that still returns None gets the generic stub reason, because that is the “should have worked and didn’t” case.

applies_to() → bool

Return True for any context (the default applies_to predicate).

caption: str | None = None
id: str
kind: Literal['figure', 'html', 'table'] = 'figure'
render: Callable[[Any], str | Stub | None]
slot: str | Callable[[Any], str] | None = 'full'
unavailable_if() → str | None

Return None for any context (the default unavailable_if predicate).

class ctdcast.reports._vendored.page_model.PanelGroup(over: Callable[[Any], Sequence[Any]], panel: Callable[[Any], Panel])[source]

A Section.panels entry that expands to N panels at resolution time.

Places a data-driven run of panels — one per item — under a single heading without inflating the section count. Use this (not Expand) when the run is over a numeric or unbounded set, e.g. one panel per isopycnal; reserve Expand’s section-level expansion for a closed editorial vocabulary. Numbering reflects editorial structure, not data cardinality.

Parameters:
  • over (Callable) – Returns the sequence of items to expand over, in display order.

  • panel (Callable) – Builds one Panel per item yielded by over.

over: Callable[[Any], Sequence[Any]]
panel: Callable[[Any], Panel]
ctdcast.reports._vendored.page_model.PanelKind

Panel content kinds. "figure" renders a base64 PNG (escaped as an image src); "html" and "table" render pre-built markup that the template macro emits with |safe. The discriminator keeps the autoescape=True boundary to one auditable branch — a figure payload is never |safe-d.

alias of Literal[‘figure’, ‘html’, ‘table’]

class ctdcast.reports._vendored.page_model.Profile(numbering: str = 'flat', entries: tuple[~ctdcast.reports._vendored.page_model.Section | ~ctdcast.reports._vendored.page_model.Expand, ...]=<factory>)[source]

An ordered page description plus a numbering policy.

Parameters:
  • numbering (str) – "flat" (content 1..N, appendices A..), "none" (no numbers), or "grouped" (reserved — not yet implemented).

  • entries (tuple of (Section or Expand)) – The page’s sections, in order.

entries: tuple[Section | Expand, ...]
numbering: str = 'flat'
ctdcast.reports._vendored.page_model.RenderContext

A page’s render context, threaded opaque through the resolver: the concrete keys are decided by each page’s own registry (grid’s Ctx, etc.), never by this package-neutral module. Named once so the resolver signatures read ctx: RenderContext with no per-signature noqa, and any future narrowing lands in one place.

class ctdcast.reports._vendored.page_model.ResolvedPanel(id: str, kind: Literal['figure', 'html', 'table'], slot: str | None, payload: str | None, caption: str | None, stub_reason: str | None = None)[source]

A panel after rendering: a payload (figure b64 or markup) or a .warn stub.

caption: str | None
id: str
property is_stub: bool

True when the panel applied but produced no output.

kind: Literal['figure', 'html', 'table']
payload: str | None
slot: str | None
stub_reason: str | None = None
class ctdcast.reports._vendored.page_model.ResolvedReport(sections: tuple[ResolvedSection, ...], not_applicable: tuple[str, ...])[source]

The full resolved page: numbered sections plus the not-applicable list.

anchor(section_id: str) → str | None[source]

Return the display number for section_id, or None if not rendered.

not_applicable: tuple[str, ...]
sections: tuple[ResolvedSection, ...]
class ctdcast.reports._vendored.page_model.ResolvedSection(id: str, number: str, title: str, level: int, intro: str | None, panels: tuple[ResolvedPanel, ...], role: str, layout: str | None = None)[source]

A section after resolution: numbered heading plus resolved panels.

id: str
intro: str | None
layout: str | None = None
level: int
number: str
panels: tuple[ResolvedPanel, ...]
role: str
title: str
class ctdcast.reports._vendored.page_model.Section(id: str, title: str, panels: tuple[str | PanelGroup, ...], level: int = 2, intro: str | None = None, applies_to: Callable[[Any], bool] | None = None, role: str = 'content', layout: str | None = None)[source]

A numbered heading and the panels beneath it.

Parameters:
  • id (str) – Unique section identifier, e.g. "hydrography". Doubles as the anchor and the cross-reference key.

  • title (str) – Human-readable heading text (without a number — the number is computed).

  • panels (tuple of (str or PanelGroup)) – Panel ids, in display order. An entry may instead be a PanelGroup, which expands to a data-driven run of panels under this one heading.

  • level (int, optional) – Heading level (2 for <h2>).

  • intro (str, optional) – Introductory prose rendered under the heading, before the panels.

  • applies_to (Callable, optional) – Predicate deciding whether the section is included. When None (default), the section applies if any of its panels apply. A section dropped here is named in the report’s “not applicable” footer line.

  • role (str, optional) – "content" (numbered 1..N) or "appendix" (numbered A..), so appendix material such as a NetCDF-variable table does not pad the science numbering.

  • layout (str, optional) – Within-section panel arrangement. None (default) stacks panels vertically; "row" lays them out in a wrapping flex row, each panel in a cell sized by its slot (so two slot="half" figures sit side-by-side and a slot="full" one wraps to its own line).

applies_to: Callable[[Any], bool] | None = None
id: str
intro: str | None = None
layout: str | None = None
level: int = 2
panels: tuple[str | PanelGroup, ...]
role: str = 'content'
title: str
class ctdcast.reports._vendored.page_model.Stub(reason: str)[source]

Returned by a panel’s render when the panel applies but could not be produced.

Carries the reason the panel is empty (e.g. the exception a draw function raised) so the page can say why a panel is absent, not merely that it is. A bare None from render still means the generic stub. The reason is shaped on construction to a single line, capped at _STUB_REASON_LIMIT characters.

Parameters:

reason (str) – Human-readable cause, appended to the generic stub text as "applicable but unavailable: <reason>" by _resolve_panels().

classmethod from_exc(exc: BaseException) → Stub[source]

Build a stub from an exception: its message, or its type name if blank.

reason: str
ctdcast.reports._vendored.page_model.resolve(profile: Profile, ctx: Any, panels: dict[str, Panel], *, drop_stub: bool = False) → ResolvedReport[source]

Resolve profile against ctx into a numbered ResolvedReport.

One pass: expand Expand entries, drop sections whose applies_to is false (collecting them for the not-applicable footer), resolve each kept section’s panels (None render → .warn stub), then number the survivors — content sections 1..N and appendix sections A...

Parameters:
  • profile (Profile) – The page’s ordered section description and numbering policy.

  • ctx (Any) – The render context passed to every predicate and render callable (dataset, config, paths — whatever the page’s panels need).

  • panels (dict of str to Panel) – The panel registry; section panels entries are ids into this map.

  • drop_stub (bool, optional) – When True, a section that applies but whose panels are all stubs (applicable-but-entirely-unavailable) is dropped and the survivors renumber over it, so the page closes cleanly. Default False keeps the heading with its stub, which surfaces the failure rather than hiding it. A section dropped this way is not added to not_applicable — that list stays reserved for genuinely-not-applicable-to-this-deployment sections, so a plot failure never reads as “not applicable”. A section with any non-stub panel is never dropped.

Returns:

Numbered, rendered sections plus the titles of any omitted sections.

Return type:

ResolvedReport

Raises:
  • NotImplementedError – If profile.numbering == "grouped" (reserved for a later branch).

  • KeyError – If a section references a panel id absent from panels.

ctdcast.reports._vendored.page_model.validate_nav(nav: Mapping) → None[source]

Raise ValueError unless the nav mapping is well formed.

The nav is a plain mapping built per page:

{"rows": [{"label": str, "pills": [pill, ...]}, ...],
 "back": pill | None,
 "inventory": [pill, ...]}

where a pill is {"label", "href", "role", "state"}. The checks: at most one pill across the rows and the inventory strip has state == "current" (two would be an ambiguous highlight; zero is valid — an inventory page rendered without its own strip highlights nothing and still shows the row to get back); every pill’s role is a ROLE_ACCENT key; every pill has a state (required, not defaulted) that is one of link/current/missing; every link pill has a non-empty href. The back up-link is field-checked but is not counted toward the current tally.

Parameters:

nav (collections.abc.Mapping) – The per-page nav mapping described above.

Raises:

ValueError – If any check fails, with a message naming the offending pill.


Page generators

Tier-2: generate a per-cast HTML report page.

ctdcast.reports.cast.generate_station_page(nc_path: Path, out_dir: Path, all_meta: list[dict[str, Any]], prev_cast_str: str | None = None, next_cast_str: str | None = None, force: bool = False, ladcp_dir: Path | None = None, ladcp_pattern: str | None = None, cast_num_str: str | None = None, sal_range: tuple[float, float] | None = None, trim_soak: bool = False, cast_notes: list[str] | None = None, cruise_info: dict | None = None, drop_stub: bool = False, inventory: list[dict[str, str]] | None = None, generated_at: str | None = None, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'}))) → Path | None[source]

Generate a per-cast HTML report page and write it to out_dir/casts/.

Parameters:
  • nc_path – Path to a single cast .nc file.

  • out_dir – Root output directory.

  • all_meta – List of dicts with keys lat, lon for all casts (used for map).

  • prev_cast_str – Full cast identifier string of the previous cast for nav links, e.g. "010" or "004b" (or None for no previous link).

  • next_cast_str – Full cast identifier string of the next cast for nav links (or None).

  • force – Overwrite existing file if True.

  • ladcp_dir – Directory containing processed LADCP .mat files named NNN.mat or NNNb.mat. If None or no matching file exists, LADCP panels are omitted.

  • ladcp_pattern – Optional filename glob for non-standard LADCP naming conventions, e.g. "msm_142_1_*.mat". The * is replaced with the zero-padded cast number. Falls back to glob-based discovery when omitted.

  • cast_num_str – Full cast identifier string, e.g. "011" or "004b". Derived from nc_path if not provided.

  • sal_range – (sal_min, sal_max) — records with ctd_salinity_1 outside this range are excluded from all plots (but the NC file is not modified). The count of excluded records is shown in the page header.

  • trim_soak – If True, apply pre-soak detection via find_soak_end(). Finds the last record within 10 dbar of the surface before the cast maximum depth, crawls back up to 20 seconds to the shallowest point preceding the real descent, and trims everything up to that point. Applied before sal_range trimming. NC files are not modified.

  • cast_notes – Optional list of free-text notes for this cast (e.g. “SBE43 malfunction”). Rendered as warning banners near the top of the page.

  • cruise_info (dict | None) – Optional cruise-level metadata used in the page header.

  • drop_stub (bool) – If True, omit sections whose figure returned None instead of rendering a stub.

  • inventory (list of dict or None) – The “Data inventory:” strip pills ({"label", "href"}) shown beneath the masthead; see inventory_pills().

  • generated_at (str or None) – Page build stamp; None uses the current UTC time. Threaded from ctdcast.report() so one build stamps every page identically.

  • cfg (ReportConfig) – Report configuration (styling, paths, display options) threaded to the plotters.

Return type:

Path to the written HTML file, or None on failure.

Tier-2: generate a per-section HTML report page.

ctdcast.reports.section.generate_section_page(section_name: str, section_cfg: dict[str, Any], profiles_path: Path, out_dir: Path, force: bool = False, section_style: str = 'pcolormesh', vmin_override: dict[str, float] | None = None, vmax_override: dict[str, float] | None = None, ladcp_dir: Path | None = None, ladcp_pattern: str | None = None, dbar_step: int = 1, prev_name: str | None = None, next_name: str | None = None, cruise_info: dict[str, Any] | None = None, inventory: list[dict[str, str]] | None = None, generated_at: str | None = None, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'}))) → Path | None[source]

Generate a section HTML report page.

Parameters:
  • section_name – Key from ctd_sections.yaml, e.g. "KTout".

  • section_cfg – Dict with keys description, cast_numbers, color.

  • profiles_path – Path to profiles.nc (built by cnv_build_profiles.py).

  • out_dir – Root output directory.

  • force – Overwrite existing file if True.

  • section_style – "pcolormesh" or "contourf" — passed through to each section figure.

  • vmin_override – Per-variable colormap limit overrides (e.g. {"SA": 34.5}).

  • vmax_override – Per-variable colormap limit overrides (e.g. {"SA": 34.5}).

  • ladcp_dir – Directory containing processed LADCP .mat files. If None, the LADCP velocity section panel is omitted.

  • ladcp_pattern – Filename pattern for LADCP files, e.g. "msm_142_1_*.mat". The * is replaced with the zero-padded cast number. Falls back to NNN.mat if not given.

  • dbar_step – Subsample the pressure axis by this step before plotting (default 1, no subsampling). build_profiles() always stores 1-dbar data; this controls plot-time resolution only.

  • prev_name – Name of the preceding section (for the ← nav button). None omits the button.

  • next_name – Name of the following section (for the → nav button). None omits the button.

  • cruise_info – Cruise-level metadata mapping used in the page header; None omits it.

  • inventory – The “Data inventory:” strip pills ({"label", "href"}) shown beneath the masthead; see inventory_pills().

  • generated_at – Page build stamp; None uses the current UTC time. Threaded from ctdcast.report() so one build stamps every page identically.

  • cfg – Report configuration (styling, paths, display) threaded to the plotters.

Return type:

Path to the written HTML file, or None on failure.

Tier-2: per-group timeseries HTML report pages.

A timeseries in this codebase is a named group of repeat casts at one location (yoyo CTDs, e.g. 24 h of repeated profiles). Config is analogous to sections: a name, a description, and a list of cast numbers.

The cruise-wide stacked overview plots (all casts, station-number x-axis) live on index.html, generated by _index.py. They are not timeseries pages.

ctdcast.reports.timeseries.generate_timeseries_page(ts_name: str, ts_cfg: dict, profiles_path: Path, out_dir: Path, force: bool = False, section_style: str = 'contourf', vmin_override: dict[str, float] | None = None, vmax_override: dict[str, float] | None = None, all_meta: list[dict] | None = None, ladcp_dir: Path | None = None, ladcp_pattern: str | None = None, dbar_step: int = 1, prev_name: str | None = None, next_name: str | None = None, cruise_info: dict[str, Any] | None = None, inventory: list[dict[str, str]] | None = None, generated_at: str | None = None, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'}))) → Path | None[source]

Generate a per-timeseries HTML page for a named group of repeat casts.

Plots both downcast and upcast profiles sorted by time_start on a shared time x-axis. Output: <out_dir>/timeseries/timeseries_<ts_name>.html.

Parameters:
  • ts_name – Group name (used in filename and page title).

  • ts_cfg – Dict with cast_numbers, description, and color keys.

  • profiles_path – Path to profiles.nc.

  • out_dir – Root output directory.

  • force – Overwrite existing file if True.

  • section_style – "pcolormesh" or "contourf".

  • vmin_override – Per-variable colormap limit overrides.

  • vmax_override – Per-variable colormap limit overrides.

  • all_meta – List of per-cast metadata dicts (keys lat, lon, cast_num); used to render a cruise-context location map. If None, no map is shown.

  • ladcp_dir – Directory containing processed LADCP .mat files. If None, the LADCP velocity panel is omitted.

  • ladcp_pattern – Filename pattern for LADCP files, e.g. "msm_142_1_*.mat". The * is replaced with the zero-padded cast number. Falls back to NNN.mat if not given.

  • dbar_step – Subsample the pressure axis by this step before plotting (default 1, no subsampling). build_profiles() always stores 1-dbar data; this controls plot-time resolution only.

  • prev_name – Name of the preceding timeseries group (for the ← nav button). None omits the button.

  • next_name – Name of the following timeseries group (for the → nav button). None omits the button.

  • cruise_info – Cruise-level metadata mapping used in the page header; None omits it.

  • inventory – The “Data inventory:” strip pills ({"label", "href"}) shown beneath the masthead; see inventory_pills().

  • generated_at – Page build stamp; None uses the current UTC time. Threaded from ctdcast.report() so one build stamps every page identically.

  • cfg – Report configuration (styling, paths, display) threaded to the plotters.

Return type:

Path to the written HTML file, or None if skipped or failed.

Tier-2: a per-file netCDF data inventory page.

Unlike the figure report pages, this one answers “what is actually in this file?” for a developer or data reviewer: every coordinate and variable with its dtype, units, CF names, value range and validity, the sensor catalog, and the global attributes grouped into their canonical sections. One page per file, generated for profiles.nc, a per-cast cast NC, or any other ctdcast product.

The tables themselves are built by the package-neutral ctdcast.reports._vendored.nc_tables builders (coordinates, variables grouped by dimension, scalars, the sensor catalog, grouped globals) and rendered by the vendored _nc_tables.html macros. What stays owned here is ctdcast-specific: the QC-exclusion and variable-renaming tables, the sensor linkage/channel tables, and the coverage check that recomputes geospatial_* / time_coverage_* from the data.

read_dataset_meta() extracts the inventory as plain data; generate_dataset_page() renders it to a self-contained HTML file. data_ranges_markup() renders the cast page’s data-ranges appendix through the same vendored variables_tables macro, so it reads identically to the inventory page.

ctdcast.reports.dataset.data_ranges_markup(nc_path: Path) → str | None[source]

Return the cast page’s netCDF data-ranges table as markup, or None when empty.

Built from the same vendored variables_rows builder and variables_tables macro as the inventory page’s “Data variables” section, so the per-cast appendix renders in the same form: variables grouped by dimension, _qc companions folded into their parent, and the full attribute set (including processing_level) behind each row’s disclosure. Every SENSOR_*/sensor_* variable is excluded (_is_sensor_var) — a per-cast file carries the sensor catalog, not the per-profile linkage/channel the inventory page tables separately. Rendered to markup here because the cast template embeds it with |safe.

Parameters:

nc_path (pathlib.Path) – The netCDF file to read.

Returns:

The table markup, or None if the file cannot be read or has no dimensioned variables.

Return type:

str or None

ctdcast.reports.dataset.generate_dataset_page(nc_path: Path, out_path: Path, *, title: str | None = None, cruise: str = '', nav_prefix: str = '', show_nav: bool = False, inventory_pills: list[dict[str, str]] | None = None, current_href: str = '', generated_at: str | None = None, sensors_href: str | None = None) → Path[source]

Render the netCDF inventory of nc_path to a self-contained HTML out_path.

Parameters:
  • nc_path – The netCDF file to inventory.

  • out_path – Destination HTML path (parent directories are created).

  • title – Page title; defaults to the file name.

  • cruise – Cruise identifier shown in the footer; empty for a standalone inspection.

  • nav_prefix – Relative path prefix to the report root for the page-nav links ("" when the page sits beside index.html).

  • show_nav – Render the full report page-nav when True (the in-report cruise inventory page). Standalone inspections leave it False so the nav’s report-relative links are not shown for an arbitrary file.

  • inventory_pills – {"label", "href"} entries for the compiled-file inventory pages (profiles/ladcp/sensors), rendered as a cross-navigation pill bar.

  • current_href – The href of this page, rendered as the non-link active pill.

  • generated_at – Page build stamp; None uses the current UTC time. Threaded from ctdcast.report() so one build stamps every page identically.

  • sensors_href – The SBE sensors page, when the report has one. The page’s Sensors section then explains the sensor variables and links there instead of repeating the tables; None (a standalone inspection) shows the tables here.

Returns:

The written out_path.

Return type:

Path

ctdcast.reports.dataset.read_dataset_meta(nc_path: Path) → dict[str, Any][source]

Read nc_path into a plain-data inventory for the netCDF inventory page.

Opens the file once and runs the vendored nc_tables builders (coordinates, variables grouped by dimension, scalars, the sensor catalog, grouped globals), keeping the owned ctdcast tables (QC exclusions, variable renaming, sensor linkage/channel) and the coverage check alongside them. A renamed variable’s source name also rides each row as original_name (the in-context original → name cell).

Returns a dict with filename, filesize, dims, summary (the headline counts), coords / variables / scalars / sensor_catalog / globals (each {"rows"|"groups", "source"}), sensor_linkage / sensor_channel ({"groups", "source"} from variables_rows() with an including predicate), coverage (the recomputed-bounds check), qc_exclusion and rename_map. On any read error returns {"filename", "error"} so the page can report it rather than failing to generate.

Parameters:

nc_path (pathlib.Path) – The netCDF file to inventory.

Returns:

The inventory, or an error dict on a read failure.

Return type:

dict

ctdcast.reports.dataset.sensor_variable_tables(ds: Dataset) → dict[str, dict[str, Any]][source]

Return the three sensor-variable tables of ds as plain data.

The SENSOR_* catalog (one row per device, via the vendored sensor_rows), and the per-profile sensor_<role> linkage and sensor_channel_<role> channel variables (via the vendored variables_rows with an including predicate, so they render with the same Length / Valid / type columns as the science variables). Shared by the netCDF inventory page and the SBE sensors page, which show the same tables.

Parameters:

ds (xarray.Dataset) – The open dataset.

Returns:

sensor_catalog ({"rows", "source"}), sensor_linkage and sensor_channel (each {"groups", "source"}); empty rows/groups when the file carries none.

Return type:

dict

A page showing a CNV’s SBE Data Processing steps and the equivalent data_processing: block.

Written by ctdcast inspect <file>.cnv -o page.html: the modules in the order they ran, each with the parameters the header records, and the block to paste into the config, with a copy button. Self-contained, like every ctdcast page.

ctdcast.reports.sbe_processing.generate_sbe_processing_page(cnv_path: Path, out_path: Path, *, title: str | None = None, generated_at: str | None = None) → Path[source]

Render a CNV’s SBE Data Processing steps and its data_processing: block to out_path.

Parameters:
  • cnv_path (pathlib.Path) – The Sea-Bird CNV.

  • out_path (pathlib.Path) – Destination HTML path (parent directories are created).

  • title (str, optional) – Page title; defaults to the file name.

  • generated_at (str, optional) – Page build stamp; None uses the current UTC time.

Returns:

The written out_path.

Return type:

pathlib.Path

Tier-2: the cruise “Processing” page — every step applied, over which casts.

Reads the per-profile processing_record that ctdcast.processors.profiles.build_profiles() writes into profiles.nc (one JSON list of steps per cast, from ctdcast.analysis.processing_record) and draws, per stage, one row per run of consecutive casts that used the same setting. A step whose setting changes more than VARIES_AFTER times is drawn as one “varies cast to cast” row with the range of its values and a figure. A row whose setting differs from SBE’s documented value is amber. What a step did on one cast (values marked, scans flagged) is on that cast’s page, not here.

read_processing_tables() extracts the rows as plain data; generate_processing_page() renders them to HTML.

ctdcast.reports.processing.PROCESSING_HREF = 'processing.html'

The page’s href, beside the other pages built from profiles.nc.

class ctdcast.reports.processing.Run(first: str, last: str, first_number: int, row: ProcessingRow | None)[source]

A run of consecutive casts that used one setting of a step.

property casts: str

Return the run as 011 or 011–014.

ctdcast.reports.processing.STAGE_TITLES = {'Sea-Bird': 'Sea-Bird — before ctdcast (from the raw header)', 'product': 'Products', 'stage 1': 'Stage 1 — reading the raw file', 'stage 2': 'Stage 2 — soak and deck', 'stage 3': 'Stage 3 — corrections'}

How each stage is headed on the page.

class ctdcast.reports.processing.StepRows(stage: str, step: str, runs: list[Run] = <factory>, number: int = 0, varies: dict[str, ~typing.Any] | None=None, figure: str | None = None, exceptions: list[dict[str, ~typing.Any]]=<factory>)[source]

One step of one stage over the cruise: its runs, or a “varies” summary.

ctdcast.reports.processing.VARIES_AFTER = 5

A step with more runs of casts than this is drawn as one “varies cast to cast” row.

ctdcast.reports.processing.generate_processing_page(profiles_path: Path, out_path: Path, *, cruise: str = '', nav_prefix: str = '', show_nav: bool = False, inventory_pills: list[dict[str, str]] | None = None, current_href: str = 'processing.html', generated_at: str | None = None) → Path[source]

Render the cruise processing page for profiles_path to out_path.

Parameters:
  • profiles_path (pathlib.Path) – A compiled profiles.nc carrying processing_record.

  • out_path (pathlib.Path) – The HTML file to write; parent directories are created.

  • cruise (str, optional) – Cruise identifier for the title and footer.

  • nav_prefix (str, optional) – Relative path to the report root for the page-nav links.

  • show_nav (bool, default False) – Render the full report page-nav (the in-report page).

  • inventory_pills (list of dict, optional) – {"label", "href"} entries for the pages built from files.

  • current_href (str, default PROCESSING_HREF) – This page’s own pill, rendered as the non-link active one.

  • generated_at (str, optional) – Page build stamp; None uses the current UTC time.

Returns:

The written out_path.

Return type:

pathlib.Path

ctdcast.reports.processing.read_processing_tables(profiles_path: Path) → dict[str, Any][source]

Return the processing page’s tables from profiles.nc, as plain data.

Parameters:

profiles_path (pathlib.Path) – A compiled profiles.nc.

Returns:

filename, n_casts, has_record and stages: a list of (stage, title, [StepRows]) in processing order.

Return type:

dict

The corrections page for temperature and salinity: alignment and cell thermal mass fits.

Drawn from the fits.nc file ctdcast fit writes under the CTD root: a summary table and the suggested processing: block, then the figures — the cruise alignment wells and the per-cast alignment, the cell thermal mass casts and cost surface, and the fits for blocks of consecutive casts.

ctdcast.reports.corrections.generate_corrections_page(fits_path: Path, out_path: Path, *, cruise: str = '', nav_prefix: str = '', inventory_pills: list[dict[str, str]] | None = None, generated_at: str | None = None) → Path[source]

Render corrections_ts.html from a fits.nc file.

Parameters:
  • fits_path (pathlib.Path) – The fits.nc written by ctdcast fit.

  • out_path (pathlib.Path) – The HTML file to write; parent directories are created.

  • cruise (str, optional) – Cruise identifier for the title.

  • nav_prefix (str, optional) – Relative path to the report root for the page-nav links.

  • inventory_pills (list of dict, optional) – The pills from ctdcast.reports._navs.inventory_pills(), including this page’s.

  • generated_at (str, optional) – Page build stamp; None uses the current UTC time.

Returns:

The written out_path.

Return type:

pathlib.Path


Interactive map

Tier-2: self-contained interactive cruise map using Leaflet.js.

Leaflet JS/CSS (~160 KB) is bundled in ctdcast/reports/_vendored/leaflet/ as package data (shared byte-identical across the sibling packages) so the generated leaflet.html requires no internet access at either generation or view time.

If a GEBCO path is configured, GEBCO bathymetry for the cruise region is rendered as an embedded PNG image layer using discrete depth bands (standard oceanographic levels: 0, 100, 200, 500, 1000, 2000, 3000, 4000, 6000 m).

Interaction:
  • Hover cast dot or section line → info panel updates (bottom-left).

  • Click cast dot → navigate directly to station page.

  • Click section line → navigate directly to section page.

  • Scroll or +/− buttons to zoom.

  • Shift+drag to box-zoom (Leaflet built-in).

ctdcast.reports.cruise_map.casts_map_context(all_meta: list[dict[str, Any]], sections_cfg: dict[str, Any] | None) → dict[str, str][source]

Return the JSON strings the casts.html interactive map needs.

Builds the track_map payload, the land-coastline GeoJSON for the data extent, and the fit bounds, each serialised for the template. When the coastline is "null" and cartopy is not installed, warns (RuntimeWarning) so a land-less map traces to a missing optional dependency rather than being silent. A "null" coastline with cartopy present is not flagged — it means the extent simply contains no land (an open-ocean cruise), which the graticule covers.

Returns:

{"casts_map_payload_json", "coastline_json", "map_bounds_json"}. With no located cast the payload is "[]" and the coastline/bounds are "null".

Return type:

dict

ctdcast.reports.cruise_map.casts_map_payload(all_meta: list[dict[str, Any]], sections_cfg: dict[str, Any] | None) → list[dict[str, Any]][source]

Return the vendored track_map payload for casts.html.

One point per cast (track is a single [lat, lon] → circle marker) and one polyline per section (in cast order), each a dict {id, href, color, track, info, link_label}. info is facts only; the macro appends the link_label link to href. Sections are listed before casts so the cast markers draw on top of the section lines.

This overlaps generate_leaflet_map(), which builds the same cast/section geometry in leaflet.html’s own (non-vendored) payload shape; the two stay separate only until V4, when leaflet.html migrates onto this track_map payload and the other builder is deleted rather than merged here.

Parameters:
  • all_meta (list of dict) – Per-cast metadata (cast_num, cast_num_str, lat, lon, time_start, max_depth).

  • sections_cfg (dict or None) – Section definitions (cast_numbers, color, description).

Returns:

The track payload. Casts with no finite position, and sections with fewer than two located casts, are omitted.

Return type:

list of dict

ctdcast.reports.cruise_map.generate_leaflet_map(all_meta: list[dict[str, Any]], sections_cfg: dict[str, Any], out_dir: Path, force: bool = False, ship_track_nc: Path | None = None, cruise: str = 'UNK', inventory: list[dict[str, str]] | None = None, generated_at: str | None = None, cfg: ReportConfig = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'}))) → Path | None[source]

Generate a Leaflet.js interactive cruise map at <out_dir>/leaflet.html.

Always regenerates. When ship_track_nc exists the ship track is loaded, subsampled, and drawn as a grey polyline behind the cast markers.

Parameters:
  • all_meta (list of dict) – Per-cast metadata (lat/lon/time/max depth/…); an empty list returns None.

  • sections_cfg (dict) – Section/grouping definitions (cast_numbers, color, …) used to colour and group the cast markers.

  • out_dir (pathlib.Path) – Report root; the page is written to out_dir / "leaflet.html".

  • force (bool, default False) – Accepted for parity with the other page builders; ignored (the map is always regenerated).

  • ship_track_nc (pathlib.Path or None, optional) – Ship-track netCDF, drawn as a background polyline when present and readable; None or a missing file omits the track.

  • cruise (str, default "UNK") – Resolved cruise identifier, shown in the map page title.

  • inventory (list of dict or None, optional) – The “Data inventory:” strip pills ({"label", "href"}) under the masthead; None omits the strip.

  • generated_at (str or None, optional) – Page build stamp; None uses the current UTC time. Threaded from ctdcast.report() so one build stamps every page identically.

  • cfg (ReportConfig, optional) – Report configuration (bathymetry path, map bounds, …) threaded to the drawers.

Returns:

The written leaflet.html path, or None when all_meta is empty.

Return type:

pathlib.Path or None


QC tables

ctdcast-owned QC table post-processing.

The QC flag-count and threshold tables are built by the vendored ctdcast.reports._vendored.nc_tables (qc_flag_rows() and qc_threshold_rows()) and rendered by its macros, file-driven from each {var}_qc companion’s own flag_values / flag_meanings. This module keeps the two ctdcast-specific pieces: collapsing dual-sensor threshold rows that share identical bounds, and the explanatory note shown with the flag-count table.

ctdcast.reports.qc_tables.QC_FLAG_NOTE = 'Flag 4 (fail) combines two independent exclusions: this variable’s own gross-range and spike tests, and the whole-cast soak / on-deck trim, which flags the same pre-descent and post-recovery scans on every variable. A variable can therefore show flagged samples that its own thresholds did not raise.'

flag 4 is not solely the variable’s own gross-range / spike test — stage 2’s whole-cast soak / on-deck trim sets flag 4 on the same scans of every variable, so a variable can show flagged samples its own thresholds never raised. Owned here (it describes ctdcast’s stage-2 behaviour, not a vendored table rule).

Type:

Explanatory caption shown with the flag-count table

ctdcast.reports.qc_tables.collapse_sibling_rows(rows: list[dict[str, Any]]) → list[dict[str, Any]][source]

Merge dual-sensor threshold rows that share identical thresholds.

conductivity_1 and conductivity_2 with the same bounds are one row, labelled conductivity_* — the thresholds are per-family, so repeating a row per sensor is noise. Siblings whose thresholds differ (e.g. a per-sensor config override) stay separate. First-seen order is preserved.


Report design — colormaps and accent

design is ctdcast’s owned hook onto the vendored report layer: the package accent for the shared CSS, and the effective per-quantity colormap table (vendored family defaults, overridden by ctdcast’s choices, resolved per variable). design_tokens is the vendored source of those family defaults.

ctdcast’s owned report design: the package accent and the effective colormaps.

This is the single owned file that configures the vendored report layer for ctdcast — the vendored modules under reports/_vendored/ name no package. The package accent is applied to the shared CSS generator here, and the family per-quantity colormap defaults are overridden with ctdcast’s own science choices and resolved to a concrete colormap name per variable.

ctdcast.reports.design.CMAPS: dict[str, str] = {'backscatter': 'OrRd', 'chlorophyll': 'YlGn', 'conductivity': 'GnBu', 'density': 'BuPu', 'depth': 'cmo.deep', 'direction': 'twilight', 'oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'par': 'cmo.solar', 'salinity': 'YlGnBu_r', 'speed': 'plasma', 'stratification': 'plasma', 'temperature': 'RdYlBu_r', 'turbidity': 'YlOrBr', 'velocity': 'RdBu_r'}

vendored family defaults, then ctdcast’s overrides.

Type:

Effective per-quantity table

ctdcast.reports.design.CMAP_OVERRIDES: dict[str, str] = {}

ctdcast’s per-quantity colormap overrides on the vendored family defaults — its current science choices. Empty: ctdcast takes the vendored family defaults for every quantity. Add a quantity -> colormap entry here to override one for ctdcast’s science (e.g. a different density map for casts) without touching the shared table; the key must be a quantity in the vendored CMAPS.

ctdcast.reports.design.COVERAGE_TOLERANCE: dict[str, float] = {'lat': 0.001, 'lon': 0.001, 'time': 1.0, 'vertical': 1.0}

Tolerances for the inventory page’s coverage check (file-stated geospatial_* / time_coverage_* versus the values recomputed from the data): a |diff| above the axis tolerance is flagged. Owned here, not vendored — the vertical axis is dbar in ctdcast and metres elsewhere, so the numbers are a per-package judgement. Degrees for lat/lon, dbar for vertical, seconds for time (second-truncated written stamps versus sub-second data times would otherwise flag every cast).

ctdcast.reports.design.CSS_OVERRIDES: dict[str, str] = {}

ctdcast’s overrides on the vendored UI-token defaults — recolours a page role (nav pill + masthead together, role-<key>), the (_QC) marker (qc-mark), or package-accent. Empty: ctdcast keeps the family colours. Each key must be an overridable token (an unknown key raises in emit_css); data palettes (QC flag colours, track colours, colormaps) are not here.

ctdcast.reports.design.FIGURE_SOURCE: bool = True

ctdcast turns the per-figure source: caption ON; the vendored default (design_tokens.SHOW_FIGURE_SOURCE) is OFF. This is the package override — the same pattern as CMAP_OVERRIDES: ctdcast’s choice lives here, not in the shared table. The report env reads it as the show_source template global.

ctdcast.reports.design.ORIGINAL_NAME_ATTRS: tuple[str, ...] = ('original_name', 'cnv_original_name', 'source_variable')

Attribute names, in priority order, that record a variable’s source name for the original → name cell in the inventory tables. original_name is the family-shared spelling ctdcast writes now (CTD and LADCP alike); cnv_original_name (CNV) and source_variable (LADCP) are the pre-0.4.0 spellings, read for older files. The first present and non-empty wins.

ctdcast.reports.design.PACKAGE_ACCENT: str = 'var(--ocean)'

ctdcast’s package accent — chosen here, not in the vendored tokens. Points at --ocean so the accent (wordmark, table header, footer rule) is ocean navy; change this one line to rebrand. Any CSS colour value works.

ctdcast.reports.design.SHARED_CSS: str = ':root {\n  --ocean: #1a3a5c;\n  --seafoam: #e8f4f8;\n  --muted: #95a5a6;\n  --text: #2c3e50;\n  --rule: #dfe6e9;\n  --bg: #ffffff;\n  --bg-sunken: #f7f9fa;\n  --warn: #e67e22;\n  --warn-bg: #fdf3e7;\n  --error: #c0392b;\n  --gray-1: #f5f7fa;\n  --gray-2: #e0e0e0;\n  --gray-3: #aaaaaa;\n  --gray-4: #888888;\n  --gray-5: #555555;\n  --gray-6: #333333;\n  --gray-7: #111111;\n  --ok: #2c6e49;\n  --role-landing: #2980b9;\n  --role-entity: #1a3a5c;\n  --role-collection: #1a3a5c;\n  --role-component: #1a3a5c;\n  --role-aggregate-a: #8e44ad;\n  --role-aggregate-b: #27ae60;\n  --role-map: #ee3377;\n  --role-up: #5d6d7e;\n  --qc-mark: var(--ok);\n  --package-accent: var(--ocean);\n  --font-sans: system-ui, -apple-system, "Segoe UI", sans-serif;\n  --font-mono: ui-monospace, "SF Mono", Menlo, Consolas, "DejaVu Sans Mono", monospace;\n  --fs-root: 14px;\n  --fs-h1: 1.75rem;\n  --fs-type: 1.35rem;\n  --fs-h2: 1rem;\n  --fs-h3: 0.88rem;\n  --fs-meta: 0.84rem;\n  --fs-note: 0.92rem;\n  --fs-nav: 0.8rem;\n  --fs-cap: 0.92rem;\n  --fs-xs: 0.75rem;\n  --fs-top: 0.72rem;\n  --fs-dt: 0.7rem;\n  --lh-root: 1.5;\n  --sp-1: 4px;\n  --sp-2: 8px;\n  --sp-3: 12px;\n  --sp-4: 16px;\n  --sp-5: 24px;\n  --sp-6: 32px;\n  --sp-7: 48px;\n  --radius-card: 8px;\n  --radius-btn: 4px;\n  --radius-pill: 999px;\n  --qc-0: #999999;\n  --qc-1: #009E73;\n  --qc-2: #56B4E9;\n  --qc-3: #E69F00;\n  --qc-4: #D55E00;\n  --qc-7: #CC79A7;\n  --qc-8: #0072B2;\n  --qc-9: #bdbdbd;\n  --qc-3-text: #9A6B00;\n}\n* { box-sizing: border-box; }\nbody {\n  font-family: var(--font-sans);\n  font-size: var(--fs-root); color: var(--text);\n  max-width: 1150px; margin: 0 auto;\n  padding: 1.5rem 2rem 4rem; line-height: var(--lh-root);\n}\np, li { max-width: 78ch; }\n.masthead {\n  background: var(--ocean); color: #fff; position: relative;\n  padding: 1.6rem 2rem; border-radius: var(--radius-card); margin-bottom: 0.9rem;\n}\n.masthead h1 { margin: 0 0 0.3rem; font-size: var(--fs-h1); font-weight: 700; }\n.masthead .sub { font-size: var(--fs-meta); opacity: 0.85; margin: 0 0 0.15rem; max-width: none; }\n.wordmark {\n  position: absolute; right: 2rem; bottom: 1.2rem;\n  font-size: var(--fs-dt); font-weight: 700; letter-spacing: 0.04em;\n  color: var(--package-accent); background: #fff; opacity: 0.85;\n  padding: 0.1rem 0.5rem; border-radius: var(--radius-pill); text-decoration: none;\n}\n.wordmark:hover { opacity: 1; }\n.meta-grid {\n  display: grid;\n  grid-template-columns: repeat(auto-fill, minmax(190px, 1fr));\n  gap: 0.5rem 2rem; font-size: var(--fs-meta); margin-top: 0.9rem;\n}\n.meta-grid dt {\n  opacity: 0.7; text-transform: uppercase; font-size: var(--fs-dt);\n  letter-spacing: 0.06em; margin-bottom: 0.1rem;\n}\n.meta-grid dd { margin: 0; font-weight: 600; }\nh2 {\n  color: var(--ocean); font-size: var(--fs-h2);\n  border-bottom: 2px solid var(--seafoam);\n  padding-bottom: 0.3rem; margin: 2.5rem 0 1rem;\n  display: flex; justify-content: space-between; align-items: baseline;\n}\n.top-link {\n  font-size: var(--fs-top); font-weight: 400; color: var(--muted);\n  text-decoration: none; margin-left: auto;\n}\n.top-link:hover { color: var(--ocean); text-decoration: underline; }\n.caption {\n  color: var(--gray-5); font-size: var(--fs-note);\n  margin-top: 0.75rem; margin-bottom: 0.75rem;\n}\n/* A section intro (the caption directly under a heading) is a lede for the whole\n   figure block, so it spans the content width rather than the 78ch prose measure a\n   paragraph would otherwise inherit — which left it stranded under full-width figures. */\nh2 + .caption { margin-top: -0.5rem; max-width: none; }\n/* Subsection headings inside a panel\'s own HTML — un-numbered, outside the jump\n   nav (the page model numbers Sections, not these).  Same navy as h2, smaller. */\nh3 {\n  color: var(--ocean); font-size: var(--fs-h3); margin: 1.2rem 0 0.4rem;\n}\nh3 + .caption { margin-top: -0.2rem; }\nfigure h3, .fig-row > h3 { margin-top: 0.6rem; }  /* first heading inside a panel sits closer */\n.explainer {\n  font-size: var(--fs-note); color: var(--text);\n  background: var(--bg-sunken); border-left: 3px solid var(--muted);\n  padding: var(--sp-3); margin: -0.25rem 0 0.75rem; border-radius: var(--radius-btn);\n}\n.warn {\n  font-size: var(--fs-note); color: var(--text);\n  background: var(--warn-bg); border-left: 3px solid var(--warn);\n  padding: var(--sp-3); margin-bottom: 0.5rem; border-radius: var(--radius-btn);\n}\n.warn::before { content: "⚠ "; }\n.warn.error { border-left-color: var(--error); }\n.jump-nav {\n  background: var(--seafoam); padding: 0.55rem 1rem;\n  border-radius: 6px; margin-bottom: 1.5rem;\n  font-size: var(--fs-nav); line-height: 2.2;\n}\n.jump-nav::before { content: "Jump to: "; opacity: 0.55; font-size: var(--fs-xs); margin-right: 0.25rem; }\n.jump-nav a {\n  color: var(--ocean); text-decoration: none;\n  font-weight: 600; margin: 0 0.5rem 0 0;\n}\n.jump-nav a::before { content: "▸ "; font-size: var(--fs-dt); }\n.fig-row {\n  display: flex; flex-wrap: wrap; gap: 1rem; margin-bottom: 1.5rem;\n  align-items: flex-start;\n}\n.fig-col { display: flex; flex-direction: column; gap: 0.75rem; }\n.fig-row.center { justify-content: center; }\n/* A multi-table panel (processing provenance) is one full-width flex item so its\n   headings and tables stack instead of tiling across the row. */\n.prov-panel { flex: 1 1 100%; }\n/* Conformance status pips — a green ✓ (matches), a red ✗ (differs) and a neutral\n   ringed dash (no reference), matching the LADCP-present/absent badges. */\n.conf {\n  display: inline-flex; align-items: center; justify-content: center;\n  width: 1.4em; height: 1.4em; border-radius: 50%;\n  font-size: var(--fs-xs); font-weight: 700; line-height: 1;\n}\n.conf-match { background: var(--ok); color: #fff; }\n.conf-differ { background: var(--error); color: #fff; }\n.conf-none { background: #fff; color: #000; border: 1px solid #000; }\nfigure { margin: 0; }\nfigure img {\n  border: 1px solid var(--rule); border-radius: var(--radius-btn);\n  display: block; width: 100%; height: auto;\n}\nfigcaption { font-size: var(--fs-cap); color: var(--gray-5); margin-bottom: 0.25rem; }\n/* Optional provenance line under a figure: which draw function produced it.\n   Off by default (vendored SHOW_FIGURE_SOURCE); a package turns it on in its\n   owned design module. */\n.fig-source {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: var(--fs-xs); color: var(--muted); margin-top: 0.15rem;\n}\n/* A stub panel\'s warning fills the figure slot it stands in for, rather than the\n   78ch prose reading measure it would otherwise inherit as a paragraph. */\nfigure .warn { max-width: none; }\ntable {\n  width: 100%; border-collapse: collapse;\n  font-size: var(--fs-note); margin: 0.6rem 0 1.2rem;\n}\nth {\n  background: var(--package-accent); color: #fff; text-align: center;\n  font-weight: 600; padding: 0.4rem 0.65rem;\n}\nth.num { text-align: right; }\ntd {\n  padding: 0.35rem 0.65rem; border-bottom: 1px solid var(--rule);\n  vertical-align: top;\n}\ntr:nth-child(even) td { background: var(--bg-sunken); }\ntd.num, .num { text-align: right; font-variant-numeric: tabular-nums; }\ntd.mono { font-family: var(--font-mono); font-size: var(--fs-xs); }\n/* netCDF inventory tables (vendored nc_tables): variable / coord / scalar / sensor /\n   global tables.  Package-neutral — the markup is emitted by templates/_nc_tables.html. */\n.var-table code { font-family: var(--font-mono); font-size: var(--fs-xs); }\n.muted { color: var(--muted); }\n.var-qc { color: var(--qc-mark); font-size: var(--fs-xs); }\n/* The original source name on its own muted line above the canonical name (name_cell), so the\n   Variable column does not widen to fit both on one line. */\n.var-orig { color: var(--muted); font-size: var(--fs-xs); }\n/* A long unbroken token (a tracking_id, a path, a dotted standard_name) in a scalar value or a\n   standard/long-name cell would widen the whole table; cap the width and break inside the word. */\n.cell-wrap { overflow-wrap: anywhere; max-width: 28rem; }\n.cell-bad { color: var(--warn); font-variant-numeric: tabular-nums; }\ntr.units th {\n  background: var(--package-accent); color: #fff; font-weight: 400;\n  font-size: var(--fs-xs); padding-top: 0;\n}\n/* Copyable YAML snippet boxes (templates/_snippet.html): one box, or a current/suggested pair\n   that stacks at phone width.  A read-only <textarea> with a full border and a drag handle\n   (resize: vertical); its rows come from the line count, so it opens without clipping. */\n.snippet-pair { display: flex; flex-wrap: wrap; gap: 1rem; margin: 0.6rem 0 1.2rem; }\n.snippet-box { flex: 1 1 22rem; min-width: 0; }\n.snippet-single .snippet-box { flex-basis: 100%; }\n.snippet-title {\n  display: flex; justify-content: space-between; align-items: center; gap: 0.5rem;\n  font-size: var(--fs-xs); color: var(--muted); margin-bottom: 0.2rem;\n}\n.snippet-copy {\n  font: inherit; font-size: var(--fs-xs); cursor: pointer; color: var(--text);\n  border: 1px solid var(--rule); background: var(--bg-sunken);\n  border-radius: 4px; padding: 0.1rem 0.5rem;\n}\n.snippet-copy:hover { background: var(--seafoam); }\ntextarea.snippet {\n  width: 100%; box-sizing: border-box; height: auto; min-height: 2.4em;\n  background: var(--bg-sunken); padding: 0.6rem 0.8rem; margin: 0;\n  white-space: pre; overflow-x: auto; resize: vertical;\n  font-family: var(--font-mono); font-size: var(--fs-xs);\n  border: 1px solid var(--rule); border-radius: 4px;\n}\n.snippet-current textarea.snippet { border-color: var(--muted); }\n.snippet-suggested textarea.snippet { border-color: var(--package-accent); }\n.attr-disclosure summary { cursor: pointer; color: var(--muted); font-size: var(--fs-xs); }\n.attr-disclosure table { margin: 0.3rem 0; width: auto; }\n.attr-disclosure th { background: transparent; color: var(--text); font-weight: 600; }\n/* QC flag-count distribution bar and legend (qc_counts_table). Flag colours are inline on each\n   segment (from the vendored QC_FLAG_COLORS), so these rules carry only the layout. */\n.qc-bar { display: flex; width: 200px; height: 13px; border-radius: 3px; overflow: hidden; gap: 1px; background: #ecf0f1; }\n.qc-bar div { height: 100%; }\n.qc-legend { display: flex; flex-wrap: wrap; gap: 0.3rem 0.9rem; font-size: 0.75rem; margin: 0.2rem 0 0.6rem; }\n.qc-legend span { display: inline-block; width: 10px; height: 10px; border-radius: 2px; vertical-align: middle; margin-right: 3px; }\n/* The source: caption hugs the table it belongs to, not the next one: a table has 1.2rem\n   bottom margin, so pull the caption up under it and keep the gap below before the next table. */\ntable + .fig-source { margin-top: -0.9rem; margin-bottom: 1.2rem; }\n/* Click-to-sort affordance: _JS_SORT_TABLES gives every sortable heading a tabindex, so\n   keying on th[tabindex] styles exactly the headings it wired (a data-nosort table or th\n   gets none).  The heading is a pointer; the active one shows the direction. */\nth[tabindex] { cursor: pointer; user-select: none; }\nth.sorted-asc::after { content: " \\25B2"; font-size: 0.8em; }\nth.sorted-desc::after { content: " \\25BC"; font-size: 0.8em; }\n.slot-full         { width: 100%; }\n.slot-twothirds     { width: calc(66.67% - 0.33rem); }\n.slot-three-fifths  { width: calc(60% - 0.40rem); }\n.slot-half          { width: calc(50% - 0.50rem); }\n.slot-two-fifths    { width: calc(40% - 0.60rem); }\n.slot-third         { width: calc(33.33% - 0.67rem); }\n.slot-quarter       { width: calc(25% - 0.75rem); }\n.masthead-header {\n  display: flex; justify-content: space-between; align-items: flex-start;\n  margin-bottom: 0.3rem;\n}\n.masthead-header h1 { margin: 0 0 0.1rem; font-size: var(--fs-h1); font-weight: 700; }\n.masthead-type {\n  font-size: var(--fs-type); font-weight: 700; opacity: 0.88; line-height: 1.35;\n  padding-top: 0.25rem;\n}\n.nav-btns { display: flex; gap: 0.5rem; }\n.btn-nav {\n  background: var(--ocean); color: #fff; padding: 0.25rem 0.75rem;\n  border-radius: var(--radius-pill); text-decoration: none; font-size: var(--fs-nav);\n}\n.btn-nav:hover { opacity: 0.85; }\n/* Masthead page-nav (vendored): the row of role pills under the masthead, and the\n   "Data inventory:" file strip.  A pill\'s colour is its role, never its page; the\n   current page\'s pill and an already-viewed file pill are muted the same way. */\n.page-nav { margin: 0.65rem 0 0.5rem; }\n/* Consecutive nav rows (a multi-row masthead) stack tighter than the first row\'s\n   top margin, which is sized for a single row. */\n.page-nav + .page-nav { margin-top: 0.15rem; }\n.page-nav-label { font-size: var(--fs-top); opacity: 0.75; margin-right: 0.3rem; }\n.nav-pill {\n  display: inline-block; padding: 0.2em 0.65em; border-radius: var(--radius-btn);\n  font-size: var(--fs-nav); font-weight: 700; text-decoration: none; color: #fff;\n  margin: 0 0.2rem 0.25rem 0;\n  /* A contrasting inner edge keeps a pill visible when its role colour matches the\n     masthead background, so colour-is-role holds on any masthead. */\n  box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.55);\n}\n.nav-landing { background: var(--role-landing); }\n.nav-entity { background: var(--role-entity); }\n.nav-collection { background: var(--role-collection); }\n.nav-component { background: var(--role-component); }\n.nav-aggregate-a { background: var(--role-aggregate-a); }\n.nav-aggregate-b { background: var(--role-aggregate-b); }\n.nav-map { background: var(--role-map); }\n.nav-up { background: var(--role-up); }\n.masthead.role-landing { background: var(--role-landing); }\n.masthead.role-entity { background: var(--role-entity); }\n.masthead.role-collection { background: var(--role-collection); }\n.masthead.role-component { background: var(--role-component); }\n.masthead.role-aggregate-a { background: var(--role-aggregate-a); }\n.masthead.role-aggregate-b { background: var(--role-aggregate-b); }\n.masthead.role-map { background: var(--role-map); }\n.masthead.role-up { background: var(--role-up); }\n.nav-current { opacity: 0.5; pointer-events: none; }\n.nav-missing { background: var(--gray-3); opacity: 0.5; pointer-events: none; }\n.inventory-strip { margin: 0 0 1rem; }\n.inventory-strip .label { font-size: var(--fs-top); opacity: 0.75; margin-right: 0.3rem; }\n.file-pill {\n  display: inline-block; background: var(--role-component); color: #fff;\n  padding: 0.2rem 0.7rem; border-radius: var(--radius-pill);\n  font-family: var(--font-mono); font-size: 0.78rem;\n  text-decoration: none; margin: 0.1rem 0.05rem;\n}\n.file-pill:hover { opacity: 0.85; }\n.file-pill-active { opacity: 0.5; pointer-events: none; }\n/* Opt-in plain masthead (vendored) for landing / navigator pages: white panel,\n   ink text, rule border, wordmark hidden.  No ctdcast page uses it yet. */\n.masthead-plain { background: #fff; color: var(--text); border: 1px solid var(--rule); }\n.masthead-plain .wordmark { display: none; }\nfooter {\n  text-align: center; padding: 1rem;\n  border-top: 1px solid var(--package-accent);\n  font-size: var(--fs-xs); color: var(--muted);\n}\nfooter a { color: var(--muted); }\n@media print {\n  body { max-width: 100%; }\n  .masthead { -webkit-print-color-adjust: exact; print-color-adjust: exact; padding: 0.9rem 1.25rem; }\n  .masthead-header h1, .masthead h1 { font-size: 1.35rem; }\n  .meta-grid { grid-template-columns: repeat(4, 1fr); gap: 0.3rem 1rem; font-size: var(--fs-xs); }\n  h2 { page-break-after: avoid; }\n  h3 { page-break-after: avoid; }\n  .fig-row, figure, table { break-inside: avoid; }\n  .jump-nav { display: none; }\n}\n'

The generated stylesheet, ready to concatenate into a page <style> block.

ctdcast.reports.design.TABLE_WIDTHS: dict[str, list[str]] = {}

Per-table-kind column widths for the inventory page ({"variables": [...], ...}); empty means the browser lays every table out. Deferred until a column misbehaves.

ctdcast.reports.design.VAR_CMAPS: dict[str, str] = {'AOU': 'RdBu_r', 'absolute_salinity': 'YlGnBu_r', 'conservative_temperature': 'RdYlBu_r', 'ctd_fluor': 'YlGn', 'ctd_oxygen': 'cmo.oxy', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_salinity': 'YlGnBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_turbidity': 'YlOrBr', 'oxygen_saturation': 'BrBG', 'sigma0': 'BuPu'}

Resolved variable -> colormap name table, the default for ctdcast.config.report_config.ReportConfig.var_cmaps. Built over the variables that carry a "cmap" today, so it has the same keys as before this change; its values are the vendored family defaults (ctdcast overrides none).

ctdcast.reports.design.cmap_for(var: str, default: str | None = None) → str[source]

Return the colormap name for a variable, resolved through the design layers.

The registry’s "cmap" is used directly when it is a literal colormap and resolved through CMAPS when it names a quantity — CMAPS.get(spec, spec) does both. A variable with no explicit "cmap" is bridged by its CF standard_name through QUANTITY_BY_STANDARD_NAME. A cmo.* result triggers register_cmocean() so the name resolves in matplotlib.

Parameters:
  • var (str) – A variable name in VARIABLES.

  • default (str or None, optional) – Colormap to fall back to when var resolves to no colormap. When given (the report path, e.g. "viridis"), the fallback is returned with a warning naming the variable — a registry gap should not stop a report. When None (the default), an unresolvable variable raises instead — the strict path a config-file validator uses to reject a bad name at load.

Returns:

The resolved colormap name, or default for an unresolvable variable.

Return type:

str

Raises:

KeyError – If var resolves to no colormap and default is None.

ctdcast.reports.design.is_qc(name: str, _ds: object = None) → bool[source]

Return whether name is a QC-companion variable (ctdcast’s _qc suffix).

The signature takes an optional dataset to match the vendored is_qc(name, ds) callable contract (some conventions need the dataset to decide); ctdcast’s rule is purely the name suffix, so the dataset is unused.

Parameters:
  • name (str) – The variable name.

  • _ds (object, optional) – The dataset, accepted for signature compatibility and unused.

Returns:

True when name ends with _qc.

Return type:

bool

ctdcast.reports.design.is_sensor(name: str) → bool[source]

Return whether name is a sensor-catalog variable (SENSOR_*).

The narrow catalog predicate, ctdcast.config.sensors.is_sensor_catalog_var(): the uppercase SENSOR_* variables that carry a physical sensor’s provenance, excluding any _qc companion. The lowercase sensor_* linkage and channel variables are not catalog entries and are excluded from the science-variable table by a broader rule in ctdcast.reports.dataset.

Parameters:

name (str) – The variable name.

Returns:

True when name is a SENSOR_* catalog entry.

Return type:

bool

ctdcast.reports.design.unit_label(units: str, standard_name: str | None = None) → str[source]

Return the display label for a units string, with ctdcast’s overrides applied.

The single display-unit entry point: ctdcast.reports._vendored.units.format_units() against ctdcast’s TABLES, so an override in this module reaches both the plot axes (via ctdcast.config.parameters.vlabel() / vunit()) and the owned report-design layer that re-exports this.

Parameters:
  • units (str) – CF/UDUNITS units string (e.g. "mS cm-1").

  • standard_name (str or None, optional) – CF standard name, for the dimensionless turbidity / salinity labels.

Returns:

The display units string; "" when units is empty.

Return type:

str

Shared report design tokens — the single source of every presentation value.

This module is written to be vendored across the packages that share the report design system. It is package-neutral — it names no package and holds only data (plus the mplstyle path, resolved relative to this file so no package name appears in the text) — so the copies can be frozen and checked later; for now this document and convention are the shared reference (no cross-repo hash test yet). A value that belongs to one package (a scientific variable registry) does not live here.

Layering: this is a leaf — it imports only pathlib at module load. cmocean (which provides the cmo.* entries in CMAPS) is imported lazily by register_cmocean(), only when such a name is actually requested, so no CSS- or geometry-only importer pays its cost. Both the plotters (which size figures from SLOTS and read CMAPS) and the report/CSS layer read this module; it reads nothing of theirs.

Templates and plotters read these values; they never restate them.

ctdcast.reports._vendored.design_tokens.QC_FLAG_COLORS: dict[str, str] = {'bad_data': '#D55E00', 'fail': '#D55E00', 'good_data': '#009E73', 'interpolated_value': '#0072B2', 'missing_data': '#bdbdbd', 'missing_value': '#bdbdbd', 'nominal_value': '#CC79A7', 'not_evaluated': '#56B4E9', 'pass': '#009E73', 'potentially_correctable_bad_data': '#E69F00', 'probably_good_data': '#56B4E9', 'suspect_or_of_high_interest': '#E69F00', 'unknown': '#999999'}

QC flag colour keyed by meaning token (so a report colours a flag by what it means, not by a value that differs between conventions), derived from QC_COLORS. A table looks a token up here; an unlisted token gets QC_FLAG_DEFAULT_COLOR.

ctdcast.reports._vendored.design_tokens.QC_FLAG_DEFAULT_COLOR: str = '#999999'

Grey fallback for a flag token no convention below names.

ctdcast.reports._vendored.design_tokens.QC_FLAG_LABELS: dict[str, str] = {'bad_data': 'bad', 'fail': 'fail', 'good_data': 'good', 'interpolated_value': 'interpolated', 'missing_data': 'missing', 'missing_value': 'missing', 'nominal_value': 'nominal', 'not_evaluated': 'not eval', 'pass': 'pass', 'potentially_correctable_bad_data': 'correctable', 'probably_good_data': 'probably good', 'suspect_or_of_high_interest': 'suspect', 'unknown': 'unknown'}

Short display label keyed by meaning token — a shortening of the CF word, nothing invented; an unlisted token falls back to the token with underscores as spaces.

ctdcast.reports._vendored.design_tokens.SHOW_FIGURE_SOURCE: bool = False

Vendored default for the per-figure source: caption (which draw function produced each panel). OFF here — a package turns it on in its owned design module (ctdcast: reports/design.py FIGURE_SOURCE), never in the shared table. Read into the report env as the show_source template global.

ctdcast.reports._vendored.design_tokens.pen(name: str) → float[source]

Return a matplotlib linewidth in points for a GMT pen-width name.

Borrows GMT’s named pen ladder (faint … wide) so plotters name line weights (lw=pen("thin")) rather than hardcoding numbers.

ctdcast.reports._vendored.design_tokens.register_cmocean() → None[source]

Register cmocean’s cmo.* colormaps with matplotlib, once.

Called only when a cmo.* name is actually requested (from a colormap resolver, or a config validator’s colormap check), so neither the import cost nor cmocean’s own import-time deprecation warnings are paid on an import of this module that never touches a cmocean map. cmocean 3.x builds its colormaps with the deprecated ListedColormap(N=...) (its code, not ours), emitting one MatplotlibDeprecationWarning per map; those are silenced here at their source — the import — rather than by a global filter.


Analysis helpers

Derived physical quantities computed from raw CTD measurements.

All functions use GSW — the same library oceanographers use directly.

Per-cast (1-D, dim=time) functions

derive_salinity SP from conductivity/temperature/pressure derive_SA Absolute Salinity from SP/pressure/lat/lon derive_CT Conservative Temperature from SA/in-situ-T/pressure derive_sigma0 Potential density anomaly from SA/CT derive_AOU Apparent Oxygen Utilization from oxygen_saturation (% sat) derive_teos10 Convenience: SA + CT + sigma0 + optional O2 unit conversion

Profiles (2-D, dims N_PROF × pressure) functions

derive_teos10_profiles SA + CT + sigma0 for compiled profiles datasets

Output variable names match the VARIABLES registry in ctdcast.config.parameters: absolute_salinity, conservative_temperature, sigma0.

Variable resolution

Functions accept both the canonical CCHDO names (ctd_temperature, ctd_salinity, ctd_oxygen) and the suffixed dual-sensor names (ctd_temperature_1, ctd_salinity_1, ctd_oxygen_1). Old pre-rename names (temperature_1, salinity_1, oxygen_1) are accepted for backward compatibility with NC files written before the stage1-normalise rename.

ctdcast.analysis.derive.derive_AOU(ds: Dataset) → Dataset[source]

Return ds with AOU added as 100 - oxygen_saturation (O₂ saturation deficit, % sat).

Note: this is a saturation-deficit proxy, not the traditional AOU in µmol/kg, because it uses oxygen_saturation (% saturation) rather than dissolved O₂ in µmol/kg.

Returns ds unchanged if no oxygen saturation variable is present or AOU already exists. Accepts oxygen_saturation (canonical) or oxsat_1 (pre-rename name).

Parameters:

ds – Dataset (any dimensionality) with oxygen_saturation or oxsat_1 in % saturation.

Returns:

New Dataset with AOU added; input is not mutated.

Return type:

xr.Dataset

ctdcast.analysis.derive.derive_CT(ds: Dataset) → Dataset[source]

Return ds with Conservative Temperature (CT) added.

Requires ds["absolute_salinity"] to already be present (call derive_SA() first). Uses gsw.CT_from_t with the first available temperature variable (ctd_temperature, ctd_temperature_1, or temperature_1) and pressure.

Parameters:

ds – Per-cast Dataset (dim=time) with absolute_salinity, a temperature variable, and pressure.

Returns:

New Dataset with ds["conservative_temperature"] added; input is not mutated.

Return type:

xr.Dataset

ctdcast.analysis.derive.derive_SA(ds: Dataset) → Dataset[source]

Return ds with Absolute Salinity (SA) added.

Uses gsw.SA_from_SP with the first available salinity variable (ctd_salinity, ctd_salinity_1, or salinity_1), pressure (dbar), and the cast’s median latitude/longitude.

Parameters:

ds – Per-cast Dataset (dim=time) with a salinity variable, pressure, latitude, longitude.

Returns:

New Dataset with ds["absolute_salinity"] added; input is not mutated.

Return type:

xr.Dataset

ctdcast.analysis.derive.derive_salinity(ds: Dataset) → Dataset[source]

Re-compute practical salinity from conductivity, temperature, pressure.

Uses gsw.SP_from_C, which expects conductivity in mS/cm. Stored conductivity is mS/cm since stage1; a file still carrying S/m (units not mS/cm) is converted by ×10. Call this after any conductivity calibration so that salinity reflects the calibrated conductivity.

Does nothing if conductivity_1 or any temperature variable is absent.

Writes output to ctd_salinity_1 / ctd_salinity_2 (CCHDO canonical names). Records the conversion method in the variable’s attrs.

Parameters:

ds – Per-cast Dataset (dim=time) containing at minimum conductivity_1, a temperature variable, and pressure in their expected units (conductivity in mS/cm, temperature in °C ITS-90, pressure in dbar).

Returns:

New Dataset with updated ctd_salinity_1 (and ctd_salinity_2 when conductivity_2 is present); input is not mutated.

Return type:

xr.Dataset

ctdcast.analysis.derive.derive_sigma0(ds: Dataset) → Dataset[source]

Return ds with potential density anomaly (sigma0) added.

Requires ds["absolute_salinity"] and ds["conservative_temperature"] to already be present. Uses gsw.sigma0.

Parameters:

ds – Per-cast Dataset (dim=time) with absolute_salinity and conservative_temperature.

Returns:

New Dataset with ds["sigma0"] added; input is not mutated.

Return type:

xr.Dataset

ctdcast.analysis.derive.derive_teos10(ds: Dataset) → Dataset[source]

Return ds with SA, CT, sigma0 added (1-D per-cast Dataset, dim=time).

Convenience function that calls derive_SA() → derive_CT() → derive_sigma0() in order. Also derives oxygen_saturation (% sat) via _derive_oxygen_saturation() — per oxygen line, from that line’s own T/S, with the composite selected by the preferred_oxygen attribute (never pairing the oxygen with the pair composite, which may be the other line).

Parameters:

ds – Per-cast Dataset (dim=time) with a salinity variable, a temperature variable, pressure, latitude, longitude.

Returns:

New Dataset with SA, CT, sigma0 added; input is not mutated.

Return type:

xr.Dataset

ctdcast.analysis.derive.derive_teos10_profiles(ds: Dataset) → Dataset[source]

Return ds with SA, CT, sigma0 added (2-D profiles Dataset).

Expects pressure as a 1-D coordinate and a temperature variable, a salinity variable, latitude, longitude with dims (N_PROF,) or (N_PROF, pressure). Returns ds unchanged if SA, CT, and sigma0 are already present.

Parameters:

ds – Profiles Dataset (dims N_PROF × pressure).

Returns:

New Dataset with SA, CT, sigma0 added; input is not mutated.

Return type:

xr.Dataset

ctdcast.analysis.derive.fill_oxygen_composite(ds: Dataset) → Dataset[source]

Return ds with empty ctd_oxygen profiles filled from ctd_oxygen_1.

A compiled profiles file holds the plain ctd_oxygen composite as soon as any cast has one (a declared preferred_oxygen cast, or a single-oxygen cast), and it is all NaN for every other cast. An undeclared dual-oxygen cast has no composite, so drawing ctd_oxygen would leave it blank. This fills each profile whose composite holds no finite value from line 1, the line an undeclared cast is drawn with, so every cast is drawn. For drawing only: the profiles file is not changed. The filled cast numbers are recorded in the composite’s filled_from_ctd_oxygen_1 attribute.

Parameters:

ds (xarray.Dataset) – A profiles dataset (N_PROF × pressure).

Returns:

A new dataset, or ds unchanged when it lacks either variable or no profile needs filling.

Return type:

xarray.Dataset

Cast geometry: along-track distance and section orientation.

Pure computation — no matplotlib, no HTML.

ctdcast.analysis.geometry.along_track_km(lats: list[float], lons: list[float]) → tuple[ndarray, str][source]

Return (cumulative_distance_km, x_axis_label) for a list of positions.

ctdcast.analysis.geometry.distance_from_km(key_lat: float, key_lon: float, lats: list[float], lons: list[float]) → ndarray[source]

Return great-circle distance in km from a key position to each position.

Used for key_cast section ordering: each cast’s x-coordinate is its distance from the chosen key cast. Uses gsw.distance per pair so the convention matches along_track_km(). A position identical to the key yields 0. A gsw.distance failure is allowed to propagate rather than being silently substituted with a fabricated distance.

ctdcast.analysis.geometry.section_orientation(lats: list[float], lons: list[float]) → bool[source]

Return True if the section x-axis should be flipped for geographic convention.

Convention: west on the left for E–W-dominant sections; north on the left for N–S-dominant sections. Dominance is determined by comparing the end-to-end longitude span against the latitude span.

Parameters:
  • lats – Latitude of each cast in the section, in cast order.

  • lons – Longitude of each cast in the section, in cast order.

Returns:

True if x_vals (cumulative along-track distance from first cast) should be replaced by x_total - x_vals before plotting.

Return type:

bool

GEBCO bathymetry loading and interpolation.

Pure computation — no matplotlib, no HTML. GEBCO stores elevation as negative below sea level; this module returns depth as positive below sea level (depth = -elevation).

ctdcast.analysis.bathymetry.dense_bathy_along_track(lats: list[float], lons: list[float], x_vals: ndarray, path: Path | None = None, n_per_segment: int = 20) → tuple[ndarray | None, ndarray | None][source]

Return (dense_x, dense_depths) interpolated between cast positions.

Generates n_per_segment equally-spaced points along each segment between consecutive casts, giving a smooth GEBCO bathymetry fill rather than the stepped appearance produced by one sample per cast. Returns (None, None) when GEBCO is unavailable or fewer than two cast positions are supplied.

ctdcast.analysis.bathymetry.interpolate_bathy_at_casts(lats: list[float], lons: list[float], path: Path | None = None) → ndarray | None[source]

Return GEBCO water depth (m, positive below sea level) at each cast position.

Uses bilinear interpolation via xarray. Returns None if GEBCO is not available or on any error. Land points (elevation > 0) are clamped to 0.

ctdcast.analysis.bathymetry.load_gebco(lat_lo: float, lat_hi: float, lon_lo: float, lon_hi: float, margin: float = 0.05, path: Path | None = None, use_cache: bool = True) → tuple[ndarray, ndarray, ndarray] | None[source]

Return a GEBCO subset as (lons, lats, depth_m) or None if unavailable.

If preload_gebco has been called for path, subsets from the in-memory numpy cache (fast). Otherwise opens the file from disk (slow).

Parameters:
  • lat_lo (float) – Southern latitude bound of the region (degrees North).

  • lat_hi (float) – Northern latitude bound of the region (degrees North).

  • lon_lo (float) – Western longitude bound of the region (degrees East).

  • lon_hi (float) – Eastern longitude bound of the region (degrees East).

  • margin (float, default 0.05) – Extra degrees added on every side, so the fill runs to the panel edge.

  • path – Path to GEBCO_2025.nc. Pass cfg.gebco_path from the caller. Returns None if not provided or file not found.

  • use_cache – When False, read the requested region from the file directly instead of subsetting the preloaded cache. Use this for a region wider than the preloaded cruise extent (e.g. the interactive map, which frames far more longitude than the per-cast maps) — the cache would otherwise clip it.

ctdcast.analysis.bathymetry.preload_gebco(path: Path, lat_lo: float, lat_hi: float, lon_lo: float, lon_hi: float, margin: float = 1.0) → bool[source]

Load a GEBCO region into memory once for the cruise area.

Call this at report-generation start with the full lat/lon extent of all casts. Subsequent load_gebco calls then subset from numpy arrays (no disk I/O) instead of reopening the file for every map figure.

Parameters:
  • path – Path to GEBCO netCDF file.

  • lat_lo – Bounding box of the cruise area.

  • lat_hi – Bounding box of the cruise area.

  • lon_lo – Bounding box of the cruise area.

  • lon_hi – Bounding box of the cruise area.

  • margin – Extra degrees around the bounding box. Default 1.0 deg.

Returns:

True if the file was found and cached successfully.

Return type:

bool

fits holds the alignment and cell-thermal-mass cost functions and the cruise aggregation behind ctdcast fit — pure numpy over a cast’s arrays, writing no files.

Fit conductivity alignment and cell thermal mass parameters from a cruise’s casts.

Two cost functions on one cast at its native scan rate, and the arithmetic that combines them over many casts. They suggest the processing.alignctd and processing.celltm values that stage 3 applies; they never change data.

  • Alignment (alignment_cost()): the mean square of high-passed practical salinity in the thermocline, as a function of the conductivity advance on top of what the data already carry (the deck unit’s). A misalignment makes salinity spike where temperature changes fast; too much advance reverses the spikes, so the cost has a minimum. Down and up are scored separately; the downcast is the one to fit (the upcast passes through the rosette’s wake), the upcast is shown beside it. Scans near the surface and scans where the package is barely moving along the leg (ship heave) are left out.

  • Cell thermal mass (ctm_cost()): the down–up difference of practical salinity in temperature bins below a window top (default 200 dbar), each bin weighted towards the time the two legs passed it, as a function of (alpha, tau). Each grid point is scored through seabirdscientific’s cell_thermal_mass, the correction stage 3 applies.

Over a cruise (cruise_surface()), each cast’s cost is divided by its value with no correction and the casts are averaged: the cruise optimum is the minimum of that average, not the average of per-cast optima. For alignment (median_curve()) each cast’s cost is divided by its own minimum and the cruise curve is the median across casts. alpha and tau trade off along a valley, so one_parameter_fits() also fits one with the other held at Sea-Bird’s default, the stable quantity for comparing casts and blocks of casts.

Original author of the cell thermal mass cost (down/up salinity in temperature bins, grid search through Sea-Bird’s cell_thermal_mass): Joel Bracamontes Ramirez, ctdproc processing.find_opt_alp_tat_fast. The alignment cost, the time weighting, the window and the cruise aggregation are not from ctdproc.

class ctdcast.analysis.fits.Cast(pressure: ndarray, temperature: ndarray, conductivity: ndarray, interval: float)[source]

One cast’s native-rate arrays for one conductivity line.

pressure

Pressure (dbar); NaN where a scan is not usable.

Type:

numpy.ndarray

temperature

ITS-90 temperature (°C) of the line.

Type:

numpy.ndarray

conductivity

Conductivity (mS/cm) of the line, as stage 2 carries it.

Type:

numpy.ndarray

interval

Time between scans (s).

Type:

float

conductivity: ndarray
interval: float
property pmax: float

The cast’s maximum pressure (dbar).

pressure: ndarray
temperature: ndarray
property turnaround: int

Index of the last scan within 2 dbar of the cast’s maximum pressure.

class ctdcast.analysis.fits.CruiseFit(surface: ndarray, index: tuple[int, ...], valley: ndarray, n_casts: int)[source]

The cruise-average cost and where it is lowest.

surface

The average of the casts’ normalised costs.

Type:

numpy.ndarray

index

Index of the minimum.

Type:

tuple of int

valley

Boolean mask of the points within VALLEY_FRACTION of the minimum.

Type:

numpy.ndarray

n_casts

How many casts went into the average.

Type:

int

index: tuple[int, ...]
n_casts: int
surface: ndarray
valley: ndarray
ctdcast.analysis.fits.DEFAULT_ALIGN_PMIN = 20.0

scans shallower than this (dbar) are left out.

Type:

Alignment cost

ctdcast.analysis.fits.DEFAULT_ALPHA = array([0.    , 0.0025, 0.005 , 0.0075, 0.01  , 0.0125, 0.015 , 0.0175,        0.02  , 0.0225, 0.025 , 0.0275, 0.03  , 0.0325, 0.035 , 0.0375,        0.04  , 0.0425, 0.045 , 0.0475, 0.05  , 0.0525, 0.055 , 0.0575,        0.06  , 0.0625, 0.065 , 0.0675, 0.07  , 0.0725, 0.075 , 0.0775,        0.08  ])

Cell thermal mass grid searched by ctm_cost(), around Sea-Bird’s (0.03, 7 s).

ctdcast.analysis.fits.DEFAULT_ALPHA_SBE = 0.03

Sea-Bird’s defaults for a TC duct and 3000-rpm pump (SBE manual p.92).

ctdcast.analysis.fits.DEFAULT_CTM_PMIN = 200.0

the near-surface water changes between legs.

Type:

Top of the cell thermal mass window (dbar)

ctdcast.analysis.fits.DEFAULT_GAP_SCALE = 300.0

weight = 1 / (gap + this).

Type:

Time scale (s) of the down/up weighting

ctdcast.analysis.fits.DEFAULT_GRADIENT = 0.02

|dT/dp| in °C per dbar, on 2-dbar bins.

Type:

Thermocline threshold for the alignment cost

ctdcast.analysis.fits.DEFAULT_MIN_SPEED = 0.25

scans moving along the leg slower than this (dbar/s) are left out (heave).

Type:

Alignment cost

ctdcast.analysis.fits.DEFAULT_RESIDUALS = array([-0.1   , -0.0975, -0.095 , -0.0925, -0.09  , -0.0875, -0.085 ,        -0.0825, -0.08  , -0.0775, -0.075 , -0.0725, -0.07  , -0.0675,        -0.065 , -0.0625, -0.06  , -0.0575, -0.055 , -0.0525, -0.05  ,        -0.0475, -0.045 , -0.0425, -0.04  , -0.0375, -0.035 , -0.0325,        -0.03  , -0.0275, -0.025 , -0.0225, -0.02  , -0.0175, -0.015 ,        -0.0125, -0.01  , -0.0075, -0.005 , -0.0025,  0.    ,  0.0025,         0.005 ,  0.0075,  0.01  ,  0.0125,  0.015 ,  0.0175,  0.02  ,         0.0225,  0.025 ,  0.0275,  0.03  ,  0.0325,  0.035 ,  0.0375,         0.04  ,  0.0425,  0.045 ,  0.0475,  0.05  ,  0.0525,  0.055 ,         0.0575,  0.06  ,  0.0625,  0.065 ,  0.0675,  0.07  ,  0.0725,         0.075 ,  0.0775,  0.08  ,  0.0825,  0.085 ,  0.0875,  0.09  ,         0.0925,  0.095 ,  0.0975,  0.1   ,  0.1025,  0.105 ,  0.1075,         0.11  ,  0.1125,  0.115 ,  0.1175,  0.12  ,  0.1225,  0.125 ,         0.1275,  0.13  ,  0.1325,  0.135 ,  0.1375,  0.14  ,  0.1425,         0.145 ,  0.1475,  0.15  ])

Residual conductivity advance searched by alignment_cost(), seconds on top of the data’s.

ctdcast.analysis.fits.DEFAULT_TEMPERATURE_BINS = 40

Temperature bins in the cell thermal mass cost.

ctdcast.analysis.fits.MAX_MIN_SPEED = 0.5

above it a slow winch would leave too few scans.

Type:

Largest min_speed accepted

class ctdcast.analysis.fits.MedianCurve(median: ndarray, lower: ndarray, upper: ndarray, index: int, n_casts: int)[source]

The median across casts of 1-D costs, each divided by its own minimum.

median

The median curve (1 at a cast’s own minimum).

Type:

numpy.ndarray

lower, upper

The 25th and 75th percentiles.

Type:

numpy.ndarray

index

Index of the median curve’s minimum.

Type:

int

n_casts

How many casts went in.

Type:

int

index: int
lower: ndarray
median: ndarray
n_casts: int
upper: ndarray
ctdcast.analysis.fits.PRESSURE_FILTER_SECONDS = 0.15

SBE Data Processing’s Filter default for pressure (SBE manual p.20).

Type:

Time constant (s) of the low-pass applied to pressure before the speed is taken

ctdcast.analysis.fits.TUKEY_ALPHA = 0.5

Tukey taper of the 1-s high-pass window in the alignment cost.

ctdcast.analysis.fits.VALLEY_FRACTION = 0.05

A cast’s down/up difference within this fraction of the cruise minimum is “in the valley”.

ctdcast.analysis.fits.WELL_DEPTH = 2.0

An alignment cost counts only if it rises to this multiple of its minimum within the search: a dead or noisy line gives a cost that wobbles scan by scan with no well.

ctdcast.analysis.fits.alignment_cost(cast: Cast, residuals: ndarray = array([-0.1, -0.0975, -0.095, -0.0925, -0.09, -0.0875, -0.085, -0.0825, -0.08, -0.0775, -0.075, -0.0725, -0.07, -0.0675, -0.065, -0.0625, -0.06, -0.0575, -0.055, -0.0525, -0.05, -0.0475, -0.045, -0.0425, -0.04, -0.0375, -0.035, -0.0325, -0.03, -0.0275, -0.025, -0.0225, -0.02, -0.0175, -0.015, -0.0125, -0.01, -0.0075, -0.005, -0.0025, 0., 0.0025, 0.005, 0.0075, 0.01, 0.0125, 0.015, 0.0175, 0.02, 0.0225, 0.025, 0.0275, 0.03, 0.0325, 0.035, 0.0375, 0.04, 0.0425, 0.045, 0.0475, 0.05, 0.0525, 0.055, 0.0575, 0.06, 0.0625, 0.065, 0.0675, 0.07, 0.0725, 0.075, 0.0775, 0.08, 0.0825, 0.085, 0.0875, 0.09, 0.0925, 0.095, 0.0975, 0.1, 0.1025, 0.105, 0.1075, 0.11, 0.1125, 0.115, 0.1175, 0.12, 0.1225, 0.125, 0.1275, 0.13, 0.1325, 0.135, 0.1375, 0.14, 0.1425, 0.145, 0.1475, 0.15]), *, gradient: float = 0.02, pmin: float = 20.0, min_speed: float = 0.25, sharpest: float | None = None) → ndarray | None[source]

Return the salinity spike cost of each residual advance, downcast and upcast.

For each advance, conductivity is advanced with seabirdscientific’s align_ctd, practical salinity is derived, and the cost is the mean square of salinity minus its 1-s running mean (a Tukey window, taper TUKEY_ALPHA), over scans in 2-dbar bins whose downcast |dT/dp| exceeds gradient, deeper than pmin, and moving along the leg faster than min_speed. Every advance is scored on the same scans (those usable for all of them), so shifting data off the ends of the record cannot change the cost.

Parameters:
  • cast (Cast) – The cast, at its native scan rate.

  • residuals (numpy.ndarray, optional) – Advances (s) to try, on top of whatever the data already carry.

  • gradient (float, optional) – Thermocline threshold, °C per dbar.

  • pmin (float, optional) – Scans shallower than this (dbar) are left out.

  • min_speed (float, optional) – Scans moving along the leg slower than this (dbar/s, see leg_speed()) are left out: ship heave stops or reverses the package, and the water around the sensors is then not the water the pump drew in. 0 keeps every scan; at most MAX_MIN_SPEED.

  • sharpest (float, optional) – Keep only this fraction (0–1) of the remaining scans per leg, those with the largest |dT/dt|. Off by default: on the OdB cruise it lost casts and changed nothing.

Returns:

Shape (2, len(residuals)): row 0 the downcast, row 1 the upcast; NaN where a leg has under 200 thermocline scans. None when the cast has no thermocline at all.

Return type:

numpy.ndarray or None

Raises:

ValueError – If min_speed is outside 0–MAX_MIN_SPEED or sharpest outside (0, 1].

ctdcast.analysis.fits.cruise_surface(costs: Sequence[ndarray], weights: Sequence[float] | None = None) → CruiseFit | None[source]

Average normalised per-cast costs and find the minimum and the valley.

Parameters:
  • costs (sequence of numpy.ndarray) – Normalised costs (from normalise()), all the same shape.

  • weights (sequence of float, optional) – A weight per cast (e.g. its |ΔT| over the window); equal when omitted.

Returns:

None when costs is empty.

Return type:

CruiseFit or None

ctdcast.analysis.fits.ctm_cost(cast: Cast, alpha: ndarray = array([0., 0.0025, 0.005, 0.0075, 0.01, 0.0125, 0.015, 0.0175, 0.02, 0.0225, 0.025, 0.0275, 0.03, 0.0325, 0.035, 0.0375, 0.04, 0.0425, 0.045, 0.0475, 0.05, 0.0525, 0.055, 0.0575, 0.06, 0.0625, 0.065, 0.0675, 0.07, 0.0725, 0.075, 0.0775, 0.08]), tau: ndarray = array([1., 1.5, 2., 2.5, 3., 3.5, 4., 4.5, 5., 5.5, 6., 6.5, 7., 7.5, 8., 8.5, 9., 9.5, 10., 10.5, 11., 11.5, 12., 12.5, 13., 13.5, 14., 14.5, 15., 15.5, 16.]), *, pmin: float = 200.0, n_bins: int = 40, gap_scale: float = 300.0) → ndarray | None[source]

Return the down/up salinity mismatch below pmin for each (alpha, tau).

Conductivity is corrected over the whole cast (the filter needs the history), then practical salinity below pmin is averaged in n_bins temperature bins on each leg. The cost is the weighted mean of (down − up)², each bin weighted by 1 / (gap + gap_scale) where gap is the time between the two legs passing it, so the bottom of the cast, where the water has had least time to change, counts most.

Parameters:
  • cast (Cast) – The cast, at its native scan rate, conductivity already aligned.

  • alpha (numpy.ndarray, optional) – The grid (tau in seconds).

  • tau (numpy.ndarray, optional) – The grid (tau in seconds).

  • pmin (float, optional) – Top of the window (dbar).

  • n_bins (int, optional) – Temperature bins across the 1st–99th percentile of the window.

  • gap_scale (float, optional) – Weighting time scale (s).

Returns:

Shape (len(alpha), len(tau)); alpha == 0 is no correction. None when the cast does not reach 60 dbar below pmin, has under 98% finite scans, spans under 0.1 °C in the window, or has fewer than 5 bins seen by both legs.

Return type:

numpy.ndarray or None

ctdcast.analysis.fits.despike_pressure(pressure: ndarray, *, window: int = 49, limit: float = 5.0) → ndarray[source]

Return pressure with spikes and impossible values set NaN.

A scan is a spike when it departs from the running median of window scans by more than limit dbar, or lies outside −5…7000 dbar. The 911plus occasionally records single-scan pressure spikes of thousands of dbar, which would otherwise set the cast’s maximum.

Parameters:
  • pressure (numpy.ndarray) – Pressure (dbar).

  • window (int, optional) – Running-median length, in scans.

  • limit (float, optional) – Departure from the running median (dbar) that marks a spike.

Returns:

A float64 copy with spikes as NaN.

Return type:

numpy.ndarray

ctdcast.analysis.fits.has_interior_minimum(cost: ndarray) → bool[source]

Return whether a 1-D cost has its minimum strictly inside the search.

A cost whose minimum is its first or last value is still falling at the end of the search: it gives no estimate, and averaged with other casts it would pull the result to that end.

Parameters:

cost (numpy.ndarray) – One cast’s cost over the searched values.

Returns:

True when the minimum is neither the first nor the last finite-searched value.

Return type:

bool

ctdcast.analysis.fits.has_well(cost: ndarray, depth: float = 2.0) → bool[source]

Return whether a 1-D alignment cost has a minimum inside the search and a real well.

Besides has_interior_minimum(), the cost must rise to depth times its minimum somewhere in the search. On the OdB cruise every working line rose at least 2.4-fold; the few that did not (a line with a fault) oscillated scan by scan with no single minimum.

Parameters:
  • cost (numpy.ndarray) – One leg’s alignment cost over the searched advances.

  • depth (float, optional) – Required ratio of the maximum to the minimum.

Returns:

True when the cost has both.

Return type:

bool

ctdcast.analysis.fits.leg_speed(cast: Cast) → ndarray[source]

Return the package’s speed along its leg (dbar/s), positive when moving the leg’s way.

Positive descending on the downcast and ascending on the upcast; heave shows as speeds near zero or negative. Pressure is low-passed with sbe_lowpass() at PRESSURE_FILTER_SECONDS first.

Parameters:

cast (Cast) – The cast.

Returns:

One value per scan.

Return type:

numpy.ndarray

ctdcast.analysis.fits.median_curve(costs: Sequence[ndarray]) → MedianCurve | None[source]

Return the cruise alignment curve: the median of the casts’ costs over their own minima.

Casts without a minimum inside the search and a real well (has_well()) are left out. The median, not the mean: a few casts rise steeply away from their minimum and would pull a mean outside the middle half of casts.

Parameters:

costs (sequence of numpy.ndarray) – One leg’s alignment cost per cast, all the same length.

Returns:

None when no cast has an interior minimum.

Return type:

MedianCurve or None

ctdcast.analysis.fits.median_speeds(cast: Cast, pmin: float = 20.0) → tuple[float, float][source]

Return the median lowering and hauling speeds (dbar/s) below pmin.

Only scans moving the leg’s way are counted, so a stop at a bottle does not pull the median down. The figure to set min_speed against.

Parameters:
  • cast (Cast) – The cast.

  • pmin (float, optional) – Scans shallower than this (dbar) are not counted.

Returns:

(down, up); NaN for a leg with no such scans.

Return type:

tuple of float

ctdcast.analysis.fits.normalise(cost: ndarray, reference: tuple[int, ...]) → ndarray | None[source]

Divide cost by its value at reference (no correction), or None if that is not usable.

Parameters:
  • cost (numpy.ndarray) – A one-leg alignment cost or a (alpha, tau) cell-thermal-mass cost surface.

  • reference (tuple of int) – The index of the no-correction value.

Returns:

The normalised cost, or None when the reference is NaN or not positive.

Return type:

numpy.ndarray or None

ctdcast.analysis.fits.one_parameter_fits(surface: ndarray, alpha: ndarray = array([0., 0.0025, 0.005, 0.0075, 0.01, 0.0125, 0.015, 0.0175, 0.02, 0.0225, 0.025, 0.0275, 0.03, 0.0325, 0.035, 0.0375, 0.04, 0.0425, 0.045, 0.0475, 0.05, 0.0525, 0.055, 0.0575, 0.06, 0.0625, 0.065, 0.0675, 0.07, 0.0725, 0.075, 0.0775, 0.08]), tau: ndarray = array([1., 1.5, 2., 2.5, 3., 3.5, 4., 4.5, 5., 5.5, 6., 6.5, 7., 7.5, 8., 8.5, 9., 9.5, 10., 10.5, 11., 11.5, 12., 12.5, 13., 13.5, 14., 14.5, 15., 15.5, 16.]), *, alpha_fixed: float = 0.03, tau_fixed: float = 7.0) → tuple[float, float][source]

Return alpha with tau held at tau_fixed, and tau with alpha held at alpha_fixed.

alpha and tau trade off along a valley, so the two-parameter minimum of one cast or a few casts wanders; with one held at Sea-Bird’s default the other is well defined.

Parameters:
  • surface (numpy.ndarray) – A cost surface on the (alpha, tau) grid.

  • alpha (numpy.ndarray, optional) – The grid.

  • tau (numpy.ndarray, optional) – The grid.

  • alpha_fixed (float, optional) – The values held fixed.

  • tau_fixed (float, optional) – The values held fixed.

Returns:

(alpha at tau_fixed, tau at alpha_fixed); NaN where the row or column is all NaN.

Return type:

tuple of float

ctdcast.analysis.fits.sbe_lowpass(x: ndarray, time_constant: float, interval: float) → ndarray[source]

Low-pass x the way SBE Data Processing’s Filter does.

A single-pole filter with the given time constant, run forward and then backward so the result has no phase shift (SBE manual p.101).

Parameters:
  • x (numpy.ndarray) – The series, without NaN (fill gaps first).

  • time_constant (float) – Filter time constant (s).

  • interval (float) – Time between scans (s).

Returns:

The filtered series, same length.

Return type:

numpy.ndarray

ctdcast.analysis.fits.snap_to_default(surface: ndarray, alpha: ndarray = array([0., 0.0025, 0.005, 0.0075, 0.01, 0.0125, 0.015, 0.0175, 0.02, 0.0225, 0.025, 0.0275, 0.03, 0.0325, 0.035, 0.0375, 0.04, 0.0425, 0.045, 0.0475, 0.05, 0.0525, 0.055, 0.0575, 0.06, 0.0625, 0.065, 0.0675, 0.07, 0.0725, 0.075, 0.0775, 0.08]), tau: ndarray = array([1., 1.5, 2., 2.5, 3., 3.5, 4., 4.5, 5., 5.5, 6., 6.5, 7., 7.5, 8., 8.5, 9., 9.5, 10., 10.5, 11., 11.5, 12., 12.5, 13., 13.5, 14., 14.5, 15., 15.5, 16.]), *, tolerance: float = 0.02, alpha_default: float = 0.03, tau_default: float = 7.0, alpha_scale: float = 0.01, tau_scale: float = 1.0) → tuple[float, float][source]

Return the (alpha, tau) within tolerance of the cost minimum closest to the default.

Any grid point whose cost is within tolerance of the minimum is treated as equally good; among those the one nearest Sea-Bird’s default is returned, distance measured in alpha_scale / tau_scale units (a step of tau_scale in tau counts as much as alpha_scale in alpha). The default itself is returned when it falls inside the region.

Parameters:
  • surface (numpy.ndarray) – A cruise cost surface on the (alpha, tau) grid.

  • alpha (numpy.ndarray, optional) – The grid.

  • tau (numpy.ndarray, optional) – The grid.

  • tolerance (float, optional) – The acceptability fraction above the minimum (0.02 = 2%).

  • alpha_default (float, optional) – The point to stay close to.

  • tau_default (float, optional) – The point to stay close to.

  • alpha_scale (float, optional) – The per-axis distance units.

  • tau_scale (float, optional) – The per-axis distance units.

Returns:

(alpha, tau); (nan, nan) when the surface has no usable minimum.

Return type:

tuple of float

ctdcast.analysis.fits.window_delta_t(cast: Cast, pmin: float = 200.0) → tuple[float, float][source]

Return |T(bottom) − T(pmin)| on the downcast and the upcast.

The temperature change across the cell thermal mass window: where it is small the window carries no gradient and the fit learns nothing from the cast.

Parameters:
  • cast (Cast) – The cast.

  • pmin (float, optional) – Top of the window (dbar).

Returns:

(down, up) in °C; NaN when the cast does not reach 60 dbar below pmin.

Return type:

tuple of float

processing_record lists every step applied to a cast — stage 1, the Sea-Bird steps in the raw header, stage 2, stage 3 and products — with the setting kept apart from what it did on the cast; profiles.nc stores it per cast as processing_record.

What was done to one cast, step by step, as plain rows: the cast’s processing record.

One list per cast, in the order the steps ran: how stage 1 read the raw file, the Sea-Bird steps recorded in its header (the deck unit’s advance and each SBE Data Processing module, with the conformance check against SBE’s documented values), stage 2’s soak and deck rule, and ctdcast’s stage-3 steps and products. Each row separates the setting (what was configured, the same on every cast processed alike) from the outcome (what the step did on this cast, such as how many values Wild Edit marked), so casts can be compared on their settings.

The cast page draws a cast’s rows; the profiles compile stores every cast’s rows in profiles.nc (record_json()), and the cruise processing page draws them as runs of casts. Everything is read from the stage file alone.

ctdcast.analysis.processing_record.BINAVG_KEPT_PARTLY_FLAGGED = "kept the good values of scans with a flagged value; seabirdscientific's bin_average drops such a scan whole"

The exception a product’s Bin Average records on a cast where it kept part of a flagged scan.

class ctdcast.analysis.processing_record.ProcessingRow(stage: str, step: str, producer: str, version: str, setting: str, outcome: str = '', variables: str = '', state: str = 'no_reference', reference: str = '', source: str = '', exception: str = '')[source]

One step applied to a cast.

stage

One of STAGES.

Type:

str

step

The step’s name (wildedit, alignctd, celltm, binavg (1dbar_down)…).

Type:

str

producer

What applied it (Sea-Bird’s software, or ctdcast and the seabirdscientific function).

Type:

str

version

The producer’s version, when the file records it.

Type:

str

setting

What was configured; casts processed alike have the same setting.

Type:

str

outcome

What the step did on this cast (counts), not compared across casts.

Type:

str

variables

The variables the step changed or marked.

Type:

str

state

The conformance check: match, differ or no_reference.

Type:

str

reference

The documented value checked against, when there is one.

Type:

str

source

Where that value comes from.

Type:

str

exception

How the step ran differently from its setting on this cast, as a fixed phrase that reads the same on every cast it applies to ("" when it ran as set). Not part of the setting, so it does not split casts into runs; the processing page lists it apart.

Type:

str

ctdcast.analysis.processing_record.STAGES = ('stage 1', 'Sea-Bird', 'stage 2', 'stage 3', 'product')

The stages a row can belong to, in the order they run.

ctdcast.analysis.processing_record.ctdcast_correction_rows(ds: Dataset) → list[tuple[Correction, ConformanceTick]][source]

Return ctdcast’s stage-3 corrections as the cast page’s (record, tick) rows.

Parameters:

ds (xarray.Dataset) – A stage-3 cast file.

Returns:

(Correction, ConformanceTick) per step, in the order stage 3 applied them; the record’s parameters are the setting and the outcome joined.

Return type:

list of tuple

ctdcast.analysis.processing_record.ctdcast_versions(ds: Dataset, method: str) → str[source]

Return "ctdcast X, seabirdscientific Y" for a stage-3 step, from the file alone.

ctdcast.analysis.processing_record.processing_rows(ds: Dataset) → list[ProcessingRow][source]

Return every step applied to a cast, in the order they ran.

Parameters:

ds (xarray.Dataset) – A cast’s stage file (any stage; a stage-1 file has only the stage-1 and Sea-Bird rows).

Returns:

Stage 1, the Sea-Bird header’s steps, stage 2, stage 3 and products.

Return type:

list of ProcessingRow

ctdcast.analysis.processing_record.record_json(ds: Dataset) → str[source]

Return processing_rows() as one JSON string, for a per-profile variable.

Parameters:

ds (xarray.Dataset) – A cast’s stage file.

Returns:

A JSON list of row objects (the ProcessingRow fields).

Return type:

str

ctdcast.analysis.processing_record.rows_from_json(text: str) → list[ProcessingRow][source]

Return the rows of a record_json() string; an empty string gives no rows.

Parameters:

text (str) – The stored JSON.

Returns:

The cast’s rows.

Return type:

list of ProcessingRow

sbe_compare compares a ctdcast stage file with a Sea-Bird CNV made from the same .hex, scan by scan: per-variable differences where neither side flags the scan, and the flags of each side counted against the other.

Compare a ctdcast stage file with a Sea-Bird CNV made from the same .hex.

The check behind every Sea-Bird step ctdcast applies: run the step on the .hex path, read the CNV the cruise made with the same step, and see whether the two agree scan by scan. Both come from the same raw scans, so at the native rate scan k in one is scan k in the other; the CNV is read through stage 1’s own renaming, so a variable has the same name and units on both sides.

What Sea-Bird marks as bad is kept apart from the numbers. Wild Edit replaces a value it rejects with the file’s bad_flag (-9.990e-29), and Loop Edit sets the flag column for a whole scan; both count as flagged in the CNV. On the ctdcast side a value is flagged when its {var}_qc is QARTOD 3 (suspect) or 4 (fail). Differences are taken only where neither side flags the scan, and the flagged scans are compared as flags.

ctdcast.analysis.sbe_compare.FLAGGED_QC = (3, 4)

QARTOD flags that count as flagged on the ctdcast side.

class ctdcast.analysis.sbe_compare.FlagAgreement(name: str, ref: int, ours: int, both: int)[source]

Where ctdcast and a CNV mark the same variable’s values.

name

Variable name.

Type:

str

ref

Values the CNV marks.

Type:

int

ours

Values ctdcast marks.

Type:

int

both

Values both mark.

Type:

int

class ctdcast.analysis.sbe_compare.VariableComparison(name: str, units: str, n_compared: int, median: float, rms: float, max_abs: float, flagged_ref: int, flagged_ours: int, flagged_both: int)[source]

One variable’s agreement between a ctdcast stage file and a CNV.

name

Variable name, the same on both sides.

Type:

str

units

Units of the differences (the ctdcast variable’s units).

Type:

str

n_compared

Scans where neither side flags the value and both are finite.

Type:

int

median, rms, max_abs

Of ctdcast minus CNV over the compared scans; NaN when none.

Type:

float

flagged_ref

Scans the CNV flags (bad-flag value or Loop Edit).

Type:

int

flagged_ours

Scans the ctdcast {name}_qc flags (3 or 4).

Type:

int

flagged_both

Scans flagged on both sides.

Type:

int

ctdcast.analysis.sbe_compare.compare(ours: Dataset, ref: Dataset, variables: list[str] | None = None) → list[VariableComparison][source]

Compare each variable present in both datasets, scan by scan.

Parameters:
  • ours (xarray.Dataset) – A ctdcast stage file read from the .hex.

  • ref (xarray.Dataset) – The CNV from read_reference().

  • variables (list of str, optional) – Which variables; default every one-dimensional numeric variable both carry, other than flags and Sea-Bird’s own derived quantities (sbe_*).

Returns:

In the order of variables, or of ours by default.

Return type:

list of VariableComparison

Raises:

ValueError – When the two have different scan counts: the comparison is scan by scan, and a difference in length means one of them dropped or averaged scans.

ctdcast.analysis.sbe_compare.comparison_table(rows: list[VariableComparison]) → str[source]

Return rows as a plain-text table, one variable per line.

Parameters:

rows (list of VariableComparison) – From compare().

Returns:

Columns: variable, units, scans compared, median, rms, max |d|, flagged (CNV / ctdcast / both).

Return type:

str

ctdcast.analysis.sbe_compare.flag_agreement(ours: dict[str, ndarray], ref: Dataset) → list[FlagAgreement][source]

Compare ctdcast’s marks for one step with the values the CNV set to its bad flag.

Sea-Bird’s Wild Edit replaces each value it rejects with the file’s bad flag, so a CNV’s per-value bad flags are Wild Edit’s marks; Loop Edit’s whole-scan marks are kept apart, in sbe_scan_flagged, and do not count here.

Parameters:
Returns:

One per variable in ours that the CNV also carries.

Return type:

list of FlagAgreement

ctdcast.analysis.sbe_compare.read_reference(cnv_path: Path | str) → Dataset[source]

Read a Sea-Bird CNV as stage 1 would name it, with Sea-Bird’s flags kept apart.

Parameters:

cnv_path (path-like) – The CNV.

Returns:

The CNV’s variables under ctdcast’s names and units. Values Sea-Bird flagged are NaN, and each variable that had any carries a boolean {var}_sbe_flagged; a scan Loop Edit marked is flagged in every variable. The two kinds are also kept apart: {var}_sbe_value_flagged for values set to the bad flag (Wild Edit) and sbe_scan_flagged for scans Loop Edit marked.

Return type:

xarray.Dataset


Cast processing

Stage 1 — CNV-to-netCDF conversion.

Defines the CtdBackend Protocol, concrete backend implementations, and stage1(), the public function that converts a directory of CNV files to per-cast netCDF. To add a new backend implement CtdBackend and add a branch in get_ctd_backend() — nothing else changes.

The converters module re-exports these names for backward compatibility.

class ctdcast.processors.stage1.CtdBackend(*args, **kwargs)[source]

Protocol for per-cast CNV-to-netCDF converters.

convert_cast(cnv_path: Path, nc_path: Path, *, force: bool = False, cruise_info: dict | None = None, sensor_overrides: SensorOverrides | None = None) → bool[source]

Convert one CNV file to netCDF.

Parameters:
  • cnv_path – Path to the raw SBE CNV input file.

  • nc_path – Desired output netCDF path.

  • force – If True, overwrite an existing nc_path.

  • cruise_info – The config cruise_info: mapping, stamped as cruise identity on the output; None writes none.

  • sensor_overrides – The config sensors: overrides, used to resolve the per-cast sensor catalog; None uses an empty SensorOverrides.

Returns:

True if the file was written; False if skipped.

Return type:

bool

ctdcast.processors.stage1.find_xmlcon(hex_path: Path) → Path[source]

Return the .xmlcon beside hex_path with the same stem, matched case-insensitively.

Seasave’s own naming mixes case (MIXSED2_004_b.hex beside MIXSED2_004_B.XMLCON), so both the stem and the extension are compared without case.

Parameters:

hex_path (pathlib.Path) – The .hex file.

Returns:

The matching .xmlcon.

Return type:

pathlib.Path

Raises:

FileNotFoundError – If there is no matching .xmlcon, or more than one.

ctdcast.processors.stage1.get_ctd_backend(name: str) → CtdBackend[source]

Return a CtdBackend instance for the given backend name.

Parameters:

name – "seasenselib" (.cnv) or "hex" (SBE 911plus .hex + .xmlcon).

Raises:
  • ValueError – If name is not a recognised backend.

  • ImportError – If the requested backend’s package is not installed.

ctdcast.processors.stage1.run(cnv_dir: Path, nc_dir: Path, *, force: bool = False, dry_run: bool = False, cast_tags: set[str] | None = None, **kw: object) → int[source]

Run stage1 (CNV → netCDF) for explicit input and output directories.

Called by ctdcast.processors.process() with stage=1 or stage="stage1".

Parameters:
  • cnv_dir – Directory containing raw SBE CNV files.

  • nc_dir – The CTD stage root; stage 1 writes stage1/<stem>_stage1.nc under it (the stage1 directory is created if absent).

  • force – Overwrite existing NC files.

  • dry_run – Print what would be converted without writing any files.

  • cast_tags – If given, process only files whose stem contains one of the zero-padded 3-digit cast numbers (e.g. {"042", "043"}).

  • **kw – Passed to stage1() (e.g. backend, pattern).

Returns:

Number of files written (0 for dry_run).

Return type:

int

ctdcast.processors.stage1.stage1(cnv_dir: Path, nc_dir: Path, *, backend: str = 'seasenselib', force: bool = False, cast_filter: int | list[int] | None = None, pattern: str = '*.cnv', cruise_info: dict | None = None, sensor_overrides: SensorOverrides | None = None) → int[source]

Convert per-cast CNV files to netCDF using the specified backend.

Parameters:
  • cnv_dir – Directory containing raw SBE CNV files.

  • nc_dir – The CTD stage root; stage 1 writes stage1/<stem>_stage1.nc under it (the stage1 directory is created if absent).

  • backend – Backend name (currently only "seasenselib").

  • force – Overwrite existing netCDF files.

  • cast_filter – If given, convert only files whose stem contains the zero-padded cast number. Accepts a single int or a list of ints for multi-cast filtering.

  • pattern – Filename glob pattern applied within cnv_dir (default: "*.cnv").

  • cruise_info – The config cruise_info: mapping, stamped as cruise identity on each per-cast file; None writes none (the default, so bare conversions are unchanged).

  • sensor_overrides – The config sensors: overrides, used to resolve the per-cast sensor catalog; None uses an empty SensorOverrides.

Returns:

Number of files written (skipped files not counted).

Return type:

int

Raises:

ImportError – If the chosen backend’s package is not installed.

Stage 2 — trim.

Downcast/upcast splitting and soak / back-on-deck detection. This is processing, not analysis: it decides which scans belong to the real cast.

apply_stage2() is the pipeline entry point: it sets QARTOD flag 4 on soak and post-recovery deck records and records the parameters used in ds.attrs["history"]. find_soak_end and find_cast_end are kept public because reports.cast calls them directly for report-time plot trimming (that coupling will be removed in a later phase when reports read flags from the files).

The turnaround convention (last pressure within 2 dbar of the maximum) and the soak/deck algorithms are deliberate — see the individual docstrings.

ctdcast.processors.stage2.apply_clock_offset(ds: Dataset, offset_seconds: float, *, n_casts: int | None = None, segment_sd: float | None = None) → Dataset[source]

Shift a cast’s time coordinate by a clock offset, preserving the uncorrected time.

A clock correction is a uniform translation of the time axis — every channel shifted identically, no measured value recomputed — which is why it belongs at stage 2 and is safe on already-binned data at the current sampling. offset_seconds is NMEA - System (the seconds added to acquisition time to obtain corrected time). The uncorrected time is kept as the time_orig auxiliary coordinate, whose presence also marks the file as corrected; and time_coverage_* are recomputed so the file does not contradict its own axis.

n_casts and segment_sd are the offset’s evidence — the count and sd of the population that produced it — supplied from the config that recorded the offset. Whichever is given is stamped onto clock_offset_seconds so the uncertainty travels with the number; when both are absent (a hand-written config), no statistics are recorded rather than a fabricated sd 0.00.

Refuses (raises ValueError) when the file already carries time_orig (already corrected — re-run from stage 1), when its time_coordinate_source classifies as GPS/NMEA (the coordinate is already on GPS, so a correction would introduce an error), or when that source cannot be classified as the System clock (unknown or absent — refuse rather than assume). The clock is classified with ctdcast.config.cnv_header.start_time_clock(), not a substring.

ctdcast.processors.stage2.apply_curated_drop(ds: Dataset, drop_names: list[str] | None = None) → Dataset[source]

Drop the curated set of SBE-derived channels stage 1 kept, recording what went.

Stage 1 is a faithful translation and keeps every CNV column (SeaBird-computed quantities under an sbe_ prefix); stage 2 is curated and removes them by default so the working product is not cluttered with duplicates of quantities ctdcast recomputes. The stage-1 file remains the record of what existed, so nothing is lost.

Parameters:
  • ds – The stage-2 Dataset (post soak/deck flags and clock correction).

  • drop_names – Explicit names to drop (the config trim.drop_sbe: list). None uses the default: every sbe_* channel present (the known likely-dead-weight set). An unrecognised channel is kept — name it in trim.drop_sbe: to drop it. A name not present is ignored.

Returns:

A new Dataset without the dropped channels; unchanged when none are present. The dropped names are recorded in history and in a dropped_channels attribute, so the file states what it no longer contains.

Return type:

xr.Dataset

ctdcast.processors.stage2.apply_stage2(ds: Dataset, *, near_surface_dbar: float = 10.0, search_seconds: float = 20.0, deck_window_seconds: float = 20.0, margin_dbar: float = 0.5, max_deck_dbar: float = 20.0) → Dataset[source]

Apply QARTOD flag 4 to soak and post-recovery deck records.

Creates {var}_qc arrays (int8, flag 1=pass) for each physical data variable, then sets flag 4 (fail) on the pre-descent soak window and the post-recovery on-deck window. Records the parameters used in ds.attrs["history"] so the treatment is reproducible from the output file alone.

Parameters:
  • ds – Per-cast Dataset (dim=time).

  • near_surface_dbar – Passed to find_soak_end — pressure threshold for last near-surface crossing before the real descent.

  • search_seconds – Passed to find_soak_end — backward-crawl window width.

  • deck_window_seconds – Passed to find_cast_end — tail window for on-deck reference pressure.

  • margin_dbar – Passed to find_cast_end — added to on-deck median to form the cut.

  • max_deck_dbar – Passed to find_cast_end — if on-deck median exceeds this, no trim.

Returns:

New Dataset; input is not mutated.

Return type:

xr.Dataset

ctdcast.processors.stage2.find_cast_end(pressure: ndarray, times: ndarray, deck_window_seconds: float = 20.0, margin_dbar: float = 0.5, max_deck_dbar: float = 20.0) → int[source]

Return the exclusive end index, trimming post-recovery deck records.

Algorithm:

  1. Take the median pressure of the last deck_window_seconds seconds as the on-deck reference pressure. Using a median handles sensor offset (the pressure sensor may not read exactly 0 dbar when the CTD is in the air) and is robust to brief oscillations on deck.

  2. Find the first index after the pressure maximum where pressure falls at or below p_deck_median + margin_dbar. Trim from that index onward.

Returns len(pressure) (no trim) if:

  • the record is empty or the CTD never returned near the surface (p_deck_median > max_deck_dbar), or

  • pressure never drops to the threshold on the upcast.

Parameters:
  • pressure – Pressure array in dbar.

  • times – Time coordinate array (numpy.datetime64 or numeric seconds).

  • deck_window_seconds – Duration of the tail window used to estimate on-deck pressure.

  • margin_dbar – Added to the on-deck median to form the cut threshold.

  • max_deck_dbar – If the on-deck median exceeds this value the CTD is considered not to have returned to the surface and no trim is applied.

Returns:

Exclusive end index; slice with ds.isel(time=slice(None, idx)).

Return type:

int

ctdcast.processors.stage2.find_soak_end(pressure: ndarray, times: ndarray, near_surface_dbar: float = 10.0, search_seconds: float = 20.0) → int[source]

Return the index at which the real downcast begins (exclusive end of soak).

Algorithm (three steps):

  1. Find i_max, the index of the global pressure maximum (deepest point of the cast). Searching only in pressure[0:i_max+1] keeps the upcast recovery — when the CTD returns to the surface at the end of the cast — from being confused with the pre-soak position.

  2. Within pressure[0:i_max+1], find the last index where pressure < near_surface_dbar. For a typical MSM-style cast this falls on the early real descent, just as the CTD passes near_surface_dbar going downward.

  3. Crawl backward from that index within search_seconds to find the minimum pressure — the shallowest point (closest to the surface) just before the real descent began. Return the index immediately after that minimum as the start of the real downcast.

In bad-weather conditions where the CTD soaks at depth and is never raised back to the surface, step 3 finds the minimum within the soak window and removes only the first search_seconds of the soak. The operator- visible effect is a truncation of the pre-soak data, not a clean removal.

Parameters:
  • pressure – Pressure array in dbar (1-D, same length as times).

  • times – Time coordinate array. May be numpy.datetime64 or numeric seconds; elapsed time is computed relative to times[0].

  • near_surface_dbar – Pressure threshold used to find the last near-surface crossing before the main descent. Default is 10 dbar (≈10 m), safely below the typical soak depth of 8–10 m.

  • search_seconds – Width of the backward-crawl window (seconds) used to find the pre-descent surface minimum. Default is 20 s.

Returns:

Index of the first record to keep; slice with ds.isel(time=slice(idx, None)). Returns 0 if the cast never reaches below near_surface_dbar (no trim applied).

Return type:

int

ctdcast.processors.stage2.run(root: Path, *, force: bool = False, dry_run: bool = False, cast_tags: set[str] | None = None, cruise_cfg: dict | None = None, **kw: object) → int[source]

Apply stage 2 (soak/deck flagging) across the casts under root.

Reads each cast’s stage-1 file, applies apply_stage2(), and writes a new stage2/<stem>_stage2.nc — never in place, so stage 1 stays frozen and the run is re-runnable. Reads are strict: a cast with no stage-1 file is skipped with a warning, not silently promoted from a lower stage. Called by ctdcast.processors.process() with stage=2.

Parameters:
  • root – The CTD stage root (ctd_root). Stage files live under root/stage1/ … root/stage2/; an old flat nc_dir is read as stage 1 via the compatibility shim in ctdcast.processors.stage_layout.

  • force – Rewrite the stage-2 file even when it already exists. Without force, a cast whose stage2/<stem>_stage2.nc exists is skipped.

  • dry_run – Print what would be processed without writing any output.

  • cast_tags – If given, process only casts selected by these zero-padded tags (e.g. {"042"}), matched on the parsed cast identity.

  • cruise_cfg – The settings from ctdcast.config.layout.processing_view(), read for the stage-2 curated drop (trim.drop_sbe) and the clock correction; None uses defaults.

  • **kw – Tuning forwarded to apply_stage2() (e.g. near_surface_dbar); keys it does not accept are ignored.

Returns:

Number of stage-2 files written (0 for dry_run).

Return type:

int

Raises:

FileNotFoundError – If root does not exist or is not a directory.

ctdcast.processors.stage2.split_cast(ds: Dataset) → tuple[Dataset, Dataset][source]

Split ds (individual cast file, dim=time) into (downcast, upcast).

Uses the turnaround convention: last index where pressure is within 2 dbar of its maximum.

Stage 3 — QC, calibration, and derived-variable orchestrator.

Stage3 is iterative: re-run it as calibration improves. Each run applies the per-sensor conductivity slope and offset and the processing steps configured for the cruise (data_processing:), re-derives salinity, derives SBE 43 oxygen from the voltage where a cast carries it, and then runs gross-range and spike QC on the corrected values.

ctdcast.processors.stage3.product_path(root: Path, stem: str, name: str) → Path[source]

Return where a cast’s product is written: <root>/products/<name>/<stem>_<name>.nc.

Parameters:
  • root (pathlib.Path) – The CTD stage root (ctd_root).

  • stem (str) – The cast’s file stem (MIXSED2_050).

  • name (str) – The product’s name.

Returns:

The product file’s path.

Return type:

pathlib.Path

ctdcast.processors.stage3.run(root: Path, *, force: bool = False, dry_run: bool = False, cast_tags: set[str] | None = None, cruise_info: dict | None = None, **kw: object) → int[source]

Apply stage 3 (QC + calibration) across the casts under root.

Reads each cast’s stage-2 file, applies stage3(), and writes a new stage3/<stem>_stage3.nc — never in place. Reads are strict: a cast with no stage-2 file is skipped with a warning (its soak/deck flags were never applied, so QC’ing it would manufacture a product whose filename lies). Called by ctdcast.processors.process() with stage=3.

Parameters:
  • root – The CTD stage root (ctd_root). Stage files live under root/stage2/ … root/stage3/.

  • force – Rewrite the stage-3 file even when it already exists. Without force, a cast whose stage3/<stem>_stage3.nc exists is skipped.

  • dry_run – Print what would be processed without writing any output.

  • cast_tags – If given, process only casts selected by these zero-padded tags (e.g. {"042"}), matched on the parsed cast identity.

  • cruise_info – The config cruise_info: block. When it declares data_mode: D, each stage-3 file is stamped data_mode = "D"; if no calibration was actually applied the delayed-mode claim is unsupported, so the cast is named in a warning and the gap recorded in history.

  • **kw – Passed to stage3() (e.g. cruise_cfg).

Returns:

Number of stage-3 files written (0 for dry_run).

Return type:

int

Raises:

FileNotFoundError – If root does not exist or is not a directory.

ctdcast.processors.stage3.stage3(ds: Dataset, cruise_cfg: dict | None = None, *, cast_number: int | None = None, cast_label: str = '?', context: StepContext | None = None) → Dataset[source]

Apply the configured processing steps, derived variables and QC to a per-cast Dataset.

Applies, in order:

  1. The per-sensor conductivity slope and offset (data_processing.slope_offset), as Sea-Bird applies them when it converts the raw counts.

  2. data_processing.steps, in the order listed: wildedit and loopedit (ctdcast.processors.editing), filter and window_filter (ctdcast.processors.filtering), alignctd and celltm (ctdcast.processors.corrections.apply_corrections()), from ctdcast.processors.steps.STEPS. A step ctdcast does not apply yet is skipped (run refuses it unless data_processing.allow_unapplied), with a warning and a history note. The order they ran in is written to the data_processing_steps attribute.

  3. Re-derives practical salinity whenever a step changed conductivity, temperature or pressure.

  4. Derives ctd_oxygen from the SBE 43 voltage on a cast that carries oxygen_raw_<N> and no converted oxygen (ctdcast.processors.corrections.derive_oxygen()), with the window in data_processing.oxygen.

  5. Two-tier gross-range QC and the QARTOD spike test, on the corrected values, using the package defaults merged with qc.gross_range / qc.spike.

Parameters:
  • ds (xarray.Dataset) – Per-cast Dataset (dim=time), already through stage1 and stage2.

  • cruise_cfg (dict or None) – The settings from ctdcast.config.layout.processing_view(): data_processing and qc are read here.

  • cast_number (int or None) – The cast’s number, for per-cast-range values.

  • cast_label (str) – How the cast is named in warnings (e.g. "011").

  • context (StepContext, optional) – Filled in as the steps run (Wild Edit’s marks, Loop Edit’s scans), for the products made from this cast in the same run.

Returns:

New Dataset; input is not mutated. Values read from a file (stored float32) are computed on in float64.

Return type:

xarray.Dataset

Stage QC — two-tier gross-range and spike flagging.

Each test has a suspect tier (QARTOD flag 3) and a fail tier (flag 4); the wider fail bound wins, and a more-severe flag is never downgraded (worst-flag-wins). Non-finite samples are marked missing (flag 9), not pass. The thresholds applied are recorded as attributes on each {var}_qc companion so the treatment reconstructs from the file alone. Operates on per-cast Datasets (dim=time); call after apply_stage2 so the soak/deck flags are already present.

Note: config overrides are trusted, not validated — a suspect range set wider than its fail range is accepted as given (ioos_qc would reject it).

ctdcast.processors.qc.GROSS_RANGE_FAIL: dict[str, tuple[float, float]] = {'conductivity_1': (0.0, 75.0), 'conductivity_2': (0.0, 75.0), 'ctd_fluor': (0.0, 50.0), 'ctd_oxygen': (0.0, 450.0), 'ctd_oxygen_1': (0.0, 450.0), 'ctd_oxygen_2': (0.0, 450.0), 'ctd_salinity': (0.0, 40.0), 'ctd_salinity_1': (0.0, 40.0), 'ctd_salinity_2': (0.0, 40.0), 'ctd_temperature': (-2.5, 40.0), 'ctd_temperature_1': (-2.5, 40.0), 'ctd_temperature_2': (-2.5, 40.0), 'ctd_turbidity': (0.0, 50.0), 'fluorescence': (0.0, 50.0), 'oxsat_1': (0.0, 200.0), 'oxygen_1': (0.0, 450.0), 'oxygen_saturation': (0.0, 200.0), 'pressure': (-5.0, 7000.0), 'salinity_1': (0.0, 40.0), 'salinity_2': (0.0, 40.0), 'temperature_1': (-2.5, 40.0), 'temperature_2': (-2.5, 40.0), 'turbidity': (0.0, 50.0)}

outside is instrument malfunction.

Type:

Gross-range FAIL bounds (flag 4)

ctdcast.processors.qc.GROSS_RANGE_SUSPECT: dict[str, tuple[float, float]] = {'conductivity_1': (0.0, 65.0), 'conductivity_2': (0.0, 65.0), 'ctd_salinity': (2.0, 40.0), 'ctd_salinity_1': (2.0, 40.0), 'ctd_salinity_2': (2.0, 40.0), 'ctd_temperature': (-2.0, 35.0), 'ctd_temperature_1': (-2.0, 35.0), 'ctd_temperature_2': (-2.0, 35.0), 'pressure': (-0.5, 7000.0), 'salinity_1': (2.0, 40.0), 'salinity_2': (2.0, 40.0), 'temperature_1': (-2.0, 35.0), 'temperature_2': (-2.0, 35.0)}

outside is oceanographically implausible.

Type:

Gross-range SUSPECT bounds (flag 3)

ctdcast.processors.qc.QARTOD_MISSING = np.int8(9)

no measurement exists at that point (e.g. shifted past a cast’s end).

Type:

QARTOD 9 “missing”

ctdcast.processors.qc.QARTOD_SUSPECT = np.int8(3)

QARTOD primary flag values (IOOS QARTOD). The complete vocabulary — every value and its meaning — is encoded in _qc_attrs(); these name the two flags the ctdcast pipeline sets, so the code that writes a flag, the code that masks on it, and the vocabulary that gives it meaning share one definition.

ctdcast.processors.qc.SPIKE_FAIL: dict[str, float] = {'conductivity_1': 5.0, 'conductivity_2': 5.0, 'ctd_salinity': 2.0, 'ctd_salinity_1': 2.0, 'ctd_salinity_2': 2.0, 'ctd_temperature': 6.0, 'ctd_temperature_1': 6.0, 'ctd_temperature_2': 6.0, 'pressure': 50.0, 'salinity_1': 2.0, 'salinity_2': 2.0, 'temperature_1': 6.0, 'temperature_2': 6.0}

Spike FAIL thresholds (flag 4). Oxygen has no fail default yet (suspect only).

ctdcast.processors.qc.SPIKE_SUSPECT: dict[str, float] = {'conductivity_1': 2.0, 'conductivity_2': 2.0, 'ctd_oxygen': 20.0, 'ctd_oxygen_1': 20.0, 'ctd_oxygen_2': 20.0, 'ctd_salinity': 1.0, 'ctd_salinity_1': 1.0, 'ctd_salinity_2': 1.0, 'ctd_temperature': 2.0, 'ctd_temperature_1': 2.0, 'ctd_temperature_2': 2.0, 'oxygen_1': 20.0, 'pressure': 10.0, 'salinity_1': 1.0, 'salinity_2': 1.0, 'temperature_1': 2.0, 'temperature_2': 2.0}

Spike SUSPECT thresholds (flag 3) on |v[i] - (v[i-1]+v[i+1])/2|, in the variable’s units. Fluorescence and turbidity are excluded — natural fine-scale variability, not instrument spikes.

ctdcast.processors.qc.apply_gross_range(ds: Dataset, thresholds: dict | None = None) → Dataset[source]

Two-tier gross-range QC: flag 3 outside suspect bounds, flag 4 outside fail.

Creates {var}_qc companions (int8, 1=pass) as needed, sets suspect (3) then fail (4) so the wider fail bound wins, and records the applied bounds (qc_gross_range_{suspect,fail}_{min,max}) on each companion so the report reads them back. A more-severe flag is never downgraded.

Parameters:
  • ds – Per-cast Dataset (dim=time); input is not mutated.

  • thresholds – Config overrides with suspect and/or fail sub-dicts of {var: (min, max)}, merged over GROSS_RANGE_SUSPECT / GROSS_RANGE_FAIL.

Returns:

New Dataset with the flags and threshold attributes.

Return type:

xr.Dataset

ctdcast.processors.qc.apply_spike_test(ds: Dataset, thresholds: dict | None = None) → Dataset[source]

Two-tier QARTOD spike test: flag 3 above the suspect threshold, flag 4 above fail.

The spike metric for an interior sample is |v[i] - (v[i-1] + v[i+1]) / 2|; endpoints are not evaluated. Records the thresholds (qc_spike_{suspect,fail}_threshold) on each {var}_qc. Fluorescence and turbidity have no spike test (natural fine-scale variability). A more-severe flag is never downgraded.

Parameters:
  • ds – Per-cast Dataset (dim=time); input is not mutated.

  • thresholds – Config overrides with suspect and/or fail sub-dicts of {var: threshold}, merged over SPIKE_SUSPECT / SPIKE_FAIL.

Returns:

New Dataset with the flags and threshold attributes.

Return type:

xr.Dataset

ctdcast.processors.qc.usable_pressure(ds: Dataset) → ndarray[source]

Return the cast’s pressure, NaN where pressure_qc is fail (4) or missing (9).

Pressure places every other value in the cast: it picks the deepest scan, the bins and the grid. A scan whose pressure failed a test (a Wild Edit mark, a gross-range fail) has no trustworthy depth, so it is left out of all three, as SBE Data Processing drops a scan Wild Edit marked. Without pressure_qc the pressure is returned as it is.

Parameters:

ds (xarray.Dataset) – A cast with pressure and, optionally, pressure_qc.

Returns:

Pressure as float, a copy.

Return type:

numpy.ndarray

Cruise-level profile compiler: per-cast netCDF → profiles.nc.

Reads all per-cast netCDF files in a directory, splits each into downcast and upcast halves, bins to a common 1-dbar grid, and writes a single (N_PROF × pressure) netCDF. The converters module re-exports build_profiles for backward compatibility.

ctdcast.processors.profiles.build_profiles(nc_dir: Path, profiles_path: Path, *, force: bool = False, gebco_path: Path | None = None, dbar: int = 1, cruise_info: dict | None = None, cruise_cfg: dict | None = None, refuse_catalog_less: bool = False) → bool[source]

Compile per-cast netCDF files into a single profiles.nc on a dbar-spaced grid.

Reads all *.nc files in nc_dir, splits each cast into downcast and upcast halves, bins to a common dbar-dbar pressure grid (default 1 dbar), and writes a single (N_PROF × pressure) netCDF. N_PROF is a plain integer index (0, 1, 2, …); cast identity is carried by cast_number, cast_suffix, and cast_direction variables. The bin spacing is recorded in the pressure_spacing_dbar global attribute so the gridding can be reconstructed from the output file alone.

Per-cast scalar variables added to the output:

  • max_pressure_dbar — maximum pressure recorded over the full cast.

  • gebco_depth_m — GEBCO bathymetry depth (m, positive down) at the max-pressure lat/lon position; NaN when gebco_path is None or the file is unavailable.

The altimeter channel (when present in the input files) is binned onto the 1-dbar grid as a standard 2-D variable.

Samples carrying a QARTOD fail (4) or missing (9) flag on their {var}_qc companion are NaN-masked before binning, so failed data does not enter the bin means; a suspect (3) sample is kept, as in a product’s Bin Average. Each science variable records how many finite input samples it carried (qc_input_samples) and how many were excluded (qc_excluded_samples).

Parameters:
  • nc_dir – Directory containing per-cast netCDF files.

  • profiles_path – Output path for the compiled profiles netCDF.

  • force – Overwrite an existing profiles_path.

  • gebco_path – Path to a GEBCO_2025.nc file. Used to look up water depth at each cast’s max-pressure position. Pass cfg.gebco_path when calling from report generation code. Silently omitted when None.

  • dbar – Vertical bin spacing (dbar) of the output grid. Default 1. Use 2 (or more) to average adjacent pressure levels together, reducing per-level noise when the raw scan resolution does not justify a 1-dbar grid.

  • cruise_info – The cruise_info: mapping from the cruise config. Supplies the cruise id (so the compiled file is not labelled UNK), the authored discovery fields, people, embargo, and the ship/start_date from which the EXPOCODE coordinate is derived. Coverage bounds and creation time are computed from the data, not taken from here.

  • cruise_cfg – The settings from ctdcast.config.layout.processing_view(). Used only to reconcile the preferred_pair / preferred_oxygen declaration against the per-cast sensor serials (validate_preferred()); a declared range crossing a hardware swap, or a swap segment the declaration does not cover, is warned — never an error, never a block on compiling.

  • refuse_catalog_less – Policy for a CTD cast whose per-cast file carries no SENSOR_* catalog (it predates sensor provenance). The default False is the library behaviour: warn once, name the files, and stamp the admission into the output so the gap is visible in the file itself. The pipeline driver (ctdcast process --stage profiles and ctdcast run) passes True so the compile refuses instead — at the point a product is shipped, re-running stage 1 to build the catalog is the actionable fix.

Returns:

True if profiles.nc was written; False if skipped (existed, force=False).

Return type:

bool

Raises:

ValueError – If no recognised cast files are found in nc_dir, or if refuse_catalog_less is True and any cast carries no sensor catalog.

ctdcast.processors.profiles.run(nc_dir: Path, profiles_path: Path, *, force: bool = False, dry_run: bool = False, **kw: object) → bool[source]

Build profiles.nc from NC files in nc_dir.

Called by ctdcast.processors.process() with stage="profiles".

Parameters:
  • nc_dir – Directory of per-cast netCDF files.

  • profiles_path – Output path for the compiled profiles netCDF.

  • force – Overwrite an existing profiles.nc.

  • dry_run – Print what would be built without writing any output.

  • **kw – Passed to build_profiles() (e.g. gebco_path).

Returns:

True if profiles.nc was written; False if skipped (or dry_run).

Return type:

bool

ctdcast.processors.profiles.validate_preferred_against_catalog(cruise_cfg: dict | None, catalog_by_cast: dict[int, list[dict]]) → list[str][source]

Reconcile the preferred-sensor declaration against the per-cast sensor serials.

Runs validate_preferred() for every group and returns the collected messages — it does not emit them, so each caller chooses how (the profiles compile re-raises them as warnings; ctdcast validate collects them into its own report). Reporting at both call sites catches a bad declaration before compiling. The conditions reported: a declared range crossing a hardware-segment boundary, and a derived segment the declaration does not cover. A partial declaration is a normal mid-processing state, never an error.

Parameters:
  • cruise_cfg – The settings from ctdcast.config.layout.processing_view() (None or absent declarations → no messages).

  • catalog_by_cast – Per-cast SENSOR_* catalog records keyed by integer cast number.

Returns:

The reconciliation messages (empty when the declaration is coherent).

Return type:

list of str

Read the SENSOR_* catalog stage 1 built, from any per-cast stage file.

Stage 1 writes a dimensionless SENSOR_<TYPE>_<SERIAL> variable per physical sensor, carrying its sensor_role and sensor_channel. This module reads that catalog back — the inverse of the stage-1 builder — so every later step (the stage-3 preferred-sensor stamp, the profiles.nc compile, and ctdcast validate) shares one reader and no stage imports a later stage.

ctdcast.processors.sensor_catalog.catalog_by_cast_number(per_identity: Iterable[tuple[tuple[int, str], list[dict]]]) → tuple[dict[int, list[dict]], list[str]][source]

Collapse per-identity catalogs to one per cast number, flagging sibling mismatches.

The preferred-sensor declaration is per cast number, so a plain cast and its lettered sibling (010 / 010b) share one declaration and collapse to one entry here. When two siblings sharing a number carry different sensor serials, the per-number declaration cannot distinguish them — a warning naming both casts is returned so the operator knows the reconciliation treats them as one.

Parameters:

per_identity (iterable of ((int, str), list of dict)) – ((cast_number, cast_suffix), records) pairs — one per cast identity, records as returned by read_cast_sensor_catalog().

Returns:

tuple of (dict of {int – The catalog keyed by cast number (a later sibling overwrites an earlier one), and the sibling-mismatch warning strings (empty when no number has differing siblings).

Return type:

list of dict}, list of str)

ctdcast.processors.sensor_catalog.read_cast_sensor_catalog(ds: Dataset) → list[dict][source]

Return one record per SENSOR_* catalog entry in a per-cast dataset.

Reads the catalog stage 1 built: each dimensionless SENSOR_<TYPE>_<SERIAL> variable, taking its sensor_role and sensor_channel off the entry itself (not off the data variables). A sensor with no stored variable — pH, a transmissometer — is therefore read exactly like one that has a variable, which is what lets the compile aggregate without re-parsing the CNV header.

Parameters:

ds (xarray.Dataset) – A per-cast dataset carrying the stage-1 SENSOR_* catalog variables.

Returns:

One record per catalog entry, each with name (the catalog variable name, already resolved at stage 1), role, channel (int, or -1 if unstated) and attrs (the full entry attributes, verbatim). [] when the cast carries no catalog.

Return type:

list of dict

Stamped history notes for the processing stages.

Every stage records what it did — and the parameters it used — as a line in the CF history global attribute, so the treatment is reconstructable from the output file alone. Because each stage reads its predecessor and copies its attributes, history accumulates: stage 3 inherits the stage 1 and stage 2 lines and appends its own.

The format, from one helper so it stays consistent, is:

<timestamp> <producer> <version> <stage>: <note>

joined with newlines. ctdcast’s own stages use the defaults — an ISO-8601 UTC timestamp, producer ctdcast — giving <ISO-8601 UTC> ctdcast <version> <stage>. An upstream Sea-Bird step overrides producer ("SBE Data Processing"), timestamp (the tool’s own verbatim stamp, no Z) and the stage field (the module name, e.g. celltm), so a stage-1 file’s history shows Sea-Bird’s own lines alongside ctdcast’s.

ctdcast.processors.history.PL_CONVERTED = 'Instrument data that has been converted to geophysical values'

OceanSITES reference-table-3 processing_level values, verbatim. A variable can carry several at once (converted, then calibrated, then flagged): they are joined with "; " in the order applied by add_processing_level(), so the attribute doubles as the per-variable procedure sequence. Comma is unusable as a separator — RANGES_FLAGGED contains one.

ctdcast.processors.history.add_processing_level(attrs: MutableMapping[str, object], value: str) → None[source]

Append a table-3 processing_level value to attrs, idempotently.

The attribute is an ordered set joined with "; ": value is appended only if it is not already present, so re-running a stage — or two stages that apply the same procedure (stage-2 soak/deck and stage-3 gross-range both flag) — never accumulates a duplicate. Order of first application is preserved, so the attribute reads as the procedure sequence.

Parameters:
  • attrs – A variable’s attribute mapping (ds[var].attrs), mutated in place.

  • value – One of the PL_* table-3 strings.

ctdcast.processors.history.append_history(attrs: MutableMapping[str, object], note: str, *, stage: str, version: str = '0.4.1', producer: str = 'ctdcast', timestamp: str | None = None, prepend: bool = False) → None[source]

Append a stamped history line to attrs in place.

Parameters:
  • attrs – The attribute mapping to extend — an xarray ds.attrs or the plain dict a builder assembles before constructing its Dataset. Mutated in place: the existing history (if any) is preserved and the new line is appended after a newline.

  • note – The human-readable record of the operation, including the parameters it used (e.g. "gross_range: ctd_salinity_1:[2.0,42.0]").

  • stage – The stage token that did the work — "stage1", "stage2", "stage3", "profiles", "ladcp_profiles" for ctdcast’s own stages, or a Sea-Bird module name ("celltm", "binavg", …) for an upstream step.

  • version – The version to stamp; defaults to the installed ctdcast package version.

  • producer – Who did the work — "ctdcast" by default. An upstream Sea-Bird step passes "SBE Data Processing" so the line reads as Sea-Bird’s, not ctdcast’s.

  • timestamp – The stamp to use. None (the default) uses the current ISO-8601 UTC time. A Sea-Bird step passes its own verbatim timestamp, kept as-is — no Z is appended, because it comes from a processing workstation whose offset is unknown and a different clock again from the deck unit.

  • prepend – Insert the line at the front of history instead of the end. Used for an upstream step (a Sea-Bird module) that predates the reader’s own line, so the record stays oldest-first; the default appends.

The processing steps data_processing.steps may list: one table, used by stage 3 and the checks.

Each Step names a Sea-Bird module, says whether stage 3 applies it yet, how it is applied, and how its parameters are checked before any cast is processed. STEPS is the single list: adding a step is one row here; stage 3, iter_steps() and validate_data_processing() all read it.

A step listed in the config but not yet applied is refused unless the config says allow_unapplied: true beside steps: the steps after it would otherwise run on data the config meant to be changed first, and the stage-3 file would look complete. With the switch, the step is skipped, named in a warning, in history and in the file’s data_processing_steps attribute.

ctdcast.processors.steps.PRODUCT_ONLY = ('split', 'binavg')

allowed only in data_processing.products.

Type:

Steps that change which scans there are

ctdcast.processors.steps.STEPS: dict[str, Step] = {'alignctd': Step(name='alignctd', apply=<function _apply_correction.<locals>.run>, check=<function _check_alignctd>), 'binavg': Step(name='binavg', apply=None, check=<function _check_binavg>), 'celltm': Step(name='celltm', apply=<function _apply_correction.<locals>.run>, check=<function _check_celltm>), 'filter': Step(name='filter', apply=<function _apply_filtering.<locals>.run>, check=<function _check_filter>), 'loopedit': Step(name='loopedit', apply=<function _apply_loopedit>, check=<function _check_loopedit>), 'split': Step(name='split', apply=None, check=<function _check_split>), 'wildedit': Step(name='wildedit', apply=<function _apply_wildedit>, check=<function _check_wildedit>), 'window_filter': Step(name='window_filter', apply=<function _apply_filtering.<locals>.run>, check=<function _check_window_filter>)}

Every step data_processing.steps may list, in no particular order.

class ctdcast.processors.steps.Step(name: str, apply: Callable[[Dataset, dict, StepContext], Dataset] | None, check: Callable[[Any, int | None], None])[source]

One processing step stage 3 knows.

name

The step’s name in data_processing.steps, as Sea-Bird names the module.

Type:

str

apply

apply(ds, params, ctx) -> ds; None while stage 3 does not apply it yet.

Type:

callable or None

check

check(params, cast): raises ValueError on a malformed entry for that cast.

Type:

callable

class ctdcast.processors.steps.StepContext(cast_number: int | None = None, cast_label: str = '?', excluded: ndarray | None = None, marked: dict[str, ~numpy.ndarray]=<factory>, changed: set[str] = <factory>, edge_masks: dict[str, ~numpy.ndarray]=<factory>, applied: list[str] = <factory>)[source]

What one cast’s steps share as they run, in order.

cast_number

The cast’s number, for per-cast-range values.

Type:

int or None

cast_label

How the cast is named in warnings.

Type:

str

excluded

Scans an earlier Loop Edit marked, for a later Wild Edit’s or Window Filter’s exclude_flagged.

Type:

numpy.ndarray or None

marked

{variable: mask} of values an earlier Wild Edit marked, which later filters leave out.

Type:

dict

changed

Variables whose values a step changed.

Type:

set of str

edge_masks

{variable: mask} of scans an alignment set NaN.

Type:

dict

applied

What ran, in order, one entry per step ("filter (not applied)" for one skipped).

Type:

list of str

ctdcast.processors.steps.iter_steps(data_processing: dict | None) → list[tuple[str, dict]][source]

Return data_processing.steps as (name, parameters) pairs, in order.

Parameters:

data_processing (dict or None) – The data_processing: config block.

Returns:

One pair per entry; a step may appear more than once.

Return type:

list of (str, dict)

Raises:

ValueError – When an entry is not a one-key mapping or names an unknown step.

ctdcast.processors.steps.unapplied(data_processing: dict | None) → list[str][source]

Return the listed steps stage 3 does not apply yet, in order, each once.

Parameters:

data_processing (dict or None) – The data_processing: config block.

Returns:

Step names.

Return type:

list of str

ctdcast.processors.steps.validate_data_processing(data_processing: dict | None) → None[source]

Check the data_processing: block before any cast is processed.

Every step’s values are resolved for the default and for every cast named in a range, so a typo or a non-numeric value fails once, up front. A listed step stage 3 does not apply yet is refused unless allow_unapplied: true.

Parameters:

data_processing (dict or None) – The data_processing: config block.

Raises:

ValueError – On the first malformed entry, naming it; or on a step not yet applied, without allow_unapplied.

Stage-3 editing at the native scan rate: Sea-Bird’s Wild Edit and Loop Edit.

Wild Edit marks values that sit far from the rest of their block of scans, as SBE Data Processing’s module of the same name does: in each block of scans_per_block scans, the values beyond pass1_nstd standard deviations of the block mean are set aside, the mean and standard deviation are recomputed from what is left, and a value is marked when it lies beyond pass2_nstd of those and farther than mindelta from the mean. The last, partial block is judged against the last full scans_per_block scans of the cast.

Sea-Bird replaces a marked value with its bad flag; ctdcast keeps the value and sets {var}_qc to QARTOD 4 (fail), so nothing is lost and the edit is visible in the file. The parameters and the number of values marked are recorded on each variable and in history.

The marking is seabirdscientific.processing.wild_edit()’s; ctdcast turns its bad-flag values into _qc flags and keeps the data.

Where it appears to differ from SBE Data Processing (Sea-Bird’s Windows program). On a block where a channel sits at one or two A/D levels (an SBE 43 voltage, altimeter or fluorescence near the surface), the standard deviation left after the first pass is about zero. With mindelta 0 the Windows program then marks every value in the block; seabirdscientific marks only the values off the block’s main level. On OdB cast 050 every value ctdcast marked was also marked in the cruise’s CNV, which marked 5–10 times more on those channels, in whole blocks. The cause is inferred from the output, not from the Windows program’s source. A mindelta of a few A/D steps on such channels avoids both.

Loop Edit marks whole scans where the package went up on the downcast (or down on the upcast), moved slower than min_velocity, or was still in the surface soak, with seabirdscientific.processing.loop_edit(). ctdcast keeps every value: the marks go into loop_edit_flag and QARTOD 4 in each variable’s _qc, and later steps (Wild Edit and Window Filter with exclude_flagged, Bin Average) leave the marked scans out.

Deck pressure. With deck_pressure: true, seabirdscientific offsets the soak window by the first scan’s depth. On OdB casts 011, 017 and 050, whose CNV headers say useDeckPress = 1, SBE Data Processing’s marks match no offset instead (the recordings start with the package already in the water, 1.8–7.5 dbar): with the first-scan offset the soak runs 90–800 scans longer, with none the two agree except at 20–40 single scans at the speed threshold. deck_pressure also takes a number, the deck pressure in dbar, so deck_pressure: 0 reproduces those CNVs.

Configuration, a step in data_processing.steps:

- wildedit:
    pass1_nstd: 2.0
    pass2_nstd: 20.0
    mindelta: 0.0
    scans_per_block: 100
    exclude_flagged: true    # leave scans an earlier Loop Edit marked out of the statistics
    variables: [pressure, ctd_temperature_1, conductivity_1]
- loopedit:
    min_velocity: 0.25         # dbar/s; or mean_speed_percent: 20 with window_seconds: 300
    surface_soak: {min_depth: 5.0, max_depth: 20.0, deck_pressure: true}   # or false
    exclude_flagged: true
ctdcast.processors.editing.DEFAULT_WILD_EDIT_VARIABLES = ('pressure', 'ctd_temperature_1', 'ctd_temperature_2', 'conductivity_1', 'conductivity_2', 'oxygen_raw_1', 'oxygen_raw_2')

Variables edited when the config names none.

ctdcast.processors.editing.LOOP_EDIT_FLAG = 'loop_edit_flag'

What loop_edit_flag holds.

class ctdcast.processors.editing.LoopEdit(min_velocity: float, mean_speed_percent: float | None, window_seconds: float, surface_soak: bool, min_depth: float, max_depth: float, deck_pressure: bool | float, exclude_flagged: bool, starts_below: str = 'skip')[source]

Resolved Loop Edit parameters.

min_velocity

Slowest good speed along the leg, dbar/s (fixed), or the floor under the percent rule.

Type:

float

mean_speed_percent

When set, a scan is good if its speed is at least this percentage of the mean speed over window_seconds; None for the fixed rule.

Type:

float or None

window_seconds

The window of the mean-speed rule.

Type:

float

surface_soak

Mark the surface soak: the scans before the package passes min_depth after its last excursion above it, below max_depth.

Type:

bool

min_depth, max_depth

The soak window, in metres.

Type:

float

deck_pressure

True: offset the soak window by the first scan’s depth (seabirdscientific’s meaning); a number: offset it by that pressure, in dbar; False: no offset.

Type:

bool or float

exclude_flagged

Keep the marks of an earlier Loop Edit.

Type:

bool

starts_below

What to do with a cast whose recording is below the soak window before it is in it (a yo-yo cut into casts at depth): "skip" runs it without the soak test, as there is no soak to remove; "fail" refuses the cast.

Type:

str

describe() → str[source]

Return the parameters as one line, for attributes and history.

ctdcast.processors.editing.SOAK_NOT_APPLIED = 'surface soak not applied'

How a cast’s record starts when Loop Edit ran it without the soak test.

ctdcast.processors.editing.WILD_EDIT_DEFAULTS: dict[str, float | int | bool] = {'exclude_flagged': True, 'mindelta': 0.0, 'pass1_nstd': 2.0, 'pass2_nstd': 20.0, 'scans_per_block': 100}

SBE Data Processing’s example values (its Wild Edit dialog), used for a key the config leaves out.

class ctdcast.processors.editing.WildEdit(pass1_nstd: float, pass2_nstd: float, mindelta: float, scans_per_block: int, exclude_flagged: bool, variables: tuple[str, ...])[source]

Resolved Wild Edit parameters.

pass1_nstd, pass2_nstd

Standard deviations for the first and second passes.

Type:

float

mindelta

A value closer to the block mean than this is never marked, in the variable’s units.

Type:

float

scans_per_block

Scans per block.

Type:

int

exclude_flagged

Leave scans an earlier Loop Edit marked out of the block statistics.

Type:

bool

variables

Variables to edit.

Type:

tuple of str

describe() → str[source]

Return the parameters as one line, for attributes and history.

ctdcast.processors.editing.apply_loop_edit(ds: Dataset, params: dict, interval: float, *, excluded: ndarray | None = None, cast_label: str | None = None) → tuple[Dataset, ndarray][source]

Apply Loop Edit to one cast: mark whole scans, keep every value.

A cast whose recording is below the soak window before it is in it has no soak to remove: with surface_soak.starts_below: skip (the default) it runs without the soak test and the reason is recorded on loop_edit_flag and in history; with fail it is refused. A cast that never goes below the window runs without the soak test either way, with its reason recorded.

The marks are written as loop_edit_flag (1 where marked) and as QARTOD 4 in every variable that has a _qc; the parameters are recorded on loop_edit_flag and in history.

Parameters:
  • ds (xarray.Dataset) – A dataset at its native scan rate, with pressure.

  • params (dict) – The loopedit step’s parameters (see resolve_loop_edit()).

  • interval (float) – Scan interval, seconds.

  • excluded (numpy.ndarray, optional) – Scans an earlier Loop Edit marked.

  • cast_label (str, optional) – The cast’s id ("051", "122b"), for the error message.

Returns:

A new dataset (the input is not mutated) and the scans marked, including any from an earlier Loop Edit kept by exclude_flagged.

Return type:

tuple of (xarray.Dataset, numpy.ndarray)

Raises:

ValueError – On malformed parameters, no pressure, or (with starts_below: fail) a cast whose recording starts below the soak window.

ctdcast.processors.editing.apply_wild_edit(ds: Dataset, cfg: dict | None, *, excluded: ndarray | None = None, cast_label: str = '?') → tuple[Dataset, dict[str, ndarray]][source]

Apply Wild Edit to one cast: mark outliers QARTOD 4 in each named variable’s _qc.

Parameters:
  • ds (xarray.Dataset) – A stage-2 dataset at its native scan rate.

  • cfg (dict or None) – {"wildedit": ...}: the step’s parameters from data_processing.steps.

  • excluded (numpy.ndarray, optional) – Scans an earlier Loop Edit marked, left out of the statistics when exclude_flagged.

  • cast_label (str, optional) – How the cast is named in warnings.

Returns:

A new dataset (the input is not mutated) and {variable: mask} of the values marked. Without a wildedit entry the dataset is returned unchanged. A cast Sea-Bird already wild-edited is skipped, with a warning and a history note.

Return type:

tuple of (xarray.Dataset, dict)

ctdcast.processors.editing.loop_edit_mask(pressure: ndarray, params: LoopEdit, interval: float, latitude: float, excluded: ndarray | None = None) → ndarray[source]

Return the scans Loop Edit marks, with seabirdscientific.processing.loop_edit().

Parameters:
  • pressure (numpy.ndarray) – Sea pressure, dbar, at the native scan rate.

  • params (LoopEdit) – The resolved parameters.

  • interval (float) – Scan interval, seconds.

  • latitude (float) – For the depth conversion.

  • excluded (numpy.ndarray, optional) – Scans an earlier Loop Edit marked, kept when exclude_flagged.

Returns:

Boolean, true at the scans marked.

Return type:

numpy.ndarray

ctdcast.processors.editing.resolve_loop_edit(params: object) → LoopEdit[source]

Return the Loop Edit parameters of a loopedit step.

Parameters:

params (dict) – min_velocity (default 0.25 dbar/s), or mean_speed_percent with window_seconds (default 300); surface_soak: {min_depth, max_depth, deck_pressure, starts_below} (default 5, 20, true, skip), or surface_soak: false; exclude_flagged (default true).

Returns:

The resolved parameters.

Return type:

LoopEdit

Raises:

ValueError – On an unknown key or a value of the wrong kind.

ctdcast.processors.editing.resolve_wild_edit(cfg: dict | None) → WildEdit | None[source]

Return the Wild Edit parameters from {"wildedit": parameters}, or None when absent.

Parameters:

cfg (dict or None) – {"wildedit": ...}: the step’s parameters from data_processing.steps.

Returns:

None when wildedit is absent or empty.

Return type:

WildEdit or None

Raises:

ValueError – On an unknown key or a value of the wrong kind.

ctdcast.processors.editing.soak_window_reached(pressure: ndarray, params: LoopEdit, latitude: float, excluded: ndarray | None = None) → bool[source]

Return whether the cast has a surface soak for Loop Edit to look for.

The soak test needs a scan between min_depth and max_depth (offset as deck_pressure says) before the first scan below max_depth, leaving out scans an earlier Loop Edit marked when exclude_flagged, as seabirdscientific’s search does. A recording that starts below the window (the logging began at depth, even if the package rose into the window later), or a cast that never goes below it, has no surface soak for that search to find; seabirdscientific’s loop_edit then fails on an empty search.

Parameters:
  • pressure (numpy.ndarray) – Sea pressure, dbar; NaNs are interpolated, as Loop Edit runs on it.

  • params (LoopEdit) – The resolved parameters.

  • latitude (float) – For the depth conversion.

  • excluded (numpy.ndarray, optional) – Scans an earlier Loop Edit marked.

Returns:

True when an unmarked scan lies in the soak window before the first unmarked scan below.

Return type:

bool

ctdcast.processors.editing.wild_edit_mask(values: ndarray, params: WildEdit, excluded: ndarray | None = None) → ndarray[source]

Return where Wild Edit marks values, using seabirdscientific.processing.wild_edit().

Parameters:
  • values (numpy.ndarray) – One variable at the native scan rate; NaN is never marked and never counted.

  • params (WildEdit) – The resolved parameters.

  • excluded (numpy.ndarray, optional) – Boolean, true at scans to leave out of the block statistics (an earlier Loop Edit’s marks); used only when params.exclude_flagged.

Returns:

Boolean, true at the values marked.

Return type:

numpy.ndarray

Stage-3 filters at the native scan rate: Sea-Bird’s Filter and Window Filter.

  • Filter (filter step): Sea-Bird’s low-pass filter, a single-pole filter run forward and backward so it adds no lag, with one time constant (SBE Data Processing manual, Filter). Sea-Bird’s module applies two time constants, A and B, to two lists of variables in one run; in data_processing.steps that is two filter entries. Applied with seabirdscientific.processing.low_pass_filter().

  • Window Filter (window_filter step): a boxcar, cosine, triangle, gaussian or median window of width scans, with seabirdscientific.processing.window_filter().

Both change values; the parameters are recorded on each variable (filters, one entry per filter, in order) and in history. Values an earlier Wild Edit marked are left out of the filter, as SBE Data Processing leaves out its bad flags: the filter runs across them on values interpolated from their neighbours, and the marked values themselves are kept as they were. On OdB cast 050, Filter on .hex data matches the cruise’s CNV to its rounding for pressure (0.15 s) and fluorescence (0.03 s).

Configuration, steps in data_processing.steps:

- filter: {time_constant: 0.15, variables: [pressure]}
- window_filter: {type: median, width: 10, variables: [pressure, ctd_fluor],
                  exclude_flagged: true}     # gaussian also takes half_width, offset
ctdcast.processors.filtering.apply_filter(ds: Dataset, params: dict, *, marked: dict[str, ndarray] | None = None) → tuple[Dataset, list[str]][source]

Apply one filter step: Sea-Bird’s low-pass filter, forward and backward.

Parameters:
  • ds (xarray.Dataset) – A stage-2 dataset at its native scan rate.

  • params (dict) – The step’s time_constant and variables.

  • marked (dict of str to numpy.ndarray, optional) – {variable: mask} of values an earlier Wild Edit marked; filtered across, kept.

Returns:

A new dataset (the input is not mutated) and the variables filtered.

Return type:

tuple of (xarray.Dataset, list of str)

Raises:

ValueError – On malformed parameters, or a dataset not at its native scan rate.

ctdcast.processors.filtering.apply_window_filter(ds: Dataset, params: dict, *, marked: dict[str, ndarray] | None = None, excluded: ndarray | None = None) → tuple[Dataset, list[str]][source]

Apply one window_filter step.

Parameters:
  • ds (xarray.Dataset) – A stage-2 dataset at its native scan rate.

  • params (dict) – The step’s parameters (see check_window_filter()).

  • marked (dict of str to numpy.ndarray, optional) – {variable: mask} of values an earlier Wild Edit marked; left out of the window.

  • excluded (numpy.ndarray, optional) – Scans an earlier Loop Edit marked; left out of the window when exclude_flagged.

Returns:

A new dataset (the input is not mutated) and the variables filtered.

Return type:

tuple of (xarray.Dataset, list of str)

Raises:

ValueError – On malformed parameters, or a dataset not at its native scan rate.

ctdcast.processors.filtering.check_filter(params: object) → tuple[float, list[str]][source]

Return (time_constant, variables) from a filter step’s parameters.

Parameters:

params (dict) – The step’s parameters.

Returns:

The time constant in seconds and the variables to filter.

Return type:

tuple of (float, list of str)

Raises:

ValueError – On an unknown key, a missing or non-positive time constant, or no variables.

ctdcast.processors.filtering.check_window_filter(params: object) → dict[source]

Return the resolved parameters of a window_filter step.

Parameters:

params (dict) – The step’s parameters: type, width (scans), variables, and optionally exclude_flagged and, for a gaussian, half_width and offset (seconds).

Returns:

type, width, variables, exclude_flagged, half_width, offset.

Return type:

dict

Raises:

ValueError – On an unknown key or type, or a width under 2.

Products: files made from the stage-3 file by further steps, such as a 1 dbar downcast.

Sea-Bird processing usually runs one sequence of steps and then branches: the same corrected scans become a 1 s time series, a 1 dbar downcast and a 1 dbar upcast, each with its own Loop Edit and Bin Average. data_processing.products lists these branches; each has a name and its own steps, run on the stage-3 data (every scan, already through data_processing.steps):

data_processing:
  steps: [...]                       # the stage-3 file
  products:
    - name: 1dbar_down
      steps:
        - split: down
        - loopedit: {min_velocity: 0.25}
        - binavg: {bin: decibars, size: 1}
    - name: 1sec
      steps:
        - binavg: {bin: seconds, size: 1}

A product may use any step; split and binavg are product-only, because the stage-3 file keeps every scan, and binavg comes last. Each product is written to <ctd_root>/products/<name>/<cast>_<name>.nc; the stage-3 file is unchanged.

Bin Average (binavg) uses seabirdscientific.processing.bin_average(). Bins are decibars (on pressure), seconds (from the first scan) or scans. A value is left out of its bin when its _qc is 4 (fail) or 9 (missing) — so Wild Edit’s marks, stage 2’s soak and deck flags and a failed gross-range test leave out that one value, not its whole scan — and, with exclude_flagged, the scans Loop Edit marked are left out entirely, as SBE Data Processing does. Salinity is re-derived from the binned conductivity, temperature and pressure. Bins of a pressure product run down then up unless a split chose one leg.

ctdcast.processors.products.BIN_TYPES = {'decibars': 'pressure', 'scans': 'nScan', 'seconds': 'elapsed_seconds'}

Bin types, and the variable each bins on.

ctdcast.processors.products.bin_average(ds: Dataset, params: dict) → Dataset[source]

Bin-average a cast with seabirdscientific.processing.bin_average().

Parameters:
  • ds (xarray.Dataset) – A cast at its native scan rate (dim time), possibly one leg from split_leg().

  • params (dict) – The binavg step’s parameters (see check_binavg()).

Returns:

Dim bin: each binned variable, nbin (scans in the bin), and time (the bin’s mean time). Salinity is re-derived from the binned values.

Return type:

xarray.Dataset

ctdcast.processors.products.check_binavg(params: object) → dict[source]

Return the resolved parameters of a binavg step.

Parameters:

params (dict) – bin (decibars, seconds, scans), size, and optionally exclude_flagged (default true), min_scans (1), max_scans, skip_over (scans dropped at the start, 0), omit (at the end, 0), surface_bin ({min, max, value} or null) and interpolate (false).

Returns:

The parameters with defaults filled in.

Return type:

dict

Raises:

ValueError – On an unknown key or a value of the wrong kind.

ctdcast.processors.products.check_products(products: object) → list[dict][source]

Return data_processing.products, checked.

Parameters:

products (list or None) – Each entry {name, steps}.

Returns:

The products.

Return type:

list of dict

Raises:

ValueError – On a missing or unsafe name, a repeated name, a step not allowed here, binavg before the last step, or more than one split.

ctdcast.processors.products.check_split(params: object) → str[source]

Return the leg a split step keeps: "down" or "up".

Parameters:

params (str or dict) – down / up, or {leg: down}.

Returns:

"down" or "up".

Return type:

str

Raises:

ValueError – On anything else.

ctdcast.processors.products.describe_product_steps(steps: list[dict]) → str[source]

Return a product’s configured steps as one line: split down; binavg bin=decibars size=1.

Parameters:

steps (list of dict) – The product’s steps, each a one-key mapping of step name to its parameters.

Returns:

The steps in order, "; "-separated; a mapping’s key=value pairs follow the step name in their configured order.

Return type:

str

ctdcast.processors.products.make_product(ds: Dataset, product: dict, *, cast_number: int | None, cast_label: str, marked: dict[str, ndarray] | None = None) → Dataset[source]

Run one product’s steps on a finished stage-3 dataset.

Parameters:
  • ds (xarray.Dataset) – The stage-3 dataset (every scan).

  • product (dict) – {name, steps} from data_processing.products.

  • cast_number (int or None) – For per-cast-range values in the product’s steps.

  • cast_label (str) – How the cast is named in warnings.

  • marked (dict of str to numpy.ndarray, optional) – {variable: mask} of the values stage 3’s Wild Edit marked, which a filter in the product steps over as at stage 3. Without it (a product made later from the file), every value flagged fail or missing outside Loop Edit’s scans is stepped over: the file keeps the flag, not which step raised it.

Returns:

The product; product_name and data_processing_steps attributes say what it is.

Return type:

xarray.Dataset

ctdcast.processors.products.split_leg(ds: Dataset, leg: str) → Dataset[source]

Return the downcast (to the deepest scan, inclusive) or the upcast (from it).

Parameters:
  • ds (xarray.Dataset) – A cast at its native scan rate, with pressure.

  • leg (str) – "down" or "up".

Returns:

The scans of that leg; the dataset’s product_leg attribute names it.

Return type:

xarray.Dataset

Stage-3 corrections at the native scan rate: alignment, cell thermal mass, and SBE 43 oxygen.

These are the Sea-Bird processing steps that only make sense on unbinned, unfiltered data at the instrument’s own scan rate (24 Hz on a 911plus), applied with Sea-Bird’s seabirdscientific toolkit:

  • alignment (processing.align_ctd): advance conductivity, or an SBE 43 voltage, relative to pressure by a configured number of seconds;

  • cell thermal mass (processing.cell_thermal_mass): correct conductivity for the heat the conductivity cell stores, from the temperature of the same line;

  • oxygen (conversion.convert_sbe43_oxygen): derive ctd_oxygen from the aligned SBE 43 voltage and the corrected temperature, salinity and pressure of its line, with the tau and hysteresis corrections of Sea-Bird Application Note 64-3.

Where this diverges from seabirdscientific (3.1.1). The tau and hysteresis corrections are computed here (sbe43_dvdt(), sbe43_hysteresis(), sbe43_tau_term()) and folded into the voltage, and convert_sbe43_oxygen is then called with both of its corrections off. Two reasons: speed (seabirdscientific fits a regression per scan for dV/dt, about 11 s on a 3000 dbar cast; the same least-squares slope as a convolution agrees to 1e-12 V/s in milliseconds), and the hysteresis recursion (seabirdscientific feeds the corrected previous voltage where Application Note 64-3 uses the uncorrected one; the two differ by a few µmol/kg at depth). The divergence is recorded on every derived variable (oxygen_hysteresis_method) and should be removed once seabirdscientific matches Application Note 64-3: call convert_sbe43_oxygen with apply_tau_correction and apply_hysteresis_correction on again, and drop the three functions.

Every step records its parameters on the variable it changed and in history, so the correction is reconstructable from the output file alone. A step that cannot apply to a cast (the data is binned, or Sea-Bird already applied the same step) is skipped with a warning and a history note; the cast’s other stage-3 steps still run.

Configuration (data_processing:, see ctdcast.config.layout): alignctd and celltm are steps in data_processing.steps, each entry a bare value or a default and/or ranges (casts + value) declaration; the oxygen window and the per-sensor conductivity slope and offset sit beside the steps:

data_processing:
  slope_offset:                # per conductivity sensor: C' = slope * C + offset
    conductivity_1: {slope: 1.0000452, offset: 0.0}
  oxygen:
    tau_window_seconds: 2.0    # window for the SBE 43 tau correction's dV/dt
  steps:
    - alignctd:                # seconds; + advances the variable relative to pressure
        conductivity: 0.0
        oxygen: 3.0
        conductivity_2: {ranges: [{casts: [[30, 45]], value: 0.021}]}
    - celltm:                  # alpha and tau (1/beta, seconds); conductivity only
        conductivity: {alpha: 0.03, tau: 7.0}
class ctdcast.processors.corrections.CorrectionRecord(changed: list[str] = <factory>, alignment: dict[str, float]=<factory>, cell_thermal_mass: dict[str, tuple[float, float]]=<factory>, edge_masks: dict[str, ~numpy.ndarray]=<factory>, skipped: list[str] = <factory>)[source]

What apply_corrections() did to one cast, for stage 3 and the compiled product.

alignment: dict[str, float]

{variable: seconds} advances applied.

cell_thermal_mass: dict[str, tuple[float, float]]

{variable: (alpha, tau)} cell-thermal-mass corrections applied.

changed: list[str]

Variables whose values changed (conductivity and SBE 43 voltages).

edge_masks: dict[str, ndarray]

{variable: boolean mask} scans set NaN by an alignment.

skipped: list[str]

One-line reasons for steps that were configured but skipped.

ctdcast.processors.corrections.DEFAULT_OXYGEN_TAU_WINDOW_SECONDS = 2.0

Default window (s) for the SBE 43 tau correction’s dV/dt.

ctdcast.processors.corrections.NATIVE_SCAN_INTERVAL_SECONDS: dict[str, float] = {'SBE 9': 0.041666666666666664}

Native scan interval by instrument, as ctdcast.config.cnv_header.detect_instrument() names it. Extend as other instruments arrive.

ctdcast.processors.corrections.SBE43_HYSTERESIS_METHOD = 'Sea-Bird Application Note 64-3: Oxnew(i) = (Ox(i) + Oxnew(i-1)*C*D - Ox(i-1)*C)/D, Ox(i-1) uncorrected (seabirdscientific 3.1.1 uses the corrected value)'

What the oxygen_hysteresis_method attribute records, so a reader of the file knows which recursion was used.

ctdcast.processors.corrections.align(values: ndarray, offset_seconds: float, interval_seconds: float) → tuple[ndarray, ndarray][source]

Advance values by offset_seconds with seabirdscientific’s align_ctd.

Positive advances the variable relative to pressure: the value at scan k becomes the one measured offset_seconds later (linear interpolation between scans). Values that would come from beyond either end of the cast are NaN.

Parameters:
  • values (numpy.ndarray) – One variable at the native scan rate.

  • offset_seconds (float) – The advance, in seconds.

  • interval_seconds (float) – Time between scans.

Returns:

The aligned values (float64) and a boolean mask of the scans set NaN because they fell past an end.

Return type:

tuple of (numpy.ndarray, numpy.ndarray)

Raises:

ValueError – If seabirdscientific returns an array of a different length.

ctdcast.processors.corrections.apply_corrections(ds: Dataset, cruise_cfg: dict | None, cast_number: int | None, *, cast_label: str = '?') → tuple[Dataset, CorrectionRecord][source]

Apply the configured alignment and cell thermal mass corrections to one cast.

Parameters:
  • ds (xarray.Dataset) – A stage-2 dataset at its native scan rate.

  • cruise_cfg (dict or None) – {"alignctd": ...} and/or {"celltm": ...}: one step’s parameters from data_processing.steps.

  • cast_number (int or None) – The cast’s number, for per-range values.

  • cast_label (str, optional) – How the cast is named in warnings (e.g. "011").

Returns:

A new dataset (the input is not mutated) and what was done. With neither block configured, the dataset is returned unchanged.

Return type:

tuple of (xarray.Dataset, CorrectionRecord)

Raises:

ValueError – On malformed configuration.

ctdcast.processors.corrections.cell_thermal_mass(conductivity_mS_cm: ndarray, temperature: ndarray, alpha: float, tau_seconds: float, interval_seconds: float) → ndarray[source]

Correct conductivity for cell thermal mass with seabirdscientific’s cell_thermal_mass.

seabirdscientific’s filter works in S/m (its 0.1 × (1 + 0.006 (T − 20)) term is S/m per °C), so conductivity is converted from mS/cm to S/m, corrected, and converted back.

Parameters:
  • conductivity_mS_cm (numpy.ndarray) – Conductivity in mS/cm at the native scan rate.

  • temperature (numpy.ndarray) – Temperature (°C, ITS-90) of the same line; must be finite throughout, since the recursive filter would carry a NaN to every later scan.

  • alpha (float) – Thermal anomaly amplitude.

  • tau_seconds (float) – Thermal anomaly time constant (1/beta), in seconds.

  • interval_seconds (float) – Time between scans.

Returns:

Corrected conductivity in mS/cm (float64).

Return type:

numpy.ndarray

Raises:

ValueError – If the temperature has non-finite values, or alpha < 0 or tau <= 0. Alpha = 0 returns the conductivity unchanged.

ctdcast.processors.corrections.derive_oxygen(ds: Dataset, cruise_cfg: dict | None = None, *, cast_label: str = '?', marked: dict[str, ndarray] | None = None) → tuple[Dataset, list[str]][source]

Derive ctd_oxygen from each SBE 43 voltage, as Sea-Bird’s Data Conversion does.

For each oxygen_raw_<N> with no converted oxygen beside it (a CNV’s own ctd_oxygen is never re-derived), oxygen in µmol/kg is computed with convert_sbe43_oxygen from the (aligned) voltage, the temperature, practical salinity and pressure of line N (line 1 if the cast has no line N), and the sensor’s coefficients from the .xmlcon in raw_metadata, with the tau and hysteresis corrections on (Sea-Bird Application Note 64-3). One sensor gives plain ctd_oxygen; two give ctd_oxygen_1/_2.

Parameters:
  • ds (xarray.Dataset) – A stage-3 dataset after alignment, CTM and salinity.

  • cruise_cfg (dict or None) – The data_processing: block; oxygen.tau_window_seconds sets the tau-correction window.

  • cast_label (str, optional) – How the cast is named in warnings.

  • marked (dict of str to numpy.ndarray, optional) – {variable: mask} of values an earlier Wild Edit marked. The tau and hysteresis corrections step scan to scan, so a marked voltage, temperature, conductivity or pressure would spread into the neighbouring oxygen; each is replaced by interpolation from its unmarked neighbours for the conversion, and the oxygen at those scans is flagged 4.

Returns:

A new dataset and the names of the variables written.

Return type:

tuple of (xarray.Dataset, list of str)

ctdcast.processors.corrections.flag_missing(ds: Dataset, var: str, mask: ndarray) → None[source]

Set {var}_qc to QARTOD 9 (missing) where mask is true, in place.

Parameters:
  • ds (xarray.Dataset) – The dataset to flag.

  • var (str) – The data variable; its {var}_qc is changed if it exists.

  • mask (numpy.ndarray) – Boolean, true at the scans with no measurement.

ctdcast.processors.corrections.native_interval(ds: Dataset) → tuple[float | None, str | None][source]

Return the scan interval to correct ds with, or why it cannot be corrected.

Alignment, cell thermal mass and the SBE 43 tau correction act scan by scan; on binned or averaged data they would be wrong. All of these must hold: sample_interval_seconds equals the instrument’s native interval (911plus: 1/24 s), the deck unit averaged no scans, and the Sea-Bird chain has no binavg.

The interval returned is the instrument’s exact native interval (911plus: 1/24 s), not the recorded one: a CNV writes it rounded (seconds: 0.0416667), and the rounded value makes seabirdscientific’s time axis one sample long for some cast lengths. A stage file written before stage 1 recorded the interval falls back to the CNV header’s # interval line.

Parameters:

ds (xarray.Dataset) – A stage-2 or stage-3 per-cast dataset.

Returns:

(interval_seconds, None) at the native rate, else (None, reason).

Return type:

tuple of (float or None, str or None)

ctdcast.processors.corrections.native_rate_reason(ds: Dataset) → str | None[source]

Return why ds is not at its instrument’s native scan rate, or None if it is.

A thin wrapper over native_interval().

Parameters:

ds (xarray.Dataset) – A stage-2 or stage-3 per-cast dataset.

Returns:

A one-line reason, or None when the data is at the native rate.

Return type:

str or None

ctdcast.processors.corrections.resolve_alignment(cfg: dict | None, var: str, cast_number: int | None) → tuple[float, str] | None[source]

Return the configured advance (s) for var on cast_number, and the key it came from.

Parameters:
  • cfg (dict or None) – {"alignctd": ...}: the step’s parameters from data_processing.steps.

  • var (str) – A stage variable: conductivity_1/2 or oxygen_raw_1/2.

  • cast_number (int or None) – The cast’s number (a lettered cast resolves by its number).

Returns:

(seconds, "alignctd.<key> <default|range>"), or None when nothing is configured.

Return type:

tuple of (float, str) or None

Raises:

ValueError – On an unknown key, a malformed entry, or overlapping ranges with different values.

ctdcast.processors.corrections.resolve_cell_thermal_mass(cfg: dict | None, var: str, cast_number: int | None) → tuple[float, float, str] | None[source]

Return the configured (alpha, tau_seconds, source) for conductivity var, or None.

The celltm block may hold default/ranges itself (every conductivity channel) and per-channel keys (conductivity_2) that win over it.

Parameters:
  • cfg (dict or None) – {"celltm": ...}: the step’s parameters from data_processing.steps.

  • var (str) – conductivity_1 or conductivity_2.

  • cast_number (int or None) – The cast’s number.

Returns:

(alpha, tau, "celltm[.<key>] <default|range>"), or None when nothing is configured.

Return type:

tuple of (float, float, str) or None

Raises:

ValueError – On an unknown key, a value without alpha and tau, or conflicting ranges.

ctdcast.processors.corrections.resolve_oxygen_window(cfg: dict | None) → float[source]

Return the SBE 43 tau-correction window (s) from data_processing.oxygen.

Parameters:

cfg (dict or None) – The data_processing: config block.

Returns:

oxygen.tau_window_seconds, or DEFAULT_OXYGEN_TAU_WINDOW_SECONDS.

Return type:

float

Raises:

ValueError – If the block is not a mapping, has unknown keys, or the window is not a number spanning more than two native scans.

ctdcast.processors.corrections.resolve_slope_offset(block: dict | None, var: str, cast_number: int | None) → tuple[float, float, str] | None[source]

Return (slope, offset, source) for conductivity var on cast_number, or None.

data_processing.slope_offset holds one entry per conductivity sensor (conductivity_1, conductivity_2), each a bare {slope:, offset:} or a {default:, ranges:} declaration of them; offset defaults to 0.

Parameters:
  • block (dict or None) – The data_processing.slope_offset block.

  • var (str) – conductivity_1 or conductivity_2.

  • cast_number (int or None) – The cast’s number.

Returns:

None when nothing is configured for var on this cast.

Return type:

tuple of (float, float, str) or None

Raises:

ValueError – On an unknown key or a malformed value.

ctdcast.processors.corrections.sbe43_dvdt(volts: ndarray, window_seconds: float, interval: float) → ndarray[source]

Return dV/dt for the SBE 43 tau correction: a least-squares slope over a centred window.

The same slope seabirdscientific’s convert_sbe43_oxygen fits scan by scan, as one convolution. floor(window / 2 / interval) scans each side; the scans within that many of either end get 0, as in seabirdscientific.

Parameters:
  • volts (numpy.ndarray) – SBE 43 voltage at the native scan rate, without gaps.

  • window_seconds (float) – Width of the fitting window, in seconds.

  • interval (float) – Time between scans, in seconds.

Returns:

dV/dt in V/s, the same length as volts.

Return type:

numpy.ndarray

ctdcast.processors.corrections.sbe43_hysteresis(volts: ndarray, pressure: ndarray, coefs: Oxygen43Coefficients, interval: float) → ndarray[source]

Return SBE 43 voltage corrected for hysteresis, as Sea-Bird Application Note 64-3 gives it.

Oxnew(i) = (Ox(i) + Oxnew(i-1)·C·D − Ox(i-1)·C) / D with Ox = V + Voffset, D = 1 + H1·(exp(P/H2) − 1) and C = exp(−interval/H3); Ox(i-1) is the uncorrected previous value. Written as y(i) = C·y(i-1) + (x(i) − C·x(i-1))/D(i), a first-order recursive filter.

Parameters:
  • volts (numpy.ndarray) – SBE 43 voltage, without gaps.

  • pressure (numpy.ndarray) – Pressure (dbar), same length.

  • coefs (seabirdscientific.cal_coefficients.Oxygen43Coefficients) – The sensor’s calibration (h1, h2, h3, v_offset).

  • interval (float) – Time between scans, in seconds.

Returns:

Corrected voltage (V), the same length; the first scan is unchanged.

Return type:

numpy.ndarray

ctdcast.processors.corrections.sbe43_oxygen(volts: ndarray, temperature: ndarray, pressure: ndarray, salinity: ndarray, coefs: Oxygen43Coefficients, window_seconds: float, interval: float) → ndarray[source]

Return SBE 43 oxygen (µmol/kg) with the tau and Application Note 64-3 hysteresis corrections.

dV/dt comes from the uncorrected voltage and hysteresis acts on the voltage, as in seabirdscientific; the corrected voltage plus the tau term then goes through convert_sbe43_oxygen with its own corrections off.

Parameters:
  • volts (numpy.ndarray) – SBE 43 voltage, ITS-90 temperature (°C), pressure (dbar) and practical salinity of one unbroken run of finite scans.

  • temperature (numpy.ndarray) – SBE 43 voltage, ITS-90 temperature (°C), pressure (dbar) and practical salinity of one unbroken run of finite scans.

  • pressure (numpy.ndarray) – SBE 43 voltage, ITS-90 temperature (°C), pressure (dbar) and practical salinity of one unbroken run of finite scans.

  • salinity (numpy.ndarray) – SBE 43 voltage, ITS-90 temperature (°C), pressure (dbar) and practical salinity of one unbroken run of finite scans.

  • coefs (seabirdscientific.cal_coefficients.Oxygen43Coefficients) – The sensor’s calibration.

  • window_seconds (float) – The tau correction’s dV/dt window, in seconds.

  • interval (float) – Time between scans, in seconds.

Returns:

Oxygen in µmol/kg.

Return type:

numpy.ndarray

ctdcast.processors.corrections.sbe43_tau_term(dvdt: ndarray, temperature: ndarray, pressure: ndarray, coefs: Oxygen43Coefficients) → ndarray[source]

Return the tau correction in volts: tau20·exp(D1·P + D2·(T − 20))·dV/dt.

Added to the voltage, it gives what seabirdscientific’s equation does with its tau term.

Parameters:
  • dvdt (numpy.ndarray) – From sbe43_dvdt().

  • temperature (numpy.ndarray) – ITS-90 temperature (°C).

  • pressure (numpy.ndarray) – Pressure (dbar).

  • coefs (seabirdscientific.cal_coefficients.Oxygen43Coefficients) – The sensor’s calibration (tau_20, d1, d2).

Returns:

The term, in volts.

Return type:

numpy.ndarray

fit is ctdcast fit: it scores every native-rate stage-2 cast with fits, writes the cost surfaces to fits.nc, and turns them into the cruise summary and the suggested data_processing: block.

ctdcast fit: fit alignment and cell thermal mass over a cruise and record the results.

Reads every stage-2 cast at its native scan rate, scores each conductivity line with the cost functions in ctdcast.analysis.fits, and writes the per-cast cost surfaces to <ctd_root>/fits.nc. The cruise and per-block averages are not stored — summarise() computes them from the per-cast costs at report time. The report draws the corrections page from that file. Nothing here changes a stage file: the values reach stage 3 only through the config.

Two passes: alignment first, over every cast; then cell thermal mass on conductivity advanced by the cruise’s fitted (downcast) alignment for that line, because a misaligned line fits the wrong (alpha, tau).

ctdcast.processors.fit.DEFAULT_BLOCK = 10

Default number of consecutive casts per block.

ctdcast.processors.fit.FITS_FILENAME = 'fits.nc'

The file fit writes and report reads, under the CTD root.

class ctdcast.processors.fit.FitSettings(ctm_pmin: float = 200.0, gradient: float = 0.02, align_pmin: float = 20.0, min_speed: float = 0.25, gap_seconds: float = 300.0, ctm_tolerance: float = 0.02, block: int = 10, residuals: ndarray = <factory>, alpha: ndarray = <factory>, tau: ndarray = <factory>)[source]

The choices a fit was made with; recorded in fits.nc.

ctm_pmin

Top of the cell thermal mass window (dbar).

Type:

float

gradient

Thermocline threshold for the alignment cost (°C per dbar).

Type:

float

align_pmin

Alignment cost: scans shallower than this (dbar) are left out.

Type:

float

min_speed

Alignment cost: scans moving along the leg slower than this (dbar/s) are left out; 0 keeps every scan.

Type:

float

gap_seconds

Down/up weighting time scale (s).

Type:

float

ctm_tolerance

Acceptability fraction above the cost minimum for the recommended (alpha, tau): any point within it is treated as equally good (0.02 = 2%).

Type:

float

block

Consecutive casts per block.

Type:

int

residuals, alpha, tau

The grids searched.

Type:

numpy.ndarray

align_pmin: float = 20.0
alpha: ndarray
block: int = 10
ctm_pmin: float = 200.0
ctm_tolerance: float = 0.02
classmethod from_config(processing: dict | None) → FitSettings[source]

Build settings from the fit block, defaults for anything missing.

Parameters:

processing (dict or None) – The settings from ctdcast.config.layout.processing_view() (its fit).

Returns:

The settings.

Return type:

FitSettings

Raises:

ValueError – On an unknown key, a value that is not a positive number, or a min_speed outside 0–0.5 dbar/s.

gap_seconds: float = 300.0
gradient: float = 0.02
min_speed: float = 0.25
residuals: ndarray
tau: ndarray
class ctdcast.processors.fit.LineSummary(line: int, residual: float, alignment_n: int, residual_up: float, alignment_n_up: int, alpha_rec: float, tau_rec: float, alpha_at_tau: float, tau_at_alpha: float, ctm_n: int)[source]

What the fits say for one conductivity line.

line

1 (primary) or 2 (secondary).

Type:

int

residual

Cruise residual advance (s) on top of the data’s: the minimum of the downcast’s median curve, the value suggested.

Type:

float

alignment_n

Casts in the downcast curve.

Type:

int

residual_up

The same for the upcast, shown beside it.

Type:

float

alignment_n_up

Casts in the upcast curve.

Type:

int

alpha_rec, tau_rec

The recommended (alpha, tau): the point within ctm_tolerance of the cost minimum closest to Sea-Bird’s default. The value suggested in the YAML.

Type:

float

alpha_at_tau, tau_at_alpha

One-parameter fits at Sea-Bird’s default for the other.

Type:

float

ctm_n

Casts in the cell thermal mass average.

Type:

int

alignment_n: int
alignment_n_up: int
alpha_at_tau: float
alpha_rec: float
ctm_n: int
line: int
residual: float
residual_up: float
tau_at_alpha: float
tau_rec: float
ctdcast.processors.fit.cast_arrays(ds: Dataset, line: int, interval: float) → Cast | None[source]

Return one line of a stage-2 cast as Cast, or None.

Scans stage 2 flagged (soak, on deck) are excluded, the record is trimmed to the first and last usable scan, and pressure spikes are set NaN.

Parameters:
  • ds (xarray.Dataset) – A stage-2 cast.

  • line (int) – 1 or 2.

  • interval (float) – The native scan interval (s).

Returns:

None when the line’s temperature or conductivity is absent, or no scan is usable.

Return type:

Cast or None

ctdcast.processors.fit.cruise_advance(costs: list[ndarray], residuals: ndarray) → float | None[source]

Return the residual advance at the minimum of a line’s cruise downcast curve.

The one function both the fit pass and summarise() use, so the advance the cell thermal mass fit runs on and the advance the report suggests cannot diverge. Each cost is evaluated at the float32 precision fits.nc stores, so the result is the same whether the costs come straight from the fit (float64) or are read back from the file (float32).

Parameters:
  • costs (list of numpy.ndarray) – One downcast alignment cost per cast (the leg = 0 row of alignment_cost).

  • residuals (numpy.ndarray) – The residual-advance grid the costs were scored on.

Returns:

The advance (s) at the cruise minimum, or None when no cast has a well.

Return type:

float or None

ctdcast.processors.fit.fit_cruise(root: Path, settings: FitSettings, *, cast_tags: set[str] | None = None, progress: bool = True) → Dataset[source]

Fit every native-rate stage-2 cast under root and return the fits.nc dataset.

Parameters:
  • root (pathlib.Path) – The CTD root (data.ctd_root).

  • settings (FitSettings) – The window, threshold and grids.

  • cast_tags (set of str, optional) – Restrict to these zero-padded cast numbers (--only).

  • progress (bool, optional) – Print one line per cast.

Returns:

Per-cast costs, |ΔT|, maximum pressure and skip reasons, and the alignment each line’s cell thermal mass was fitted on.

Return type:

xarray.Dataset

Raises:

FileNotFoundError – If root has no stage-2 files.

ctdcast.processors.fit.suggested_yaml(summaries: list[LineSummary]) → str[source]

Return a paste-ready data_processing: snippet from the cruise summaries.

Built as a dict and serialised with yaml.safe_dump(), so the snippet parses back to the same values the resolvers read: an alignctd step per line (the downcast residual) and a celltm step (the recommended alpha/tau), in Sea-Bird’s order. Values are rounded to the grids’ resolution (advance and alpha to 4 dp, tau to 2 dp).

Parameters:

summaries (list of LineSummary) – From summarise() over the whole cruise.

Returns:

The YAML text; "" when nothing was fitted.

Return type:

str

ctdcast.processors.fit.summarise(fits: Dataset, *, casts: slice | None = None) → list[LineSummary][source]

Cruise (or block) fits per line from a fits.nc dataset.

Cell thermal mass costs are weighted by each cast’s |ΔT| across the window, so a cast with no gradient there contributes nothing.

Parameters:
  • fits (xarray.Dataset) – From fit_cruise() or fits.nc.

  • casts (slice, optional) – Restrict to these casts (a block).

Returns:

One per line with any usable cast.

Return type:

list of LineSummary


Stage layout

Where each stage’s files live and how a file’s stage is read from its name.

On-disk stage layout: per-stage paths and best-available cast-file discovery.

The single source of truth for the stage-file naming, so nothing elsewhere hard-codes _stageN or stageN/. Each processing stage writes its own per-cast netCDF under a stage subdirectory of one instrument root, with the stage carried in the filename as well as the path:

<root>/stage1/<cast_stem>_stage1.nc
<root>/stage2/<cast_stem>_stage2.nc
<root>/stage3/<cast_stem>_stage3.nc

The subdirectory bounds each directory’s file count by cast count rather than cast count times stages; the filename suffix means a file copied out of its directory is still identifiable and still parses. parse_stage() reads the stage off the filename and does not trust the parent directory, so the two can disagree (the filename wins, with a warning) without losing the file.

The cast stages here mirror the "cast"-scope entries of ctdcast.processors.STAGES (the pipeline registry); the two are tied by a consistency test rather than derived from each other, because the registry imports the stage modules that import this one — deriving would be an import cycle.

ctdcast.processors.stage_layout.PRODUCT_SUFFIX = 'profiles.nc'

Filename suffix of the compiled gridded products (profiles.nc, ladcp_profiles.nc) that sit at the stage root beside the stage directories.

ctdcast.processors.stage_layout.STAGES: tuple[int, ...] = (1, 2, 3)

The per-cast stages that write stage files, in ascending order.

ctdcast.processors.stage_layout.STAGE_DIRS: dict[int, str] = {1: 'stage1', 2: 'stage2', 3: 'stage3'}

Subdirectory under the instrument root that holds each stage’s files. This is the one hand-maintained map; the suffixes and the stage tuple derive from it, so adding a stage (e.g. a future hex→CNV stage 0) is a single line here.

ctdcast.processors.stage_layout.STAGE_SUFFIXES: dict[int, str] = {1: '_stage1', 2: '_stage2', 3: '_stage3'}

Filename suffix (before .nc) carried by each stage’s per-cast file. The stage’s directory name and filename suffix are the same token by construction, matching the sibling oceanarray package’s “stage name doubles as the suffix”.

ctdcast.processors.stage_layout.best_available(root: Path | str, cast_stem: str) → Path | None[source]

Return the highest-stage file present for cast_stem, else None.

Precedence is stage 3, then stage 2, then stage 1 — the one place this rule lives.

Parameters:
  • root (Path or str) – The instrument stage root.

  • cast_stem (str) – The cast’s base stem, without any stage suffix.

Returns:

The best-available per-cast file, or None when no stage file exists.

Return type:

Path or None

ctdcast.processors.stage_layout.group_by_cast(root: Path | str) → dict[tuple[int, str], dict[int, Path]][source]

Map each cast identity to the stage files present for it.

Walks root/stage*/ and groups every recognised stage file by its cast identity (cast_num, cast_suffix) — so a plain cast NNN and its lettered sibling NNNb are distinct keys. Files whose name carries no stage suffix or no cast number are skipped.

A suffix-less *.nc directly under the root (the old flat nc_dir layout, and the committed test fixtures) is folded in as stage 1, unless a nested stage1/…_stage1.nc already exists for that cast — the nested file wins. Compiled products such as profiles.nc carry no cast number and are skipped automatically.

Parameters:

root (Path or str) – The instrument stage root.

Returns:

{(cast_num, cast_suffix): {stage: path}}.

Return type:

dict

ctdcast.processors.stage_layout.is_product_name(name: Path | str) → bool[source]

Return whether name is a compiled-product file, not a per-cast file.

Compiled products (…profiles.nc) live at the stage root; they are terminal gridded artefacts, not casts, and must never be folded into cast discovery — even when the name carries a cruise number (e.g. msm_142_profiles.nc), which would otherwise parse as cast 142.

ctdcast.processors.stage_layout.is_up_to_date(target: Path | str, sources: Iterable[Path]) → bool[source]

Return whether target exists and is newer than every source in sources.

The one skip/re-run test for a derived file (a stage output or a compiled product): skip only when the output already exists and no input has been rewritten since (by mtime). This is what makes a forced re-run of an earlier step propagate — process --stage 1 --only 42 --force followed by a plain process --stage 2 3 profiles regenerates cast 42 downstream instead of silently skipping because a stale output happened to exist. A missing source is ignored (it cannot make the target stale).

ctdcast.processors.stage_layout.matches_tags(cast_id: tuple[int, str], tags: set[str]) → bool[source]

Return whether cast_id is selected by any zero-padded cast tag.

Matches on the parsed cast identity, not a filename substring — so a cruise or leg number in the stem cannot be mistaken for the cast number (the bug in the old tag in stem rule), and a lettered sibling 004b is selected by its own tag ("004b") or by the bare number ("004").

Parameters:
  • cast_id (tuple of (int, str)) – The (cast_num, cast_suffix) identity from group_by_cast().

  • tags (set of str) – Zero-padded cast tags (e.g. {"042", "004b"}), as the CLI produces from --only.

Returns:

True if any tag names this cast.

Return type:

bool

ctdcast.processors.stage_layout.parse_stage(path: Path | str) → tuple[str, int] | None[source]

Return (base_stem, stage) parsed from a filename, or None.

The stage is read from the filename suffix, not the parent directory, so a file copied out of its stage directory still parses. When the filename suffix and the parent directory disagree, the filename wins and a warning is emitted rather than the file being misread or dropped.

Parameters:

path (Path or str) – A per-cast netCDF path or name.

Returns:

The base stem (stage suffix stripped) and the stage number, or None when the name carries no recognised stage suffix.

Return type:

tuple of (str, int) or None

ctdcast.processors.stage_layout.select_best_available(root: Path | str) → list[tuple[tuple[int, str], Path, int]][source]

Return (cast_id, best_path, source_stage) per cast, sorted by identity.

The one place the best-available precedence lives for every consumer (the report, build_profiles, the LADCP compile). best_path is the highest-stage file present (3 > 2 > 1); source_stage is that stage, or 0 when the best file is a flat/suffix-less file that does not state its own stage (the compatibility shim only assumes stage 1, so 0 = “unknown, guessed stage 1” stays distinct from a stated stage 1).

Parameters:

root (Path or str) – The instrument stage root.

Returns:

One ((cast_num, cast_suffix), path, source_stage) per cast, sorted by cast identity.

Return type:

list of (tuple(int, str), Path, int)

ctdcast.processors.stage_layout.stage_dir(root: Path | str, stage: int, *, create: bool = False) → Path[source]

Return root/stageN.

Parameters:
  • root (Path or str) – The instrument stage root (e.g. the CTD or LADCP root).

  • stage (int) – The processing stage (1, 2, or 3).

  • create (bool, optional) – Create the directory (and parents) when true.

Returns:

The stage subdirectory.

Return type:

Path

ctdcast.processors.stage_layout.stage_path(root: Path | str, cast_stem: str, stage: int) → Path[source]

Return the per-cast output path root/stageN/<cast_stem>_stageN.nc.

Parameters:
  • root (Path or str) – The instrument stage root.

  • cast_stem (str) – The cast’s base stem, without any stage suffix (e.g. mixsed2_017).

  • stage (int) – The processing stage (1, 2, or 3).

Returns:

The stage-suffixed per-cast netCDF path.

Return type:

Path

LADCP processing: LDEO .mat → per-cast netCDF → compiled ladcp_profiles.nc.

Mirrors the CTD pipeline (stage1 convert_cast → build_profiles): convert_ladcp_cast() translates one LDEO .mat solution to a per-cast ladcp_<cast_id>.nc on the native 10 m depth grid, with storage dtypes reduced for file size; the compiler (added in build_ladcp_profiles()) concatenates those per-cast files onto a common depth axis.

ctdcast.processors.ladcp.build_ladcp_profiles(ladcp_nc_dir: Path, ladcp_profiles_path: Path, *, force: bool = False, cruise_info: dict | None = None) → bool[source]

Compile per-cast ladcp_*.nc into ladcp_profiles.nc.

The LADCP parallel of ctdcast.processors.profiles.build_profiles(). Because each cast is already on a uniform 10 m grid, this is a common-axis alignment (not a regrid): every profile is reindexed onto the deepest cast’s depth axis (NaN below its own bottom) and stacked on a new N_PROF dimension. Per-cast scalars become N_PROF vectors; cruise-common provenance is kept in attrs, per-cast-varying provenance is already stored as variables. Returns True if written, False when there is nothing to compile.

Skips when ladcp_profiles.nc already exists and is newer than every per-cast source file (same source-mtime rule as the CTD compiler and the processing stages); force rebuilds regardless.

cruise_info (the config cruise_info: block) supplies discovery metadata, people, embargo, and the ship/date for the EXPOCODE coordinate. Coverage bounds (lat/lon from the per-cast positions, vertical from the depth axis in metres) and the creation time are computed from the data.

ctdcast.processors.ladcp.convert_ladcp_cast(mat_path: Path, nc_path: Path, *, cast_num: int, cast_suffix: str = '', force: bool = False, cruise_info: dict | None = None) → bool[source]

Convert one LDEO .mat to a per-cast LADCP netCDF.

Parameters:
  • mat_path – Path to the LDEO IXv14 .mat solution.

  • nc_path – Output ladcp_<cast_id>.nc path.

  • cast_num – Cast identity written into the file (and used to join to profiles.nc).

  • cast_suffix – Cast identity written into the file (and used to join to profiles.nc).

  • force – Overwrite an existing nc_path if True.

  • cruise_info – The config cruise_info: mapping, stamped as cruise identity (cruise + platform_* + expocode) so the file is self-describing; None writes none.

Returns:

True if the file was written; False if skipped (already exists, not forced).

Return type:

bool

ctdcast.processors.ladcp.run_compile(ladcp_nc_dir: Path, ladcp_profiles_path: Path, *, force: bool = False, dry_run: bool = False, cruise_info: dict | None = None, **kw: object) → bool[source]

Build ladcp_profiles.nc from ladcp_*.nc in ladcp_nc_dir.

The LADCP parallel of ctdcast.processors.profiles.run().

ctdcast.processors.ladcp.run_convert(ladcp_dir: Path, ladcp_nc_dir: Path, *, force: bool = False, dry_run: bool = False, cast_tags: set[str] | None = None, cruise_info: dict | None = None, **kw: object) → int[source]

Convert every LADCP .mat in ladcp_dir to a per-cast netCDF.

The LADCP parallel of ctdcast.processors.stage1.run(): discovers the .mat files, derives each cast’s identity from its filename, and writes ladcp_nc_dir/stage1/ladcp_<cast_id>_stage1.nc. LADCP has a single processing stage, so its stage-1 file is its per-cast product. Files with no cast number in the stem are skipped. Returns the number of files written (0 for dry_run). cruise_info is stamped as cruise identity on each file.

Canonicalise variable units at each processing boundary.

The units knowledge — which spelling is canonical per quantity, which reader spellings convert to it and with what factor — is the shared family data in ctdcast.reports._vendored.units_tables, read through ctdcast.reports._vendored.units.resolve_units(); ctdcast’s view of it, with its own additions, is ctdcast.config.unit_tables.TABLES. This module holds only the transform that applies it, to_canonical_units() — a loop over resolve_units run at the netCDF write boundary (every stage persists through the writer, so each stage’s output is canonicalised). Every written file carries one canonical spelling per quantity, a factor ≠ 1 spelling has its values converted, and an unrecognised spelling stops the run loudly rather than being silently overwritten.

The display spelling (mS cm-1 → mS/cm) is a separate concern, derived from the canonical string by ctdcast.config.unit_tables.unit_label(); it is never stored.

exception ctdcast.processors.units.UnitsError[source]

A units string cannot be related to a canonical spelling.

Raised by resolve_units() for a present spelling that is not a recognised member of its canonical’s alias group, and by merge_tables() for an alias factor that disagrees with the base. A dedicated ValueError subclass so a caller can catch this specifically without swallowing unrelated ValueError exceptions.

ctdcast.processors.units.to_canonical_units(ds: xr.Dataset, *, tables: Tables = Tables(canonical={'sea_water_pressure': 'dbar', 'latitude': 'degrees_north', 'longitude': 'degrees_east', 'sea_water_temperature': 'degree_Celsius', 'sea_water_conservative_temperature': 'degree_Celsius', 'sea_water_electrical_conductivity': 'mS cm-1', 'sea_water_practical_salinity': '1', 'sea_water_absolute_salinity': 'g kg-1', 'moles_of_oxygen_per_unit_mass_in_sea_water': 'umol kg-1', 'mass_concentration_of_chlorophyll_in_sea_water': 'mg m-3', 'sea_water_turbidity': '1', 'altitude_of_sea_floor': 'm', 'sea_water_sigma_theta': 'kg m-3', 'eastward_sea_water_velocity': 'm s-1', 'northward_sea_water_velocity': 'm s-1', 'square_of_brunt_vaisala_frequency_in_sea_water': 'rad2 s-2'}, aliases={'degree_Celsius': {'degC': 1.0, 'degrees_C': 1.0, 'Degrees C': 1.0, '°C': 1.0, 'ITS-90, deg C': 1.0}, 'mS cm-1': {'mS/cm': 1.0, 'S/m': 10.0}, 'm': {'meters': 1.0}, 'dbar': {'db': 1.0}, 'm s-1': {'m/s': 1.0}, 'umol kg-1': {'umol/kg': 1.0, 'µmol/kg': 1.0}, 'kg m-3': {'kg/m³': 1.0}, 'g kg-1': {'g/kg': 1.0}, 'mg m-3': {'mg/m^3': 1.0}, 'percent': {'% saturation': 1.0}, 'degrees_north': {'degree_north': 1.0, 'degree_N': 1.0, 'degrees_N': 1.0, 'degreeN': 1.0, 'degreesN': 1.0}, 'degrees_east': {'degree_east': 1.0, 'degree_E': 1.0, 'degrees_E': 1.0, 'degreeE': 1.0, 'degreesE': 1.0}, 'degree': {'degrees': 1.0, '°': 1.0}, 'V': {'volts': 1.0}, 's': {'seconds': 1.0}}, scoped={'sea_water_practical_salinity': {'PSU': 1.0}, 'sea_water_turbidity': {'NTU': 1.0}, 'latitude': {'deg': 1.0}, 'longitude': {'deg': 1.0}}, labels={'degree_Celsius': '°C', 'degrees_north': '°N', 'degrees_east': '°E', 'percent': '%', 'degree': '°'}, labels_by_standard_name={'sea_water_turbidity': 'NTU', 'sea_water_practical_salinity': 'PSU'}, tokens={'umol': 'µmol'}), registry: dict[str, str] | None = None, log_fn: Callable[[str], None] | None = None, stage: int | str | None = None) → xr.Dataset[source]

Rewrite each registered variable’s units to its canonical spelling.

The canonical for a variable is its registry units when the variable is registered (known by name, which works before the writer stamps standard_name on the dataset), else the canonical for its CF standard_name. The current units string is resolved against that canonical’s accepted group (the canonical ×1 plus the family aliases plus the scoped spellings for the quantity); a factor ≠ 1 match multiplies the values and drops any stale integer packing, a pure spelling rewrite leaves the values untouched. The conversion is not stamped on the variable — a factor ≠ 1 is reported through log_fn at the boundary. Temperature variables additionally get the CF-1.11 units_metadata = "temperature: on_scale".

A registered variable with no units attribute has its canonical filled from the registry (ctdcast derives composites and carries channels whose units are supplied at the write boundary, not by the reader) — a fill, not a conversion. The pass is idempotent — a variable already carrying its canonical string is left unchanged — so it runs at every write without double-converting (stage 2/3 re-read an already-canonical stage-1 file). Unregistered engineering variables (no registry entry and no matching standard_name) are left untouched.

Parameters:
  • ds (xarray.Dataset) – Dataset to canonicalise in place (also returned).

  • tables (Tables, optional) – The units view to resolve against; defaults to ctdcast.config.unit_tables.TABLES.

  • registry (dict of str to str, optional) – {variable name: standard_name} map; defaults to ctdcast.config.unit_tables.registry_standard_names(). Used to find a variable’s standard_name (for the scoped spellings) before the writer stamps it on the dataset.

  • log_fn (callable, optional) – Called with one message per variable whose units string changed.

  • stage (int or str, optional) – Processing stage, used only to annotate the log and error messages.

Returns:

The same dataset, with canonical units on every registered variable.

Return type:

xarray.Dataset

Raises:

UnitsError – If a registered variable carries a units string that is present but is not a recognised spelling of its canonical. The pass never guesses or silently passes an unknown unit through; a missing units attribute is filled (see above), not raised.


Readers

Public reader shim for SBE CNV files.

Delegates to the active CtdBackend so callers are insulated from which library does the actual parsing. A future hexadecimal-reader backend will be swappable here without touching any caller.

ctdcast.readers.cnv.read(cnv_path: Path, *, backend: str = 'seasenselib') → Dataset[source]

Read a single SBE CNV file and return an xarray Dataset.

The Dataset is loaded into memory before the temporary netCDF file is removed; the returned object has no open file handles.

Parameters:
  • cnv_path – Path to the raw SBE CNV file.

  • backend – Backend name (currently only "seasenselib").

Returns:

In-memory Dataset with variables as produced by the backend.

Return type:

xr.Dataset

Raises:
  • ImportError – If the requested backend package is not installed.

  • FileNotFoundError – If cnv_path does not exist.

Reader for LDEO IXv14 LADCP .mat files.

Locates the .mat file for a cast (find_ladcp_file()), loads it with a single set of scipy.io.loadmat options (read_ladcp()), and maps the result struct to a single-cast xarray.Dataset on the native 10 m depth grid (read_ladcp_cast()). The .mat is the LDEO IX velocity solution; its ~50 fields are mapped to the compiled-dataset schema.

ctdcast.readers.ladcp.MatField

A field read from a scipy.io.loadmat mat-struct — an ndarray, a mat_struct, or a scalar, depending on how MATLAB stored it. Named once here so the struct accessors below read field: MatField with no per-signature noqa, the explanation travels into the docs, and a future narrowing happens in one place.

ctdcast.readers.ladcp.find_ladcp_file(ladcp_dir: Path, cast_num: int, cast_suffix: str = '', ladcp_pattern: str | None = None) → Path | None[source]

Return the .mat file for cast_num in ladcp_dir, or None if absent.

If ladcp_pattern is given (e.g. "msm_142_1_*.mat"), the * wildcard is replaced with the zero-padded cast number (and optional suffix) and that name is tried first. Falls back to standard names (NNN.mat, NNNb.mat) then a *_NNN.mat glob for cruise-prefixed filenames. The first glob match (lexicographic) is returned when multiple files match.

ctdcast.readers.ladcp.read_ladcp(path: Path | str) → dict[str, Any][source]

Load an LDEO IXv14 LADCP .mat file.

Uses squeeze_me=True and struct_as_record=False so the LADCP result struct is reachable as read_ladcp(path)["dr"] with attribute access.

ctdcast.readers.ladcp.read_ladcp_cast(path: Path | str, *, cast_num: int, cast_suffix: str = '') → Dataset[source]

Map an LDEO LADCP .mat to a single-cast Dataset on the native 10 m grid.

Returns a Dataset with dimension depth (uniform 10 m, positive down), an auxiliary pressure(depth) coordinate (dbar, the bridge to profiles.nc), the inverse (u/v) and shear (u_shear/v_shear/w_shear) velocity solutions, per-instrument down/up-looker profiles, per-cast scalars (barotropic, bottom-track, position, instrument_config), and the LADCP processing provenance as global attributes. Velocity carries the CF eastward/northward/error_sea_water_velocity standard names.

Reader for per-cast sensor metadata written by seasenselib.

Parses the raw_metadata global attribute (a JSON blob) into a list of sensor descriptors for the cast page.

ctdcast.readers.metadata.parse_sensor_channels(ds: Dataset) → list[dict][source]

Return one full descriptor per sensor channel in ds, from the raw header.

A thin reader over ctdcast.config.cnv_header.parse_sensor_block() (the single parser of the <Sensors> block, authoritative because seasenselib’s per-channel cnv_sensor_N dicts are lossy for some channels): it resolves the block comment to a canonical role and normalises the calibration_date. Free (unused) channels get role = None and an empty serial.

A cast read from a .hex has no <Sensors> block in its header; its sensors come from the .xmlcon carried in raw_metadata, rendered in the same record shape by ctdcast.readers.xmlcon.sensor_records().

Returns [] if raw_metadata carries neither a header sensor block nor an .xmlcon. Each dict has channel, element, sensor_id, serial, calibration_date (normalised), slope, offset and role (canonical role or None).

ctdcast.readers.metadata.parse_sensor_info(ds: Dataset) → list[dict[str, str]][source]

Extract sensor serial numbers and calibration dates from ds.

Parses the raw_metadata global attribute (a JSON string written by seasenselib) and returns one entry per sensor channel that has both a sensor_type and a serial_number.

Parameters:

ds – Per-cast Dataset as opened from a netCDF file.

Returns:

Each dict has keys sensor_type (human-readable label), serial_number, and calibration_date. Returns [] if raw_metadata is absent, unparseable, or contains no usable sensors.

Return type:

list[dict[str, str]]

ctdcast.readers.metadata.source_to_canonical(ds: Dataset, *, lower_keys: bool = False) → dict[str, str][source]

Reconstruct a reader’s {source_name: canonical_name} rename table from ds.

Reads each coordinate and data variable’s recorded source name (_SOURCE_NAME_ATTRS) and maps it to the variable’s canonical name, keeping only variables whose source name actually differs. This is the authoritative, per-cast rename the reader applied — more complete than the static CNV_ALIASES, which misses unit spellings such as c0mS/cm. lower_keys lower-cases the keys, for case-insensitive lookup against header channel names.

Reader for Sea-Bird SBE 911plus .hex files, on seabirdscientific directly.

A .hex holds one line of hexadecimal per scan at the instrument’s native rate (24 Hz on a 911plus), after a *-prefixed header that ends at *END*. Reading it takes the matching .xmlcon (ctdcast.readers.xmlcon) for the channel layout and the calibration coefficients.

What read_hex() returns, at the native rate and with nothing removed:

  • pressure, ctd_temperature_1/2, conductivity_1/2 in mS/cm, each with the .xmlcon Slope and Offset applied as Sea-Bird’s DatCnv does;

  • every voltage channel as raw volts (volt<N>_raw; an SBE 43 channel as oxygen_raw_<N>), plus the engineering value for each sensor seabirdscientific converts (fluorescence, turbidity, altimeter, beam transmission) and a quick-look SBE 43 oxygen;

  • the deck unit’s per-scan status bits and data-integrity counter;

  • time, latitude, longitude coordinates.

The time axis is built forward from the first scan: scan k is at T0 + k × interval. T0 is the header’s NMEA UTC (Time) (GPS time when acquisition started) when present and sane, else the header’s System UpLoad Time (the PC clock at the first scan), uncorrected and labelled as the System clock so the stage-2 clock correction can apply to it.

class ctdcast.readers.hex.BottleCheck(n_bottles: int, max_deviation_seconds: float, passed: bool)[source]

Result of checking bottle-fire times against bottle-fire scan numbers.

max_deviation_seconds: float

Largest |fire time − (upload time + scan × interval)|, in seconds.

n_bottles: int

Number of bottle lines read.

passed: bool

Whether every bottle is within the tolerance.

ctdcast.readers.hex.DEFAULT_NMEA_TOLERANCE_SECONDS = 3600.0

Default limit on how far the NMEA header time may sit from the PC upload time before it is distrusted (a GPS receiver with no date set reports year 2000).

class ctdcast.readers.hex.HexFile(header: str, lines: list[str])[source]

A .hex split into its header and scan lines.

header: str

The * header lines up to and including *END*, Unix newlines.

lines: list[str]

One hexadecimal string per scan, stripped.

ctdcast.readers.hex.RAW_METADATA_SCHEMA = 'ctdcast-raw-metadata/1'

Schema tag of the raw_metadata envelope a .hex cast carries.

ctdcast.readers.hex.SBE911_SCAN_RATE_HZ = 24.0

The 911plus’s native scan rate.

class ctdcast.readers.hex.TimeAnchor(t0: datetime, source: str, note: str)[source]

The time of a cast’s first scan and where it came from.

note: str

Why this anchor was chosen, for history.

source: str

"NMEA time, header" or "System UTC, first data scan".

Type:

The time_coordinate_source wording, in Sea-Bird’s bracket vocabulary

t0: datetime

Time of the first scan (naive, UTC or PC clock as source says).

ctdcast.readers.hex.check_bottle_log(bl_path: Path | str, upload_time: datetime, interval_seconds: float, *, tolerance_seconds: float = 1.0) → BottleCheck[source]

Check a .bl bottle log against the scan clock.

Each .bl line holds a bottle’s fire time (PC clock, whole seconds) and the scan range it covers. If the upload time is the first scan and scans are evenly spaced, every fire time equals upload_time + first_scan × interval to within a second. A wrong anchor or a file with dropped scans fails.

Parameters:
  • bl_path (pathlib.Path or str) – The .bl file.

  • upload_time (datetime) – The header’s System UpLoad Time (the same PC clock as the fire times).

  • interval_seconds (float) – Time between scans.

  • tolerance_seconds (float, optional) – Allowed deviation; the fire times have one-second resolution (default 1 s).

Returns:

The comparison.

Return type:

BottleCheck

ctdcast.readers.hex.enabled_sensors(instrument: XmlconInstrument) → list[Sensors][source]

Return the seabirdscientific Sensors list that decodes this instrument’s scans.

Every voltage channel present is enabled, used or not, so each scan’s voltage words are all read and kept as raw volts.

Parameters:

instrument (XmlconInstrument) – The parsed .xmlcon.

Returns:

The sensors to pass to read_sbe911plus_data.

Return type:

list of seabirdscientific.instrument_data.Sensors

ctdcast.readers.hex.read_hex(hex_path: Path | str, xmlcon_path: Path | str, *, nmea_tolerance_seconds: float = 3600.0) → Dataset[source]

Read an SBE 911plus .hex with its .xmlcon into a native-rate Dataset.

Parameters:
  • hex_path (pathlib.Path or str) – The .hex file.

  • xmlcon_path (pathlib.Path or str) – The .xmlcon holding the calibration coefficients to convert with.

  • nmea_tolerance_seconds (float, optional) – See time_anchor().

Returns:

Dimension time (one entry per scan); variables and coordinates as described in the module docstring. Global attributes include raw_metadata (the header and the .xmlcon verbatim), input_format = "hex", sample_interval_seconds, time_coordinate_source and seabirdscientific_version.

Return type:

xarray.Dataset

Raises:

ValueError – If the layout checks fail, the instrument is not a 911plus, or the header carries no usable time.

ctdcast.readers.hex.read_hex_lines(path: Path | str) → HexFile[source]

Split a .hex into its header and its scan lines.

The file is decoded as Latin-1, deliberately rather than UTF-8: Seasave writes the header in the Windows code page (** Ship: Odón de Buen is the single byte 0xF3), and Latin-1 decodes every byte without raising. The scan lines are plain ASCII either way.

Parameters:

path (pathlib.Path or str) – The .hex file.

Returns:

The header and the scan lines.

Return type:

HexFile

Raises:

ValueError – If the file has no *END* line.

ctdcast.readers.hex.time_anchor(header: str, *, nmea_tolerance_seconds: float = 3600.0) → TimeAnchor[source]

Choose the time of the first scan from a .hex header.

Parameters:
  • header (str) – The .hex header text.

  • nmea_tolerance_seconds (float, optional) – The largest acceptable difference between the NMEA header time and the PC upload time; beyond it the NMEA time is distrusted (default 1 h).

Returns:

The NMEA header time when present and within tolerance, else the PC upload time.

Return type:

TimeAnchor

Raises:

ValueError – If the header has neither a System UpLoad Time nor an NMEA UTC (Time).

Warns:

UserWarning – When the PC clock is used, so a cast without GPS time is never silent.

Reader for Sea-Bird .xmlcon instrument configuration files (SBE 911plus).

An .xmlcon is the configuration Seasave writes beside each .hex: the instrument settings (which channels are suppressed, what the deck unit appends to each scan) and one <Sensor index=…> element per channel, holding the sensor’s serial number, calibration date and coefficients.

This module turns it into three things:

  • XmlconInstrument, the parsed settings and sensors;

  • seabirdscientific coefficient objects for the sensors ctdcast converts at stage 1 (temperature, conductivity, Digiquartz pressure, SBE 43 oxygen, ECO, altimeter, C-Star);

  • sensor records shaped exactly like ctdcast.config.cnv_header.parse_sensor_block()’s, so the per-cast sensor catalog is built by the same code for a .hex cast as for a .cnv one.

The <sensor> block a CNV header embeds is the same XML as the .xmlcon’s <Sensor> element, wrapped differently and preceded by a comment naming the channel and its quantity (<!-- Frequency 3, Temperature, 2 -->). sensor_records() rebuilds that wrapping, so raw_block reads the same whichever file the sensor came from.

Original author: Joel Bracamontes Ramirez, ctdproc (parsers.load_xmlcon), whose approach this follows: walk the <Sensor> elements in order, tell primary from secondary by the order of repeated sensor types, and build seabirdscientific coefficient objects. Rewritten for ctdcast.

ctdcast.readers.xmlcon.N_FREQUENCY_CHANNELS = 5

T, C, P, T2, C2.

Type:

Frequency channels on a 911plus before suppression

ctdcast.readers.xmlcon.N_VOLTAGE_CHANNELS = 8

Voltage channels on a 911plus before suppression (4 words of 2 channels each).

class ctdcast.readers.xmlcon.XmlconInstrument(name: str, instrument_type: int, frequency_channels_suppressed: int, voltage_words_suppressed: int, scans_to_average: int, nmea_position_added: bool, nmea_time_added: bool, nmea_depth_added: bool, scan_time_added: bool, surface_par_added: bool, sensors: tuple[XmlconSensor, ...])[source]

The parsed <Instrument> of an .xmlcon.

by_element(element: str) → list[XmlconSensor][source]

Return the sensors with element tag element, in index order.

Parameters:

element (str) – The element tag, e.g. "ConductivitySensor".

Returns:

Possibly empty.

Return type:

list of XmlconSensor

frequency_channels_suppressed: int

Number of frequency channels suppressed (0–2).

instrument_type: int

Sea-Bird’s Instrument Type code (8 is the 911plus).

property n_frequency: int

Number of frequency channels present (5 minus those suppressed).

property n_voltage: int

Number of voltage channels present (8 minus two per suppressed word).

name: str

The instrument name, e.g. "SBE 911plus/917plus CTD".

nmea_depth_added: bool

Whether the deck unit appends the ship’s NMEA depth to each scan.

nmea_position_added: bool

Whether the deck unit appends the ship’s NMEA position to each scan.

nmea_time_added: bool

Whether the deck unit appends the ship’s NMEA time to each scan.

scan_time_added: bool

Whether the PC’s scan time is appended to each scan.

scans_to_average: int

Scans averaged by the deck unit.

sensors: tuple[XmlconSensor, ...]

The sensors, in index order.

surface_par_added: bool

Whether a surface PAR voltage is appended to each scan.

voltage_words_suppressed: int

Number of voltage words suppressed (0–4); each word is two channels.

class ctdcast.readers.xmlcon.XmlconSensor(index: int, element: str, sensor_id: str, serial: str, calibration_date: str, kind: str, number: int, comment: str, body: str, node: Element)[source]

One <Sensor> of an .xmlcon.

body: str

The sensor element’s XML, verbatim, with Unix newlines.

calibration_date: str

The calibration date as written (may be empty).

comment: str

The quantity text Seasave would write in the CNV sensor comment, e.g. "Temperature, 2".

element: str

The sensor’s element tag, e.g. "TemperatureSensor".

index: int

The .xmlcon index, 0-based.

kind: str

"frequency" or "voltage".

node: Element

The parsed sensor element (the child of <Sensor>).

number: int

frequency 0–4, voltage 0–7.

Type:

The channel number within its kind

sensor_id: str

Sea-Bird’s SensorID for the element.

serial: str

The serial number as written (may be empty).

text(tag: str) → str | None[source]

Return the stripped text of a direct child tag, or None if absent.

Parameters:

tag (str) – The child element name.

Returns:

The text, or None when the element has no such child.

Return type:

str or None

value(tag: str) → float[source]

Return the float value of a direct child tag of the sensor element.

Parameters:

tag (str) – The child element name, e.g. "Slope".

Returns:

The parsed value.

Return type:

float

Raises:

KeyError – If the sensor element has no such child.

ctdcast.readers.xmlcon.altimeter_coefficients(sensor: XmlconSensor) → AltimeterCoefficients[source]

Return altimeter coefficients (ScaleFactor as slope, Offset).

Parameters:

sensor (XmlconSensor) – An AltimeterSensor.

Returns:

The coefficients.

Return type:

seabirdscientific.cal_coefficients.AltimeterCoefficients

ctdcast.readers.xmlcon.conductivity_coefficients(sensor: XmlconSensor) → ConductivityCoefficients[source]

Return the conductivity coefficients (equation 1: G, H, I, J, CPcor, CTcor, WBOTC).

Parameters:

sensor (XmlconSensor) – A ConductivitySensor with UseG_J = 1.

Returns:

Slope and Offset are not part of it; the reader applies them.

Return type:

seabirdscientific.cal_coefficients.ConductivityCoefficients

Raises:

ValueError – If the sensor uses the older equation or has no equation-1 coefficients.

ctdcast.readers.xmlcon.cstar_coefficients(sensor: XmlconSensor) → CstarCoefficients[source]

Return WET Labs C-Star coefficients (M, B, path length in m).

Parameters:

sensor (XmlconSensor) – A WET_LabsCStar.

Returns:

The coefficients.

Return type:

seabirdscientific.cal_coefficients.CstarCoefficients

ctdcast.readers.xmlcon.eco_coefficients(sensor: XmlconSensor) → ECOCoefficients[source]

Return ECO coefficients (scale factor and dark output) for a fluorometer or turbidity meter.

Parameters:

sensor (XmlconSensor) – A FluoroWetlabECO_AFL_FL_Sensor (dark output Vblank) or TurbidityMeter (dark output DarkVoltage).

Returns:

slope = ScaleFactor and offset = the dark voltage, as convert_eco computes slope * (V - offset).

Return type:

seabirdscientific.cal_coefficients.ECOCoefficients

ctdcast.readers.xmlcon.oxygen43_coefficients(sensor: XmlconSensor) → Oxygen43Coefficients[source]

Return the SBE 43 coefficients of the Sea-Bird (2007 and later) equation.

Parameters:

sensor (XmlconSensor) – An OxygenSensor with Use2007Equation = 1.

Returns:

The coefficients.

Return type:

seabirdscientific.cal_coefficients.Oxygen43Coefficients

Raises:

ValueError – If the sensor uses the Owens-Millard equation, which ctdcast does not convert.

ctdcast.readers.xmlcon.parse_xmlcon(text: str) → XmlconInstrument[source]

Parse the text of an SBE 911plus .xmlcon.

Parameters:

text (str) – The whole file, already decoded.

Returns:

The instrument settings and its sensors.

Return type:

XmlconInstrument

Raises:

ValueError – If the file has no <Instrument> or <SensorArray>, or if the number of sensors does not match the channels the suppression settings leave: a layout ctdcast would otherwise read into the wrong channels.

ctdcast.readers.xmlcon.pressure_digiquartz_coefficients(sensor: XmlconSensor) → PressureDigiquartzCoefficients[source]

Return the Digiquartz pressure coefficients, including Slope, Offset and AD590M/B.

seabirdscientific’s Digiquartz converter applies the Slope and Offset itself (in dbar), so they belong in the coefficient object, and the reader must not apply them again.

Parameters:

sensor (XmlconSensor) – A PressureSensor (Digiquartz with temperature compensation).

Returns:

The coefficients.

Return type:

seabirdscientific.cal_coefficients.PressureDigiquartzCoefficients

ctdcast.readers.xmlcon.read_xmlcon(path: Path | str) → tuple[XmlconInstrument, str][source]

Read and parse an .xmlcon file.

The file is decoded as Latin-1, deliberately rather than UTF-8: Seasave writes text in the Windows code page, and Latin-1 decodes every byte without raising.

Parameters:

path (pathlib.Path or str) – The .xmlcon file.

Returns:

The parsed instrument and the file’s text, verbatim (for raw_metadata).

Return type:

tuple of (XmlconInstrument, str)

Raises:

ValueError – See parse_xmlcon().

ctdcast.readers.xmlcon.sensor_records(instrument: XmlconInstrument) → list[dict][source]

Return one raw record per sensor, shaped like parse_sensor_block’s.

Parameters:

instrument (XmlconInstrument) – A parsed .xmlcon.

Returns:

Keys channel (1-based), element, sensor_id, serial, calibration_date, slope, offset ("1.0" / "0.0" when absent), comment and raw_block, as ctdcast.config.cnv_header.parse_sensor_block() returns them for a CNV header.

Return type:

list of dict

ctdcast.readers.xmlcon.temperature_coefficients(sensor: XmlconSensor) → TemperatureFrequencyCoefficients[source]

Return the frequency-temperature coefficients (G, H, I, J, F0) of sensor.

Parameters:

sensor (XmlconSensor) – A TemperatureSensor with UseG_J = 1.

Returns:

Slope and Offset are not part of it; the reader applies them.

Return type:

seabirdscientific.cal_coefficients.TemperatureFrequencyCoefficients

Raises:

ValueError – If the sensor uses the older A–D equation (UseG_J = 0), which ctdcast does not convert.


Writers

CF-compliant netCDF writer for per-cast Datasets.

Augments the variable attributes produced by seasenselib with proper CF metadata from ctdcast.config.parameters.VARIABLES and writes QARTOD flag variables with the CF flag_values / flag_meanings convention. Writes atomically via a .nc.tmp intermediary.

ctdcast.writers.netcdf.write(ds: Dataset, path: Path, *, encoding: dict | None = None) → None[source]

Write ds to path with CF-1.13 attributes and QARTOD flag metadata.

Each registered variable’s units is first canonicalised to its CF spelling by ctdcast.processors.units.to_canonical_units() (which raises UnitsError on a present unrecognised spelling — the write is aborted, nothing is left on disk — and fills a missing units attribute from the registry). Then, for each variable present in both ds and VARIABLES — including coordinates such as latitude/longitude — applies long_name, standard_name, and comment (when defined). For each {var}_qc variable, generates complete CF flag attributes. Sets Conventions = "CF-1.13" unless the caller already declared one (a richer value such as "CF-1.13, ACDD-1.3" is preserved).

Writes atomically: writes to path.with_suffix(".nc.tmp") then replaces path so a failed write never leaves a partial file.

Every numeric variable with at least one dimension (coordinates included) is written with lossless zlib compression at level 4. The shuffle filter is applied to all of them except float64, where it was measured to enlarge ctdcast’s science columns. Compression is transparent on read and changes no stored values; a caller-supplied encoding for a variable is left untouched.

Parameters:
  • ds – Dataset to write (per-cast, dim=time, or profiles N_PROF×pressure).

  • path – Output netCDF path.

  • encoding – Optional xarray encoding dict passed through to to_netcdf.

Optimal storage-dtype selection for netCDF output.

Package-local data-saving utility — not part of the vendored report design system (which is about producing identical reports, not identical data). The two functions are ported from oceanarray and may diverge as ctdcast’s on-disk conventions require; keep them in sync by choice, not by vendoring discipline.

find_best_dtype() picks a variable’s storage dtype from its name and current dtype; cast_output_dtypes() applies that across a whole dataset (coordinates included) at the one write seam, shrinking file size (float64 → float32, int64 → int32, QC → int8) without touching time, position or provenance. widen_floats() is the reverse for a stage that reads a file to compute on it: storage is float32, arithmetic is float64.

ctdcast.writers.dtypes.cast_output_dtypes(ds: Dataset) → Dataset[source]

Cast every variable in ds to its optimal storage dtype.

Calls find_best_dtype() per variable, coordinates included, and rebuilds only those that change. Attributes are preserved. The input dataset is not modified. A float variable cast to an integer has NaN written as 9 (QARTOD missing) for a flag; ctdcast has no other float-to-integer case (serial numbers are text), and the 0 fill kept for one is oceanarray’s rule, copied unchanged.

Parameters:

ds (xr.Dataset) – Dataset to cast.

Returns:

New dataset with optimised dtypes, ready for NetCDF output.

Return type:

xr.Dataset

ctdcast.writers.dtypes.find_best_dtype(var_name: str, da: DataArray) → type[source]

Determine the optimal storage dtype for a variable.

Parameters:
  • var_name (str) – Variable name.

  • da (xr.DataArray) – Data array to inspect.

Returns:

Recommended numpy dtype.

Return type:

type

Notes

Rules applied in order:

  • String / datetime / timedelta / object variables: unchanged.

  • time as a word in the name: unchanged (preserve datetime64 / float encoding).

  • latitude / longitude (and lat / lon): float64, as everywhere in the family; they compress to almost nothing, so float32 would save no space.

  • *_qc suffix, or flag in a ctdcast name: int8. Sea-Bird’s own columns (sbe_) are never made integers: sbe_flag holds the bad flag -9.99e-29, which an integer would truncate to 0 (not flagged).

  • serial_number or serial: int32.

  • Integer input: downsize to int32 if stored as int64, else unchanged.

  • float64 input: float32 (about 10⁻⁷ relative, two to three orders of magnitude below the CTD sensors’ resolution).

  • Anything else: unchanged.

ctdcast.writers.dtypes.open_widened(path: Path, **open_kw: object) → Dataset[source]

Read a ctdcast file into memory, floats as float64, and close it.

The one way a stage reads a file it will compute on.

Parameters:
  • path (pathlib.Path) – The netCDF file.

  • **open_kw – Passed to xarray.open_dataset() (engine defaults to netcdf4).

Returns:

In memory, no open file handle, float32 variables as float64.

Return type:

xr.Dataset

ctdcast.writers.dtypes.widen_floats(ds: Dataset) → Dataset[source]

Return ds with every float32 variable as float64, for computation.

Files are stored as float32 (cast_output_dtypes()); a stage that reads one and computes on it (filters, recursive corrections, TEOS-10) does so in float64, so the float32 rounding happens once, at the write, and never compounds.

Parameters:

ds (xr.Dataset) – A dataset read from a ctdcast file.

Returns:

A new dataset, always (so a caller can change it freely); float32 variables (coordinates included) are float64. The input is not modified.

Return type:

xr.Dataset


Configuration

Config loading utilities for ctdcast reports.

exception ctdcast.config.loader.ConfigError[source]

A YAML file ctdcast reads could not be used as written; the message says where and why.

class ctdcast.config.loader.SectionsConfig(sections: dict[str, dict[str, ~typing.Any]]=<factory>, timeseries: dict[str, dict[str, ~typing.Any]]=<factory>, cruise_info: dict[str, ~typing.Any]=<factory>)[source]

Parsed contents of a ctd_sections.yaml file.

Loaded once at the report() entry point and passed to page builders, replacing four independent yaml.safe_load calls scattered across the reports package.

classmethod from_yaml(path: Path | str) → SectionsConfig[source]

Load a SectionsConfig from a ctd_sections.yaml file.

Returns an empty SectionsConfig if the file does not exist.

ctdcast.config.loader.groupings_path(data: dict[str, Any] | None) → Path | None[source]

Return the groupings YAML named by a config data: block.

The file defines two kinds of cast group – sections: (transects plotted against distance) and timeseries: (repeat stations plotted against time) – so groupings_yaml is the key, and ctd_groupings.yaml the conventional filename. section_yaml named only half of what the file does; it stays accepted, with a DeprecationWarning, until 0.5.0.

Parameters:

data (dict or None) – The config’s data: mapping.

Returns:

The path, or None when neither key is set.

Return type:

Path or None

ctdcast.config.loader.load_config(path: Path | str) → dict[str, Any][source]

Read a cruise config.yaml: a mapping, with no key repeated in one block.

Parameters:

path (path-like) – The config file.

Returns:

The parsed config; empty for an empty file.

Return type:

dict

Raises:
  • ConfigError – As load_yaml(), or when the file is not a mapping of blocks.

  • FileNotFoundError – When the file does not exist.

ctdcast.config.loader.load_display_config(cruise_cfg: dict[str, Any]) → dict[str, dict][source]

Return VARIABLES with cruise-level overrides applied.

Package defaults come from ctdcast.config.parameters.VARIABLES. Per-cruise overrides are read from cruise_cfg["display"]["variables"] (the display: block in the cruise config.yaml). Later keys win. Returns a new dict; nothing global is mutated, so the result can be recorded in the output file’s attributes for provenance.

Example cruise config override:

display:
  variables:
    temperature_1:
      vmin: 4
      vmax: 25
ctdcast.config.loader.load_yaml(path: Path | str) → Any[source]

Read a YAML file, refusing a key repeated in one mapping.

Parameters:

path (path-like) – The file.

Returns:

The parsed content (None for an empty file).

Return type:

object

Raises:
  • ConfigError – When the file cannot be parsed, or a key appears twice in the same block; the message names the file, the key and the lines, and what to change.

  • FileNotFoundError – When the file does not exist.

ctdcast.config.loader.warn_section_yaml_deprecated() → None[source]

Warn that section_yaml is deprecated in favour of groupings_yaml.

The single notice for the config-key spelling and the report() / init parameter spelling, so every entry point that still honours section_yaml emits the same DeprecationWarning naming the replacement and the removal version (0.5.0).

Frozen per-run report configuration, built once and threaded to the plotters.

ReportConfig replaces the runtime-mutable display globals that used to live on the plotting module (GEBCO_PATH, CLEAN_SPINES, the figsizes, the map bounds, and the colormap overrides). Building it once in ctdcast.report() and passing it down makes rendering order-independent and safe to parallelise — nothing mutates module state between figures.

DEFAULT_REPORT_CONFIG holds the defaults: the previous module-global values, except the overview-panel shape, which is 9 × 3 in (3:1).

ctdcast.config.report_config.DEFAULT_REPORT_CONFIG = ReportConfig(gebco_path=None, clean_spines=True, profile_figsize=(7.0, 10.0), overview_figsize=(9.0, 3.0), map_lat_min=None, map_lat_max=None, map_lon_min=None, map_lon_max=None, var_cmaps=mappingproxy({'ctd_temperature_1': 'RdYlBu_r', 'ctd_temperature_2': 'RdYlBu_r', 'ctd_temperature': 'RdYlBu_r', 'ctd_salinity_1': 'YlGnBu_r', 'ctd_salinity_2': 'YlGnBu_r', 'ctd_salinity': 'YlGnBu_r', 'ctd_oxygen_1': 'cmo.oxy', 'ctd_oxygen_2': 'cmo.oxy', 'ctd_oxygen': 'cmo.oxy', 'oxygen_saturation': 'BrBG', 'ctd_fluor': 'YlGn', 'ctd_turbidity': 'YlOrBr', 'conservative_temperature': 'RdYlBu_r', 'absolute_salinity': 'YlGnBu_r', 'sigma0': 'BuPu', 'AOU': 'RdBu_r'}))

The render defaults — byte-identical to the former plots.py module globals.

class ctdcast.config.report_config.ReportConfig(gebco_path: Path | None = None, clean_spines: bool = True, profile_figsize: tuple[float, float]=(7.0, 10.0), overview_figsize: tuple[float, float]=(9.0, 3.0), map_lat_min: float | None = None, map_lat_max: float | None = None, map_lon_min: float | None = None, map_lon_max: float | None = None, var_cmaps: Mapping[str, str]=<factory>)[source]

Immutable display settings for one report render.

gebco_path

GEBCO bathymetry netCDF used for map backgrounds and cast-depth lookups. None renders maps without bathymetry (not an error).

Type:

Path or None

clean_spines

Hide the top and right axis spines on profile/scatter axes when True.

Type:

bool

profile_figsize

Figure size in inches for the T–S density profile figure.

Type:

tuple of float

overview_figsize

(width, height) in inches of the cruise-overview panels. The report draws them at the full slot width, so only the aspect ratio is used there.

Type:

tuple of float

map_lat_min, map_lat_max, map_lon_min, map_lon_max

Explicit map bounds; None falls back to a data-driven extent.

Type:

float or None

var_cmaps

Variable-name to colormap-name lookup for discrete colorbars.

Type:

Mapping[str, str]

property map_bounds: tuple[float | None, float | None, float | None, float | None]

Return (lat_min, lat_max, lon_min, lon_max) for the map drawers.