ctdcast 0.1.0__tar.gz

ctdcast-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eleanor Frajka-Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ctdcast-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: ctdcast
+Version: 0.1.0
+Summary: Self-contained HTML report generator for shipboard CTD and LADCP data
+Author: Angel Ruiz-Angulo
+Author-email: Eleanor Frajka-Williams <eleanorfrajka@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ocean-uhh/ctdcast
+Project-URL: Source, https://github.com/ocean-uhh/ctdcast
+Project-URL: Documentation, https://ocean-uhh.github.io/ctdcast
+Project-URL: Bug Tracker, https://github.com/ocean-uhh/ctdcast/issues
+Keywords: oceanography,CTD,LADCP,shipboard,seawater,report
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gsw>=3.6
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: xarray>=2023.1
+Requires-Dist: netcdf4>=1.6
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: ruamel.yaml>=0.18
+Requires-Dist: scipy>=1.9
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.2; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Dynamic: license-file
+
+# ctdcast
+
+[![Tests](https://github.com/ocean-uhh/ctdcast/actions/workflows/tests.yml/badge.svg)](https://github.com/ocean-uhh/ctdcast/actions/workflows/tests.yml)
+[![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%20–%203.13-blue?logo=python&logoColor=white)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://opensource.org/licenses/MIT)
+[![Docs](https://img.shields.io/badge/docs-gh--pages-blue)](https://ocean-uhh.github.io/ctdcast/)
+
+Self-contained HTML report generator for shipboard CTD and LADCP data.
+Produces portable HTML files — all figures embedded as base64 PNGs, no external requests —
+for three report types: per-cast station pages, transect section pages, and a cruise-wide
+time series page.
+
+Designed for use at sea where internet connectivity is limited or absent.
+All output files are fully self-contained and work offline.
+
+---
+
+## Install
+
+```bash
+pip install ctdcast
+```
+
+For development (editable install from source):
+
+```bash
+git clone https://github.com/ocean-uhh/ctdcast
+cd ctdcast
+python -m venv venv
+source venv/bin/activate        # macOS / Linux
+# venv\Scripts\activate         # Windows
+pip install -e .
+```
+
+Dependencies: `gsw`, `matplotlib`, `numpy`, `xarray`, `netcdf4`, `jinja2`, `pyyaml`, `scipy`
+
+CTD conversion: `seasenselib` converts raw CNV files to the netCDF format expected by ctdcast (`ctdcast draft` or `ctdcast run --ctd`). Install with `pip install seasenselib`. Pre-converted netCDF files from other tools must match ctdcast's variable naming convention (see docs).
+
+To verify the installation, run the bundled demo against the committed fixture casts:
+
+```bash
+ctdcast run config_demo.yaml   # writes demo_report/index.html
+```
+
+For a full walkthrough see the [Quickstart guide](https://ocean-uhh.github.io/ctdcast/quickstart.html).
+
+---
+
+## Quick start
+
+### Quick look (no config file needed)
+
+Raw CNV files fresh off the instrument? One command gives you station pages + index + map:
+
+```bash
+ctdcast draft /path/to/cnv/           # generates ./ctd_draft/index.html
+ctdcast draft /path/to/cnv/ out/ --cruise odb2026   # with cruise ID
+ctdcast draft /path/to/cnv/ --dry-run               # preview what would happen
+```
+
+Requires `seasenselib` for CNV conversion (`pip install seasenselib`).
+
+### Full workflow (with config)
+
+For sections, time series, and LADCP panels you need a `config.yaml`:
+
+#### 1. Write a config
+
+```bash
+ctdcast init                        # writes a template config.yaml
+ctdcast init --interactive          # guided setup: prompts for paths and
+                                      # auto-detects sections/timeseries from profiles.nc
+ctdcast validate config.yaml        # check paths before the first run
+```
+
+#### 2. Generate
+
+```bash
+ctdcast run config.yaml             # smart update — skips up-to-date pages
+ctdcast run config.yaml --force     # rebuild everything
+ctdcast run config.yaml --cast 42   # rebuild one cast page
+```
+
+Open `<output.dir>/index.html` in any browser.
+
+---
+
+## Input data
+
+| File | Description |
+|---|---|
+| `cnv_nc/*.nc` | Per-cast netCDF files, one per CTD cast |
+| `profiles.nc` | Compiled profiles on a 1 dbar grid |
+| `ctd_sections.yaml` | Section definitions — which casts belong to each transect |
+
+### ctd_sections.yaml format
+
+```yaml
+sections:
+  KTout:
+    description: "Kögur Transect outflow"
+    color: "#e41a1c"
+    cast_numbers: [[1, 12], 15]   # ranges and/or individual cast numbers
+  FARDWO:
+    description: "FARDWO mooring array"
+    color: "#377eb8"
+    cast_numbers: [[20, 35], "22b"]   # add "NNNb" to include a lettered sibling cast
+```
+
+Cast numbers are kept in the order written. An integer or range selects the
+plain casts; a lettered sibling event (from a ``NNNb`` / ``NNN_b`` file) is a
+distinct cast and must be named explicitly as a quoted ``"NNNb"`` string.
+
+---
+
+## Output structure
+
+```
+<output.dir>/
+    index.html              front page — map + stats + navigation
+    casts.html      table of all casts (latest first)
+    sections.html           section cards with links
+    timeseries.html         T, S, O₂ vs time × pressure
+    casts/
+        cast_001.html
+        cast_002.html
+        ...
+    sections/
+        section_KTout.html
+        ...
+```
+
+Each station page shows: CT profile, T/S/σ₀ triple-axis profile, T-S diagram coloured by
+O₂ saturation, auxiliary profiles (O₂, fluorescence, turbidity), N²/Turner-angle stability
+panels, and a cruise-track map with the cast highlighted.
+
+---
+
+## GEBCO bathymetry
+
+Maps show GEBCO 2025 bathymetry when `gebco_nc` is set in `config.yaml`.
+The file (~8 GB) is not bundled. Maps render without bathymetry if the path is missing — not an error.
+
+---
+
+## Documentation
+
+Full documentation: [ocean-uhh.github.io/ctdcast](https://ocean-uhh.github.io/ctdcast/)

ctdcast-0.1.0/README.md

@@ -0,0 +1,148 @@
+# ctdcast
+
+[![Tests](https://github.com/ocean-uhh/ctdcast/actions/workflows/tests.yml/badge.svg)](https://github.com/ocean-uhh/ctdcast/actions/workflows/tests.yml)
+[![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%20–%203.13-blue?logo=python&logoColor=white)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://opensource.org/licenses/MIT)
+[![Docs](https://img.shields.io/badge/docs-gh--pages-blue)](https://ocean-uhh.github.io/ctdcast/)
+
+Self-contained HTML report generator for shipboard CTD and LADCP data.
+Produces portable HTML files — all figures embedded as base64 PNGs, no external requests —
+for three report types: per-cast station pages, transect section pages, and a cruise-wide
+time series page.
+
+Designed for use at sea where internet connectivity is limited or absent.
+All output files are fully self-contained and work offline.
+
+---
+
+## Install
+
+```bash
+pip install ctdcast
+```
+
+For development (editable install from source):
+
+```bash
+git clone https://github.com/ocean-uhh/ctdcast
+cd ctdcast
+python -m venv venv
+source venv/bin/activate        # macOS / Linux
+# venv\Scripts\activate         # Windows
+pip install -e .
+```
+
+Dependencies: `gsw`, `matplotlib`, `numpy`, `xarray`, `netcdf4`, `jinja2`, `pyyaml`, `scipy`
+
+CTD conversion: `seasenselib` converts raw CNV files to the netCDF format expected by ctdcast (`ctdcast draft` or `ctdcast run --ctd`). Install with `pip install seasenselib`. Pre-converted netCDF files from other tools must match ctdcast's variable naming convention (see docs).
+
+To verify the installation, run the bundled demo against the committed fixture casts:
+
+```bash
+ctdcast run config_demo.yaml   # writes demo_report/index.html
+```
+
+For a full walkthrough see the [Quickstart guide](https://ocean-uhh.github.io/ctdcast/quickstart.html).
+
+---
+
+## Quick start
+
+### Quick look (no config file needed)
+
+Raw CNV files fresh off the instrument? One command gives you station pages + index + map:
+
+```bash
+ctdcast draft /path/to/cnv/           # generates ./ctd_draft/index.html
+ctdcast draft /path/to/cnv/ out/ --cruise odb2026   # with cruise ID
+ctdcast draft /path/to/cnv/ --dry-run               # preview what would happen
+```
+
+Requires `seasenselib` for CNV conversion (`pip install seasenselib`).
+
+### Full workflow (with config)
+
+For sections, time series, and LADCP panels you need a `config.yaml`:
+
+#### 1. Write a config
+
+```bash
+ctdcast init                        # writes a template config.yaml
+ctdcast init --interactive          # guided setup: prompts for paths and
+                                      # auto-detects sections/timeseries from profiles.nc
+ctdcast validate config.yaml        # check paths before the first run
+```
+
+#### 2. Generate
+
+```bash
+ctdcast run config.yaml             # smart update — skips up-to-date pages
+ctdcast run config.yaml --force     # rebuild everything
+ctdcast run config.yaml --cast 42   # rebuild one cast page
+```
+
+Open `<output.dir>/index.html` in any browser.
+
+---
+
+## Input data
+
+| File | Description |
+|---|---|
+| `cnv_nc/*.nc` | Per-cast netCDF files, one per CTD cast |
+| `profiles.nc` | Compiled profiles on a 1 dbar grid |
+| `ctd_sections.yaml` | Section definitions — which casts belong to each transect |
+
+### ctd_sections.yaml format
+
+```yaml
+sections:
+  KTout:
+    description: "Kögur Transect outflow"
+    color: "#e41a1c"
+    cast_numbers: [[1, 12], 15]   # ranges and/or individual cast numbers
+  FARDWO:
+    description: "FARDWO mooring array"
+    color: "#377eb8"
+    cast_numbers: [[20, 35], "22b"]   # add "NNNb" to include a lettered sibling cast
+```
+
+Cast numbers are kept in the order written. An integer or range selects the
+plain casts; a lettered sibling event (from a ``NNNb`` / ``NNN_b`` file) is a
+distinct cast and must be named explicitly as a quoted ``"NNNb"`` string.
+
+---
+
+## Output structure
+
+```
+<output.dir>/
+    index.html              front page — map + stats + navigation
+    casts.html      table of all casts (latest first)
+    sections.html           section cards with links
+    timeseries.html         T, S, O₂ vs time × pressure
+    casts/
+        cast_001.html
+        cast_002.html
+        ...
+    sections/
+        section_KTout.html
+        ...
+```
+
+Each station page shows: CT profile, T/S/σ₀ triple-axis profile, T-S diagram coloured by
+O₂ saturation, auxiliary profiles (O₂, fluorescence, turbidity), N²/Turner-angle stability
+panels, and a cruise-track map with the cast highlighted.
+
+---
+
+## GEBCO bathymetry
+
+Maps show GEBCO 2025 bathymetry when `gebco_nc` is set in `config.yaml`.
+The file (~8 GB) is not bundled. Maps render without bathymetry if the path is missing — not an error.
+
+---
+
+## Documentation
+
+Full documentation: [ocean-uhh.github.io/ctdcast](https://ocean-uhh.github.io/ctdcast/)

ctdcast-0.1.0/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-0.1.0/ctdcast/__main__.py

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

ctdcast-0.1.0/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-0.1.0/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-0.1.0/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