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

Backend 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_awac	Read Spectra from Nortec AWAC NMEA file.
read_dataset	Format and attach SpecArray accessor to an existing xarray dataset.
read_datawell	Read Spectra from Datawell spt file.
read_era5	Read Spectra from ECMWF ERA5 netCDF format.
read_funwave	Read Spectra in Funwave format.
read_funwave_new	Read Spectra in Funwave WK_NEW_DATA2D wavemaker 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_wavespectra	Read Spectra from from netCDF or ZARR format in Wavespectra convention.
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 opened with xarray’s open_dataset and open_mfdataset functions, can also be provided 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 opened from both local and remote (bucket) stores. Files in NetCDF format can be opened from remote (i.e., bucket) stores when they are opened using fsspec.