TorchRiver

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

Installation

pip install torchriver

In Google Colab:

%pip install -q torchriver

TorchRiver Quick Start

Open the main full notebook:

• GitHub: https://github.com/torchriver/torchriver/blob/main/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: https://github.com/torchriver/torchriver/blob/main/notebooks/TorchRiver_Quick_Start_small.ipynb
• Colab: https://colab.research.google.com/github/torchriver/torchriver/blob/main/notebooks/TorchRiver_Quick_Start_small.ipynb

Quick start in Python

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)

Kaggle example

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.

Notebooks

All notebooks install TorchRiver from PyPI with %pip install -q torchriver.

Notebook	Purpose	GitHub	Colab
notebooks/TorchRiver_Quick_Start.ipynb	Main full quick-start runner	https://github.com/torchriver/torchriver/blob/main/notebooks/TorchRiver_Quick_Start.ipynb	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://github.com/torchriver/torchriver/blob/main/notebooks/TorchRiver_Quick_Start_small.ipynb	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://github.com/torchriver/torchriver/blob/main/notebooks/02_quick_start_synthetic_train_predict.ipynb	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://github.com/torchriver/torchriver/blob/main/notebooks/03_kaggle_url_train_river.ipynb	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://github.com/torchriver/torchriver/blob/main/notebooks/08_save_load_triver.ipynb	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://github.com/torchriver/torchriver/blob/main/notebooks/09_gradio_rtl_arabic.ipynb	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:

https://github.com/torchriver/torchriver/blob/main/notebooks/00_INDEX.ipynb

Examples

pip install torchriver
python examples/01_train_synthetic.py
python examples/02_train_kaggle_url.py

See examples/README.md for all script examples:

https://github.com/torchriver/torchriver/blob/main/examples/README.md

Compatible data format

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_m3s

Prediction

project.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.

Gradio API

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")

Save/load

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)

Tests

pytest

Repository folders

docs/       Documentation
examples/   Runnable Python examples
notebooks/  Colab and Jupyter notebooks
data/       Small sample datasets
tests/      Pytest tests

Links

• Repository: https://github.com/torchriver/torchriver
• Notebooks: https://github.com/torchriver/torchriver/blob/main/notebooks/
• Quick Start Notebook: https://github.com/torchriver/torchriver/blob/main/notebooks/TorchRiver_Quick_Start.ipynb
• Small Quick Start Notebook: https://github.com/torchriver/torchriver/blob/main/notebooks/TorchRiver_Quick_Start_small.ipynb
• Examples: https://github.com/torchriver/torchriver/tree/main/examples
• Docs: https://github.com/torchriver/torchriver/tree/main/docs
• Tests: https://github.com/torchriver/torchriver/tree/main/tests

License

MIT