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, andstage="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 inSTAGESorder regardless of the order requested.None(the default) runs every stage in order.cnv_dir – CTD pipeline paths.
cnv_diris the external CNV input;ctd_rootis the directory ctdcast owns, holdingstage1/…stage3/and the compiled product. Present → CTD participates in the relevant stages.ctd_root – CTD pipeline paths.
cnv_diris the external CNV input;ctd_rootis the directory ctdcast owns, holdingstage1/…stage3/and the compiled product. Present → CTD participates in the relevant stages.hex_dir – Raw SBE 911plus
.hexinput and the switch between it andcnv_dir("cnv"or"hex"; seeStagePaths.from_config()).ctd_raw_format – Raw SBE 911plus
.hexinput and the switch between it andcnv_dir("cnv"or"hex"; seeStagePaths.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_dirare 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_dirare 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_dirare 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_dirare 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
Noneor 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
.ncfiles.out_dir – Root output directory.
profiles_path – Path to compiled
profiles.nc. Required for section and time series pages.groupings_yaml – Cast groupings —
sections:andtimeseries:. Conventionallyctd_groupings.yaml.section_yaml – Superseded spelling of groupings_yaml; accepted, and used only when groupings_yaml is absent.
ladcp_dir – Directory containing processed LADCP
.matfiles namedNNN.matorNNNb.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. Seefind_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 toTrue.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 inconfig.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 withctd_salinity_1outside 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 (--stagechoices, 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 itsrunwrapper, so there is no per-source token:--stage 1ingests CTD and LADCP,--stage profilescompiles 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_pathis the highest-stage file present (3 > 2 > 1);source_stageis 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
142inmsm_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). ReturnsNonewhen no 3+-digit group is present.A per-cast file may carry a stage suffix (
_stage1…_stage3; seectdcast.processors.stage_layout). It is stripped first, so a lettered cast likemixsed2_029_b_stage1parses to(29, "b")— otherwise the trailing_stage1defeats 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_numbersspec 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
ValueErroron 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_numbersspec 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 station10. Use this where callers key on the integer station (LADCP files, map positions, membership); useexpand_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/NNNbconvention 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,latsandlons.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_pathsupplies the bathymetry andmap_boundscan 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,lonandcast_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_pathsupplies the bathymetry andmap_boundscan 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_pathsupplies the bathymetry andmap_boundscan 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
latandlon; 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_pathsupplies the bathymetry andmap_boundscan 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_pathsupplies 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_fluorandctd_turbidity(or their old names) found in it gets a panel.cfg (ReportConfig) – Report configuration;
clean_spinessets 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
pressureand the T/S channels; CT, SA and σ₀ are derived here (TEOS-10) and the downcast is selected.cfg (ReportConfig) – Report configuration;
clean_spinessets 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}_qccompanion. 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_qccompanion 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’sdraw_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_spinesdrives 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
pressureand the T/S channels; CT, SA and σ₀ are derived here (TEOS-10) and the downcast is selected.cfg (ReportConfig) – Report configuration;
clean_spinessets 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
pressureand the T/S channels; CT, SA and σ₀ are derived here (TEOS-10) and the downcast is selected.ladcp_path (pathlib.Path, optional) – LADCP
.matfile 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_spinesis 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
pressureand the T/S channels; CT, SA and σ₀ are derived here (TEOS-10) and the downcast is selected. Withoxygen_saturation(or the oldoxsat_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_spinessets 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
pressureand the T/S channels; CT, SA and σ₀ are derived here (TEOS-10) and the downcast is selected.cfg (ReportConfig) – Report configuration;
clean_spinessets 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_cmapsis used, andoverview_figsizesets 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 usesoverview_figsizeas 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_cmapsgives 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_salinityandconservative_temperature.cfg (ReportConfig) – Report configuration;
clean_spinessets 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_temperatureand an oxygen variable.cfg (ReportConfig) – Report configuration;
clean_spinessets 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_salinityandconservative_temperature.x_vals (numpy.ndarray) – Along-track position (km) of each profile; sets the colour.
cfg (ReportConfig) – Report configuration;
clean_spinessets 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) withabsolute_salinity,conservative_temperatureandtime_start.cfg (ReportConfig) – Report configuration;
clean_spinessets 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_His 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)wherefig_wequals the slot’scanonical inch width and
css_slotis 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
Nonewhen there is nothing to plot (no segments — ano_clock_pairorinsufficientverdict).- 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_spinessets 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
pressureandtime.cfg (ReportConfig) – Report configuration;
clean_spinessets 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_spinessets 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_numberandcast_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_cmapsgives 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_startis 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
pressureand 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_spinessets 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.matfiles, 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
.matfile for this cast.cfg (ReportConfig) – Report configuration;
clean_spinessets 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_spinesis used, andoverview_figsizesets 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 usesoverview_figsizeas 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
.matfiles.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; whenNonethe aspect-ratio formulasection_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 toNNN.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; whenNoneit 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
Nonewhen 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.ncfor the overview panels.- Parameters:
ds_ladcp (xarray.Dataset) – Compiled LADCP profiles (dims
N_PROF×depth) withu,v,cast_number,latitudeandlongitude.cfg (ReportConfig) – Report configuration;
gebco_pathsupplies the bathymetry.
- Returns:
The shared grid, or None when
u/vare 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
.matfiles.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 toNNN.mat.cfg (ReportConfig) – Report configuration;
gebco_pathsupplies 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.ncdataset.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.ncdataset.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.ncdataset.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.ncdataset.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.ncdataset.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.ncdataset; itsblockattribute 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.ncdataset.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.ncdataset.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.ncdataset.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.ncdataset.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.ncdataset.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(viaunit_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_locatablefor free-aspect axes; hand-reserved inches whenever the aspect is locked or the axes are hand-placed. Do not addset_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
BoundaryNormand 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
BoundaryNormbar can still show ~6 round labels (e.g. 34.8, 34.9, … 35.2) instead of one label per boundary. UsesMaxNLocatorwith 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,contourfset, …).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 cruiseconfig.yaml; usectdcast.config.loader.load_display_config().- Derived
Computed from another constant; must live here to avoid drift.
- Deferred
Belongs in
oceanvisonce 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_varpicks the composite when the cast declaredpreferred_oxygen, and falls back toctd_oxygen_1on 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 andVARIABLES[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_oxygenand line-1ctd_oxygen_1stand for each other, as inresolve_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-Nonehit wins, in that order.- Parameters:
overrides (dict of str to float) – The
vminorvmaxoverride 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
Nonewhen 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 voltagevolt<N>_rawwith no sensor conversion is kept for the record, not used; neither is a measurement a_qcflag 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_1form. Returns var unchanged when neither is present, so the caller’s draw function then returnsNonefor the missing variable.- Parameters:
ds – The dataset whose variables to resolve against.
var – The requested variable name (plain or
_1/_2suffixed).
- 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-emptyunits, or just"Label"when it is dimensionless. The display unit is derived from the CFunitsstring byctdcast.config.unit_tables.unit_label()(the vendoredformat_unitsagainst ctdcast’sTABLES), never the ASCII-safeunitsstring 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 CFunitsstring viactdcast.config.unit_tables.unit_label(), so it is defined for every entry withunitsand agrees withvlabel().
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>_preferredstamp and the single-sensor presence test) —("temperature", "conductivity")for the pair,("oxygen",)for oxygen. The chosen indexed role isf"{base}_{index}"withindexfrom 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’ssegment_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 (fromprocessors.sensor_catalog.read_cast_sensor_catalog), keyed by cast number.
- Returns:
(first_cast, last_cast, segment_key, casts)for each run, in cast order.castsis 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_1andoxygen_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
primaryandsecondarysensors 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_rolesmust 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.
secondarywhere onlytemperature_1/conductivity_1exist).- 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:
1for"primary",2for"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 rolef"{role}_{index}"(index from use) to itsSENSOR_*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_rolesto 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_keyin 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
castskey, a value outsideUSE_VALUES, or two ranges covering this cast with differentuse(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_rolesmember, in order: theSENSOR_*catalog variable name for that indexed role, orNonewhen 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 byctdcast fitto 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 (fromprocessors.sensor_catalog.read_cast_sensor_catalog).
- Returns:
One catalog name (or
None) pergroup.segment_rolesmember, 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 allresolve_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:
group (SensorGroup) – The group to check.
cruise_cfg (dict) – The settings from
ctdcast.config.layout.processing_view().catalog_by_cast (dict of {int: list of dict}) – Per-cast catalog records, keyed by cast number.
- 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:
The universal
sbe_sensors.yamlshipped in this package, keyed on the numeric SeaBirdSensorIDfrom the CNV header (SensorRegistry).The operator’s cruise
config.yamlsensors: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 (seectdcast.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
.hexcarries the SBE 43 voltage (oxygen_raw_N) at stage 1, andctd_oxygenonly 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 –
fluorometeris the instrument,ctd_fluorthe fluorescence. A role absent here (transmissometer, pH, SPAR/PAR, a user polynomial today) still gets a catalog entry. On a.hexcast it links by.xmlconchannel 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.
overridesis keyed by role ("altimeter") or, to disambiguate two different-model devices in one role,"role:serial"("altimeter:42299").aliasesmaps 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
serialafter 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 barerole.
- classmethod from_cruise_config(cruise_cfg: dict[str, Any] | None) SensorOverrides[source]
Build from a cruise
config.yamlmapping (itssensors: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>.roleis 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. ASENSOR_*_qccompanion is not an entry, and neither are the lowercasesensor_<role>linkage orsensor_channel_<role>variables.- Parameters:
name (hashable) – The variable name, as
Dataset.variablesyields it.- Returns:
Truewhen name starts withSENSOR_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_idis the numeric SeaBird SensorID (as a string);serialthe verbatim serial number (a string — leading zeros are significant);rolea canonical ctdcast role;elementthe CNV element name for cross-checking against the registry;castan 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 withsensor_model="UNK"and a loud, actionable warning; withstrict=Trueit raisesValueErrorinstead.- Raises:
TypeError – if
serialis not astr(guards YAML octal coercion of leading-zero serials).ValueError – if
strictand 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_ROLESrole 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()ofserial; deprecated alias, removed in 0.5.0.sanitize/sanitiseis a British/American variant word, so the family uses one spelling-neutral name (serial_slug) for the filename/variable-safe form.
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_*andtime_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 fromcruise_info:in the cruise config, once, at the level it is true.identity —
cruise,platform_*andexpocode. Constant for a ctdcast file, so all three are globals. (CCHDO’s exchange format storesexpocodeper 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_..._delayedandsp032_..._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 asUNKCRUISEinctdcast.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 madecruisevanish 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 — aplatform_vocabularyURI 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, whichidentity_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_startis the earliest start andtime_coverage_endthe 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_startis the earliest start andtime_coverage_endthe 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_*andtime_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 andNone. The resolver keeps its strict raising contract for direct callers; this is the lenient wrapper the file builders use.A missing
platform/ship_slugorstart_dateis different: the cruise is mid-processing and has simply not settled that value yet. ReturningNonethere 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
Noneas 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;
Noneonly 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. Theexpocodeis not here — the caller emits it as anN_PROFcoordinate.- 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 toctdcast.config.people.contributor_attrs(), which writes only the roles each contributor scoped to this product (theirroles: {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_dbarfor the grid token indataset_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.
cruiseis 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 acruise_idattribute leak into every file.cruise_idstays 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
Nonewhen 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_modeand itsdata_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_modeor 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>.ncfor a compiled product, or None when noidexists.ACDD notes that the
idmay 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
idfollows 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_identifieris the institution’s own name for the cruise and carries the date explicitly, since a project short name likemixsed2has none. The product and grid then distinguish the files within one cruise.The leading
<expocode>_ctdis 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. Readsdata_mode,naming_authorityandinternal_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_modeanddata_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_GROUPSorder; 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 trailingOTHER_GROUP. Empty groups are omitted.- Returns:
[{"title": str, "rows": [(key, value), ...]}, ...]. The key isrows(notitems) so a Jinja template’sgroup.rowsdoes 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, theplatform_*block, andexpocode. 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.Noneor 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
licenseciting NERC L08 and COAR whencruise_info.embargois present. The release date isembargo.untilwhen set, otherwiseend_date + 2 years. Machine readers also getdate_availableandaccess_constraint;a bare CC BY statement when
cruise_info.licensenames it and there is no embargo;nothing when neither is configured — an absent
licenseasserts nothing, which is safer mid-cruise than a wrong claim.
- Parameters:
cruise_info (dict) – The
cruise_info:mapping.- Returns:
licenseand, 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_modifiedand CF/ACDD conformance tags.Deliberately not
history. Every other writer appends to that attribute throughctdcast.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 inCREATION_NOTEand 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. baremeteor) raises with the message naming the alternatives;a slug whose
ices_codeisnull(a vessel with no code yet) raises rather than emitting a malformed EXPOCODE;a derived code appearing in
forbidden_codesraises — 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_slugstraps (slug → why it is refused), forctdcast 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.yamlslug, or an inline platform record carrying at leastices_code(seeresolve_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"forodbdeparting 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
Nonewhen not derivable.Returns
None(rather than raising) when the config supplies noship_slugor nostart_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 viaderive_expocode(), because those are authoring mistakes.- Parameters:
cruise_info (dict) – The
cruise_info:mapping from the cruise config.- Returns:
The EXPOCODE, or
Nonewhen the slug/start_dateis absent.- Return type:
str or None
Notes
The slug is read from
cruise_info["platform"], falling back tocruise_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_codestraps (ICES code → why it is refused), forctdcast 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_slugstill 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, orNone.Accepts a
date/datetime(YAML parses a bare2026-03-27as adate), an ISO"YYYY-MM-DD"string, or a compact"YYYYMMDD"string. ReturnsNoneforNoneor 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_nameandplatform_ices_codefrom 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.yamlslug, or an inline platform record (seeresolve_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(notnative_name), for the report masthead and for defaulting the free-textshipinctdcast initfrom the chosen slug — deriving the name from the ICES code (unambiguous) rather than resolving a typed name into a code (ambiguous). ReturnsNonewhen 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_slugvalue — a key inplatforms.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 leastices_code(for the EXPOCODE) andname, plus optionalplatform(L06 category) andplatform_vocabulary. This mirrors the inline institution form, so a user can name a new vessel in their own config without first editingplatforms.yaml.- Parameters:
platform (str or dict) – A
platforms.yamlslug, 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 forcontributing_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.allmeans 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_typevalues.
- 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_vocabularyis absent.
- ctdcast.config.people.DEFAULT_ROLE_VOCABULARY = 'C89'
Used when
cruise_info.role_vocabularyis 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
uriis what goes intocontributor_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/creatorblock 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_institutionscomes fromcruise_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;Noneuses 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").Nonereturns the union across every scope, which is what validation wants.
- Returns:
Role tokens as written in config (codes or prefLabels),
allfirst 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:
the packaged
ctdcast/config/institutions.yaml(the shipped defaults);~/.config/ctdcast/institutions.yaml(or$CTDCAST_CONFIG_DIR), for institutions an individual or lab uses across cruises;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.institutionsmay be written inline with its ownnameandid— seeresolve_institution(). Inline is the most reproducible option, since the config then carries everything the file asserts.- Parameters:
extra (Path or str, optional) – The
institutions_filefrom 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_vocabularyselects by short name and defaults toDEFAULT_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 inlinecruise_info.institutionsentries that carry their ownname/idand 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};sourceis"packaged","user", the config file’s path, or"inline". Inline entries have an emptyslug— 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_filefrom 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 tocontributor_idis 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}, orNonewhen 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 toDEFAULT_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_vocabularyselects the vocabulary by short name and defaults toDEFAULT_ROLE_VOCABULARY.- Returns:
name (str)
spec (dict) –
uri,titleandtermsfor 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.- 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_secondsisnmea_utc - system_utc(positive when the system clock is slow relative to GPS), orNoneif either timestamp is absent or unparseable.system_dt/nmea_dtare the same two clocks already parsed todatetimewhile computing the offset, exposed so callers need not re-parse the verbatim strings;system_upload_dtissystem_uploadparsed 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.
stateisCONFORMANCE_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, sosourcenames where the reference came from and the tick is a match indicator, not a verdict.keyaligns the tick to theCorrectionit belongs to ("celltm","align", a suffixed"wildedit_2"); several ticks share one key when a correction expands per sensor/channel (labeldisambiguates the sub-rows).detailis the parsed-vs-reference text;variablesnames the variable(s) the step modified, for a display column (conductivity_1for a cell-thermal-mass row, the smoothed channels for a filter row,all channels: raw→physicalfor 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.
labelis the display name ("align (deck)","celltm","celltm (2)"for a repeat);keyis the attribute suffix ("align","celltm","celltm_2").parametersis 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.
advancemaps 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 withmodelNonemeans 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.
stepsis 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.verbatimis 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.moduleis the name exactly as the header spells it (datcnv,wildedit,Derive).paramsmaps 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 asno, 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
historyline’s components.timestampis the module’s verbatim SBE stamp (noZ);stageis the module name as spelled;noteis its salient-parameter body. The deck-unit align has no timestamp and is not a history note (it iscorrection_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 + offsetatdatcnvto 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.kindis"temperature"/"conductivity"/"pressure";labeldisambiguates dual sensors ("temperature_1","temperature_2"), or is the bare kind when a sensor is single.slopeandoffsetare kept verbatim as the config spells them, so no precision is lost.slope_nondefault/offset_nondefaultflag 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_appliedis 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.
channelis the SBE column (c0S/m);deckandsoftwareare the two advances in seconds andtotaltheir sum, which is what the data carry.- channel: str
- deck: float
- 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_timevalue and the provenance named in its bracket.sourceis the verbatim bracket text ("System UTC, first data scan.");clockandanchorare its resolved halves.sourceis""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
.hexheader.- Returns:
"modules": the set of SBE Data Processing modules in the chain, lower-cased ({"datcnv", "celltm", "binavg", …});"aligned":{variable: seconds}for each channel analignctdstep advanced, namedconductivity_1,oxygen_2,temperature_1…;"align_unparsed":alignctdchannels 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, onecorrection_<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 absentcorrection_<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_calibrationsheader parse and, since the sensor catalog, on the per-castSENSOR_*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.0for a slope,0.0for 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
celltmrows, 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:
- 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:
- 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 thatCONFORMANCE_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 bykey, 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 singleCONFORMANCE_NO_REFERENCEtick — a dash, never a cross. The comparison reads the structuredProcessingStepparameters 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’soriginal_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 (seeconformance_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 9vsSBE19plus), so it is normalised to a single space afterSBE(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_metadataattr.raw_metadatais the JSON envelope seasenselib writes and stage 1 carries through:{"schema": ..., "raw_format": "sbe-cnv", "blocks": {"header": "<* and # lines>", ...}}. Returns theblocks.headerstring, orNoneif 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 yieldsNone.
- 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_REFERENCEtick.- Return type:
- 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_dateline 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 notkey = valueis preserved inProcessingChain.verbatimbut 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
# intervalline as(kind, value), or(None, None).kindis the word Sea-Bird writes, lower-cased:"seconds"for scan-rate or time-averaged data (seconds: 0.0416667at 24 Hz,seconds: 1after a 1 s average),"decibars"for pressure-binned data. A.hexheader 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),slopeandoffset(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, andraw_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 (seectdcast.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 inAcquisition.verbatim. Unrecognised lines are not fatal. Absence of the deck-unit line yields an emptyDeckUnit.
- ctdcast.config.cnv_header.parse_start_time(header_text: str) StartTime[source]
Parse
# start_timeand resolve its bracket to a(clock, anchor)pair.The provenance bracket is optional: a
start_timeline without one still yields its timestamp value, withclock/anchor"unknown". A file with nostart_timeline at all (e.g. a raw HEX, which carries no#block) returnsvalue=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
filterrows.- 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:
- 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_metadataenvelope, or None.- Parameters:
raw_metadata (str or None) – The
raw_metadataattribute (JSON).name (str) – The block:
"header"(CNV or.hexheader) or"xmlcon"(a.hexcast’s.xmlcon).
- Returns:
The block’s text;
Noneif the attribute is absent, not JSON, or has no non-empty string underblocks.<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
historyshows what SBE did before ctdcast, oldest-first. A module with no_dateline — 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 incorrection_<module>andsbe_processing_orderbut not inhistory. The deck-unit align has no timestamp either and is recorded only ascorrection_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 overparse_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>_2and 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
alignctdadvance 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
alignctdstep; empty when nothing stacks.- Return type:
list of StackedAdvance
- ctdcast.config.cnv_header.start_time_clock(bracket: str) str[source]
Classify a
time_coordinate_sourcebracket 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 inskippedwith 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-readydata_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) pluspreferred_pair,preferred_oxygen,clock,qc,fitanddata_processingfrom 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.
kindis"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 onkindalone, never on the note prose.resolution_caveatis 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 viachangepoints.- 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 nestedstageN/layout, a flatnc_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’sstart_timebracket anchors the coordinate to (systemvsnmea) — 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.
nmeaneeds no correction;systemis 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 nostart_timebracket was parsed, so whether a correction applies isundetermined— 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
clockYAML for a step/constant verdict, orNoneif inapplicable.One
segmentsentry per segment, keyed on inclusive cast-number ranges (thectd_groupings.yamlidiom). ReturnsNonefordrift(no applier),no_clock_pairandinsufficient. 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_castsandclock_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
Sectionper item yielded byover.
- over: Callable[[Any], Sequence[Any]]
- 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"— orNonewhen the panel applies but no output could be produced (a plot raised, or the variable is absent), which the resolver turns into a.warnstub. May instead return aStubto carry the reason the panel is empty, so the stub says why. Figure adapters wrap the existing_make_*_b64functions 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 imagesrc.slot (str or Callable or None, optional) –
SLOTSkey giving the panel’s display width, or a callablectx -> slotthat 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.Nonemarks a figure that is not rendered through the slot system: it is emitted as a bare.figthat fills the content column (noslot-*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.
Falseomits 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), orNoneto proceed. A returned reason becomes a.warnstub with that reason andrenderis not called. This is the channel for defects knowable from context; arenderthat still returnsNonegets 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_topredicate).
- caption: str | None = None
- id: str
- kind: Literal['figure', 'html', 'table'] = 'figure'
- slot: str | Callable[[Any], str] | None = 'full'
Return None for any context (the default
unavailable_ifpredicate).
- class ctdcast.reports._vendored.page_model.PanelGroup(over: Callable[[Any], Sequence[Any]], panel: Callable[[Any], Panel])[source]
A
Section.panelsentry 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; reserveExpand’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
Panelper item yielded byover.
- over: Callable[[Any], Sequence[Any]]
- ctdcast.reports._vendored.page_model.PanelKind
Panel content kinds.
"figure"renders a base64 PNG (escaped as an imagesrc);"html"and"table"render pre-built markup that the template macro emits with|safe. The discriminator keeps theautoescape=Trueboundary 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'
- 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 readctx: RenderContextwith 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
.warnstub.- 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 (
2for<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"(numbered1..N) or"appendix"(numberedA..), 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 itsslot(so twoslot="half"figures sit side-by-side and aslot="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
renderwhen 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
Nonefromrenderstill means the generic stub. Thereasonis shaped on construction to a single line, capped at_STUB_REASON_LIMITcharacters.- 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
Expandentries, drop sections whoseapplies_tois false (collecting them for the not-applicable footer), resolve each kept section’s panels (Nonerender →.warnstub), then number the survivors —contentsections1..NandappendixsectionsA...- 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
panelsentries 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:
- Raises:
NotImplementedError – If
profile.numbering == "grouped"(reserved for a later branch).KeyError – If a section references a panel id absent from panels.
Raise
ValueErrorunless 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 hasstate == "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’sroleis aROLE_ACCENTkey; every pill has astate(required, not defaulted) that is one oflink/current/missing; everylinkpill has a non-emptyhref. Thebackup-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
.ncfile.out_dir – Root output directory.
all_meta – List of dicts with keys
lat,lonfor 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
.matfiles namedNNN.matorNNNb.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 withctd_salinity_1outside 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; seeinventory_pills().generated_at (str or None) – Page build stamp;
Noneuses the current UTC time. Threaded fromctdcast.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 bycnv_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
.matfiles. 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 toNNN.matif 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;
Noneomits it.inventory – The “Data inventory:” strip pills (
{"label", "href"}) shown beneath the masthead; seeinventory_pills().generated_at – Page build stamp;
Noneuses the current UTC time. Threaded fromctdcast.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, andcolorkeys.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
.matfiles. 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 toNNN.matif 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;
Noneomits it.inventory – The “Data inventory:” strip pills (
{"label", "href"}) shown beneath the masthead; seeinventory_pills().generated_at – Page build stamp;
Noneuses the current UTC time. Threaded fromctdcast.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_rowsbuilder andvariables_tablesmacro as the inventory page’s “Data variables” section, so the per-cast appendix renders in the same form: variables grouped by dimension,_qccompanions folded into their parent, and the full attribute set (includingprocessing_level) behind each row’s disclosure. EverySENSOR_*/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 besideindex.html).show_nav – Render the full report page-nav when
True(the in-report cruise inventory page). Standalone inspections leave itFalseso 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;
Noneuses the current UTC time. Threaded fromctdcast.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_tablesbuilders (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 asoriginal_name(the in-contextoriginal → namecell).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"}fromvariables_rows()with an including predicate),coverage(the recomputed-bounds check),qc_exclusionandrename_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 vendoredsensor_rows), and the per-profilesensor_<role>linkage andsensor_channel_<role>channel variables (via the vendoredvariables_rowswith 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_linkageandsensor_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;
Noneuses 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
011or011–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.nccarryingprocessing_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;
Noneuses 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_recordandstages: 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.htmlfrom afits.ncfile.- Parameters:
fits_path (pathlib.Path) – The
fits.ncwritten byctdcast 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;
Noneuses 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.htmlinteractive map needs.Builds the
track_mappayload, 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_mappayload forcasts.html.One point per cast (
trackis a single[lat, lon]→ circle marker) and one polyline per section (in cast order), each a dict{id, href, color, track, info, link_label}.infois facts only; the macro appends thelink_labellink tohref. 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 inleaflet.html’s own (non-vendored) payload shape; the two stay separate only until V4, whenleaflet.htmlmigrates onto thistrack_mappayload 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_ncexists 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;
Noneor 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;Noneomits the strip.generated_at (str or None, optional) – Page build stamp;
Noneuses the current UTC time. Threaded fromctdcast.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.htmlpath, orNonewhenall_metais 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_1andconductivity_2with the same bounds are one row, labelledconductivity_*— 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 -> colormapentry 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), orpackage-accent. Empty: ctdcast keeps the family colours. Each key must be an overridable token (an unknown key raises inemit_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 asCMAP_OVERRIDES: ctdcast’s choice lives here, not in the shared table. The report env reads it as theshow_sourcetemplate 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 → namecell in the inventory tables.original_nameis the family-shared spelling ctdcast writes now (CTD and LADCP alike);cnv_original_name(CNV) andsource_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
--oceanso 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 nametable, the default forctdcast.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 throughCMAPSwhen it names a quantity —CMAPS.get(spec, spec)does both. A variable with no explicit"cmap"is bridged by its CFstandard_namethroughQUANTITY_BY_STANDARD_NAME. Acmo.*result triggersregister_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. WhenNone(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
_qcsuffix).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:
Truewhen 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 uppercaseSENSOR_*variables that carry a physical sensor’s provenance, excluding any_qccompanion. The lowercasesensor_*linkage and channel variables are not catalog entries and are excluded from the science-variable table by a broader rule inctdcast.reports.dataset.- Parameters:
name (str) – The variable name.
- Returns:
Truewhen name is aSENSOR_*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’sTABLES, so an override in this module reaches both the plot axes (viactdcast.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 getsQC_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.pyFIGURE_SOURCE), never in the shared table. Read into the report env as theshow_sourcetemplate 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 deprecatedListedColormap(N=...)(its code, not ours), emitting oneMatplotlibDeprecationWarningper 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
AOUalready exists. Acceptsoxygen_saturation(canonical) oroxsat_1(pre-rename name).- Parameters:
ds – Dataset (any dimensionality) with
oxygen_saturationoroxsat_1in % saturation.- Returns:
New Dataset with
AOUadded; 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 (callderive_SA()first). Usesgsw.CT_from_twith the first available temperature variable (ctd_temperature,ctd_temperature_1, ortemperature_1) andpressure.- Parameters:
ds – Per-cast Dataset (dim=time) with
absolute_salinity, a temperature variable, andpressure.- 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_SPwith the first available salinity variable (ctd_salinity,ctd_salinity_1, orsalinity_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 (unitsnot mS/cm) is converted by ×10. Call this after any conductivity calibration so that salinity reflects the calibrated conductivity.Does nothing if
conductivity_1or 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, andpressurein their expected units (conductivity in mS/cm, temperature in °C ITS-90, pressure in dbar).- Returns:
New Dataset with updated
ctd_salinity_1(andctd_salinity_2whenconductivity_2is 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"]andds["conservative_temperature"]to already be present. Usesgsw.sigma0.- Parameters:
ds – Per-cast Dataset (dim=time) with
absolute_salinityandconservative_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 derivesoxygen_saturation(% sat) via_derive_oxygen_saturation()— per oxygen line, from that line’s own T/S, with the composite selected by thepreferred_oxygenattribute (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
pressureas a 1-D coordinate and a temperature variable, a salinity variable,latitude,longitudewith 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_oxygenprofiles filled fromctd_oxygen_1.A compiled profiles file holds the plain
ctd_oxygencomposite as soon as any cast has one (a declaredpreferred_oxygencast, or a single-oxygen cast), and it is all NaN for every other cast. An undeclared dual-oxygen cast has no composite, so drawingctd_oxygenwould 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’sfilled_from_ctd_oxygen_1attribute.- 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_castsection ordering: each cast’s x-coordinate is its distance from the chosen key cast. Usesgsw.distanceper pair so the convention matchesalong_track_km(). A position identical to the key yields 0. Agsw.distancefailure 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 byx_total - x_valsbefore 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
Noneif 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_gebcohas 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_pathfrom 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_gebcocalls 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’scell_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_FRACTIONof 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, taperTUKEY_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 mostMAX_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_SPEEDor 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 (
tauin seconds).tau (numpy.ndarray, optional) – The grid (
tauin 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 == 0is 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()atPRESSURE_FILTER_SECONDSfirst.- 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.
alphaandtautrade 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
toleranceof the minimum is treated as equally good; among those the one nearest Sea-Bird’s default is returned, distance measured inalpha_scale/tau_scaleunits (a step oftau_scalein tau counts as much asalpha_scalein 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.
- 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,differorno_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
ProcessingRowfields).- 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}_qcflags (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:
ours (dict of str to numpy.ndarray) –
{variable: mask}from one ctdcast step (e.g.ctdcast.processors.editing.apply_wild_edit()).ref (xarray.Dataset) – The CNV from
read_reference().
- 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_flaggedfor values set to the bad flag (Wild Edit) andsbe_scan_flaggedfor 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;Nonewrites none.sensor_overrides – The config
sensors:overrides, used to resolve the per-cast sensor catalog;Noneuses an emptySensorOverrides.
- 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
.xmlconbeside hex_path with the same stem, matched case-insensitively.Seasave’s own naming mixes case (
MIXSED2_004_b.hexbesideMIXSED2_004_B.XMLCON), so both the stem and the extension are compared without case.- Parameters:
hex_path (pathlib.Path) – The
.hexfile.- 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()withstage=1orstage="stage1".- Parameters:
cnv_dir – Directory containing raw SBE CNV files.
nc_dir – The CTD stage root; stage 1 writes
stage1/<stem>_stage1.ncunder 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.ncunder 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;Nonewrites none (the default, so bare conversions are unchanged).sensor_overrides – The config
sensors:overrides, used to resolve the per-cast sensor catalog;Noneuses an emptySensorOverrides.
- 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
timecoordinate 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_secondsisNMEA - System(the seconds added to acquisition time to obtain corrected time). The uncorrected time is kept as thetime_origauxiliary coordinate, whose presence also marks the file as corrected; andtime_coverage_*are recomputed so the file does not contradict its own axis.n_castsandsegment_sdare 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 ontoclock_offset_secondsso the uncertainty travels with the number; when both are absent (a hand-written config), no statistics are recorded rather than a fabricatedsd 0.00.Refuses (raises
ValueError) when the file already carriestime_orig(already corrected — re-run from stage 1), when itstime_coordinate_sourceclassifies 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 withctdcast.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).Noneuses the default: everysbe_*channel present (the known likely-dead-weight set). An unrecognised channel is kept — name it intrim.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
historyand in adropped_channelsattribute, 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}_qcarrays (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 inds.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:
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.
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), orpressure never drops to the threshold on the upcast.
- Parameters:
pressure – Pressure array in dbar.
times – Time coordinate array (
numpy.datetime64or 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):
Find
i_max, the index of the global pressure maximum (deepest point of the cast). Searching only inpressure[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.Within
pressure[0:i_max+1], find the last index wherepressure < near_surface_dbar. For a typical MSM-style cast this falls on the early real descent, just as the CTD passesnear_surface_dbargoing downward.Crawl backward from that index within
search_secondsto 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_secondsof 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.datetime64or numeric seconds; elapsed time is computed relative totimes[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 belownear_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 newstage2/<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 byctdcast.processors.process()withstage=2.- Parameters:
root – The CTD stage root (
ctd_root). Stage files live underroot/stage1/…root/stage2/; an old flatnc_diris read as stage 1 via the compatibility shim inctdcast.processors.stage_layout.force – Rewrite the stage-2 file even when it already exists. Without
force, a cast whosestage2/<stem>_stage2.ncexists 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;Noneuses 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 newstage3/<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 byctdcast.processors.process()withstage=3.- Parameters:
root – The CTD stage root (
ctd_root). Stage files live underroot/stage2/…root/stage3/.force – Rewrite the stage-3 file even when it already exists. Without
force, a cast whosestage3/<stem>_stage3.ncexists 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 declaresdata_mode: D, each stage-3 file is stampeddata_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 inhistory.**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:
The per-sensor conductivity slope and offset (
data_processing.slope_offset), as Sea-Bird applies them when it converts the raw counts.data_processing.steps, in the order listed:wildeditandloopedit(ctdcast.processors.editing),filterandwindow_filter(ctdcast.processors.filtering),alignctdandcelltm(ctdcast.processors.corrections.apply_corrections()), fromctdcast.processors.steps.STEPS. A step ctdcast does not apply yet is skipped (runrefuses it unlessdata_processing.allow_unapplied), with a warning and ahistorynote. The order they ran in is written to thedata_processing_stepsattribute.Re-derives practical salinity whenever a step changed conductivity, temperature or pressure.
Derives
ctd_oxygenfrom the SBE 43 voltage on a cast that carriesoxygen_raw_<N>and no converted oxygen (ctdcast.processors.corrections.derive_oxygen()), with the window indata_processing.oxygen.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_processingandqcare 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}_qccompanions (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
suspectand/orfailsub-dicts of{var: (min, max)}, merged overGROSS_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
suspectand/orfailsub-dicts of{var: threshold}, merged overSPIKE_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_qcis 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_qcthe pressure is returned as it is.- Parameters:
ds (xarray.Dataset) – A cast with
pressureand, 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
*.ncfiles 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 bycast_number,cast_suffix, andcast_directionvariables. The bin spacing is recorded in thepressure_spacing_dbarglobal 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
altimeterchannel (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}_qccompanion 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_pathwhen 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 labelledUNK), the authored discovery fields, people, embargo, and theship/start_datefrom 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 thepreferred_pair/preferred_oxygendeclaration 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 defaultFalseis 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 profilesandctdcast run) passesTrueso 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.ncfrom NC files in nc_dir.Called by
ctdcast.processors.process()withstage="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 validatecollects 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()(Noneor 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 byread_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 itssensor_roleandsensor_channeloff 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-1if unstated) andattrs(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_levelvalues, verbatim. A variable can carry several at once (converted, then calibrated, then flagged): they are joined with"; "in the order applied byadd_processing_level(), so the attribute doubles as the per-variable procedure sequence. Comma is unusable as a separator —RANGES_FLAGGEDcontains one.
- ctdcast.processors.history.add_processing_level(attrs: MutableMapping[str, object], value: str) None[source]
Append a table-3
processing_levelvalue 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
historyline to attrs in place.- Parameters:
attrs – The attribute mapping to extend — an
xarrayds.attrsor the plaindicta builder assembles before constructing its Dataset. Mutated in place: the existinghistory(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 — noZis 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
historyinstead 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.stepsmay 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.stepsas(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_flagholds.
- 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_depthafter its last excursion above it, belowmax_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
- 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
- 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 onloop_edit_flagand inhistory; withfailit 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 onloop_edit_flagand inhistory.- Parameters:
ds (xarray.Dataset) – A dataset at its native scan rate, with
pressure.params (dict) – The
loopeditstep’s parameters (seeresolve_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 (withstarts_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 fromdata_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 awildeditentry the dataset is returned unchanged. A cast Sea-Bird already wild-edited is skipped, with a warning and ahistorynote.- 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
loopeditstep.- Parameters:
params (dict) –
min_velocity(default 0.25 dbar/s), ormean_speed_percentwithwindow_seconds(default 300);surface_soak: {min_depth, max_depth, deck_pressure, starts_below}(default 5, 20, true,skip), orsurface_soak: false;exclude_flagged(default true).- Returns:
The resolved parameters.
- Return type:
- 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 fromdata_processing.steps.- Returns:
None when
wildeditis 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_depthandmax_depth(offset asdeck_pressuresays) before the first scan belowmax_depth, leaving out scans an earlier Loop Edit marked whenexclude_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’sloop_editthen 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 (
filterstep): 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; indata_processing.stepsthat is twofilterentries. Applied withseabirdscientific.processing.low_pass_filter().Window Filter (
window_filterstep): a boxcar, cosine, triangle, gaussian or median window ofwidthscans, withseabirdscientific.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
filterstep: 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_constantandvariables.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_filterstep.- 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 afilterstep’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_filterstep.- Parameters:
params (dict) – The step’s parameters:
type,width(scans),variables, and optionallyexclude_flaggedand, for a gaussian,half_widthandoffset(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 fromsplit_leg().params (dict) – The
binavgstep’s parameters (seecheck_binavg()).
- Returns:
Dim
bin: each binned variable,nbin(scans in the bin), andtime(the bin’s mean time). Salinity is re-derived from the binned values.- Return type:
xarray.Dataset
Return the resolved parameters of a
binavgstep.- Parameters:
params (dict) –
bin(decibars,seconds,scans),size, and optionallyexclude_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) andinterpolate(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,
binavgbefore the last step, or more than onesplit.
- ctdcast.processors.products.check_split(params: object) str[source]
Return the leg a
splitstep 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’skey=valuepairs 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}fromdata_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_nameanddata_processing_stepsattributes 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_legattribute 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): derivectd_oxygenfrom 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_methodattribute 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_secondslater (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 fromdata_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_oxygenfrom 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 ownctd_oxygenis never re-derived), oxygen in µmol/kg is computed withconvert_sbe43_oxygenfrom 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.xmlconinraw_metadata, with the tau and hysteresis corrections on (Sea-Bird Application Note 64-3). One sensor gives plainctd_oxygen; two givectd_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_secondssets 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}_qcto QARTOD 9 (missing) where mask is true, in place.- Parameters:
ds (xarray.Dataset) – The dataset to flag.
var (str) – The data variable; its
{var}_qcis 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_secondsequals the instrument’s native interval (911plus: 1/24 s), the deck unit averaged no scans, and the Sea-Bird chain has nobinavg.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# intervalline.- 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 fromdata_processing.steps.var (str) – A stage variable:
conductivity_1/2oroxygen_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
celltmblock may holddefault/rangesitself (every conductivity channel) and per-channel keys (conductivity_2) that win over it.- Parameters:
cfg (dict or None) –
{"celltm": ...}: the step’s parameters fromdata_processing.steps.var (str) –
conductivity_1orconductivity_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
alphaandtau, 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, orDEFAULT_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_offsetholds one entry per conductivity sensor (conductivity_1,conductivity_2), each a bare{slope:, offset:}or a{default:, ranges:}declaration of them;offsetdefaults to 0.- Parameters:
block (dict or None) – The
data_processing.slope_offsetblock.var (str) –
conductivity_1orconductivity_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_oxygenfits 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) / DwithOx = V + Voffset,D = 1 + H1·(exp(P/H2) − 1)andC = exp(−interval/H3);Ox(i-1)is the uncorrected previous value. Written asy(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_oxygenwith 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
fitwrites andreportreads, 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
fitblock, defaults for anything missing.- Parameters:
processing (dict or None) – The settings from
ctdcast.config.layout.processing_view()(itsfit).- Returns:
The settings.
- Return type:
- Raises:
ValueError – On an unknown key, a value that is not a positive number, or a
min_speedoutside 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_toleranceof 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 precisionfits.ncstores, 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 = 0row ofalignment_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.ncdataset.- 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: analignctdstep per line (the downcast residual) and acelltmstep (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.ncdataset.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()orfits.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
Nonewhen 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 castNNNand its lettered siblingNNNbare distinct keys. Files whose name carries no stage suffix or no cast number are skipped.A suffix-less
*.ncdirectly under the root (the old flatnc_dirlayout, and the committed test fixtures) is folded in as stage 1, unless a nestedstage1/…_stage1.ncalready exists for that cast — the nested file wins. Compiled products such asprofiles.nccarry 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 --forcefollowed by a plainprocess --stage 2 3 profilesregenerates 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 stemrule), and a lettered sibling004bis 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 fromgroup_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, orNone.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
Nonewhen 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_pathis the highest-stage file present (3 > 2 > 1);source_stageis 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_*.ncintoladcp_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 newN_PROFdimension. Per-cast scalars becomeN_PROFvectors; 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.ncalready exists and is newer than every per-cast source file (same source-mtime rule as the CTD compiler and the processing stages);forcerebuilds regardless.cruise_info(the configcruise_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
.matto a per-cast LADCP netCDF.- Parameters:
mat_path – Path to the LDEO IXv14
.matsolution.nc_path – Output
ladcp_<cast_id>.ncpath.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;Nonewrites 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.ncfromladcp_*.ncin 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
.matin ladcp_dir to a per-cast netCDF.The LADCP parallel of
ctdcast.processors.stage1.run(): discovers the.matfiles, derives each cast’s identity from its filename, and writesladcp_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_infois 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 bymerge_tables()for an alias factor that disagrees with the base. A dedicatedValueErrorsubclass so a caller can catch this specifically without swallowing unrelatedValueErrorexceptions.
- 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
unitswhen the variable is registered (known by name, which works before the writer stampsstandard_nameon the dataset), else the canonical for its CFstandard_name. The currentunitsstring is resolved against that canonical’s accepted group (the canonical×1plus the family aliases plus the scoped spellings for the quantity); a factor≠ 1match 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≠ 1is reported through log_fn at the boundary. Temperature variables additionally get the CF-1.11units_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 toctdcast.config.unit_tables.registry_standard_names(). Used to find a variable’sstandard_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.loadmatmat-struct — an ndarray, amat_struct, or a scalar, depending on how MATLAB stored it. Named once here so the struct accessors below readfield: MatFieldwith 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
Noneif 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.matglob 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
.matfile.Uses
squeeze_me=Trueandstruct_as_record=Falseso the LADCP result struct is reachable asread_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
.matto a single-cast Dataset on the native 10 m grid.Returns a Dataset with dimension
depth(uniform 10 m, positive down), an auxiliarypressure(depth)coordinate (dbar, the bridge toprofiles.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 CFeastward/northward/error_sea_water_velocitystandard 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-channelcnv_sensor_Ndicts are lossy for some channels): it resolves the block comment to a canonicalroleand normalises thecalibration_date.Free(unused) channels getrole = Noneand an empty serial.A cast read from a
.hexhas no<Sensors>block in its header; its sensors come from the.xmlconcarried inraw_metadata, rendered in the same record shape byctdcast.readers.xmlcon.sensor_records().Returns
[]ifraw_metadatacarries neither a header sensor block nor an.xmlcon. Each dict haschannel,element,sensor_id,serial,calibration_date(normalised),slope,offsetandrole(canonical role orNone).
- 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_metadataglobal attribute (a JSON string written by seasenselib) and returns one entry per sensor channel that has both asensor_typeand aserial_number.- Parameters:
ds – Per-cast Dataset as opened from a netCDF file.
- Returns:
Each dict has keys
sensor_type(human-readable label),serial_number, andcalibration_date. Returns[]ifraw_metadatais 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 staticCNV_ALIASES, which misses unit spellings such asc0mS/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/2in mS/cm, each with the.xmlconSlope and Offset applied as Sea-Bird’s DatCnv does;every voltage channel as raw volts (
volt<N>_raw; an SBE 43 channel asoxygen_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,longitudecoordinates.
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
.hexsplit 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_metadataenvelope a.hexcast 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_sourcewording, in Sea-Bird’s bracket vocabulary
- t0: datetime
Time of the first scan (naive, UTC or PC clock as
sourcesays).
- 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
.blbottle log against the scan clock.Each
.blline 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 equalsupload_time + first_scan × intervalto within a second. A wrong anchor or a file with dropped scans fails.- Parameters:
bl_path (pathlib.Path or str) – The
.blfile.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:
- ctdcast.readers.hex.enabled_sensors(instrument: XmlconInstrument) list[Sensors][source]
Return the seabirdscientific
Sensorslist 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
.hexwith its.xmlconinto a native-rate Dataset.- Parameters:
hex_path (pathlib.Path or str) – The
.hexfile.xmlcon_path (pathlib.Path or str) – The
.xmlconholding 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 includeraw_metadata(the header and the.xmlconverbatim),input_format = "hex",sample_interval_seconds,time_coordinate_sourceandseabirdscientific_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
.hexinto 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 Buenis 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
.hexfile.- Returns:
The header and the scan lines.
- Return type:
- 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
.hexheader.- Parameters:
header (str) – The
.hexheader 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:
- Raises:
ValueError – If the header has neither a
System UpLoad Timenor anNMEA 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.hexcast as for a.cnvone.
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 Typecode (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
.xmlconindex, 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
SensorIDfor the element.
- serial: str
The serial number as written (may be empty).
- 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
ConductivitySensorwithUseG_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 outputVblank) orTurbidityMeter(dark outputDarkVoltage).- Returns:
slope= ScaleFactor andoffset= the dark voltage, asconvert_ecocomputesslope * (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
OxygenSensorwithUse2007Equation = 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:
- 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
.xmlconfile.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
.xmlconfile.- 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),commentandraw_block, asctdcast.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
TemperatureSensorwithUseG_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
unitsis first canonicalised to its CF spelling byctdcast.processors.units.to_canonical_units()(which raisesUnitsErroron 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 andVARIABLES— including coordinates such aslatitude/longitude— applieslong_name,standard_name, andcomment(when defined). For each{var}_qcvariable, generates complete CF flag attributes. SetsConventions = "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-suppliedencodingfor 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 the0fill 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.
timeas a word in the name: unchanged (preserve datetime64 / float encoding).latitude/longitude(andlat/lon):float64, as everywhere in the family; they compress to almost nothing, so float32 would save no space.*_qcsuffix, orflagin a ctdcast name:int8. Sea-Bird’s own columns (sbe_) are never made integers:sbe_flagholds the bad flag-9.99e-29, which an integer would truncate to 0 (not flagged).serial_numberorserial:int32.Integer input: downsize to
int32if stored asint64, else unchanged.float64input: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()(enginedefaults tonetcdf4).
- 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.yamlfile.Loaded once at the
report()entry point and passed to page builders, replacing four independentyaml.safe_loadcalls scattered across the reports package.- classmethod from_yaml(path: Path | str) SectionsConfig[source]
Load a
SectionsConfigfrom actd_sections.yamlfile.Returns an empty
SectionsConfigif 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) andtimeseries:(repeat stations plotted against time) – sogroupings_yamlis the key, andctd_groupings.yamlthe conventional filename.section_yamlnamed only half of what the file does; it stays accepted, with aDeprecationWarning, until 0.5.0.- Parameters:
data (dict or None) – The config’s
data:mapping.- Returns:
The path, or
Nonewhen 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 fromcruise_cfg["display"]["variables"](thedisplay:block in the cruiseconfig.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 (
Nonefor 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_yamlis deprecated in favour ofgroupings_yaml.The single notice for the config-key spelling and the
report()/initparameter spelling, so every entry point that still honourssection_yamlemits the sameDeprecationWarningnaming 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.pymodule 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.
Nonerenders 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;
Nonefalls 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.