GaugePredict Documentation
GaugePredict ingests basin-wide USGS gauge time series, automatically aligns and cleans multi-site predictors, and generates one-day forecasts that can be used to fill gaps in target-site records (typically downstream conditions), as well as daily to multi-week forecasts of target-site conditions (eg. water level or discharge). Target-site observations can be pulled directly from USGS or ingested from user-provided CSV files. The model uses a hybrid neural network (CNN–LSTM), with optional Shapley additive explanations (SHAP)-based predictor selection to retain only the most informative gauges and keep the workflow lightweight on computers with limited computational capability. While notebooks and workflows demonstrate the package using water level and discharge forecasts in the Mississippi River Basin in the manuscripts and notebooks, the setup is flexible and can be applied to other basins, other USGS parameters, and user-defined target-site datasets.
Getting Started
Key Features
- Extended-range forecasts
Generate predictions from 1 to 30 days ahead for water discharge and gauge levels
- Basin-wide analysis
Automatically process and align multi-site time series across entire hydrological basins
- Explainability
Use SHAP values to understand feature importance and select optimal predictor sites
- GPU acceleration
Support for CUDA-enabled GPUs for accelerated neural network training
- Flexible models
Hybrid CNN-LSTM architectures optimized for hydrological time series
- Workflow notebooks
Complete examples for every step: data preparation, training, and visualization
Core Components
- Downloader Module
Retrieve USGS NWIS daily-values data and build gauge catalogs organized by hydrological unit code.
- Predict Module
Neural network architectures, training utilities, and inference functions for discharge forecasting.
- Routines Module
Core data processing and utility functions used across GaugePredict.
- Plotting Module
Comprehensive visualization tools for model predictions, SHAP analysis, and geospatial context.