Wai is a research dashboard for exploring coastal water levels. It brings public NOAA data, model estimates, uncertainty, and tide movement into one control panel that is easier to inspect and compare.
Wai is a research tool, not an emergency or navigation system. Do not use it for flood warnings, evacuation decisions, vessel operations, insurance, or infrastructure safety.
- Browse active NOAA CO-OPS water-level stations across the United States.
- Compare measured water levels with NOAA astronomical tide predictions.
- View available NOAA Operational Forecast System guidance on the same UTC timeline.
- Follow an animated shoreline cross-section as the selected time changes.
- Replay held-out model estimates with uncertainty, error, and baseline comparisons.
- Connect a CSV export or another tide-gauge provider to the same pipeline.
Version 2 adds nationwide station discovery, live NOAA data layers, a clearer dashboard, beginner onboarding, and stronger evidence and artifact checks. The full change list is in CHANGELOG.md.
Wai uses Python 3.13 or newer and uv for setup.
git clone https://github.com/dcablayan/Wai.git
cd Wai
uv sync --locked --all-extras
make dashboardStreamlit prints the local address when the dashboard is ready. Open that address in a browser, then choose a data source from the sidebar.
If this is your first Python project, follow docs/getting_started.md. It walks through installing the tools, starting the dashboard, choosing a station, understanding datums, and fixing common setup problems.
Wai keeps live public data separate from model backtests so the numbers are not easy to misread.
| View | What it shows | What it means |
|---|---|---|
| Live NOAA CO-OPS | Recent public observations, NOAA tide predictions, and available NOAA guidance | A live data monitor; NOAA predictions are not Wai machine-learning forecasts |
| Synthetic backtest | Held-out model estimates, observed outcomes, uncertainty, and error | A repeatable research test using generated demo data, not a live sensor feed |
In live mode, select a region or search by station name or ID. Wai downloads a bounded time window only for the station you choose. No NOAA API key is needed. Stations without published tide predictions still work as observation-only monitors, including Great Lakes gauges.
The bundled station catalog makes the selector useful when NOAA discovery is temporarily unavailable. Refresh it with:
make noaa-stationsThe main modeling idea is simple:
- Start with known tidal structure, such as NOAA tide predictions or harmonic time features.
- Model the remaining difference with small statistical or machine-learning methods.
- Compare the result with strong baselines, including persistence and the NOAA tide prediction itself.
- Evaluate only on future, held-out time windows and report uncertainty and failure cases.
Run the complete offline evidence pipeline with:
make demo
make test
make coverageStart with reports/summary.json for the machine-readable index or docs/research-report.md for the written research summary.
| Evidence | Use it for | Do not treat it as |
|---|---|---|
| Synthetic demo | Checking code, splits, uncertainty, and model comparisons | Real-world forecast skill |
| NOAA-derived tidecast benchmark | Comparing simple methods on a smooth tidal signal | Noisy observed water levels |
| NOAA mock evaluation | Testing the offline API and evaluation path | Live NOAA performance |
| NOAA live evaluation | Comparing models and NOAA baselines on a short public-data window | Operational or seasonal validation |
Mock and live NOAA results are written to different files. The scientific evidence audit checks that they remain separate.
Wai can read a CSV without changing the forecasting code:
uv run python -m scripts.run_gauge_forecast \
--csv my_gauge.csv \
--station-id MY-GAUGE-01 \
--timestamp-col time \
--water-level-col level_ft \
--units ftFor a reusable station catalog or a new provider adapter, see docs/onboarding_new_gauge.md.
Wai includes three numerical orchestration modes:
miniis the fast default path.ultracan coordinate several numerical experts and verification steps.legacykeeps the original router available for regression testing.
No language model generates the water-level values. Numerical experts, statistical combination, physical checks, and explicit fallback rules produce the estimates.
uv run python -m scripts.run_orchestrated_forecast --mode mini --horizon-minutes 360
uv run python -m scripts.run_orchestrated_forecast --mode ultra --horizon-minutes 360Technical details are in docs/forecast_orchestrator.md.
- The checked-in demo metrics come from synthetic data and are sanity checks.
- Short NOAA API windows do not prove seasonal or extreme-event performance.
- The current checked-in reports do not include real wind, pressure, rainfall, or wave forcing.
- Split-conformal intervals are measured empirically because tidal time series do not guarantee the assumptions behind ideal coverage.
- Terrain in the tide animation is illustrative, not surveyed bathymetry.
- Wai does not provide validated storm-surge, tsunami, flood, or safety alerts.
Read docs/model_card.md for intended use, failure modes, and the exact evidence boundaries.
app.py Streamlit control panel
src/ data adapters, models, forecasting, and verification
scripts/ repeatable evaluations and report builders
tests/ unit, integration, security, and evidence tests
data/ synthetic demo inputs and the NOAA station catalog
reports/ generated metrics and research reports
docs/ onboarding, model card, methods, and deeper explanations
make dashboard # start the control panel
make demo # regenerate offline research evidence
make test # run the test suite
make coverage # enforce coverage checks
make noaa-stations # refresh the nationwide station catalogThe locked environment is stored in uv.lock. A pip-compatible
requirements.txt is included for environments that cannot use uv.
MIT — see LICENSE.