API documentation

General description of modules, objects and functions in wavespectra.

Wavespectra accessors

SpecArray

Extends DataArray with methods to deal with wave spectra.

SpecDataset

Extends xarray's Dataset to deal with wave spectra datasets.

* The two accessors are attached to the respective xarray objects via the spec namespace.

SpecArray

All methods in SpecArray accessor are also available from SpecDataset.

Integrated spectral parameters

SpecArray.hs

Spectral significant wave height Hm0.

SpecArray.hmax

Maximum wave height Hmax.

SpecArray.tp

Peak wave period Tp.

SpecArray.tm01

Mean absolute wave period Tm01.

SpecArray.tm02

Mean absolute wave period Tm02.

SpecArray.dpm

Peak wave direction Dpm.

SpecArray.dp

Peak wave direction Dp.

SpecArray.dm

Mean wave direction from the 1st spectral moment Dm.

SpecArray.dspr

Directional wave spreading Dspr.

SpecArray.swe

Spectral width parameter by Cartwright and Longuet-Higgins (1956).

SpecArray.sw

Spectral width parameter by Longuet-Higgins (1975).

Spectral partitioning

SpecArray.split

Split spectra over freq and/or dir dims.

SpecArray.partition

Partition wave spectra using Hanson's watershed algorithm.

Other methods

SpecArray.momf

Calculate given frequency moment.

SpecArray.momd

Calculate given directional moment.

SpecArray.wavelen

Wavelength L from frequency coords.

SpecArray.celerity

Wave celerity C from frequency coords.

SpecArray.stats

Calculate multiple spectral stats into a Dataset.

SpecArray.plot

Plot spectra in polar axis.

SpecArray.scale_by_hs

Scale spectra using expression based on Significant Wave Height hs.

SpecArray.oned

Returns the one-dimensional frequency spectra.

SpecArray.to_energy

Convert from energy density (m2/Hz/degree) into wave energy spectra (m2).

SpecArray.interp

Interpolate onto new spectral basis.

SpecArray.interp_like

Interpolate onto coordinates from other spectra.

SpecDataset

SpecDataset.sel

Select stations near or at locations defined by (lons, lats) vector.

Output methods described in the Output functions section: to_swan to_netcdf to_octopus to_ww3 to_json

Input functions

NetCDF-based input functions

read_ww3

Read Spectra from WAVEWATCHIII native netCDF format.

read_ncswan

Read Spectra from SWAN native netCDF format.

read_wwm

Read Spectra from WWMII native netCDF format.

read_netcdf

Read Spectra from generic netCDF format.

read_era5

Read Spectra from ECMWF ERA5 netCDF format.

* These functions also support Zarr files

Other input functions

read_swan

Read Spectra from SWAN ASCII file.

read_triaxys

Read spectra from TRIAXYS wave buoy ASCII files.

read_spotter

Read Spectra from spotter JSON file.

read_octopus

Read spectra from Octopus file format.

read_dataset

Format and attach SpecArray accessor to an existing xarray dataset.

read_ndbc

Read spectra from NDBC wave buoy ASCII files.

read_json

Read Spectra from json.

Convenience SWAN ASCII input functions

input.swan.read_swans

Read multiple SWAN ASCII files into single Dataset.

input.swan.read_hotswan

Read partial SWAN hotfiles into single gridded hotfile Dataset.

input.swan.read_swanow

Read SWAN nowcast from fileglob, keep overlapping dates from most recent files.

Output functions

SpecDataset.to_swan

Write spectra in SWAN ASCII format.

SpecDataset.to_netcdf

Write spectra in netCDF format using wavespectra conventions.

SpecDataset.to_octopus

Save spectra in Octopus format.

SpecDataset.to_ww3

Save spectra in native WW3 netCDF format.

SpecDataset.to_json

Write spectra in json format.

Spectral reconstruction

Spectral reconstruction functionality is under development. There are functions available to fit parametric spectrum shapes from wave partitions but the construct api is not properly established.

construct.jonswap

Constructs JONSWAP spectra.

construct.ochihubble

Construct OCHIHUBBLE spectra.

construct.helpers.spread

Generic spreading function.

construct.helpers.arrange_inputs

Check all inputs are same shape and add frequency and direction dims.

construct.helpers.make_dataset

Package spectral matrix to xarray.

construct.helpers.check_coordinates

Check coordinates are consistent with parameter.

Internal core functions and objects

watershed module

core.watershed.partition

Watershed partitioning.

core.watershed.nppart

Watershed partition on a numpy array.

core.watershed.hs

Significant wave height Hmo.

core.watershed.frequency_resolution

Frequency resolution array.

core.watershed.inflection

Points of inflection in smoothed frequency spectra.

attributes module

core.attributes.set_spec_attributes

Standarise CF attributes in specarray variables

core.attributes.attrs

npstats

core.npstats.hs

Significant wave height Hmo.

core.npstats.dpm_gufunc

dpm_gufunc(x1, x2, x3, /, out=None, *, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj, axes, axis])

core.npstats.dp_gufunc

dp_gufunc(x1, x2, /, out=None, *, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj, axes, axis])

core.npstats.tps_gufunc

tps_gufunc(x1, x2, x3, /, out=None, *, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj, axes, axis])

core.npstats.tp_gufunc

tp_gufunc(x1, x2, x3, /, out=None, *, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj, axes, axis])

xrstats

core.xrstats.peak_wave_direction

Peak wave direction Dp.

core.xrstats.mean_direction_at_peak_wave_period

Mean direction at the peak wave period Dpm.

core.xrstats.peak_wave_period

Smooth Peak wave period Tp.

select module

core.select.sel_nearest

Select sites from nearest distance.

core.select.sel_bbox

Select sites within bbox.

core.select.sel_idw

Select sites from inverse distance weighting.

core.select.Coordinates.distance

Distance between each station in (dset_lons, dset_lats) and site (lon, lat).

core.select.Coordinates.nearer

Nearer stations in (dset_lons, dset_lats) to site (lon, lat).

core.select.Coordinates.nearest

Nearest station in (dset_lons, dset_lats) to site (lon, lat).

utils module

core.utils.wavelen

Wavelength L.

core.utils.wavenuma

Chen and Thomson wavenumber approximation.

core.utils.celerity

Wave celerity C.

core.utils.dnum_to_datetime

Convert from numeric date to datetime.

core.utils.to_nautical

Convert from cartesian to nautical angle.

core.utils.unique_indices

Remove duplicate indices from dataset.

core.utils.unique_times

Remove duplicate times from dataset.

core.utils.to_datetime

Convert Datetime64 date to datatime.

core.utils.spddir_to_uv

Converts (spd, dir) to (u, v).

core.utils.uv_to_spddir

Converts (u, v) to (spd, dir).

core.utils.interp_spec

Interpolate onto new spectral basis.

core.utils.flatten_list

Flatten list of lists

core.utils.regrid_spec

Regrid spectra onto new spectral basis.

swan module

core.swan.read_tab

Read swan table file.

core.swan.SwanSpecFile

Read spectra in SWAN ASCII format.

core.swan._dateparse

Date parsing to read SWAN tab files.