User Guide

SeaSenseLib provides a simple, unified API for oceanographic data processing. This guide shows you how to read, process, and visualize data from various oceanographic instruments. This guide covers the generalised API for working with the library.

  • For the legacy API, see the developers_guide.

  • For a complete walkthrough with examples, see the Demo Notebook.

  • For a examples loading different moored instrument formats, see the Mooring Demo Notebook.

  • For a list of supported formats and instruments, see Supported File Formats.

Quick Start

Basic Usage:

import seasenselib as ssl

# Read any supported format
dataset = ssl.read("your_data_file.cnv")

# Create plots
ssl.plot('ts-diagram', dataset, title="T-S Diagram")
ssl.plot('depth-profile', dataset, title="CTD Profile")

# Export data
ssl.write(dataset, 'output.nc')

Reading Data

SeaSenseLib automatically detects file formats and converts data to standardized xarray Datasets:

import seasenselib as ssl

# Automatic format detection
ctd_data = ssl.read("profile.cnv")           # SeaBird CTD
rbr_data = ssl.read("logger.rsk")            # RBR instruments
netcdf_data = ssl.read("data.nc")            # NetCDF files

# Explicit format specification (when needed)
nortek_data = ssl.read("current.dat",
                      file_format='nortek-ascii',
                      header_file="current.hdr")

Supported Formats:

  • SeaBird: CNV files from CTD casts and moorings

  • RBR: RSK native format and MATLAB exports

  • Nortek: Aquadopp current meter data

  • NetCDF: CF-compliant oceanographic data

  • CSV: Comma-separated sensor data

  • ADCP: MATLAB format current profiler data

For a complete list of format keys and usage examples, see Supported File Formats.

Creating Plots

Generate standard oceanographic visualizations with simple commands:

Temperature-Salinity Diagrams:

ssl.plot('ts-diagram', dataset, title="Station T-S Diagram")
ssl.plot('ts-diagram', dataset, output_file="ts_plot.png")

Vertical Profiles:

ssl.plot('depth-profile', dataset, title="CTD Cast")

Time Series:

# Single parameter
ssl.plot('time-series', dataset, parameters=['temperature'])

# Multiple parameters
ssl.plot('time-series', dataset,
         parameters=['temperature', 'salinity'],
         title="Mooring Data")

Exporting Data

Save processed data in various formats:

# NetCDF (recommended for oceanographic data)
ssl.write(dataset, 'processed_data.nc')

# CSV for spreadsheets
ssl.write(dataset, 'data_export.csv')

# Excel format
ssl.write(dataset, 'report.xlsx')

Data Processing

SeaSenseLib includes basic processing tools:

from seasenselib.processors import SubsetProcessor, StatisticsProcessor

# Extract data subsets
subset = SubsetProcessor(dataset)
shallow_data = subset.set_parameter_name('pressure').set_parameter_value_max(50).get_subset()

# Calculate statistics
stats = StatisticsProcessor(dataset, 'temperature')
temperature_stats = stats.get_all_statistics()
print(f"Mean temperature: {temperature_stats['mean']:.2f}°C")

Command Line Interface

Use SeaSenseLib from the command line for common workflows:

# Convert data formats
seasenselib convert -i input.cnv -o output.nc

# Show file information
seasenselib show -i data_file.cnv

# Create plots
seasenselib plot ts-diagram -i data.nc -o ts_diagram.png
seasenselib plot depth-profile -i data.nc -o profile.png
seasenselib plot time-series -i data.nc -p temperature

# List available formats
seasenselib list readers

Working with Different Instruments

CTD Profile Data (SeaBird):

# Read vertical cast data
ctd_cast = ssl.read("station001.cnv")
ssl.plot('depth-profile', ctd_cast, title="Station 001")
ssl.plot('ts-diagram', ctd_cast, title="Water Mass Analysis")

Moored Time Series (SeaBird MicroCAT):

# Read mooring data
mooring = ssl.read("microcat_series.cnv")
ssl.plot('time-series', mooring,
         parameters=['temperature', 'salinity'],
         title="Mooring Time Series")

RBR Temperature Loggers:

# Native RSK format
rbr_data = ssl.read("solo_logger.rsk")
ssl.plot('time-series', rbr_data, parameters=['temperature'])

# MATLAB export
rbr_matlab = ssl.read("rbr_export.mat", file_format='rbr-matlab')

Current Meter Data (Nortek):

# Requires both data and header files
current_data = ssl.read("aquadopp.dat",
                       file_format='nortek-ascii',
                       header_file="aquadopp.hdr")
ssl.plot('time-series', current_data,
         parameters=['east_velocity', 'north_velocity'])

Getting Help

For advanced usage, custom readers, or library extension, see the Developers Guide.