Quick Start

Installation

If you haven’t installed GaugePredict yet, see the Installation guide.

Basic Usage

Downloading USGS Data

Start by downloading discharge data for a USGS gauge site:

from GaugePredict.downloader import download_usgs_data

# Download discharge data for a site
data = download_usgs_data(
    site_id="07374000",
    start_date="2020-01-01",
    end_date="2023-12-31",
    parameter="00060"  # Discharge in cubic feet per second
)

print(data.head())  # View first few rows

Training a Forecast Model

Train a neural network model to forecast discharge. run_horizon expects preprocessed predictor files (see the downloader notebook) plus a small hyperparameter dictionary:

import torch.nn as nn
from GaugePredict.predict import run_horizon

hp = {
    "sequence_length": 30,
    "cutoff_date": "2023-01-01",
    "batch_size": 32,
    "epochs": 50,
    "learning_rate": 1e-3,
    "weight_decay": 1e-4,
    "loss_function": nn.MSELoss(),
    "max_grad_norm": 1.0,
}

results = run_horizon(
    forecast_horizon=7,
    data_files="path/to/predictor/files",  # directory or file bundle produced by downloader
    use_csv_target=False,
    target_site="07374000",
    target_parameter_code="00060",
    start_date="2020-01-01",
    end_date="2023-12-31",
    tz="UTC",
    hp=hp,
    device="cuda"  # or "cpu"
)

print(f"Model Performance: R² = {results['metrics']['r2']}")

Working With Results

The results dict returned by run_horizon includes:

  • metrics: R², NSE, and Willmott index for the test split

  • y_pred / y_true: arrays in original units

  • history: per-epoch training metrics

  • model_path: where the trained model is saved (if you set out_dir)

Complete Workflow

For comprehensive examples, explore the Jupyter notebooks in the examples/notebooks/ directory:

1. Data Preparation (downloader_notebook.ipynb)

  • Download and preprocess basin-wide USGS data

  • Align time series across multiple gauge sites

  • Handle missing values and data quality issues

2. Model Training (training_notebook.ipynb)

  • Train CNN-LSTM models for multiple forecast horizons (1-30 days)

  • Evaluate performance with hydrological metrics (NSE, R², RMSE)

  • Visualize training history and loss curves

3. Visualization & Analysis (figure_creating_notebook.ipynb)

  • Generate forecast performance plots

  • Create SHAP site selection maps

  • Analyze feature importance across time

Common Tasks

Download Data

Retrieve USGS data using downloader module

Train Models

Build neural networks with predict module

Visualize Results

Create plots with plotting module

Next Steps

  • Read the API Reference documentation for detailed function references

  • Explore the Examples for advanced workflows

  • Check out the GitHub repository for source code and contributions

Need Help?

  • Documentation: See the API Reference section for function details

  • Issues: Report bugs on GitHub Issues

  • Examples: Look for Jupyter notebooks in examples/notebooks/

For detailed examples, see the Examples page.