API Reference

Submodules

ewdm.helpers module

ewdm.helpers.get_sampling_frequency(time: DataArray, precision: int = 3) → float[source]

Try to figure out the sampling frequency for a time coordinate.

Parameters:

time (xr.DataArray) – Time data array.
precision (int, optional) – Number of decimal places to round to.
3. (Defaults to)

Returns:

Estimated sampling frequency.

Return type:

float

ewdm.helpers.wavenumber(f: ndarray, d: float = 100) → ndarray[source]

Compute wavenumber according to Hunt approximation.

Parameters:

f (np.ndarray) – Frequency array.
d (float, optional) – Depth. Defaults to 100.

Returns:

Computed wavenumber array.

Return type:

np.ndarray

Raises:

ValueError – If depth is negative.

ewdm.main module

class ewdm.main.Arrays(dataset: Dataset, fs: float | None = None, interpolate: bool = True, max_nan_ratio: float = 0.1, max_time_gap: str = '10s', normalise: bool = True)[source]

Bases: _BaseClass

Perform EWDM for spatial arrays of surface eleavtion data.

Parameters:

dataset (xr.Dataset) – Dataset containing input data. Typical wave staff
at (measurements are characterised by sea surface elevation data)
elevation (different spatial location. ADCP along-beam echo-based surface)
convenction (can also be considered as a form of spatial arrays. The)
is (followed for variable names)
code-block: (..) –
python: <xarray.Dataset> Dimensions: (time: 4096, element: 6) Coordinates:
- time (time) float64
- element (element) int64 0 1 2 3 4 5
Data variables:
surface_elevation (time, element) float64 position_x (element) float64 position_y (element) float64

sampling_rate

4

Returns:

Dataset containing produced directional spectra and directional spreading function.

Return type:

xr.Dataset

array_geometry(dataset: Dataset) → ndarray[source]

Compute array of spatial differences for each point.

This method takes the dataset containing the position (x and y) of each element of the spatial array and calculate the position difference vector.

compute(omin: float = -5, omax: float | None = None, nvoice: float = 16, cross_wavelet: bool = False, solver: str = 'lstsq', rcond: float | None = None, dd: float = 5.0, kappa: float = 36.0, use: str = 'displacements', block_size: str = '30min') → Dataset[source]

Perform computation using specified parameters.

Parameters:

omin (float, optional) – Minimum octave (default is -5).
omax (float, optional) – Maximum octave. If None, it is automatically determined based sampling frequency. The final frequency array is logaritmically distributed from 2**omin to 2**omax.
nvoice (float, optional) – Number of voices for the computation (default is 16).
cross_wavelet (bool, optional) – Whether or not use cross-wavelet product to compute phase differences between array pairs. If False then arithmetic substraction is used (default).
solver (str, option) – Wavenumber solver method. Two options are available: 1 or ‘lstsq’ or ‘least-square’: Least-square solution of all possible pair. combination. 2 or ‘pairwise’ or ‘pair-wise’: Pair-wise solution and averaging…
rcond (float, optional) – If solver is lstsq this argument is passed to np.linalg.lstsq function. It is a cut-off ration for small singular values of matrix dphi.
dd (float, optional) – Directional resolution in degrees (default is 5 degrees).
kappa (float, optional) – Smoothness parameter for Kernel Density Estimation. Small values of kappa produce oversmooth results (default is 36.0).
use (str, optional) – Type of data to perform estimation. It should be should be either displacements, velocities or accelerations.” (default is “displacements”).
block_size (str) – If dataset contains more than one hour of data, split dataset into blocks of block_size and perform computation over each block. The resulting output will have a time dimension. It is advisable to choose values of no more than half-hour. Default block_size=”30min”.

Returns:

Dataset containing the directional spectrum, directional: distribution, and frequency spectrum.

Return type:

xr.Dataset

compute_angle(complex_data)[source]: Compute and wrap angle in radians from complex argument.

compute_wavenumbers(dx, dphi, solver='lstsq')[source]

Compute wavenumber vector from phase differences and distances.

This method take the point distances and the phase differences arrays and returns the wavenumber vector components and residuals.

estimate_directional_distribution(dataset) → Dataset[source]

Estimate the directional distribution of wave energy.

This method calculates the wavelet power and local wave direction using the local estimates of wavenumber vector and then estimates the directional distribution function and directional spectra.

Returns:

Dataset containing the directional spectrum, directional distribution, and frequency spectrum.

Return type:

xr.Dataset

Raises:

Exception – If use is not one of displacements, velocities,
accelerations –

classmethod from_numpy(time: ndarray, surface_elevation: ndarray, position_x: ndarray, position_y: ndarray, **kwargs)[source]

Create an instance of Arrays from numpy arrays.

Parameters:

time – Time array
surface_elevation – Surface elevation array. The size of this object should be consistent with the number of elements in the array.
position_x – Easting coordinate of array elements in metres
position_y – Northing coordinate of array elements in metres

phase_differences(coeffs: Dataset, cross_wavelet=False) → ndarray[source]: Compute array with phase differences between array pairs

wavelet_coefficients(dataset: Dataset) → Dataset[source]

Estimate wavelet coefficients

This method takes the dataset containing the sea surface elevation data at different elements of the array and returns the corresponding wavelet complex coefficients for each element.

class ewdm.main.Triplets(dataset: Dataset, fs: float | None = None, interpolate: bool = True, max_nan_ratio: float = 0.1, max_time_gap: str = '10s', normalise: bool = True)[source]

Bases: _BaseClass

Perform EWDM for triplet-based data such as wave buoys or ADCPs.

Parameters:

dataset (xr.Dataset) – Dataset containing input data. Users may have
example (different input variables depending on the kind of devide. For)

:param : :param Typical GPS buoys deliver horizontal displacements or velocities. Other: :param buoys only provide horizontal acceleration. ADPCs provide two: :param dimensional components of horizonal velocities and echo-based sea: :param surface elevation. Hence: :param the dataset should contain either: :param displacements: :param velocities or accelerations. Sea surface elevation should: :param be provided in all cases. The convention followed for variable names is:

<xarray.Dataset>
Dimensions:                 (time)
Coordinates:
  * time                    (time) datetime64[ns]
Data variables:
    eastward_displacement   (time) float32
    northward_displacement  (time) float32
    surface_elevation       (time) float32
    eastward_velocity       (time) float32
    northward_velocity      (time) float32
    eastward_acceleration   (time) float32
    northward_acceleration  (time) float32
    eastward_slope          (time) float32
    northward_slope         (time) float32
Attributes: (1/1)
    sampling_rate:           2.5

Returns:: Dataset containing produced directional spectra and directional spreading function.
Return type:: xr.Dataset

compute(omin: float = -5, omax: float | None = None, nvoice: float = 16, dd: float = 5.0, kappa: float = 36.0, use: str = 'displacements', block_size: str = '30min') → Dataset[source]

Perform computation using specified parameters.

Parameters:

omin (float, optional) – Minimum octave (default is -5).
omax (float, optional) – Maximum octave. If None, it is automatically determined based sampling frequency. The final frequency array is logaritmically distributed from 2**omin to 2**omax.
nvoice (float, optional) – Number of voices for the computation (default is 16).
dd (float, optional) – Directional resolution in degrees (default is 5 degrees).
kappa (float, optional) – Smoothness parameter for Kernel Density Estimation. Small values of kappa produce oversmooth results (default is 36.0).
use (str, optional) – Type of data to perform estimation. It should be should be either displacements, velocities or accelerations.” (default is “displacements”).
block_size (str) – If dataset contains more than one hour of data, split dataset into blocks of block_size and perform computation over each block. The resulting output will have a time dimension. It is advisable to choose values of no more than half-hour. Default block_size=”30min”.

Returns:

Dataset containing the directional spectrum, directional: distribution, and frequency spectrum.

Return type:

xr.Dataset

compute_accelerations()[source]: Compute acceleration componentes from velocities

compute_velocities()[source]: Compute velocity componentes from displacements

estimate_directional_distribution(dataset) → Dataset[source]

Estimate the directional distribution of wave energy.

This method calculates the wavelet power and local wave direction using the specified method (displacements, velocities, or accelerations) and then estimates the directional distribution function and directional spectra.

Returns:

Dataset containing the directional spectrum, directional distribution, and frequency spectrum.

Return type:

xr.Dataset

Raises:

Exception – If use is not one of displacements, velocities,
accelerations –

estimate_wavelet_power(dataset) → DataArray[source]

Estimate the wavelet power of the surface elevation data.

This method computes the continuous wavelet transform (CWT) of the surface elevation data in the dataset to estimate the wavelet power.

Returns:

The wavelet power of the surface elevation data.

Return type:

np.ndarray

Raises:

Exception – If the ‘surface_elevation’ data is not available
in the dataset. –

classmethod from_numpy(time: ndarray, surface_elevation: ndarray, eastward_displacement: ndarray | None = None, northward_displacement: ndarray | None = None, eastward_velocity: ndarray | None = None, northward_velocity: ndarray | None = None, eastward_acceleration: ndarray | None = None, northward_acceleration: ndarray | None = None, **kwargs)[source]

Create an instance of Triplets from numpy arrays.

Parameters:

time – time
surface_elevation – Surface elevation array
eastward_displacement – Eastward displacements
northward_displacement – Northward displacements
eastward_velocities – Eastward velocities
northward_velocities – Northward velocities
eastward_acceleration – Eastward accelerations
northward_acceleration – Northward accelerations
time – Time values.

theta_from_accelerations(dataset) → DataArray[source]

Compute local wave direction from wave accelerations.

This method calculates the local wave direction using the eastward and northward velocities along with the surface elevation from the dataset. This method is based on Peláez-Zapata et al (2024).

Returns:

Local wave direction in degrees.

Return type:

xr.DataArray

Raises:

Exception – If eastward_acceleration and northward_acceleration
are not available in the dataset. –

theta_from_displacements(dataset) → DataArray[source]

Compute local wave direction from wave displacements.

This method calculates the local wave direction using the eastward and northward displacements along with the surface elevation from the dataset. This method is based on Peláez-Zapata et al (2024).

Returns:

Local wave direction in degrees.

Return type:

xr.DataArray

Raises:

Exception – If eastward_displacement and northward_displacement
are not available in the dataset. –

theta_from_slopes(dataset)[source]

Compute local wave direction from wave slopes.

This method calculates the local wave direction using the eastward and northward slopes, also known as roll and pitch, respectively, along with the surface elevation from the dataset. This method is based on Krogstad et al. (2005).

Returns:

Local wave direction in degrees.

Return type:

xr.DataArray

Raises:

Exception – If eastward_slope and northward_slope
are not available in the dataset. –

theta_from_velocities(dataset) → DataArray[source]

Compute local wave direction from wave velocities.

This method calculates the local wave direction using the eastward and northward velocities along with the surface elevation from the dataset. This method is based on Peláez-Zapata et al (2024).

Returns:

Local wave direction in degrees.

Return type:

xr.DataArray

Raises:

Exception – If eastward_displacement and northward_displacement
are not available in the dataset. –

ewdm.parameters module

ewdm.plots module

ewdm.plots.plot_directional_spectrum(da: DataArray | ndarray, frqs: str | ndarray = 'frequency', dirs: str | ndarray = 'direction', ax=None, smooth=None, cmap=None, levels: int = 30, vmin: float | int | None = None, vmax: float | int | None = None, contours: float | int | None = None, colorbar: bool = False, wspd: float | int | None = None, wdir: float | int | None = None, wind_sea_radius: float | int | None = None, curspd: float | int | None = None, curdir: float | int | None = None, cbar_kw={}, axes_kw={}) → None[source]

Make a simple plot of a directional wave spectrum.

Parameters:

da – Directional spectrum data.
frqs – Frequency label name or numpy array.
dirs – Direction label name or numpy array.
ax (optional) – Matplotlib axis object.
smooth (tuple) – Smoothing factor for visualisation. Defaults to None.
cmap (optional) – Colormap for the plot. Defaults to None.
levels (int) – Number of contour levels. Defaults to 30. If None, pseudo-color plot is made.
vmin (int or float) – Minimum value for colormap.
vmax (int or float]) – Maximum value for colormap.
contours (int or float) – Specific contour levels to plot on top.
colorbar (bool) – Whether to display colorbar. Defaults to False.
wspd (int or float) – Wind speed value to draw arrow. Defaults to None.
wdir (int or float) – Wind direction value in cartesian convention.
wind_sea_radius (int or float) – Whether to display wind sea separation radius.
curspd (int or float) – Current speed value.
curdir (int or float) – Current direction value in cartesian convention.
cbar_kw (dict) – Additional arguments for colorbar.
axes_kw (dict) – Additional arguments for plot axes.

Returns:

fig, ax

ewdm.sources module

class ewdm.sources.CDIPDataSourceRealTime(station_id: str | int)[source]

Bases: object

Class to handle CDIP real-time buoy data

read_dataset(time_start: str | datetime64 | None = None, time_end: str | datetime64 | None = None) → Dataset[source]

Read dataset from a specified time range and location.

Parameters:

time_start (str or np.datetime64): Start time of the range to extract from the dataset. Format: ‘YYYY-MM-DD HH:MM:SS’.

time_end (str or np.datetime64): End time of the range to extract from the dataset. Format ‘YYYY-MM-DD HH:MM:SS’.

Returns: - ds (xr.Dataset): Dataset containing the extracted data.

class ewdm.sources.SpotterBuoysDataSource(fname: str = 'displacement.csv')[source]

Bases: object

Class to handle Spotter buoy data parsed from SD Card

read_dataset()[source]: Read raw data file and return xarray object.

ewdm.wavelets module

class ewdm.wavelets.Morlet(f0=6)[source]

Bases: object

Implements the Morlet wavelet class.

Note that the input parameters f and f0 are angular frequencies. f0 should be more than 0.8 for this function to be correct, its default value is f0 = 6.

Adapted from: @regeirk/pycwt

property coi: e-Folding Time as of Torrence and Compo (1998).

cone_of_influence(ntime, fs)[source]

Determines the cone-of-influence.

Note that it is returned as a function of time in Fourier periods. Uses triangualr Bartlett window with non-zero end-points.

property flambda: Fourier wavelength as of Torrence and Compo (1998).

psi(t)[source]: Morlet wavelet as described in Torrence and Compo (1998).

psi_ft(f)[source]: Fourier transform of the approximate Morlet wavelet.

property sup: Wavelet support defined by the e-Folding time.

ewdm.wavelets.cwt(data: ~numpy.ndarray | ~xarray.core.dataarray.DataArray, freqs: ~numpy.ndarray, fs: float | None = None, mother: ~ewdm.wavelets.Morlet = <ewdm.wavelets.Morlet object>, normalise: bool = False) → DataArray[source]

This function computes the continuous wavelet transform.

Parameters:

data (p.ndarray, xr.DataArray) – Input signal array.
freqs (np.ndarray) – Frequency array.
fs (float) – Sampling frequency. Default is 2 * freqs[-1].
mother (Morlet) – Mother wavelet class. Default is Morlet(6.).
normalise (bool) – Whether to normalise the signal variance.

Returns:

Continuous wavelet transform of the input signal.

Return type:

xr.DataArray

ewdm.wavelets.xwt(data_x: ~numpy.ndarray | list | ~xarray.core.dataarray.DataArray, data_y: ~numpy.ndarray | list | ~xarray.core.dataarray.DataArray, freqs: ~numpy.ndarray, fs: float | None = None, mother: ~ewdm.wavelets.Morlet = <ewdm.wavelets.Morlet object>) → DataArray[source]

This function compute the continuous wavelet transform

Parameters:

data_x (numpy.ndarray, list, xr.DataArray) – Input signal arrays.
data_y (numpy.ndarray, list, xr.DataArray) – Input signal arrays.
freqs (numpy.ndarray) – Frequencies
fs (float) – Sampling frequency. Default fs=1
mother – instance of Mother wavelet class. Default is Morlet(6.).

Returns:

Cross-wavelet coefficients

Return type:

Wxy

Module contents

Top-level package for ewdm