wavespectra

An open source project for working with ocean wave spectral data.
https://github.com/wavespectra/wavespectra

Category: Hydrosphere
Sub Category: Waves and Currents

Keywords

ocean python spectra statistics wave xarray

Keywords from Contributors

mesh vtk

Last synced: about 11 hours ago
JSON representation

Repository metadata

Library for ocean wave spectra

• Host: GitHub
• URL: https://github.com/wavespectra/wavespectra
• Owner: wavespectra
• License: mit
• Created: 2019-08-30T22:19:36.000Z (over 6 years ago)
• Default Branch: main
• Last Pushed: 2025-10-30T19:51:43.000Z (about 2 months ago)
• Last Synced: 2025-12-08T21:57:19.428Z (17 days ago)
• Topics: ocean, python, spectra, statistics, wave, xarray
• Language: Python
• Homepage: https://wavespectra.readthedocs.io/en/latest/
• Size: 4.21 MB
• Stars: 89
• Watchers: 12
• Forks: 35
• Open Issues: 5
• Releases: 23
• Metadata Files:
  • Readme: README.rst
  • Changelog: HISTORY.rst
  • Contributing: CONTRIBUTING.rst
  • License: LICENSE.txt
  • Code of conduct: CODE_OF_CONDUCT.md
  • Support: docs/support.rst
  • Authors: AUTHORS.rst

README.rst

          ===========
wavespectra
===========

.. image:: https://deepwiki.com/badge.svg
   :target: https://deepwiki.com/wavespectra/wavespectra
   :alt: Ask DeepWiki

.. image:: https://zenodo.org/badge/205463939.svg
   :target: https://zenodo.org/badge/latestdoi/205463939
   :alt: DOI

.. image:: https://img.shields.io/github/actions/workflow/status/wavespectra/wavespectra/python-publish.yml
   :target: https://github.com/wavespectra/wavespectra/actions
   :alt: Build Status

.. image:: https://coveralls.io/repos/github/wavespectra/wavespectra/badge.svg?branch=master
   :target: https://coveralls.io/github/wavespectra/wavespectra?branch=master
   :alt: Coverage

.. image:: https://readthedocs.org/projects/wavespectra/badge/?version=latest
   :target: https://wavespectra.readthedocs.io/en/latest/
   :alt: Documentation

.. image:: https://img.shields.io/pypi/v/wavespectra.svg
   :target: https://pypi.org/project/wavespectra/
   :alt: PyPI

.. image:: https://img.shields.io/pypi/dm/wavespectra
   :target: https://pypistats.org/packages/wavespectra
   :alt: Downloads

.. image:: https://anaconda.org/conda-forge/wavespectra/badges/version.svg
   :target: https://anaconda.org/conda-forge/wavespectra
   :alt: Conda

.. image:: https://img.shields.io/pypi/pyversions/wavespectra
   :target: https://pypi.org/project/wavespectra/
   :alt: Python

**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.

.. _xarray: https://xarray.pydata.org/

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:

.. code-block:: console

   # Basic installation
   $ pip install wavespectra

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

Or from conda-forge:

.. code-block:: console

   $ conda install -c conda-forge wavespectra

Basic Usage
-----------

.. code-block:: python

   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
-----------------------------------

.. code-block:: python

   # 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:

.. code-block:: python

   # 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:

.. code-block:: python

   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
~~~~~~~~~~~~~~~~

.. code-block:: python

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

Wave Physics
~~~~~~~~~~~~

.. code-block:: python

   # 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`_

.. _wavespectra.readthedocs.io: https://wavespectra.readthedocs.io/en/latest/
.. _Installation Guide: https://wavespectra.readthedocs.io/en/latest/install.html
.. _Quick Start Tutorial: https://wavespectra.readthedocs.io/en/latest/quickstart.html
.. _Spectral Construction: https://wavespectra.readthedocs.io/en/latest/construction.html
.. _API Reference: https://wavespectra.readthedocs.io/en/latest/api.html
.. _Example Gallery: https://wavespectra.readthedocs.io/en/latest/gallery.html

Development
===========

Contributing
------------

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

.. _Contributing Guide: https://wavespectra.readthedocs.io/en/latest/contributing.html

Development Installation
------------------------

.. code-block:: console

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

Running Tests
-------------

.. code-block:: console

   $ pytest tests

Building Documentation
----------------------

.. code-block:: console

   $ make docs

Citation
========

If you use wavespectra in your research, please cite:

.. code-block:: bibtex

   @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.

.. _LICENSE: LICENSE.txt

Support
=======

- **Documentation**: `wavespectra.readthedocs.io`_
- **Issues**: `GitHub Issues`_
- **Discussions**: `GitHub Discussions`_

.. _GitHub Issues: https://github.com/wavespectra/wavespectra/issues
.. _GitHub Discussions: https://github.com/wavespectra/wavespectra/discussions

        

---

Owner metadata

• Name: Wavespectra
• Login: wavespectra
• Email:
• Kind: organization
• Description: Libraries for ocean wave spectra
• Website:
• Location:
• Twitter:
• Company:
• Icon url: https://avatars.githubusercontent.com/u/54727176?v=4
• Repositories: 1
• Last ynced at: 2023-03-05T17:57:21.085Z
• Profile URL: https://github.com/wavespectra

---

GitHub Events

Total

• Create event: 11
• Issues event: 11
• Release event: 6
• Watch event: 12
• Delete event: 8
• Issue comment event: 35
• Push event: 27
• Pull request review event: 2
• Pull request review comment event: 2
• Pull request event: 7
• Fork event: 4

Last Year

• Create event: 9
• Release event: 5
• Issues event: 11
• Watch event: 11
• Delete event: 8
• Issue comment event: 22
• Push event: 18
• Pull request event: 5
• Fork event: 4

---

Committers metadata

Last synced: 6 days ago

Name	Email	Commits
Rafael Guedes	r****s@o****e	1370
Tom Durrant	t****t@g****m	34
Ruben de Bruin	3****n	29
metocean-jorge.perez	j****z@m****z	24
d.johnson@metocean.co.nz	d****n@m****z	18
Matthew Iannucci	m****i@g****m	17
Sebastien Delaux	s****x@o****e	11
John Harrington	j****n@j****m	7
Ryan Coe	r****e@s****v	6
Paul Branson	p****n@c****u	6
Dave	d****n@o****e	4
Henrique Rapizo	h****o@m****z	2
dependabot[bot]	4****]	2
Ruben de Bruin	r****n@h****m	2
Murex93	s****n@l****a	1
Spicer Bak	8****F	1
cmichelenstrofer	c****l@s****v	1
gregchalmers	g****s@m****z	1
Color Code	c****e@l****m	1
lubyant	b****8@w****u	1

Committer domains:

• metocean.co.nz: 4
• oceanum.science: 3
• sandia.gov: 2
• wisc.edu: 1
• live.ca: 1
• hmc-heerema.com: 1
• csiro.au: 1
• johnch.com: 1

---

Issue and Pull Request metadata

Last synced: about 1 month ago

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/wavespectra/wavespectra

---

---

---

Package metadata

• Total packages: 3
• Total downloads:
  • pypi: 5,733 last-month
• Total docker downloads: 122
• Total dependent packages: 3 (may contain duplicates)
• Total dependent repositories: 6 (may contain duplicates)
• Total versions: 105
• Total maintainers: 1

---

Dependencies

Score: 16.21595530536139