Surfe Diem — Groundswell Direction (Sin Component) Forecast v1 (USA Southwest, 6h)
Model Description
A LightGBM regression model trained to predict sin component of groundswell direction — part of a circular decomposition to eliminate the 0/360° discontinuity 6 hours in advance using real-time buoy observations from NOAA's National Data Buoy Center (NDBC).
Developed by: Surfe Diem
Model type: Gradient Boosted Decision Trees (LightGBM)
Language: Python
License: MIT
Intended Use
Primary Use Case
Predict the sin component of groundswell direction. Pair with the ground_dir_cos model to reconstruct full direction in degrees. Forecast horizon: 6 hours.
Out-of-Scope Use
- Horizons other than 6 hours (separate models exist for 6h, 12h, 24h, 48h)
- Wave height or period; must be paired with ground_dir_cos for meaningful direction output
- Regions outside the California coast (model trained on USA Southwest NDBC stations only)
- Real-time safety-critical applications without human oversight
Training Data
Stations: 15 NDBC buoys along the California coast
46011, 46012, 46013, 46014, 46022, 46025, 46026, 46027, 46028, 46042, 46047, 46053, 46054, 46069, 46086
Records: ~2.08M observations (259 Parquet files with stdmet and spectral aligned columns)
Features:
- Meteorological: wave height, period, direction, wind speed/direction, pressure, temperature
- Spectral compression: 9 physics-informed features derived from ~150 raw spectral bands
- Ground swell energy, direction, quality (< 0.08 Hz)
- Mid-range energy, direction, quality (0.08–0.12 Hz)
- Wind wave energy, direction, quality (> 0.12 Hz)
- Circular decomposition: sin/cos encoding for all direction columns
- Temporal lag features: 1h, 3h, 6h, 12h lags across all features
Split: 80/20 train/test, time-series ordered (no shuffle)
Model Performance
Test MAE: 0.0879 unit circle [-1, 1]
MAE is on the unit circle [-1, 1]. Combine with the cos model via atan2(sin, cos) to recover degrees.
Evaluated on held-out data with proper time-series validation (train on past, test on future).
Training Details
Algorithm: LightGBM
Objective: Regression (MAE / L1 loss)
Learning rate: 0.05
Num leaves: 31
Feature fraction: 0.9
Bagging fraction: 0.8
Max iterations: 2000 (early stopping, patience=50)
Feature engineering:
- Station IDs encoded as fixed
CategoricalDtype for inference consistency
- Lag features filled with 0 for single-observation inference
How to Use
1import lightgbm as lgb
2import pandas as pd
3import numpy as np
4from huggingface_hub import hf_hub_download
5
6# Load model
7model_path = hf_hub_download(repo_id="surfe-diem/surfe-diem-v1-usa-southwest-ground-dir-sin-6h-model", filename="surfe_diem_v1_usa_southwest_ground_dir_sin_6h_model.txt")
8model = lgb.Booster(model_file=model_path)
9
10# Prepare observation with engineered features + lags + station_id
11# See full inference pipeline in the GitHub repo
12obs = pd.DataFrame({
13 'wvht': [2.5], 'dpd': [12.0], 'apd': [8.5],
14 'mwd': [270], 'wspd': [15.0], 'wdir': [280],
15 'pres': [1013.0], 'atmp': [18.0], 'wtmp': [16.0],
16 # ... + spectral band features + lag features + station_id
17})
18
19prediction = model.predict(obs)[0] # unit circle [-1, 1]
Full inference pipeline available in the
GitHub repo.
Limitations
- No history for single observations: Lag features set to 0 for real-time single-row inference (slight accuracy degradation vs. buffered inference)
- Regional specificity: Trained only on California coast buoys
- Forecast horizon: 6 hours only — separate models cover 6h, 12h, 24h, 48h
- Spectral dependency: Full accuracy requires spectral band data; older buoy files without spectral data contribute only standard met features
Citation
1@misc{surfediem2026wave,
2 author = {Surfe Diem},
3 title = {Wave Forecasting Models v1 - USA Southwest},
4 year = {2026},
5 publisher = {Hugging Face},
6 howpublished = {\url{https://huggingface.co/surfe-diem}}
7}
Model Card Contact
For questions or issues, please open an issue in the
GitHub repository.
