wavespectra 4.4.0__tar.gz → 4.4.2__tar.gz

wavespectra-4.4.2/PKG-INFO

@@ -0,0 +1,399 @@
+Metadata-Version: 2.4
+Name: wavespectra
+Version: 4.4.2
+Summary: Library for ocean wave spectra
+Author-email: Wavespectra Developers <r.guedes@oceanum.science>
+Maintainer-email: Rafael Guedes <r.guedes@oceanum.science>, Tom Durrant <t.durrant@oceanum.science>
+License: Copyright (c) 2018 MetOcean Solutions Ltd
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Documentation, https://wavespectra.readthedocs.io/en/latest/
+Project-URL: Source, https://github.com/wavespectra/wavespectra
+Project-URL: Tracker, https://github.com/wavespectra/wavespectra/issues
+Project-URL: Changelog, https://github.com/wavespectra/wavespectra/blob/master/HISTORY.rst
+Keywords: wave,spectra,ocean,xarray,statistics,analysis
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+License-File: AUTHORS.rst
+Requires-Dist: click
+Requires-Dist: dask
+Requires-Dist: matplotlib
+Requires-Dist: python-dateutil
+Requires-Dist: pyyaml
+Requires-Dist: sortedcontainers
+Requires-Dist: scipy
+Requires-Dist: xarray
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: tox; extra == "test"
+Requires-Dist: ruff; extra == "test"
+Provides-Extra: extra
+Requires-Dist: fsspec; extra == "extra"
+Requires-Dist: gcsfs; extra == "extra"
+Requires-Dist: h5netcdf; extra == "extra"
+Requires-Dist: netCDF4; extra == "extra"
+Requires-Dist: zarr; extra == "extra"
+Provides-Extra: docs
+Requires-Dist: cmocean; extra == "docs"
+Requires-Dist: ipython; extra == "docs"
+Requires-Dist: pickleshare; extra == "docs"
+Requires-Dist: pydata_sphinx_theme; extra == "docs"
+Requires-Dist: sphinxcontrib-programoutput; extra == "docs"
+Requires-Dist: sphinx-book-theme; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-autobuild; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
+Requires-Dist: sphinx-gallery; extra == "docs"
+Dynamic: license-file
+
+===========
+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