doc: update documentation for new functionality (#83)

Author: ali-cetin-4ss

docs/api_ref/index.rst

@@ -19,6 +19,7 @@ functions and methods.
     complex_to_polar
     CosineFullSpreading
     CosineHalfSpreading
+    DirectionalBinSpectrum
     DirectionalSpectrum
     Grid
     JONSWAP
@@ -33,6 +34,7 @@ functions and methods.
     rigid_transform_heave
     rigid_transform_surge
     rigid_transform_sway
+    WaveBinSpectrum
     WaveSpectrum
 
 

docs/user_guide/calculate_response.rst

@@ -109,8 +109,7 @@ and provides useful spectrum operations, such as:
     .. math::
         S_x(\omega, \theta) = H_x(\omega, \theta)H_x^{*}(\omega, \theta) S_{\zeta}(\omega, \theta)
 
-    To obtain the one-dimentional spectrum (which is what you would measure with
-    a sensor), you need to integrate over direction:
+    To obtain the one-dimentional spectrum, you need to integrate over direction:
 
     .. math::
         S_x(\omega) = \int S_x(\omega, \theta) d\theta

docs/user_guide/concepts_utils/directional_bin_spectrum.rst

@@ -0,0 +1,97 @@
+DirectionalBinSpectrum
+======================
+The :class:`~waveresponse.DirectionalBinSpectrum` class provides an interface for
+handling 2-D directional spectra. :class:`~waveresponse.DirectionalBinSpectrum`
+extends :class:`~waveresponse.Grid`, and contains spectrum density as a function
+of frequency, binned by direction.
+
+.. math::
+    \sum_{i=0}^n{S_i(\omega, \delta\left(\theta - \theta_i\right))}
+
+The :class:`~waveresponse.DirectionalBinSpectrum` is initialized with a frequency
+list (1-D array), a direction list (1-D array) and corresponding spectrum
+density values, binned by direction (2-D array).
+
+.. code-block:: python
+
+    import numpy as np
+    from waveresponse as wr
+
+
+    freq = np.linspace(0.0, 1.0, 50)
+    dirs = np.linspace(0.0, 360.0, endpoint=False)
+    vals = np.random.random((len(freq), len(dirs)))
+
+    spectrum = wr.DirectionalBinSpectrum(
+        freq,
+        dirs,
+        vals,
+        freq_hz=True,
+        degrees=True,
+        clockwise=False,
+        waves_coming_from=False,
+    )
+
+The :class:`~waveresponse.DirectionalBinSpectrum` class extends the :class:`~waveresponse.Grid`
+class with the following:
+
+Calculate the variance (i.e., integral) and standard deviation of the spectrum:
+
+.. code-block:: python
+
+    # Variance
+    var = spectrum.var()
+
+    # Standard deviation
+    std = spectrum.std()
+
+Integrate (or sum) over one of the axes to obtain a one-dimentional spectrum.
+You can specify whether to integrate over the frequency axis (``axis=0``), or
+sum over the direction axis (``axis=1``), by setting the appropriate `axis` parameter.
+
+.. code-block:: python
+
+    # "Non-directional" spectrum
+    spectrum_nondir = spectrum.spectrum1d(axis=1)
+
+    # Directional "histogram"
+    spectrum_dir = spectrum.spectrum1d(axis=0)
+
+Calculate spectral moments by calling the :meth:`~waveresponse.DirectionalBinSpectrum.moment`
+method with the desired order, `n`.
+
+.. code-block:: python
+
+    # Zeroth-order moment
+    m0 = spectrum.moment(0)
+
+    # First-order moment
+    m1 = spectrum.moment(1)
+
+    # Second-order moment
+    m2 = spectrum.moment(2)
+
+    # Etc.
+
+Calculate the mean zero-crossing period, Tz:
+
+.. code-block:: python
+
+    spectrum.tz
+
+Calculate extreme values using the :meth:`~waveresponse.DirectionalSpectrum.extreme`
+method. The method takes three arguments: the duration of the process (in seconds),
+the quantile, ``q``, and a boolean flag, ``absmax``, determining whether to compute absolute
+value extremes (or only consider the maxima (`default`)).
+
+.. code-block:: python
+
+    duration = 3 * 3600   # 3 hours
+
+    # Extreme maximum
+    mpm = spectrum.extreme(duration, q=0.37)   # most probable maximum (MPM)
+    q90 = spectrum.extreme(duration, q=0.90)   # 90-th quantile
+
+    # Extreme absolute value maximum (i.e., minima are taken into account)
+    mpm = spectrum.extreme(duration, q=0.37, absmax=True)   # most probable maximum (MPM)
+    q90 = spectrum.extreme(duration, q=0.90, absmax=True)   # 90-th quantile

docs/user_guide/concepts_utils/index.rst

@@ -11,5 +11,7 @@ This section will introduce concepts and utilites that are useful when working w
 
    grid
    rao
+   directional_bin_spectrum
    directional_spectrum
+   wave_bin_spectrum
    wave_spectrum

docs/user_guide/concepts_utils/wave_bin_spectrum.rst

@@ -0,0 +1,61 @@
+WaveBinSpectrum
+===============
+The :class:`~waveresponse.WaveBinSpectrum` class provides an interface for handling
+2-D directional wave spectra. :class:`~waveresponse.WaveSpectrum` extends
+:class:`~waveresponse.DirectionalBinSpectrum`, and contains spectrum density as a function
+of frequency, binned by direction.
+
+.. math::
+    \sum_{i=0}^n{S_{\zeta, i}(\omega, \delta\left(\theta - \theta_i\right))}
+
+The :class:`~waveresponse.WaveSpectrum` is initialized with a frequency
+list (1-D array), a direction list (1-D array) and corresponding spectrum
+density values, binned by direction (2-D array).
+
+.. code-block:: python
+
+    import numpy as np
+    import waveresponse as wr
+
+
+    freq = np.linspace(0.0, 1.0, 50)
+    dirs = np.linspace(0.0, 360.0, endpoint=False)
+    vals = np.random.random((len(freq), len(dirs)))
+
+    wave = wr.WaveBinSpectrum(
+        freq,
+        dirs,
+        vals,
+        freq_hz=True,
+        degrees=True,
+        clockwise=False,
+        waves_coming_from=False,
+    )
+
+
+The :class:`~waveresponse.WaveBinSpectrum` class extends the
+:class:`~waveresponse.DirectionalBinSpectrum` class with the following:
+
+Calculate the significant wave height, Hs:
+
+.. code-block:: python
+
+    wave.hs
+
+Calculate the wave peak period, Tp:
+
+.. code-block:: python
+
+    wave.tp
+
+Calculate the wave peak direction:
+
+.. code-block:: python
+
+    wave.dirp()
+
+Calculate the mean wave direction:
+
+.. code-block::
+
+    wave.dirm()

docs/user_guide/standardized_spectra.rst

@@ -338,3 +338,18 @@ according to:
 
 
 where :math:`s` is a spreading coefficient, and :math:`\Gamma` is the Gamma function.
+
+In addition, the spreading functions in ``waveresponse`` cand determine discrete
+direction bins with equal energy:
+
+.. code:: python
+
+    import waveresponse as wr
+
+
+    spread_fun = wr.CosineFullSpreading(s=2, degrees=True)
+    discrete_dirs = spread_fun.discrete_directions(5, direction_offset=0.0)
+
+
+which may be used to spread 1-D 'non-directional' wave spectrum into waves
+with equal energy.

src/waveresponse/_core.py

@@ -1833,7 +1833,7 @@ class DirectionalBinSpectrum(_SpectrumMixin, Grid):
     """
     Directional binned spectrum.
 
-    The ``DirectionalBinSpectrum`` class extends the :class:`~waveresponse.BinGrid`
+    The ``DirectionalBinSpectrum`` class extends the :class:`~waveresponse.Grid`
     class and represents a two-dimensional frequency/wave-direction grid. The spectrum values
     represent spectral density as a function of frequency, binned by direction.