wavespectra 4.4.2

Library for ocean wave spectra

Python library for ocean wave spectral data analysis and processing

Wavespectra is a powerful, open-source Python library built on top of xarray for working with ocean wave spectral data. It provides comprehensive tools for reading, analysing, manipulating, and visualising wave spectra from various sources including numerical models and buoy observations.

Key Features

• Unified Data Model: Built on xarray with standardised conventions for wave spectral data

• Extensive I/O Support: Read/write 15+ formats including WW3, SWAN, ERA5, NDBC, and more

• Rich Analysis Tools: 60+ methods for wave parameter calculation and spectral transformations

• Spectral Partitioning: Separate wind sea and swell using multiple algorithms (PTM1-5, watershed, wave age)

• Spectral Construction: Create synthetic spectra using parametric forms (JONSWAP, TMA, Gaussian, Pierson-Moskowitz)

• Flexible Visualisation: Polar spectral plots with matplotlib integration

• High Performance: Leverages dask for efficient processing of large datasets

• Extensible: Plugin architecture for custom readers and analysis methods

Quick Start

Installation

Install from PyPI:

# Basic installation
$ pip install wavespectra

# Full installation with all optional dependencies
$ pip install wavespectra[extra]

Or from conda-forge:

$ conda install -c conda-forge wavespectra

Basic Usage

import xarray as xr
from wavespectra import read_swan

# Read wave spectra from various formats
dset = read_swan("spectra.swn")  # SWAN format
# dset = xr.open_dataset("era5.nc", engine="era5")  # ERA5 reanalysis
# dset = xr.open_dataset("ww3.nc", engine="ww3")    # WAVEWATCH III

# Calculate wave parameters
hs = dset.spec.hs()          # Significant wave height
tp = dset.spec.tp()          # Peak period
dm = dset.spec.dm()          # Mean direction
dspr = dset.spec.dspr()      # Directional spreading

# Multiple parameters at once
stats = dset.spec.stats(["hs", "tp", "dm", "dspr"])

# Spectral transformations
spectrum_1d = dset.spec.oned()                    # Convert to 1D
subset = dset.spec.split(fmin=0.05, fmax=0.5)     # Frequency subset
rotated = dset.spec.rotate(angle=15)              # Rotate directions
interpolated = dset.spec.interp(freq=new_freq)    # Interpolate

# Visualisation
dset.spec.plot(kind="contourf", figsize=(8, 6))   # Polar plot

Working with Different Data Sources

# Numerical model outputs
ww3_data = xr.open_dataset("ww3_output.nc", engine="ww3")
swan_data = read_swan("swan_output.swn")
era5_data = xr.open_dataset("era5_waves.nc", engine="era5")

# Buoy observations
ndbc_data = xr.open_dataset("ndbc_data.nc", engine="ndbc")
triaxys_data = xr.open_dataset("triaxys.nc", engine="triaxys")

# All use the same analysis interface
for dataset in [ww3_data, swan_data, era5_data]:
    hs = dataset.spec.hs()
    tp = dataset.spec.tp()

Advanced Analysis

Spectral Partitioning

Separate spectra into wind sea and swell components using various methods:

# PTM1: Watershed partitioning with wind sea identification
partitions = dset.spec.partition.ptm1(
    wspd=dset.wspd, wdir=dset.wdir, dpt=dset.dpt, swells=2
)

# PTM3: Simple ordering by wave height (no wind/depth needed)
partitions = dset.spec.partition.ptm3(parts=3)

# PTM4: Wave age criterion to separate wind sea from swell
partitions = dset.spec.partition.ptm4(
    wspd=dset.wspd, wdir=dset.wdir, dpt=dset.dpt, agefac=1.7
)

# PTM1_TRACK: Track partitions from unique wave systems over time
# Useful for following the evolution of individual swell events
partitions = dset.spec.partition.ptm1_track(
    wspd=dset.wspd, wdir=dset.wdir, dpt=dset.dpt, swells=2
)

Spectral Construction

Create synthetic spectra from parametric forms:

from wavespectra.construct.frequency import jonswap, tma, gaussian
from wavespectra.construct.direction import cartwright
from wavespectra.construct import construct_partition

# Create JONSWAP spectrum for developing seas
freq = np.arange(0.03, 0.4, 0.01)
spectrum = jonswap(freq=freq, hs=2.5, fp=0.1, gamma=3.3)

# Create TMA spectrum for finite depth
spectrum_shallow = tma(freq=freq, hs=2.0, fp=0.1, dep=15)

# Create 2D spectrum by combining frequency and directional components
dir = np.arange(0, 360, 10)
spectrum_2d = jonswap(freq=freq, hs=2.5, fp=0.1) * cartwright(dir=dir, dm=270, dspr=30)

# Or use construct_partition for a complete 2D spectrum
spectrum_2d = construct_partition(
    freq_name="jonswap",
    dir_name="cartwright",
    freq_kwargs={"freq": freq, "hs": 2.5, "fp": 0.1, "gamma": 3.3},
    dir_kwargs={"dir": dir, "dm": 270, "dspr": 30}
)

Spectral Fitting

# Fit parametric forms to existing spectra
jonswap_params = dset.spec.fit_jonswap()          # Fit JONSWAP spectrum

Wave Physics

# Calculate wave physics parameters
celerity = dset.spec.celerity(depth=50)           # Wave speed
wavelength = dset.spec.wavelen(depth=50)          # Wavelength
stokes_drift = dset.spec.uss()                    # Stokes drift

Data Requirements

Wavespectra expects xarray objects with specific coordinate and variable naming:

Required coordinates:

• freq: Wave frequency in Hz

• dir: Wave direction in degrees (for 2D spectra)

Required variables:

• efth: Wave energy density in m²/Hz/degree (2D) or m²/Hz (1D)

Optional variables:

• wspd: Wind speed in m/s

• wdir: Wind direction in degrees

• dpt: Water depth in metres

Supported Formats

Input and Output Formats

• Wave Models: WAVEWATCH III, SWAN, WWM, FUNWAVE, OrcaFlex

• Reanalysis: ERA5, ERA-Interim, ECMWF

• Observations: NDBC, TRIAXYS, Spotter, Octopus, AWAC

• Generic: NetCDF, JSON, CSV

Documentation

Full documentation is available at wavespectra.readthedocs.io

• Installation Guide

• Quick Start Tutorial

• Spectral Construction

• API Reference

• Example Gallery

Development

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Installation

$ git clone https://github.com/wavespectra/wavespectra.git
$ cd wavespectra
$ pip install -e .[extra,test,docs]

Running Tests

$ pytest tests

Building Documentation

$ make docs

Citation

If you use wavespectra in your research, please cite:

@software{wavespectra,
  author = {Guedes, Rafael and Durrant, Tom and de Bruin, Ruben and Perez, Jorge and Iannucci, Matthew and Delaux, Sebastien and Harrington, John and others},
  title = {wavespectra: Python library for ocean wave spectral data},
  url = {https://github.com/wavespectra/wavespectra},
  doi = {10.5281/zenodo.15238968}
}

Licence

This project is licenced under the MIT Licence - see the LICENSE file for details.

Support

• Documentation: wavespectra.readthedocs.io

• Issues: GitHub Issues

• Discussions: GitHub Discussions