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 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 netCDF format.
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.