Wave Parameters

Derived wave variables computed from integrated spectral wave parameters.

---

tp — Peak period

Returns peak wave period (s) as 1/fp.

Parameter	Default	Description
fp	"fp"	Peak wave frequency variable name (Hz)

derived_vars:
  - name: tp
    func: tp
    fp: peak_freq   # override if your dataset uses a different name

---

douglas_sea — Douglas sea scale

Returns the Douglas sea scale (integer 0–9) from wind-sea significant wave height.

Scale	Description	Hs range
0	Glassy	0 m
1	Rippled	0–0.1 m
2	Wavelets	0.1–0.5 m
3	Slight	0.5–1.25 m
4	Moderate	1.25–2.5 m
5	Rough	2.5–4 m
6	Very rough	4–6 m
7	High	6–9 m
8	Very high	9–14 m
9	Phenomenal	> 14 m

Parameter	Default	Description
hs_sea	"hs_sea"	Wind-sea significant wave height variable name (m)

derived_vars:
  - name: douglas_sea
    func: douglas_sea

---

douglas_swell — Douglas swell scale

Returns the Douglas swell scale (integer 0–9) from swell height and wavelength.

Parameter	Default	Description
hs_sw1	"hs_sw1"	Primary swell significant wave height variable name (m)
lp_sw1	"lp_sw1"	Primary swell peak wavelength variable name (m)

derived_vars:
  - name: douglas_swell
    func: douglas_swell

---

crossing_seas — Crossing-seas flag

Boolean mask indicating crossing-seas conditions. Crossing seas are detected when two wave systems are separated by more than an angle threshold and the weaker system carries at least a minimum energy fraction.

Parameter	Default	Description
hs	"hs"	Total significant wave height variable (m)
hs_sea	"hs_sea"	Wind-sea Hs variable (m)
hs_sw1	"hs_sw1"	Primary swell Hs variable (m)
dir_sea	"dir_sea"	Wind-sea direction variable (degrees)
dir_sw1	"dir_sw1"	Primary swell direction variable (degrees)
hs_sw2	None	Secondary swell Hs variable (enables sw2 pair checks)
dir_sw2	None	Secondary swell direction variable
hs_threshold	0.0	Minimum total Hs (m) to report crossing seas
angle_threshold	40.0	Minimum relative angle between two systems (degrees)
energy_fraction	0.2	Minimum energy fraction of the weaker system

derived_vars:
  - name: crossing_seas
    func: crossing_seas
    angle_threshold: 45.0   # tighten the directional separation criterion
    energy_fraction: 0.25

---

API reference

gridstats.derived.wave.tp(ds: xr.Dataset, *, fp: str = 'fp') -> xr.DataArray

Peak wave period from peak wave frequency.

Parameters:

Name	Type	Description	Default
ds	Dataset	Input dataset.	required
fp	str	Name of the peak wave frequency variable (Hz).	'fp'

Returns:

Type	Description
DataArray	Peak wave period DataArray (s).

gridstats.derived.wave.douglas_sea(ds: xr.Dataset, *, hs_sea: str = 'hs_sea') -> xr.DataArray

Douglas sea scale (0–9) from wind-sea significant wave height.

Scale 0 = glassy; scale 9 = phenomenal (Hs > 14 m).

Parameters:

Name	Type	Description	Default
ds	Dataset	Input dataset.	required
hs_sea	str	Name of the wind-sea significant wave height variable (m).	'hs_sea'

Returns:

Type	Description
DataArray	Douglas sea scale DataArray (integer-valued float32, 0–9).

gridstats.derived.wave.douglas_swell(ds: xr.Dataset, *, hs_sw1: str = 'hs_sw1', lp_sw1: str = 'lp_sw1') -> xr.DataArray

Douglas swell scale (0–9) from primary swell height and wavelength.

Parameters:

Name	Type	Description	Default
ds	Dataset	Input dataset.	required
hs_sw1	str	Name of the primary swell significant wave height variable (m).	'hs_sw1'
lp_sw1	str	Name of the primary swell peak wavelength variable (m).	'lp_sw1'

Returns:

Type	Description
DataArray	Douglas swell scale DataArray (integer-valued float32, 0–9).

gridstats.derived.wave.crossing_seas(ds: xr.Dataset, *, hs: str = 'hs', hs_sea: str = 'hs_sea', hs_sw1: str = 'hs_sw1', dir_sea: str = 'dir_sea', dir_sw1: str = 'dir_sw1', hs_sw2: str | None = None, dir_sw2: str | None = None, hs_threshold: float = 0.0, angle_threshold: float = 40.0, energy_fraction: float = 0.2) -> xr.DataArray

Boolean mask indicating crossing-seas conditions.

Crossing seas are identified when: (1) The relative angle between two wave systems exceeds angle_threshold. (2) The less energetic system carries at least energy_fraction of total energy (i.e. Hs_minor > sqrt(energy_fraction) * Hs_total).

Parameters:

Name	Type	Description	Default
ds	Dataset	Input dataset.	required
hs	str	Total significant wave height variable name (m).	'hs'
hs_sea	str	Wind-sea significant wave height variable name (m).	'hs_sea'
hs_sw1	str	Primary swell significant wave height variable name (m).	'hs_sw1'
dir_sea	str	Wind-sea direction variable name (degrees).	'dir_sea'
dir_sw1	str	Primary swell direction variable name (degrees).	'dir_sw1'
hs_sw2	str | None	Secondary swell Hs variable name. Set to enable sea/sw2 and sw1/sw2 pair checks.	None
dir_sw2	str | None	Secondary swell direction variable name.	None
hs_threshold	float	Minimum total Hs (m) below which crossing seas are not reported.	0.0
angle_threshold	float	Minimum relative angle (degrees) between two systems.	40.0
energy_fraction	float	Minimum energy fraction (relative to total Hs) for the weaker system.	0.2

Returns:

Type	Description
DataArray	Boolean DataArray: True where crossing seas are detected.

Reference

Li, X.M. (2016). A new insight from space into swell propagation and crossing in the global oceans. Geophysical Research Letters, 43(10).