Metadata-Version: 2.5
Name: ctdam
Version: 2.2.0
Summary: Library for conversion, processing and plotting of CTD data.
Project-URL: Homepage, https://github.com/DAM-CTD-Software/ctdam
Project-URL: Repository, https://github.com/DAM-CTD-Software/ctdam
Project-URL: Documentation, https://dam-ctd-software.github.io/ctdam
Project-URL: Issues, https://github.com/DAM-CTD-Software/ctdam/issues
Project-URL: Changelog, https://github.com/DAM-CTD-Software/ctdam/blob/main/CHANGELOG.md
Author-email: Emil Michels <emil.michels@iow.de>
License-File: LICENSE
Keywords: CTD,conversion,data,oceanography,parser,processing,seabird,visualization
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Oceanography
Requires-Python: >=3.12
Requires-Dist: docstring-parser>=0.17.0
Requires-Dist: gsw-xarray>=0.5.0
Requires-Dist: matplotlib>=3.11.1
Requires-Dist: munch>=4.0.0
Requires-Dist: netcdf4>=1.7.4
Requires-Dist: numpydoc>=1.10.0
Requires-Dist: odf-sbe>=0.3.0
Requires-Dist: scipy>=1.18.1
Requires-Dist: tomlkit>=0.12.3
Requires-Dist: tqdm>=4.67.3
Requires-Dist: xarray>=2026.7.0
Requires-Dist: xmltodict>=0.13.0
Provides-Extra: all
Requires-Dist: beautifulsoup4; extra == 'all'
Requires-Dist: bokeh; extra == 'all'
Requires-Dist: ctkmessagebox; extra == 'all'
Requires-Dist: customtkinter; extra == 'all'
Requires-Dist: platformdirs; extra == 'all'
Requires-Dist: typer; extra == 'all'
Provides-Extra: cli
Requires-Dist: platformdirs; extra == 'cli'
Requires-Dist: typer; extra == 'cli'
Provides-Extra: docs
Requires-Dist: click-extra[sphinx]>=7.9.0; extra == 'docs'
Requires-Dist: furo>=2024.8.6; extra == 'docs'
Requires-Dist: myst-parser>=4.0.1; extra == 'docs'
Requires-Dist: pyment>=0.3.3; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=2.5.0; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5.2; extra == 'docs'
Requires-Dist: sphinx>=8.1.3; extra == 'docs'
Provides-Extra: gui
Requires-Dist: ctkmessagebox; extra == 'gui'
Requires-Dist: customtkinter; extra == 'gui'
Provides-Extra: release
Requires-Dist: python-semantic-release>=9.21.1; extra == 'release'
Provides-Extra: test
Requires-Dist: pytest-cov>=7.0.0; extra == 'test'
Requires-Dist: pytest-order>=1.3.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.6.1; extra == 'test'
Requires-Dist: pytest>=7.4.2; extra == 'test'
Provides-Extra: vis
Requires-Dist: beautifulsoup4; extra == 'vis'
Requires-Dist: bokeh; extra == 'vis'
Description-Content-Type: text/markdown

# ctdam

[![image](https://img.shields.io/badge/DAM-midnightblue)](https://www.allianz-meeresforschung.de/en)
[![image](https://img.shields.io/pypi/v/ctdam.svg)](https://pypi.python.org/pypi/ctdam)
[![image](https://img.shields.io/pypi/pyversions/ctdam.svg)](https://pypi.python.org/pypi/ctdam)
[![image](https://img.shields.io/badge/docs-darkorange?logo=readdotcv)](https://dam-ctd-software.github.io/ctdam)
[![image](https://img.shields.io/pypi/l/ctdam.svg)](https://pypi.python.org/pypi/ctdam)
[![image](https://zenodo.org/badge/DOI/10.5281/zenodo.19233531.svg)](https://doi.org/10.5281/zenodo.19233531)

**ctdam** is a Python package designed to standardize and simplify the parsing, processing, and visualization of **Conductivity-Temperature-Depth (CTD) data** from diverse file formats. By converting raw CTD data into a **CF-compliant xarray Dataset**, the package enables seamless integration with the scientific Python ecosystem, leveraging the power of **xarray accessors** for data handling, analysis, and plotting.

## **Key Features**

### **1. Multi-Format Support**

Parse CTD data from a variety of file formats (e.g., `.hex`, `.cnv`, `.TOB`, `.nc`) into a **consistent, CF-compliant xarray Dataset**. The package abstracts away format-specific quirks, so you can focus on the data.

### **2. CF-Compliant Structure**

Outputs are structured as **xarray Datasets** with:

- Standardized variable names (e.g., `temperature`, `salinity`, `pressure`).
- Metadata (units, long names, coordinates) following **CF (Climate and Forecast) conventions** (e.g. `sea_water_temperature`, `sea_water_practical_salinity`, `sea_water_pressure`).
- Automatic handling of coordinate systems (e.g., depth, scan, time).

### **3. xarray Accessors for CTD Data**

Extend xarray’s functionality with **custom accessors** for CTD-specific operations:

- **Processing**: Smoothing, binning, spike removal, or unit conversion. Using enhanced Sea-Bird processing logic for compatibility.
- **Plotting**: Quick visualization of profiles, sections, or maps using Matplotlib or bokeh.
- **Data Handling**: Subsetting, merging, or exporting to NetCDF/CSV.

### **4. Modular and Extensible**

- Add support for new file formats via pluggable parsers.
- Customize processing pipelines with built-in or user-defined functions.

---

## **Installation**

The ctdam python package is distributed via PyPi, that means that you
can install it inside your python environment using your favorite
package manager:

```bash
uv add ctdam
```

```bash
pip install ctdam
```

This installs only the functionalities. To use features like the CLI,
plotting or a GUI to edit processing workflow files, you need to install
ctdam with extra optional dependencies. That looks differently
dependending on installation type:

```bash
uv add ctdam --extra cli
```

```bash
poetry add ctdam[gui]
```

```bash
pip install ctdam[vis]
```

If you don\'t care about find-grained dependency management, you can
also just install all of them with the \'all\' group.

---

## **Usage Examples**

### **1. Parse a CTD File**

```python
from ctdam import read_ctd_data

# Parse a .hex file into an xarray Dataset
ds = read_ctd_data("sbs_data/hex/EMB356_11-1.hex")
```

This assumes that the corresponding sensor metadata file (.XMLCON) resides in the same directory as the .hex and is also using a similar name.

```python
from ctdam import read_ctd_data

# Parse a .cnv file into an xarray Dataset
ds = read_ctd_data("sbs_data/cnv/EMB356_11-1.cnv")

# Parse a .TOB file into an xarray Dataset
ds = read_ctd_data("sbs_data/other/IB051044.TOB")

# Parse a NetCDF file
ds = ctd.parse("path/to/ctd_data.nc")
```

You can also add bottle information to the existing data:

```python
ds = read_ctd_data("sbs_data/cnv/EMB295_14-1.cnv")
ds.add.bottles("sbs_data/btl/EMB295_14-1.bl")
btl_ds = ds.access.btl_info()
```

### **2. Access Data and Metadata**

```python
# Print the Dataset
print(ds)

# Access a variable (e.g., temperature)
temperature = ds["temperature"]

# Check metadata (CF-compliant)
print(ds["temperature"].attrs)
```

### **3. Use xarray Accessors**

```python
# Plot a temperature profile
ds.vis.profile("temperature")

# Bin data by depth
ds.proc.module("binavg", {"bin_size": 1})

# Or apply a full processing workflow
ds.proc.workflow(modules=["loop_removal", "wfilter", "alignctd", "celltm"])
```

Workflows can be defined in the form of .toml configuration files or as plain python dictionaries:

```python
processing_config = {
    "output_type": "cnv",
    "output_dir": ".",
    "modules": {
        "airpressure": {},
        "wildedit_geomar": {"std2": 7},
        "wfilter": {},
        "celltm": {},
        "alignctd": {"Oxygen": 3},
        "SA_from_SP_Baltic": {},
        "binavg": {},
    },
}
```

All processing module behaviour can be modified via key-values, as seen
for `wildedit_geomar` and `alignctd`. In the example
config you can also see, that the original Sea-Bird processing modules can
be mixed with custom ones (airpressure) and all gsw functions
(SA_from_SP_Baltic). Its also possible to use the original Sea-Bird processing binaries, as long as they are installed on your machine.

### **4. Export to NetCDF**

```python
ds.to_netcdf("processed_ctd_data.nc")
```

---

## **Supported File Formats**

| Format | Description           | Notes                        |
| ------ | --------------------- | ---------------------------- |
| `.hex` | Seabird HEX format    | Raw data                     |
| `.cnv` | Seabird CNV format    | Default for many CTD systems |
| `.nc`  | NetCDF                | CF-compliant or raw          |
| `.TOB` | Sea&Sun CTD format    | Small handheld-CTDs          |
| `.bl`  | Seabird bottle format | Bottle closing information   |

---

## **Contributing**

Contributions are welcome! To add support for a new file format or feature:

1. Fork the repository.
2. Implement your changes in a new branch.
3. Submit a pull request with tests and documentation.

Details can be found inside [Contributing](/CONTRIBUTING.md).

---

## Context

This software is developed for the [German Marine Research Alliance
(DAM)](https://www.allianz-meeresforschung.de/en) in the context of the [Underway Data: Marine Data - Research Vessels Project](https://www.allianz-meeresforschung.de/en/activities/data-management-and-digitalisation/underway-research-data). The converter and parser are tested
against a variety of data, acquired on different German research
vessels. Because of the ongoing efforts to harmonise these
infrastructures, the diversity of the test data may be smaller than
thought and your data may pose problems to converter, parser or
processing. Please feel free to contribute to this project in order to
develop a toolkit, that is as general as possible.

---
