TorchRiver is a Python library for river low-flow and drought early warning. It provides a notebook-friendly workflow for loading river data, training forecasting models, predicting low-flow risk, saving .triver models, and launching an Arabic RTL Gradio interface.
The default architecture is river_cnn_lstm:
Conv1D -> ReLU -> MaxPool1D -> LSTM -> Dense -> probability/logit
Available architectures:
| Name | Description |
|---|---|
river_cnn_lstm |
Conv1D + LSTM hybrid (default, recommended) |
cnn_lstm |
Alias for river_cnn_lstm
|
lstm |
Pure LSTM recurrent model |
gru |
GRU recurrent model |
cnn |
Pure convolutional model |
mlp |
Multi-layer perceptron (fully connected) |
transformer |
Transformer encoder model |
custom |
Bring your own nn.Module
|
Repository: https://github.com/torchriver/torchriver
pip install torchriverIn Google Colab:
%pip install -q torchriverOpen the main full notebook:
- GitHub:
notebooks/TorchRiver_Quick_Start.ipynb - Colab:
https://colab.research.google.com/github/torchriver/torchriver/blob/main/notebooks/TorchRiver_Quick_Start.ipynb
A smaller compact notebook is also included:
- GitHub:
notebooks/TorchRiver_Quick_Start_small.ipynb - Colab:
https://colab.research.google.com/github/torchriver/torchriver/blob/main/notebooks/TorchRiver_Quick_Start_small.ipynb
from torchriver import RiverProject
project = RiverProject(title="TorchRiver", lang="ar", direction="rtl")
project.make_synthetic(
days=240,
station_codes=["R001", "R002", "R003"],
station_names={"R001": "River One", "R002": "River Two", "R003": "River Three"},
)
project.clean()
project.use_model(
"river_cnn_lstm",
horizons=[7, 14, 30],
lookback=30,
device="auto",
window_mode="per_station",
balance_classes=True,
)
project.train(epochs=2, batch_size=512, lr=0.001, seed=42)
print(project.predict_all(horizon=14))
project.save_model("river_warning_model.triver", include_recent_data=True)import os, getpass
from torchriver import RiverProject
KAGGLE_URL = "https://www.kaggle.com/datasets/assemelqirsh/elbe-river-data-lake"
os.environ["KAGGLE_USERNAME"] = "YOUR_KAGGLE_USERNAME"
os.environ["KAGGLE_KEY"] = getpass.getpass("Paste Kaggle API key/token hidden: ")
project = RiverProject(title="TorchRiver", lang="ar", direction="rtl")
project.load_kaggle(KAGGLE_URL, nrows=200_000, fallback_synthetic=False)
project.clean()
project.use_model("river_cnn_lstm", horizons=[7, 14, 30], lookback=30, window_mode="per_station", balance_classes=True)
project.train(epochs=2, batch_size=512, lr=0.001)
print(project.predict_all(horizon=14))TorchRiver never stores Kaggle API keys. Use KAGGLE_USERNAME and KAGGLE_KEY, Kaggle's standard ~/.kaggle/kaggle.json, or a hidden prompt.
All notebooks install TorchRiver from PyPI with %pip install -q torchriver.
| Notebook | Purpose | Colab link template |
|---|---|---|
notebooks/TorchRiver_Quick_Start.ipynb |
Main full quick-start runner | https://colab.research.google.com/github/torchriver/torchriver/blob/main/notebooks/TorchRiver_Quick_Start.ipynb |
notebooks/TorchRiver_Quick_Start_small.ipynb |
Small compact quick start | https://colab.research.google.com/github/torchriver/torchriver/blob/main/notebooks/TorchRiver_Quick_Start_small.ipynb |
notebooks/02_quick_start_synthetic_train_predict.ipynb |
Synthetic training and prediction | https://colab.research.google.com/github/torchriver/torchriver/blob/main/notebooks/02_quick_start_synthetic_train_predict.ipynb |
notebooks/03_kaggle_url_train_river.ipynb |
Kaggle URL training | https://colab.research.google.com/github/torchriver/torchriver/blob/main/notebooks/03_kaggle_url_train_river.ipynb |
notebooks/08_save_load_triver.ipynb |
Save/load .triver models |
https://colab.research.google.com/github/torchriver/torchriver/blob/main/notebooks/08_save_load_triver.ipynb |
notebooks/09_gradio_rtl_arabic.ipynb |
Arabic RTL Gradio UI | https://colab.research.google.com/github/torchriver/torchriver/blob/main/notebooks/09_gradio_rtl_arabic.ipynb |
See notebooks/00_INDEX.ipynb for the full notebook list.
pip install torchriver
python examples/01_train_synthetic.py
python examples/02_train_kaggle_url.pySee examples/README.md for all script examples.
Default columns:
date
station_code
station
discharge_m3s
low_flow_q10_threshold_m3s
sdi_30
precipitation_mm
temperature_c
ndwi
target_lowflow
Custom schemas are supported through mapping:
project.load_file(
"my_river_data.csv",
mapping={
"date": "day",
"station": "gauge_id",
"station_name": "gauge_name",
"discharge": "Q_m3s",
"low_flow_threshold": "Q10",
"target": "low_flow_flag",
},
)If a threshold is missing, TorchRiver computes Q10 per station. If the target is missing, it creates:
target_lowflow = discharge_m3s < low_flow_q10_threshold_m3sproject.predict(station="501060", horizon=14)
project.predict_all(horizon=14)
project.diagnose_predictions(horizon=14)Prediction uses the last lookback days for the selected station. TorchRiver does not reuse the same last rows for every station.
project.launch_river_style(share=True, api=True, direction="rtl")Client usage:
from gradio_client import Client
client = Client("GRADIO_URL")
client.predict("501060 - DRESDEN", "+14 days", api_name="/predict")project.save_model("river_warning_model.triver", include_recent_data=True)
from torchriver import load_river_model
loaded = load_river_model("river_warning_model.triver")
loaded.predict(station="501060", horizon=14)pytestdocs/ Documentation
examples/ Runnable Python examples
notebooks/ Colab and Jupyter notebooks
data/ Small sample datasets
tests/ Pytest tests
