ctdcast 0.1.0__py3-none-any.whl

ctdcast/__init__.py

@@ -0,0 +1,25 @@
+"""ctdcast — CTD data processing and reporting for shipboard oceanography.
+
+Subpackages
+-----------
+analysis:     TEOS-10, cast geometry, GEBCO bathymetry (pure computation).
+processors:   per-cast and cruise-level processing pipeline (all stages).
+readers:      format readers (LADCP ``.mat``, CNV shim, sensor metadata).
+reports:      HTML page builders and the public ``report()`` entry point.
+writers:      output writers (CF-compliant netCDF).
+
+Public API
+----------
+report(nc_dir, profiles_path, section_yaml, out_dir, force=False)
+stage1(cnv_dir, nc_dir, ...)
+profiles(nc_dir, profiles_path, ...)
+process(stage=None, *, proc_dir, force=False, **kw)
+"""
+
+from ctdcast._version import __version__
+from ctdcast.processors import process
+from ctdcast.processors.profiles import build_profiles as profiles
+from ctdcast.processors.stage1 import stage1
+from ctdcast.reports._index import report
+
+__all__ = ["__version__", "process", "profiles", "report", "stage1"]

ctdcast/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python -m ctdcast``."""
+
+from ctdcast.cli import main
+
+if __name__ == "__main__":
+    main()

ctdcast/_version.py

@@ -0,0 +1,9 @@
+"""Package version, resolved from installed metadata."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__: str = _pkg_version("ctdcast")
+except PackageNotFoundError:
+    __version__ = "0.1.0.dev0"

ctdcast/analysis/__init__.py

@@ -0,0 +1,21 @@
+"""Shared scientific analysis: TEOS-10 derived variables, cast geometry, GEBCO bathymetry."""
+
+from ctdcast.analysis.derive import (
+    derive_AOU,
+    derive_CT,
+    derive_SA,
+    derive_salinity,
+    derive_sigma0,
+    derive_teos10,
+    derive_teos10_profiles,
+)
+
+__all__ = [
+    "derive_AOU",
+    "derive_CT",
+    "derive_SA",
+    "derive_salinity",
+    "derive_sigma0",
+    "derive_teos10",
+    "derive_teos10_profiles",
+]

ctdcast/analysis/bathymetry.py

@@ -0,0 +1,200 @@
+"""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``).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import xarray as xr
+
+# Module-level numpy cache: populated by preload_gebco() at report start.
+# Maps str(path) → (all_lons, all_lats, all_depth) numpy arrays for the cruise area.
+# Once populated, load_gebco subsets with numpy (zero disk I/O).
+_GEBCO_CACHE: dict[str, tuple[np.ndarray, np.ndarray, np.ndarray]] = {}
+
+
+def preload_gebco(
+    path: Path,
+    lat_lo: float,
+    lat_hi: float,
+    lon_lo: float,
+    lon_hi: float,
+    margin: float = 1.0,
+) -> bool:
+    """Load a GEBCO region into memory once for the cruise area.
+
+    Call this at report-generation start with the full lat/lon extent of all
+    casts.  Subsequent ``load_gebco`` calls then subset from numpy arrays
+    (no disk I/O) instead of reopening the file for every map figure.
+
+    Parameters
+    ----------
+    path:
+        Path to GEBCO netCDF file.
+    lat_lo, lat_hi, lon_lo, lon_hi:
+        Bounding box of the cruise area.
+    margin:
+        Extra degrees around the bounding box.  Default 1.0 deg.
+
+    Returns
+    -------
+    bool
+        True if the file was found and cached successfully.
+    """
+    if not Path(path).exists():
+        return False
+    try:
+        bathy = xr.open_dataset(path, engine="netcdf4")
+        lon_dim = "lon" if "lon" in bathy.coords else "longitude"
+        lat_dim = "lat" if "lat" in bathy.coords else "latitude"
+        sub = bathy.sel(
+            {
+                lon_dim: slice(lon_lo - margin, lon_hi + margin),
+                lat_dim: slice(lat_lo - margin, lat_hi + margin),
+            }
+        )
+        lons = sub[lon_dim].values.copy()
+        lats = sub[lat_dim].values.copy()
+        depth = -sub["elevation"].values.copy()  # GEBCO: negative = below sea level
+        bathy.close()
+        _GEBCO_CACHE[str(path)] = (lons, lats, depth)
+        return True
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def load_gebco(
+    lat_lo: float,
+    lat_hi: float,
+    lon_lo: float,
+    lon_hi: float,
+    margin: float = 0.05,
+    path: Path | None = None,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray] | None:
+    """Return a GEBCO subset as (lons, lats, depth_m) or None if unavailable.
+
+    If ``preload_gebco`` has been called for *path*, subsets from the in-memory
+    numpy cache (fast).  Otherwise opens the file from disk (slow).
+
+    Parameters
+    ----------
+    path:
+        Path to GEBCO_2025.nc. Pass ``plots.GEBCO_PATH`` from the caller.
+        Returns None if not provided or file not found.
+    """
+    if path is None or not Path(path).exists():
+        return None
+    path_str = str(path)
+    try:
+        if path_str in _GEBCO_CACHE:
+            all_lons, all_lats, all_depth = _GEBCO_CACHE[path_str]
+            lon_mask = (all_lons >= lon_lo - margin) & (all_lons <= lon_hi + margin)
+            lat_mask = (all_lats >= lat_lo - margin) & (all_lats <= lat_hi + margin)
+            lons = all_lons[lon_mask]
+            lats = all_lats[lat_mask]
+            if lons.size == 0 or lats.size == 0:
+                return None
+            depth = all_depth[lat_mask][:, lon_mask]
+            return lons, lats, depth
+        # Fallback when preload_gebco was not called: open file directly.
+        bathy = xr.open_dataset(path, engine="netcdf4")
+        lon_dim = "lon" if "lon" in bathy.coords else "longitude"
+        lat_dim = "lat" if "lat" in bathy.coords else "latitude"
+        sub = bathy.sel(
+            {
+                lon_dim: slice(lon_lo - margin, lon_hi + margin),
+                lat_dim: slice(lat_lo - margin, lat_hi + margin),
+            }
+        )
+        lons = sub[lon_dim].values
+        lats = sub[lat_dim].values
+        depth = -sub["elevation"].values  # GEBCO: negative = below sea level
+        bathy.close()
+        return lons, lats, depth
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def interpolate_bathy_at_casts(
+    lats: list[float],
+    lons: list[float],
+    path: Path | None = None,
+) -> np.ndarray | None:
+    """Return GEBCO water depth (m, positive below sea level) at each cast position.
+
+    Uses bilinear interpolation via xarray.  Returns ``None`` if GEBCO is not
+    available or on any error.  Land points (elevation > 0) are clamped to 0.
+    """
+    if path is None or not Path(path).exists():
+        return None
+    try:
+        lats_arr = np.asarray(lats, dtype=float)
+        lons_arr = np.asarray(lons, dtype=float)
+        finite = np.isfinite(lats_arr) & np.isfinite(lons_arr)
+        if not finite.any():
+            return None
+        lat_lo = float(lats_arr[finite].min())
+        lat_hi = float(lats_arr[finite].max())
+        lon_lo = float(lons_arr[finite].min())
+        lon_hi = float(lons_arr[finite].max())
+        gebco = load_gebco(lat_lo, lat_hi, lon_lo, lon_hi, margin=0.1, path=path)
+        if gebco is None:
+            return None
+        lons_g, lats_g, depth_g = gebco
+        # depth_g shape: (N_lat, N_lon) — positive = below sea level
+        da = xr.DataArray(
+            depth_g,
+            dims=["lat", "lon"],
+            coords={"lat": lats_g, "lon": lons_g},
+        )
+        da = da.sortby("lat").sortby("lon")
+        result = da.interp(
+            lat=xr.DataArray(lats_arr, dims="n"),
+            lon=xr.DataArray(lons_arr, dims="n"),
+            method="linear",
+        )
+        return np.maximum(result.values.astype(float), 0.0)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def dense_bathy_along_track(
+    lats: list[float],
+    lons: list[float],
+    x_vals: np.ndarray,
+    path: Path | None = None,
+    n_per_segment: int = 20,
+) -> tuple[np.ndarray | None, np.ndarray | None]:
+    """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.
+    """
+    if path is None or not Path(path).exists() or len(lats) < 2:
+        return None, None
+    try:
+        dense_lats: list[float] = []
+        dense_lons: list[float] = []
+        dense_x: list[float] = []
+        for i in range(len(lats) - 1):
+            t = np.linspace(0.0, 1.0, n_per_segment, endpoint=False)
+            dense_lats.extend((lats[i] + t * (lats[i + 1] - lats[i])).tolist())
+            dense_lons.extend((lons[i] + t * (lons[i + 1] - lons[i])).tolist())
+            dense_x.extend((x_vals[i] + t * (x_vals[i + 1] - x_vals[i])).tolist())
+        dense_lats.append(lats[-1])
+        dense_lons.append(lons[-1])
+        dense_x.append(float(x_vals[-1]))
+
+        depths = interpolate_bathy_at_casts(dense_lats, dense_lons, path=path)
+        if depths is None:
+            return None, None
+        return np.array(dense_x), depths
+    except Exception:  # noqa: BLE001
+        return None, None

ctdcast/analysis/derive.py

@@ -0,0 +1,407 @@
+"""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 oxsat_1 (% 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``.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+import gsw
+import numpy as np
+import xarray as xr
+
+# ---------------------------------------------------------------------------
+# SP from C/T/P
+# ---------------------------------------------------------------------------
+
+
+def derive_salinity(ds: xr.Dataset) -> xr.Dataset:
+    """Re-compute practical salinity from conductivity, temperature, pressure.
+
+    Uses ``gsw.SP_from_C`` with conductivity in mS/cm (seasenselib stores in
+    S/m; conversion: ``C_mS_cm = conductivity_1 * 10``).  Call this after any
+    conductivity calibration so that ``salinity_1`` (and ``salinity_2`` if
+    ``conductivity_2`` is present) reflects the calibrated conductivity.
+
+    Does nothing if ``conductivity_1`` or ``temperature_1`` are absent.
+    Records the conversion method in ``salinity_1.attrs``.
+
+    Parameters
+    ----------
+    ds:
+        Per-cast Dataset (dim=time) containing at minimum ``conductivity_1``,
+        ``temperature_1``, and ``pressure`` in their expected units
+        (conductivity in S/m, temperature in °C ITS-90, pressure in dbar).
+
+    Returns
+    -------
+    xr.Dataset
+        New Dataset with updated ``salinity_1`` (and ``salinity_2`` when
+        ``conductivity_2`` is present); input is not mutated.
+    """
+    if "conductivity_1" not in ds or "temperature_1" not in ds:
+        return ds
+
+    ds = ds.copy()
+    p = ds["pressure"].values.astype(float)
+    t = ds["temperature_1"].values.astype(float)
+
+    for c_var, s_var in [
+        ("conductivity_1", "salinity_1"),
+        ("conductivity_2", "salinity_2"),
+    ]:
+        if c_var not in ds:
+            continue
+        c_s_per_m = ds[c_var].values.astype(float)
+        c_ms_cm = c_s_per_m * 10.0  # S/m → mS/cm for gsw.SP_from_C
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=RuntimeWarning, module="gsw")
+            sp = gsw.SP_from_C(c_ms_cm, t, p)
+
+        existing_attrs = dict(ds[s_var].attrs) if s_var in ds else {}
+        existing_attrs["derived_from"] = (
+            f"{c_var}, temperature_1, pressure via gsw.SP_from_C"
+        )
+        existing_attrs.setdefault("units", "1")
+        existing_attrs.setdefault("standard_name", "sea_water_practical_salinity")
+        existing_attrs.setdefault("reference_scale", "PSS-78")
+        dim = ds["pressure"].dims[0]
+        ds[s_var] = xr.DataArray(
+            sp.astype(np.float32),
+            dims=[dim],
+            attrs=existing_attrs,
+        )
+
+    return ds
+
+
+# ---------------------------------------------------------------------------
+# TEOS-10 per-cast (1-D)
+# ---------------------------------------------------------------------------
+
+
+def derive_SA(ds: xr.Dataset) -> xr.Dataset:
+    """Return *ds* with Absolute Salinity (SA) added.
+
+    Uses ``gsw.SA_from_SP`` with ``salinity_1`` (practical salinity, PSS-78),
+    ``pressure`` (dbar), and the cast's median latitude/longitude.
+
+    Parameters
+    ----------
+    ds:
+        Per-cast Dataset (dim=time) with ``salinity_1``, ``pressure``,
+        ``latitude``, ``longitude``.
+
+    Returns
+    -------
+    xr.Dataset
+        New Dataset with ``ds["absolute_salinity"]`` added; input is not mutated.
+    """
+    ds = ds.copy()
+    sp = ds["salinity_1"].values.astype(float)
+    p = ds["pressure"].values.astype(float)
+    lat = float(np.nanmedian(ds["latitude"].values))
+    lon = float(np.nanmedian(ds["longitude"].values))
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", category=RuntimeWarning, module="gsw")
+        sa = gsw.SA_from_SP(sp, p, lon, lat)
+    dim = ds["pressure"].dims[0]
+    ds["absolute_salinity"] = xr.DataArray(
+        sa.astype(np.float32),
+        dims=[dim],
+        attrs={"long_name": "Absolute Salinity", "units": "g kg-1"},
+    )
+    return ds
+
+
+def derive_CT(ds: xr.Dataset) -> xr.Dataset:
+    """Return *ds* with Conservative Temperature (CT) added.
+
+    Requires ``ds["absolute_salinity"]`` to already be present (call :func:`derive_SA` first).
+    Uses ``gsw.CT_from_t`` with in-situ ``temperature_1`` and ``pressure``.
+
+    Parameters
+    ----------
+    ds:
+        Per-cast Dataset (dim=time) with ``absolute_salinity``, ``temperature_1``,
+        ``pressure``.
+
+    Returns
+    -------
+    xr.Dataset
+        New Dataset with ``ds["conservative_temperature"]`` added; input is not mutated.
+    """
+    ds = ds.copy()
+    sa = ds["absolute_salinity"].values.astype(float)
+    t = ds["temperature_1"].values.astype(float)
+    p = ds["pressure"].values.astype(float)
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", category=RuntimeWarning, module="gsw")
+        ct = gsw.CT_from_t(sa, t, p)
+    dim = ds["pressure"].dims[0]
+    ds["conservative_temperature"] = xr.DataArray(
+        ct.astype(np.float32),
+        dims=[dim],
+        attrs={"long_name": "Conservative Temperature", "units": "degree_Celsius"},
+    )
+    return ds
+
+
+def derive_sigma0(ds: xr.Dataset) -> xr.Dataset:
+    """Return *ds* with potential density anomaly (sigma0) added.
+
+    Requires ``ds["absolute_salinity"]`` and ``ds["conservative_temperature"]`` to already be present.
+    Uses ``gsw.sigma0``.
+
+    Parameters
+    ----------
+    ds:
+        Per-cast Dataset (dim=time) with ``absolute_salinity`` and ``conservative_temperature``.
+
+    Returns
+    -------
+    xr.Dataset
+        New Dataset with ``ds["sigma0"]`` added; input is not mutated.
+    """
+    ds = ds.copy()
+    sa = ds["absolute_salinity"].values.astype(float)
+    ct = ds["conservative_temperature"].values.astype(float)
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", category=RuntimeWarning, module="gsw")
+        sig0 = gsw.sigma0(sa, ct)
+    dim = ds["absolute_salinity"].dims[0]
+    ds["sigma0"] = xr.DataArray(
+        sig0.astype(np.float32),
+        dims=[dim],
+        attrs={"long_name": "Potential density anomaly", "units": "kg m-3"},
+    )
+    return ds
+
+
+def derive_teos10(ds: xr.Dataset) -> xr.Dataset:
+    """Return *ds* with SA, CT, sigma0 added (1-D per-cast Dataset, dim=time).
+
+    Convenience function that calls :func:`derive_SA` → :func:`derive_CT` →
+    :func:`derive_sigma0` in order.  Also handles ``oxygen_1`` in two cases:
+
+    - If ``oxygen_1`` carries molar units (µmol/L or µmol/kg), derives
+      ``oxsat_1`` (% saturation) and adds it; ``oxygen_1`` is left unchanged.
+    - If ``oxygen_1`` already carries % saturation units (pre-Phase-3 NC files
+      where the variable was stored under the wrong name), renames it to
+      ``oxsat_1`` so the plotting pipeline finds it under the canonical name.
+
+    Parameters
+    ----------
+    ds:
+        Per-cast Dataset (dim=time) with ``salinity_1``, ``temperature_1``,
+        ``pressure``, ``latitude``, ``longitude``.
+
+    Returns
+    -------
+    xr.Dataset
+        New Dataset with SA, CT, sigma0 added; input is not mutated.
+    """
+    ds = derive_SA(ds)
+    ds = derive_CT(ds)
+    ds = derive_sigma0(ds)
+    if "oxygen_1" in ds:
+        units = ds["oxygen_1"].attrs.get("units", "")
+        u_lower = units.lower()
+        if "umol" in u_lower or "µmol" in u_lower:
+            sa = ds["absolute_salinity"].values.astype(float)
+            ct = ds["conservative_temperature"].values.astype(float)
+            p = ds["pressure"].values.astype(float)
+            lat = float(np.nanmedian(ds["latitude"].values))
+            lon = float(np.nanmedian(ds["longitude"].values))
+            ds = _derive_oxsat_from_oxygen(ds, sa, ct, p, lat, lon)
+        elif "%" in u_lower or "sat" in u_lower or "percent" in u_lower:
+            # Pre-Phase-3 NC files stored % saturation under "oxygen_1".
+            # Rename to the canonical "oxsat_1" so panels find it.
+            ds = ds.rename({"oxygen_1": "oxsat_1"})
+    return ds
+
+
+# ---------------------------------------------------------------------------
+# TEOS-10 profiles (2-D, dims N_PROF × pressure)
+# ---------------------------------------------------------------------------
+
+
+def derive_teos10_profiles(ds: xr.Dataset) -> xr.Dataset:
+    """Return *ds* with SA, CT, sigma0 added (2-D profiles Dataset).
+
+    Expects ``pressure`` as a 1-D coordinate and ``temperature_1``,
+    ``salinity_1``, ``latitude``, ``longitude`` as variables with dims
+    ``(N_PROF,)`` or ``(N_PROF, pressure)``.  Returns *ds* unchanged if
+    SA, CT, and sigma0 are already present.
+
+    Parameters
+    ----------
+    ds:
+        Profiles Dataset (dims N_PROF × pressure).
+
+    Returns
+    -------
+    xr.Dataset
+        New Dataset with SA, CT, sigma0 added; input is not mutated.
+    """
+    if (
+        "conservative_temperature" in ds
+        and "absolute_salinity" in ds
+        and "sigma0" in ds
+    ):
+        return ds
+    ds = ds.copy()
+    p = ds["pressure"].values.astype(float)  # (N_P,)
+    t = ds["temperature_1"].values.astype(float)  # (N_PROF, N_P)
+    sp = ds["salinity_1"].values.astype(float)  # (N_PROF, N_P)
+    lat = ds["latitude"].values.astype(float)  # (N_PROF,)
+    lon = ds["longitude"].values.astype(float)  # (N_PROF,)
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", category=RuntimeWarning, module="gsw")
+        sa = gsw.SA_from_SP(
+            sp, p[np.newaxis, :], lon[:, np.newaxis], lat[:, np.newaxis]
+        )
+        ct = gsw.CT_from_t(sa, t, p[np.newaxis, :])
+        sig0 = gsw.sigma0(sa, ct)
+    dims = tuple(ds["temperature_1"].dims)
+    ds["absolute_salinity"] = xr.DataArray(
+        sa.astype(np.float32),
+        dims=dims,
+        attrs={"long_name": "Absolute Salinity", "units": "g kg-1"},
+    )
+    ds["conservative_temperature"] = xr.DataArray(
+        ct.astype(np.float32),
+        dims=dims,
+        attrs={"long_name": "Conservative Temperature", "units": "degree_Celsius"},
+    )
+    ds["sigma0"] = xr.DataArray(
+        sig0.astype(np.float32),
+        dims=dims,
+        attrs={"long_name": "Potential density anomaly", "units": "kg m-3"},
+    )
+    return ds
+
+
+# ---------------------------------------------------------------------------
+# AOU
+# ---------------------------------------------------------------------------
+
+
+def derive_AOU(ds: xr.Dataset) -> xr.Dataset:
+    """Return *ds* with AOU added as 100 - oxsat_1 (O₂ saturation deficit, % sat).
+
+    Note: this is a saturation-deficit proxy, not the traditional AOU in
+    µmol/kg, because it uses ``oxsat_1`` (% saturation) rather than
+    dissolved O₂ in µmol/kg.  When ``oxygen_1`` (µmol/kg) is available,
+    the traditional AOU is ``gsw.O2sol(SA, CT, p, lon, lat) - oxygen_1``.
+
+    Returns *ds* unchanged if ``oxsat_1`` is absent or ``AOU`` already exists.
+
+    Parameters
+    ----------
+    ds:
+        Dataset (any dimensionality) with ``oxsat_1`` in % saturation.
+
+    Returns
+    -------
+    xr.Dataset
+        New Dataset with ``AOU`` added; input is not mutated.
+    """
+    if "AOU" in ds or "oxsat_1" not in ds:
+        return ds
+    ds = ds.copy()
+    dims = ds["oxsat_1"].dims
+    ds["AOU"] = xr.DataArray(
+        (100.0 - ds["oxsat_1"].values).astype(np.float32),
+        dims=dims,
+        attrs={"long_name": "O₂ saturation deficit", "units": "% sat"},
+    )
+    return ds
+
+
+# ---------------------------------------------------------------------------
+# Private helper
+# ---------------------------------------------------------------------------
+
+
+def _derive_oxsat_from_oxygen(
+    ds: xr.Dataset,
+    sa: np.ndarray,
+    ct: np.ndarray,
+    p: np.ndarray,
+    lat: float,
+    lon: float,
+) -> xr.Dataset:
+    """Derive ``oxsat_1`` (% saturation) from ``oxygen_1`` (µmol/L or µmol/kg).
+
+    Adds ``oxsat_1`` to *ds*; leaves ``oxygen_1`` unchanged.  Does nothing if
+    ``oxygen_1`` units do not indicate a molar concentration.  Records the
+    conversion method in ``oxsat_1`` attributes for provenance.
+
+    Parameters
+    ----------
+    ds:
+        Dataset containing ``oxygen_1`` in molar units; must already have SA/CT
+        computed (i.e. call after :func:`derive_SA` / :func:`derive_CT`).
+    sa, ct, p:
+        Absolute Salinity (g/kg), Conservative Temperature (°C), pressure (dbar)
+        arrays matching the ``oxygen_1`` dimension.
+    lat, lon:
+        Representative cast latitude and longitude for ``gsw.O2sol``.
+    """
+    units = ds["oxygen_1"].attrs.get("units", "")
+    if not units:
+        return ds
+    u_lower = units.lower()
+    if "umol" not in u_lower and "µmol" not in u_lower:
+        return ds
+
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", category=RuntimeWarning, module="gsw")
+        o2_sat_umol_kg = gsw.O2sol(sa, ct, p, lat, lon)
+
+    measured = ds["oxygen_1"].values.astype(float)
+
+    if "/l" in u_lower or "l-1" in u_lower:
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=RuntimeWarning, module="gsw")
+            rho = gsw.rho(sa, ct, p)  # kg/m³
+        o2_sat_umol_l = o2_sat_umol_kg * rho / 1000.0
+        pct_sat = measured / o2_sat_umol_l * 100.0
+        method = f"derived from oxygen_1 ({units}) via gsw.O2sol + gsw.rho"
+    else:
+        pct_sat = measured / o2_sat_umol_kg * 100.0
+        method = f"derived from oxygen_1 ({units}) via gsw.O2sol"
+
+    new_attrs = {
+        "units": "% saturation",
+        "long_name": "O₂ saturation",
+        "source_units": units,
+        "oxygen_conversion": method,
+    }
+    dim = ds["oxygen_1"].dims[0]
+    ds = ds.copy()
+    ds["oxsat_1"] = xr.DataArray(
+        pct_sat.astype(np.float32),
+        dims=[dim],
+        attrs=new_attrs,
+    )
+    return ds