Metadata-Version: 2.4
Name: ctdcast
Version: 0.2.0
Summary: Processing and reporting for shipboard CTD and LADCP data: raw files to QC'd netCDF to self-contained HTML
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: pillow>=9.0
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"
Provides-Extra: dev
Requires-Dist: ctdcast[docs,test]; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
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/)

Processing and reporting for shipboard CTD and LADCP data: from raw instrument files
through QC'd, CF/CCHDO-aligned netCDF and a compiled profiles grid, to self-contained HTML.
The reports are portable HTML files — all figures embedded as base64 PNGs, no external
requests — in three 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 ".[dev]"         # runtime + tests + docs + ruff
```

Dependencies: `gsw`, `matplotlib`, `pillow`, `numpy`, `xarray`, `netcdf4`, `jinja2`, `pyyaml`, `ruamel.yaml`, `scipy`

CTD conversion: `seasenselib` converts raw CNV files to the netCDF format expected by ctdcast (`ctdcast draft` or `ctdcast run`). 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 --only 42   # rebuild one cast page
```

Open `<output.dir>/index.html` in any browser.

Diagnose the acquisition-clock error (System vs GPS clock) for a cruise with `ctdcast clock config.yaml` — it prints a verdict and a paste-ready `processing.clock` block without writing anything.

---

## Input data

| File | Description |
|---|---|
| `ctd_nc/stageN/*_stageN.nc` | Per-cast netCDF files, one per CTD cast per stage |
| `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
    sbe_sensors.html        sensor inventory + which sensor was used on which cast
    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/)

---

## Acknowledgements

Development of this package started during the Odón de Buen cruise of AEI-DFG DS-MIXSED. DS-MIXSED is funded by the Agencia Estatal de Investigación (AEI) through the PCI 2024 call — projects PCI2024-155022-2 and PCI2024-155084-2 — and the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) — Projektnummer 541914507.

Development was assisted by Claude Code (Anthropic) and GitHub Copilot code review.
