Examples

The examples/ directory contains complete, production-ready workflows for using GaugePredict. These resources guide you through every step of the forecasting pipeline.

Jupyter Notebooks

Interactive notebooks with detailed explanations and visualizations:

Data Downloader (downloader_notebook.ipynb)

Automatically download and prepare USGS gauge data for modeling.

Training Notebook (training_notebook.ipynb)

Train CNN-LSTM models on prepared gauge data with configurable horizons and hyperparameters.

Figure Creation (figure_creating_notebook.ipynb)

Generate publication-ready visualizations and interpretability plots from trained models.

Baton Rouge Missing Data Analysis (br_gauge_missingdata_figures_notebook.ipynb)

Demonstrates model capability for filling observational gaps during gauge downtime:

  • Compare GaugePredict forecasts against measured USGS observations

  • Use USGS calculated discharge as reference during missing periods

  • Illustrate how upstream predictors enable discharge inference when target gauge is downed

Python Scripts

downloader_msr_basin.py

Download and preprocess discharge data for the Mississippi River Basin

trainingcode_bonnet_carre_spillway.py

Complete training workflow for the Bonnet Carré Spillway site

figure_creating.py

Generate visualizations from trained model outputs

br_gauge_missingdata_figures.py

Generate forecast comparison figures for missing data scenarios (e.g., downed gauges)

Data & Resources

The examples/ directory includes:

Data Files:

  • bcs_wl.csv: Sample water level dataset for Bonnet Carré Spillway

  • data/: Additional input data files

Cached Data:

  • cached_data_discharge/: Pre-processed discharge data

    (Can be generated using downloader_notebook.ipynb)

Results:

  • results/: Model outputs, predictions, and metrics

  • results/*/H01/ and results/*/H03/: Results for different forecast horizons

Geospatial Data:

  • shapefiles/HUC_Zones/: Hydrological unit code (HUC) boundaries

  • shapefiles/MSRB/: Mississippi River Basin boundary

  • shapefiles/US_STATES/: US state boundaries

Getting Started

Option 1: Interactive Notebooks (Recommended)

  1. Open Jupyter Lab in the repository:

    jupyter lab

  2. Navigate to examples/notebooks/

  3. Start with downloader_notebook.ipynb

  4. Follow the notebooks in order

Option 2: Run Scripts

  1. Navigate to the examples directory:

    cd examples/scripts

Tips & Best Practices

Data Preparation

  • Always download data before training

  • Cache data to avoid repeated API calls

  • Check for data gaps and quality issues

Model Training

  • Start with shorter prediction horizons (1-3 days)

  • Use GPU acceleration for faster training

  • Monitor validation metrics during training

Visualization

  • Create multiple horizon forecasts for comparison

  • Use SHAP plots to understand model decisions

  • Validate results against real-world observations

Need Help?

  • See API Reference for function documentation

  • Check GitHub Issues for common problems

  • Contribute improvements via pull requests