ctdam
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:
uv add ctdam
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:
uv add ctdam --extra cli
poetry add ctdam[gui]
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
from ctdam import parse
# Parse a .hex file into an xarray Dataset
ds = parse("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.
from ctdam import parse
# Parse a .cnv file into an xarray Dataset
ds = parse("sbs_data/cnv/EMB356_11-1.cnv")
# Parse a .TOB file into an xarray Dataset
ds = parse("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:
ds = parse("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
# 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
# Plot a temperature profile
ds.vis.profile("temperature")
# Plot as interactive bokeh plot
ds.vis.bokeh()
# Bin data by depth
ds.proc.bin
# 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:
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
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:
- Fork the repository.
- Implement your changes in a new branch.
- Submit a pull request with tests and documentation.
Details can be found inside Contributing.
Context
This software is developed for the German Marine Research Alliance (DAM) in the context of the Underway Data: Marine Data - Research Vessels Project. 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.
1 maintainer
Metadata
1 maintainer
Release files for ctdam 2.14.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ctdam-2.14.0.tar.gz | 2.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ctdam-2.14.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.2 MB
Release files / ctdam-2.14.0.tar.gz
| Download URL | ctdam-2.14.0.tar.gz |
|---|---|
| Size | 2.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
866c3f610f84f5415914786b0d9ccccae579ebc558c813753cf58ea3e98f9342
|
|
BLAKE2b-256 checksum How to use checksums |
73a19206d5eaf350b9897f58cbcc1476a8208abd1b1e1f36d495469f5eb31ced
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logRelease files / ctdam-2.14.0-py3-none-any.whl
| Download URL | ctdam-2.14.0-py3-none-any.whl |
|---|---|
| Size | 126.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5c3277bb2cb6e8bb52ee4a39a2402703f6593e8fefe1b74912b168a2bf3503cc
|
|
BLAKE2b-256 checksum How to use checksums |
d997e57c7f77155a1be81465a1bfd706633b544dce127e3a8dbf7c27dfa3c722
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency log
