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.hrms	Root mean square wave height Hrms.
SpecArray.hmax	Maximum wave height Hmax.
SpecArray.fp	Peak wave frequency Fp.
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	Mean directional wave spread Dspr.
SpecArray.dpspr	Peak directional wave spread Dpspr.
SpecArray.swe	Spectral width parameter by Cartwright and Longuet-Higgins (1956).
SpecArray.sw	Spectral width parameter by Longuet-Higgins (1975).
SpecArray.gw	Gaussian frequency spread by Bunney et al. (2014).
SpecArray.gamma	Jonswap peak enhancement factor gamma.
SpecArray.alpha	Jonswap fetch dependant scaling coefficient alpha.
SpecArray.goda	Goda peakedness parameter.
SpecArray.fit_jonswap	Nonlinear fit Jonswap spectra.
SpecArray.fit_gaussian	Nonlinear fit Gaussian width.
SpecArray.rmse	Root-Mean-Square Error among spectral bins.

Spectral partitioning

SpecArray.split	Split spectra over freq and/or dir dims.
SpecArray.partition
partition.partition.Partition.ptm1	PTM1 watershed partitioning.
partition.partition.Partition.ptm2	PTM2 watershed partitioning with secondary wind-sea.
partition.partition.Partition.ptm3	PTM3 watershed partitioning with no wind-sea or swell classification.
partition.partition.Partition.ptm4	PTM4 WAM partitioning of sea and swell based on wave age criterion..
partition.partition.Partition.ptm5	PTM5 SWAN partitioning of sea and swell based on user-defined threshold.
partition.partition.Partition.hp01	Hanson and Phillips 2001 spectra partitioning and swell merging.
partition.partition.Partition.bbox	Partition based on user-defined bounding boxes in frequency-direction space.
partition.partition.Partition.ptm1_track	Partition and combine spectra from the same wave system over time.

Other methods

SpecArray.momf	Frequency moment.
SpecArray.momd	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 spectra from energy density (m2/Hz/degree) into wave energy (m2).
SpecArray.interp	Interpolate onto new spectral basis.
SpecArray.interp_like	Interpolate onto coordinates from other spectra.
SpecArray.rotate	Rotate 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 to_funwave to_orcaflex

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.
read_ndbc	Read Spectra from NDBC 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_ascii	Read spectra from NDBC wave buoy ASCII files.
read_json	Read Spectra from json.
read_funwave	Read Spectra in Funwave format.
read_xwaves	Read Spectra from XWaves MAT format.
read_dataset	Format and attach SpecArray accessor to an existing xarray dataset.
read_wavespectra	Read Spectra from from netCDF or ZARR format in Wavespectra convention.
read_ww3_station	Read directional spectra from WW3 station output file.

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.
SpecDataset.to_funwave	Write spectra in Funwave format.
SpecDataset.to_orcaflex	Writes the spectrum to an Orcaflex model

Construct

construct.frequency.pierson_moskowitz	Pierson and Moskowitz spectrum for fully developed seas (Pierson and Moskowitz, 1964).
construct.frequency.jonswap	Jonswap frequency spectrum for developing seas (Hasselmann et al., 1973).
construct.frequency.tma	TMA frequency spectrum for seas in water of finite depth (Bouws et al., 1985).
construct.frequency.gaussian	Gaussian frequency spectrum (Bunney et al., 2014).
construct.direction.cartwright	Cosine-squared directional spreading of Cartwright (1963).
construct.direction.asymmetric	Asymmetric directional spreading of Bunney et al. (2014).
construct.construct_partition	Fit frequency-direction E(f, d) parametric spectrum for a partition.
construct.partition_and_reconstruct	Partition and reconstruct existing spectra to evaluate.

Internal core functions and objects

Partition subpackage

partition.partition.Partition	Spectra partition methods.
partition.partition.Partition.ptm1	PTM1 watershed partitioning.
partition.partition.np_ptm1	PTM1 spectra partitioning on numpy arrays.
partition.partition.np_ptm2	PTM2 spectra partitioning on numpy arrays.
partition.partition.np_ptm3	PTM3 spectra partitioning on numpy arrays.
partition.partition.np_hp01	Hanson and Phillips 2001 spectra partitioning on numpy arrays.
partition.tracking.dfp_wsea	Rate of change of the wind-sea peak wave frequency.
partition.tracking.dfp_swell	Rate of change of the swell peak wave frequency.
partition.tracking.match_consecutive_partitions	Match partitions of consecutive spectra based on evolution of peak frequency and peak direction.
partition.tracking.np_track_partitions	Track partitions at a site in a series of consecutive spectra based on the evolution of peak frequency and peak direction.
partition.tracking.track_partitions	Track partitions in a series of consecutive spectra based on the evolution of peak frequency and peak direction.
partition.hanson_and_phillips_2001._partition_stats	Wave stats from partition.
partition.hanson_and_phillips_2001._is_contiguous	Check if 1d partitions overlap in frequency space.
partition.hanson_and_phillips_2001._frequency_resolution	Frequency resolution.
partition.hanson_and_phillips_2001._plot_partitions
partition.hanson_and_phillips_2001.spread_hp01	Spread parameter of Hanson and Phillips (2001).
partition.hanson_and_phillips_2001._combine_last	Combine, update and reorder parts and stats.
partition.hanson_and_phillips_2001.combine_partitions_hp01	Combine swell partitions according Hanson and Phillips (2001).

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	Mean direction at the peak wave period Dpm.
core.npstats.dp	Peak wave direction Dp.
core.npstats.dm	Mean wave direction Dm.
core.npstats.tps	Smooth peak wave period Tp.
core.npstats.tp	Peak wave period Tp.
core.npstats.dpspr	Peak directional wave spread Dpspr.
core.npstats.mom1	First directional moment.
core.npstats.jonswap	Jonswap frequency spectrum for developing seas (Hasselmann et al., 1973).
core.npstats.gaussian	Gaussian frequency spectrum (Bunney et al., 2014).

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.
core.xrstats.peak_directional_spread	Wave spreading at the peak wave frequency Dpspr.

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.create_frequencies	Create an array of logarithmically spaced frequencies.
core.utils.waveage	Wave age criterion for partitioning wind-sea.
core.utils.wavelen	Wavelength L.
core.utils.wavenuma	Chen and Thomson wavenumber approximation.
core.utils.celerity	Wave celerity C.
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.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.scaled	Scale spectra.
core.utils.check_same_coordinates	Check if DataArrays have same coordinates.
core.utils.load_function	Returns a function object from string.
core.utils.to_coords	Create coordinates DataArray.
core.utils.regrid_spec	Regrid spectra onto new spectral basis.
core.utils.smooth_spec	Smooth spectra with a running average.
core.utils.is_overlap	Check if rectangles overlap.

swan module

core.swan.read_tab	Read swan table file.
core.swan.SwanSpecFile	Read spectra in SWAN ASCII format.