truetide

TrueTide

Corrected water-level forecasts for NOAA tide stations. A GRU forecasts the tide-gauge residual (observed minus harmonic prediction, meters) 24 hours ahead from the previous 72 hours of residual plus station location and time encodings. Adding the predicted residual to NOAA's published harmonic prediction gives a corrected water-level forecast; the residual is the weather-driven part (storm surge, wind setup) that harmonic analysis cannot represent.

Run it

pip install torch safetensors requests
python truetide_predict.py 8518750     # The Battery, NY — any CO-OPS id works

Prints the next 24 hours of harmonic, predicted residual, and corrected water level, fetching the live gauge feed automatically. CPU is fine; the model is ~0.5 MB.

Training

9.8M station-hours from 120 NOAA CO-OPS stations (2015-2024): verified hourly water level vs harmonic prediction, both MLLW/metric/GMT from the same API. 1.1M training windows, GRU(128x2) + MLP head, 8 epochs.

Evaluation (residual RMSE, meters)

Baselines: harmonic = official prediction as published (zero residual); persistence = last observed residual held constant.

Time split — test on 2023-24, training stations (294k windows):

Spatial split — test on 2023-24, 18 stations fully held out (50k windows):

Interface

Input: 72 hourly residuals (most recent last), then 6 statics: (lat-40)/25, (lon+100)/60, sin/cos day-of-year, sin/cos hour-of-day. Output: 24 hourly residuals, +1h .. +24h. Architecture and normalization are also recorded in the safetensors metadata. Held-out station ids are in the metadata for reproducible evaluation.

Data: NOAA CO-OPS (US Government, public domain). Model CC0.