Skip to content
tmart234Public

About

nightly ML Operations to train models that forecast river flows

Topics

Resources

Security policy

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

581 Commits

Folders and files

Repository files navigation

OpenFlow

New here? See our wiki wiki to learn more

Diagram 1

  • Automated dataset creation based on a USGS and CODWR station
  • GitHub actions ML training
  • Mobile artifacts published per training run (CoreML + TFLite + manifest) — see docs/INFERENCE.md
  • Upstream-gauge inputs: the model sees flood waves still upstream (e.g. Colorado's San Luis Valley -> Lower Taos Box). Seven rivers are registered, including the Colorado at Dotsero and at the state line and the Gunnison since 2026-11, and each river learns its own response to an upstream rise. See openFlowML/data/upstream_gauges.json.
  • Basin rain by travel-time zone: gridMET / NWS Stage IV / NWS forecast rain and snow averaged over the river-distance zones of each gauge's contributing area (not a single point, not a fixed HUC level) — see openFlowML/data/README.md
  • Model releases: every passing training run on dev/main is published as a model-YYYY.MM.DD GitHub Release by the Release Model workflow (checksums + quality gate verified, quality report in the notes); any other run can be promoted by run ID
  • Probabilistic forecast range: the model also outputs the 5–95% quantiles of each day's low and high flow. The range is calibrated per lead day on held-out years, and on the test years the 90% range held 86–89% of observed flows. The design and the experiments behind it are in docs/MODEL_DESIGN.md.
  • Leave-water-years-out cross-validation for model decisions: every water year is held out once (openFlowML/crossval.py, workflow Cross-validate Model). The default test split holds only about two snow seasons.
  • Forecast verification on every training run: per-station, per-lead-day error in cfs against a "no change" forecast, flood-peak and timing checks, and a quality gate that blocks publishing a worse model — see openFlowML/evaluate.py and quality_report.md in each release
  • Routing crest-timing backtest on every routed river's floods since 2015 (openFlowML/crest_backtest.py, CI workflow Routing Crest Backtest), and a daily forecast archive that scores OpenFlow routing, the NWS official forecast and the ML model against what the rivers did (openFlowML/score_archive.py) — see docs/VERIFICATION.md
  • Forecast CLI with charts (no trained model needed): python openFlowML/flow_forecast.py --site taos-box (also royal-gorge, conejos, dolores; add --model-dir <release> to overlay the trained ML model) writes a CSV, JSON and PNG with the peak called out — upstream routing where upstream gauges are registered, else the official NWS forecast for the gauge; also runnable from the Flow Forecast GitHub Action

About

nightly ML Operations to train models that forecast river flows

Topics

Resources

Security policy

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages