Metadata-Version: 2.4
Name: torchriver
Version: 2.0.1
Summary: River low-flow and drought forecasting with TorchRiver
Author: TorchRiver Contributors
License: MIT
Project-URL: Repository, https://github.com/torchriver/torchriver
Project-URL: Notebooks, https://github.com/torchriver/torchriver/blob/main/notebooks/
Project-URL: Quick Start Notebook, https://github.com/torchriver/torchriver/blob/main/notebooks/TorchRiver_Quick_Start.ipynb
Project-URL: Small Quick Start Notebook, https://github.com/torchriver/torchriver/blob/main/notebooks/TorchRiver_Quick_Start_small.ipynb
Project-URL: Examples, https://github.com/torchriver/torchriver/tree/main/examples
Project-URL: Documentation, https://github.com/torchriver/torchriver/tree/main/docs
Project-URL: Tests, https://github.com/torchriver/torchriver/tree/main/tests
Keywords: rivers,drought,low-flow,pytorch,gradio,time-series,hydrology
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: torch>=2.0
Requires-Dist: scikit-learn>=1.2
Requires-Dist: joblib>=1.2
Requires-Dist: matplotlib>=3.7
Requires-Dist: gradio>=4.0
Requires-Dist: opendatasets>=0.1.22
Requires-Dist: kaggle>=1.6
Requires-Dist: openpyxl>=3.1
Requires-Dist: pyarrow>=12
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: nbformat>=5; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: ui
Requires-Dist: gradio>=4.0; extra == "ui"
Requires-Dist: gradio_client>=1.0; extra == "ui"
Provides-Extra: kaggle
Requires-Dist: opendatasets>=0.1.22; extra == "kaggle"
Requires-Dist: kaggle>=1.6; extra == "kaggle"
Provides-Extra: all
Requires-Dist: torchriver[dev,kaggle,ui]; extra == "all"
Dynamic: license-file

# 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`:

```text
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

```bash
pip install torchriver
```

In Google Colab:

```python
%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

```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

```python
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

```bash
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:

```text
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:

```python
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:

```python
target_lowflow = discharge_m3s < low_flow_q10_threshold_m3s
```

## Prediction

```python
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

```python
project.launch_river_style(share=True, api=True, direction="rtl")
```

Client usage:

```python
from gradio_client import Client

client = Client("GRADIO_URL")
client.predict("501060 - DRESDEN", "+14 days", api_name="/predict")
```

## Save/load

```python
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

```bash
pytest
```

## Repository folders

```text
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
