DIWASP-Python

DIrectional WAve SPectrum analysis - Python port of the DIWASP Matlab toolbox

DIWASP is a comprehensive toolbox for estimating directional wave spectra from measurements of water surface elevation, pressure, velocity, or acceleration. This Python implementation provides a modern, user-friendly interface built on top of industry-standard scientific Python libraries.

Features

• Multiple estimation methods: DFTM, EMLM, IMLM, EMEP, and BDM
• Flexible input formats: pandas DataFrame or xarray Dataset
• Seamless integration with wavespectra for advanced wave analysis
• Windowed analysis: Process continuous time series with configurable window length and overlap
• Multiple sensor types: Pressure, velocity, acceleration, surface elevation, and more
• Array configurations: Support for single sensors or multi-sensor arrays
• Modern output: Returns wavespectra-compatible xarray Datasets with comprehensive metadata

Quick Start

Installation

pip install diwasp

Basic Usage

import pandas as pd
from diwasp import diwasp

# Load your wave data (pressure and velocity measurements)
df = pd.read_csv('wave_data.csv', index_col='time', parse_dates=True)

# Run directional wave analysis
result = diwasp(
    df,
    sensor_mapping={
        'pressure': 'pres',      # Map column names to sensor types
        'u_velocity': 'velx',
        'v_velocity': 'vely',
    },
    window_length=1800,          # 30-minute analysis windows
    window_overlap=900,           # 15-minute overlap
    depth=15.0,                  # Water depth in meters
    z=0.5,                       # Sensor height above seabed
    method='imlm',               # Iterative Maximum Likelihood Method
)

# Access wave statistics
print(f"Significant wave height: {result.hsig.values} m")
print(f"Peak period: {result.tp.values} s")
print(f"Peak direction: {result.dp.values} degrees")

# Save results
result.to_netcdf('wave_spectra.nc')

Estimation Methods

Supported Sensor Types

• Surface elevation (elev)
• Pressure (pres)
• Velocity components (velx, vely, velz, vels)
• Acceleration components (accx, accy, accz, accs)
• Surface slopes (slpx, slpy)
• Displacement (dspx, dspy)

Output Format

The function returns a wavespectra-compatible xarray Dataset containing:

Dimensions:

• time: Center time of each analysis window
• freq: Frequency bins (Hz)
• dir: Direction bins (degrees, nautical convention)

Variables:

• efth: Spectral energy density (m²/Hz/degree)
• hsig: Significant wave height (m)
• tp: Peak period (s)
• fp: Peak frequency (Hz)
• dp: Peak direction (degrees)
• dm: Mean direction (degrees)
• spread: Directional spread (degrees)

Examples

Pressure-Velocity-Velocity (PUV) Sensor

from diwasp import diwasp
import pandas as pd

# Load data
df = pd.read_csv('puv_data.csv', index_col='time', parse_dates=True)

# Analyze
result = diwasp(
    df,
    sensor_mapping={'p': 'pres', 'u': 'velx', 'v': 'vely'},
    window_length=1800,
    window_overlap=900,
    depth=20.0,
    z=0.5,
    method='imlm',
)

# Plot time series
result['hsig'].plot()

Pressure Gauge Array

# Multiple pressure sensors in triangular configuration
result = diwasp(
    df,
    sensor_mapping={'p1': 'pres', 'p2': 'pres', 'p3': 'pres'},
    window_length=1800,
    window_overlap=900,
    depth=10.0,
    x={'p1': 0, 'p2': 5, 'p3': -5},
    y={'p1': 0, 'p2': 5, 'p3': 5},
    z=0.0,
    method='emep',
)

Using xarray Dataset

import xarray as xr

ds = xr.Dataset({
    'pres': (['time'], pressure_data),
    'velx': (['time'], u_data),
    'vely': (['time'], v_data),
}, coords={
    'time': time_values,
})

result = diwasp(
    ds,
    sensor_mapping={'pres': 'pres', 'velx': 'velx', 'vely': 'vely'},
    window_length=1800,
    window_overlap=900,
    depth=15.0,
)

Documentation

Full documentation is available at https://wavespectra.github.io/diwasp-python

• Installation Guide
• High-Level Wrapper Function
• Estimation Methods
• Data Structures
• API Reference

Requirements

• Python >= 3.9
• numpy >= 1.20
• scipy >= 1.7
• xarray >= 0.19
• wavespectra >= 4.0
• pandas >= 1.3

Development

Install for Development

git clone https://github.com/wavespectra/diwasp-python.git
cd diwasp-python
pip install -e ".[dev]"

Run Tests

pytest

Code Formatting

black diwasp tests
ruff check diwasp tests

Citation

If you use DIWASP in your research, please cite the original DIWASP toolbox:

Johnson, D. (2002). DIWASP, a directional wave spectra toolbox for MATLAB: User Manual. Research Report WP-1601-DJ (V1.1), Centre for Water Research, University of Western Australia.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

• Original DIWASP Matlab toolbox: David Johnson, University of Western Australia
• Python port: Developed with support from the oceanographic community
• Built on wavespectra, xarray, and pandas

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related Projects

• wavespectra - Wave spectra analysis library
• Original DIWASP (Matlab) - The original Matlab implementation