Input & Output#

Input#

Wavespectra provides several functions for reading datasets from different file formats into SpecDataset objects. The functions are defined in modules within the wavespectra.input subpackage, for example, wavespectra.input.swan.read_swan. They can be imported from the main module level for convenience, for instance:

In [1]: from wavespectra import read_swan

In [2]: dset = read_swan("_static/swanfile.spec")

In [3]: dset.spec
Out[3]: 
<SpecDataset> Size: 35kB
Dimensions:  (time: 5, lat: 1, lon: 1, freq: 24, dir: 36)
Coordinates:
  * time     (time) datetime64[ns] 40B 2016-10-11 2016-10-12 ... 2016-10-15
  * lat      (lat) float64 8B -38.17
  * lon      (lon) float64 8B 174.7
  * freq     (freq) float64 192B 0.04 0.0452 0.0511 ... 0.5219 0.5899 0.6666
  * dir      (dir) float64 288B 5.0 15.0 25.0 35.0 ... 325.0 335.0 345.0 355.0
Data variables:
    efth     (time, lat, lon, freq, dir) float64 35kB 0.0 0.0 0.0 ... 0.0 0.0

The following conventions are expected for defining fully-supported reading functions:

Input functions must be defined in modules within the wavespectra.input subpackage.
Modules should be named as filetype.py, e.g., swan.py.
Functions should be named as read_`filetype`, e.g., read_swan.

Input functions can also be defined without following these conventions. However they will not be accessible from the main module level and will have to be imported from their full module path, e.g.

In [4]: from wavespectra.input.swan import read_hotswan

Backends engines#

Backend engines are provided to seamlessly access wavespectra datasets through the xarray.open_dataset function. These engines are designated by their respective filetype, for example:

In [5]: import xarray as xr

In [6]: dset = xr.open_dataset("_static/ww3file.nc", engine="ww3")

In [7]: dset.spec
Out[7]: 
<SpecDataset> Size: 44kB
Dimensions:  (time: 9, site: 2, freq: 25, dir: 24)
Coordinates:
  * freq     (freq) float32 100B 0.04118 0.0453 0.04983 ... 0.3352 0.3687 0.4056
  * site     (site) int32 8B 1 2
  * time     (time) datetime64[ns] 72B 2014-12-01 ... 2014-12-05
  * dir      (dir) float32 96B 270.0 255.0 240.0 225.0 ... 315.0 300.0 285.0
Data variables:
    dpt      (time, site) float32 72B ...
    efth     (time, site, freq, dir) float32 43kB ...
    lat      (site) float32 8B ...
    lon      (site) float32 8B ...
    wspd     (time, site) float32 72B ...
    wdir     (time, site) float32 72B ...

Available readers#

These input functions are currently available from the main module level:

`read_dataset`	Format and attach SpecArray accessor to an existing xarray dataset.
`read_era5`	Read Spectra from ECMWF ERA5 netCDF format.
`read_funwave`	Read Spectra in Funwave format.
`read_json`	Read Spectra from json.
`read_ncswan`	Read Spectra from SWAN native netCDF format.
`read_ndbc`	Read Spectra from NDBC netCDF format.
`read_ndbc_ascii`	Read spectra from NDBC wave buoy ASCII files.
`read_netcdf`	Read Spectra from generic netCDF format.
`read_obscape`	Read spectra from Obscape wave buoy csv files.
`read_octopus`	Read spectra from Octopus file format.
`read_spotter`	Read Spectra from Spotter file.
`read_swan`	Read Spectra from SWAN ASCII file.
`read_triaxys`	Read spectra from TRIAXYS wave buoy ASCII files.
`read_ww3`	Read Spectra from WAVEWATCHIII native netCDF format.
`read_ww3_station`	Read directional spectra from WW3 station output file.
`read_wwm`	Read Spectra from WWMII native netCDF format.
`read_xwaves`	Read Spectra from XWaves MAT format.

These functions are not accessible from the main module level and need to be imported from their full module path:

`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.

Note

Wavespectra supports different data formats including NetCDF, ASCII, JSON. netcdf-type datasets, i.e. those that can be open with xarray’s open_dataset and open_mfdataset functions, can also be prescribed in ZARR format (wavespectra uses xarray’s open_zarr function behind the scenes to open these files). Functions that support ZARR have a file_format argument option.

Files in ZARR format can be open from both local and remote (bucket) stores. Files in NetCDF format can be open from remote (i.e., bucket) stores when they are opened using fsspec.

Output#

Functions are available to write wavespectra datasets to disk in a number of different file types. Output functions are defined in modules within the wavespectra.output subpackage, for example, wavespectra.output.swan.to_swan. They are accessed as methods in the SpecDataset accessor, for instance:

In [1]: dset.spec.to_octopus("_static/octopusfile.oct")

In [2]: !head -n 20 _static/octopusfile.oct
Forecast valid for 01-Dec-2014 00:00:00
nfreqs,25
ndir,24
nrecs,9
Latitude,19.950001
Longitude,92.099998
Depth,106.59

CCYYMM,DDHHmm,LPoint,WD,WS,ETot,TZ,VMD,ETotSe,TZSe,VMDSe,ETotSw,TZSw,VMDSw,Mo1,Mo2,HSig,DomDr,AngSpr,Tau
201412,'010000,spec_20141201_00z,25,5.10,0.1426,7.86,205.8,0.0432,4.42,207.7,0.1050,11.03,204.0,0.00440,0.00078,0.7552,209,40,0
freq,0.0411800,0.0452980,0.0498278,0.0548106,0.0602916,0.0663208,0.0729529,0.0802482,0.0882730,0.0971003,0.1068103,0.1174914,0.1292405,0.1421645,0.1563810,0.1720191,0.1892210,0.2081431,0.2289574,0.2518532,0.2770385,0.3047423,0.3352166,0.3687383,0.4056121,anspec
0,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000002,0.0000026,0.0000109,0.0000369,0.0000839,0.0001605,0.0001651,0.0000985,0.0000640,0.0006226,
15,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000001,0.0000018,0.0000056,0.0000060,0.0000025,0.0000051,0.0000198,0.0000840,0.0000546,0.0001795,
30,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000003,0.0000009,0.0000008,0.0000005,0.0000005,0.0000009,0.0000578,0.0000376,0.0000992,
45,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000001,0.0000002,0.0000002,0.0000002,0.0000205,0.0000134,0.0000346,
60,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000001,0.0000001,0.0000001,0.0000143,0.0000093,0.0000238,
75,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000088,0.0000057,0.0000146,
90,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000038,0.0000025,0.0000063,
105,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000006,0.0000004,0.0000010,
120,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,0.0000000,

The following conventions are expected for defining output functions:

Output functions must be defined in modules within the wavespectra.output subpackage.
Modules should be named as filetype.py, e.g., swan.py.
Functions should be named as to_`filetype`, e.g., to_swan.
Function must accept self as the first input argument so they can be plugged in as methods in the SpecDataset accessor class.

Available writers#

These output functions are currently available as methods of SpecDataset:

`SpecDataset.to_funwave`	Write spectra in Funwave format.
`SpecDataset.to_json`	Write spectra in json format.
`SpecDataset.to_netcdf`	Write spectra in netCDF format using wavespectra conventions.
`SpecDataset.to_octopus`	Save spectra in Octopus format.
`SpecDataset.to_orcaflex`	Writes the spectrum to an Orcaflex model
`SpecDataset.to_swan`	Write spectra in SWAN ASCII format.
`SpecDataset.to_ww3`	Save spectra in native WW3 netCDF format.

Table of Contents