wavespectra

Library for ocean wave spectra

https://github.com/wavespectra/wavespectra

Keywords

Keywords from Contributors

Repository

Library for ocean wave spectra

README.rst

wavespectra
===========
Python library for ocean wave spectra.

.. image:: https://zenodo.org/badge/205463939.svg
   :target: https://zenodo.org/badge/latestdoi/205463939
.. image:: https://img.shields.io/github/actions/workflow/status/wavespectra/wavespectra/python-publish.yml
    :target: https://github.com/wavespectra/wavespectra/actions
    :alt: GitHub Workflow Status (with event)
.. image:: https://coveralls.io/repos/github/wavespectra/wavespectra/badge.svg?branch=master
    :target: https://coveralls.io/github/wavespectra/wavespectra?branch=master
.. image:: https://readthedocs.org/projects/wavespectra/badge/?version=latest
    :target: https://wavespectra.readthedocs.io/en/latest/
.. image:: https://img.shields.io/pypi/v/wavespectra.svg
    :target: https://pypi.org/project/wavespectra/
.. image:: https://img.shields.io/pypi/dm/wavespectra
    :target: https://pypistats.org/packages/wavespectra
    :alt: PyPI - Downloads
.. image:: https://anaconda.org/conda-forge/wavespectra/badges/version.svg
    :target: https://anaconda.org/conda-forge/wavespectra
.. image:: https://anaconda.org/conda-forge/wavespectra/badges/platforms.svg
    :target: https://anaconda.org/conda-forge/wavespectra
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/python/black
.. image:: https://img.shields.io/pypi/pyversions/wavespectra
    :target: https://pypi.org/project/wavespectra/
    :alt: PyPI - Python Version

Main contents:
--------------
* SpecArray_: extends xarray's `DataArray`_ with methods to manipulate wave spectra and calculate spectral statistics.
* SpecDataset_: wrapper around `SpecArray`_ with methods for selecting and saving spectra in different formats.

Documentation:
--------------
The documentation is hosted on ReadTheDocs at https://wavespectra.readthedocs.io/en/latest/.

Install:
--------
Where to get it
~~~~~~~~~~~~~~~
The source code is currently hosted on GitHub at: https://github.com/wavespectra/wavespectra

Binary installers for the latest released version are available at the `Python package index`_.

Install from pypi
~~~~~~~~~~~~~~~~~
.. code:: bash

   # Default install, miss some dependencies and functionality
   pip install wavespectra

   # Complete install
   pip install wavespectra[extra]

Install from conda
~~~~~~~~~~~~~~~~~~~
.. code:: bash

    # wavespectra is available in the conda-forge channel
    conda install -c conda-forge wavespectra

Install from sources
~~~~~~~~~~~~~~~~~~~~
Install requirements. Navigate to the base root of wavespectra_ and execute:

.. code:: bash

   # Default install, miss some dependencies and functionality
   pip install -r requirements/default.txt

   # Also, for complete install
   pip install -r requirements/extra.txt

Then install wavespectra:

.. code:: bash

   python setup.py install

   # Run pytest integration
   python setup.py test

Alternatively, to install in `development mode`_:

.. code:: bash

   pip install -e .

Code structure:
---------------
The two main classes SpecArray_ and SpecDataset_ are defined as `xarray accessors`_. The accessors are registered on xarray's DataArray_ and Dataset_ respectively as a new namespace called `spec`.

To use methods in the accessor classes simply import the classes into your code and they will be available to your xarray.Dataset or xarray.DataArray instances through the `spec` attribute, e.g.

.. code:: python

   import datetime
   import numpy as np
   import xarray as xr

   from wavespectra.specarray import SpecArray
   from wavespectra.specdataset import SpecDataset

   coords = {'time': [datetime.datetime(2017,01,n+1) for n in range(2)],
             'freq': [0.05,0.1],
             'dir': np.arange(0,360,120)}
   efth = xr.DataArray(data=np.random.rand(2,2,3),
                       coords=coords,
                       dims=('time','freq', 'dir'),
                       name='efth')

   In [1]: efth
   Out[1]:
   
   array([[[ 0.100607,  0.328229,  0.332708],
           [ 0.532   ,  0.665938,  0.177731]],

          [[ 0.469371,  0.002963,  0.627179],
           [ 0.004523,  0.682717,  0.09766 ]]])
   Coordinates:
     * freq     (freq) float64 0.05 0.1
     * dir      (dir) int64 0 120 240
     * time     (time) datetime64[ns] 2017-01-01 2017-01-02

   In [2]: efth.spec
   Out[2]:
   
   array([[[ 0.100607,  0.328229,  0.332708],
           [ 0.532   ,  0.665938,  0.177731]],

          [[ 0.469371,  0.002963,  0.627179],
           [ 0.004523,  0.682717,  0.09766 ]]])
   Coordinates:
     * freq     (freq) float64 0.05 0.1
     * dir      (dir) int64 0 120 240
     * time     (time) datetime64[ns] 2017-01-01 2017-01-02

   In [3]: efth.spec.hs()
   Out[3]:
   
   array([ 10.128485,   9.510618])
   Coordinates:
     * time     (time) datetime64[ns] 2017-01-01 2017-01-02
   Attributes:
       standard_name: sea_surface_wave_significant_height
       units: m

SpecDataset provides a wrapper around the methods in SpecArray. For instance, these produce same result:

.. code:: python

   In [4]: dset = efth.to_dataset(name='efth')

   In [5]: tm01 = dset.spec.tm01()

   In [6]: tm01.identical(dset.efth.spec.tm01())
   Out[6]: True

Data requirements:
------------------

SpecArray_ methods require DataArray_ to have the following attributes:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- wave frequency coordinate in `Hz` named as `freq` (required).
- wave frequency coordinate in `Hz` named as `freq` (required).
- wave direction coordinate in `degree` (coming from) named as `dir` (optional for 1D, required for 2D spectra).
- wave energy density data in `m2/Hz/degree` (2D) or `m2/Hz` (1D) named as `efth`

SpecDataset_ methods require xarray's Dataset_ to have the following attributes:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- spectra DataArray named as `efth`, complying with the above specifications

Examples:
---------

Define and plot spectra history from example SWAN_ spectra file:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

   from wavespectra import read_swan

   dset = read_swan('/source/wavespectra/tests/manus.spec')
   spec_hist = dset.isel(lat=0, lon=0).sel(freq=slice(0.05,0.2)).spec.oned().T
   spec_hist.plot.contourf(levels=10)

.. _SpecArray: https://github.com/wavespectra/wavespectra/blob/master/wavespectra/specarray.py
.. _SpecDataset: https://github.com/wavespectra/wavespectra/blob/master/wavespectra/specdataset.py
.. _DataArray: http://xarray.pydata.org/en/stable/generated/xarray.DataArray.html
.. _Dataset: http://xarray.pydata.org/en/stable/generated/xarray.Dataset.html
.. _readspec: https://github.com/wavespectra/wavespectra/blob/master/wavespectra/readspec.py
.. _xarray accessors: http://xarray.pydata.org/en/stable/internals.html?highlight=accessor
.. _SWAN: http://swanmodel.sourceforge.net/online_doc/swanuse/node50.html
.. _Python package index: https://pypi.python.org/pypi/wavespectra
.. _wavespectra: https://github.com/wavespectra/wavespectra
.. _development mode: https://pip.pypa.io/en/latest/reference/pip_install/#editable-installs

Owner

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 6 months ago

Packages