ST-Forecast

Author: Sandro Hunziker

Maintenance Status

🟢 Active – Ongoing development as part of SAPPHIRE Forecast Tools

---

Overview

Deep learning framework for short-term discharge forecasting in multi-basin hydrological systems. Built on Darts with probabilistic predictions via quantile regression and MC Dropout. The system is designed for operational forecasting in Central Asian basins with hydrology influenced by snow and glacier dynamics - hence strong autoregressive signals. This code was develeoped in the context of the SAPPHIRE project and funded by the Swiss Agency for Development and Cooperation. The code is the backbone of the machine learning based short-term forecasting component in the SAPPHIRE Forecast Tools. Note that this repository is still work in progress.

Installation

uv add st-forecast

Or from source:

git clone <repository-url>
cd DL-Short-Term-Forecasting
uv sync

Quick Start (CLI)

# Run the full pipeline: train → predict → evaluate → visualize
st-forecast pipeline runs/my_experiment --config configs/tide_kgz.json

# Or individual steps
st-forecast train runs/my_experiment --config configs/tide_kgz.json
st-forecast predict runs/my_experiment --split test
st-forecast evaluate runs/my_experiment --split test
st-forecast visualize runs/my_experiment --all-plots

Training a Model (Python API)

train_model() is the high-level entry point for training from external projects. It handles data splitting, scaling, training, and saves all artifacts in a format compatible with SapphirePredictor.

from st_forecast import train_model, RunConfig

config = RunConfig.from_json("configs/tide_kgz.json")
result = train_model(
    temporal_df=my_temporal_data,   # columns: date, code, discharge, P, T, ...
    static_df=my_static_data,       # indexed by basin CODE
    config=config,
    output_path="runs/my_model",
    train_years=[2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008],
    val_years=[2009, 2010],
)
# result.model, result.scalers, result.output_path

Operational Integration (SapphirePredictor)

External applications (e.g., the SAPPHIRE forecast system) use SapphirePredictor to run predictions from a trained model folder:

from st_forecast import SapphirePredictor

predictor = SapphirePredictor("runs/my_model")

# Real-time forecast
forecast = predictor.predict(
    past_measurements=discharge_df,  # columns: date, code, discharge
    covariates=weather_df,           # columns: date, code, P, T, ... (extends n days into future)
    identifier=11111,                # basin code
    n=10,                            # forecast horizon in days
)
# Returns: DataFrame with date, code, Q5, Q10, Q25, Q50, Q75, Q90, Q95

# Historical evaluation (hindcast)
hindcast = predictor.hindcast(
    past_measurements=discharge_df,
    covariates=weather_df,
    identifier=11111,
    n=10,
)
# Returns: DataFrame with date, code, forecast_step, forecast_issue_date, Q5..Q95

# Query model metadata
predictor.get_input_chunk_length()    # e.g., 30
predictor.get_max_forecast_horizon()  # e.g., 10

Configuration

Models are configured via JSON files. See docs/configuration.md for the complete reference.

{
  "region": "KGZ",
  "model_type": "TiDE",
  "model_name": "TiDE_KGZ",
  "input_chunk_length": 30,
  "forecast_horizon": 10,
  "exog_features": ["P", "T", "PET", "daylight_hours"],
  "past_features": ["moving_avr_dis_3", "moving_avr_dis_5", "moving_avr_dis_10"],
  "future_features": ["P", "T", "PET", "daylight_hours"],
  "train_years": [2000, 2001, 2002, 2003, 2004, 2005],
  "val_years": [2006, 2007],
  "test_years": [2008, 2009]
}

Documentation

• User Guide & API — train_model(), SapphirePredictor, CLI usage, evaluation, visualization
• Configuration Guide — Complete RunConfig reference
• Forecasting Approach — Methodology and data pipeline
• Models Overview — Available model architectures
• Evaluation Metrics — NSE, nRMSE, CRPS, flood metrics
• CLI Reference — Full command-line interface documentation