Metadata-Version: 2.4
Name: bakaano-hydro
Version: 1.2.2
Summary: Distributed hydrology-guided neural network for streamflow prediction
Home-page: https://github.com/confidence-duku/bakaano-hydro
Author: Confidence Duku
Author-email: confidence.duku@gmail.com
License: Apache 2.0
Project-URL: Source, https://github.com/confidence-duku/bakaano-hydro
Project-URL: Bug Tracker, https://github.com/confidence-duku/bakaano-hydro/issues
Project-URL: Documentation, https://github.com/confidence-duku/bakaano-hydro#readme
Keywords: hydrology earth system flood forecasting deep learning streamflow prediction climate risk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dask==2024.11.2
Requires-Dist: earthengine-api==1.4.3
Requires-Dist: fiona==1.10.1
Requires-Dist: future==1.0.0
Requires-Dist: geemap==0.35.1
Requires-Dist: geopandas==1.0.1
Requires-Dist: hydroeval==0.1.0
Requires-Dist: isimip-client==1.0.1
Requires-Dist: keras==3.6.0
Requires-Dist: localtileserver==0.10.6
Requires-Dist: leafmap==0.43.6
Requires-Dist: keras-tcn==3.5.6
Requires-Dist: matplotlib==3.9.2
Requires-Dist: netCDF4==1.7.2
Requires-Dist: numpy==1.26.4
Requires-Dist: pandas==2.2.3
Requires-Dist: pysheds==0.3.3
Requires-Dist: rasterio==1.4.2
Requires-Dist: requests==2.32.3
Requires-Dist: rioxarray==0.18.1
Requires-Dist: scipy==1.14.1
Requires-Dist: shapely==2.0.6
Requires-Dist: tensorflow==2.18.0
Requires-Dist: tensorflow_probability==0.25.0
Requires-Dist: tf_keras==2.18.0
Requires-Dist: xarray==2024.10.0
Requires-Dist: tqdm==4.67.1
Requires-Dist: scikit-learn==1.5.2
Provides-Extra: gpu
Requires-Dist: nvidia-cublas-cu12==12.5.3.2; extra == "gpu"
Requires-Dist: nvidia-cuda-cupti-cu12==12.5.82; extra == "gpu"
Requires-Dist: nvidia-cuda-nvcc-cu12==12.5.82; extra == "gpu"
Requires-Dist: nvidia-cuda-nvrtc-cu12==12.5.82; extra == "gpu"
Requires-Dist: nvidia-cuda-runtime-cu12==12.5.82; extra == "gpu"
Requires-Dist: nvidia-cudnn-cu12==9.3.0.75; extra == "gpu"
Requires-Dist: nvidia-cufft-cu12==11.2.3.61; extra == "gpu"
Requires-Dist: nvidia-curand-cu12==10.3.6.82; extra == "gpu"
Requires-Dist: nvidia-cusolver-cu12==11.6.3.83; extra == "gpu"
Requires-Dist: nvidia-cusparse-cu12==12.5.1.3; extra == "gpu"
Requires-Dist: nvidia-nvjitlink-cu12==12.5.82; extra == "gpu"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

[![DOI](https://zenodo.org/badge/923830097.svg)](https://doi.org/10.5281/zenodo.15227201) [![License](https://img.shields.io/github/license/confidence-duku/bakaano-hydro.svg)](https://github.com/confidence-duku/bakaano-hydro/blob/main/LICENSE) [![PyPI version](https://badge.fury.io/py/bakaano-hydro.svg)](https://pypi.org/project/bakaano-hydro/)
 [![GitHub release](https://img.shields.io/github/v/release/confidence-duku/bakaano-hydro.svg)](https://github.com/confidence-duku/bakaano-hydro/releases) [![Last Commit](https://img.shields.io/github/last-commit/confidence-duku/bakaano-hydro.svg)](https://github.com/confidence-duku/bakaano-hydro/commits/main) [![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)

# Bakaano-Hydro

## Description

Bakaano-Hydro is a distributed hydrology-guided neural network model for streamflow prediction. It uniquely integrates physically based hydrological principles with the generalization capacity of machine learning in a spatially explicit and physically meaningful way. This makes it particularly valuable in data-scarce regions, where traditional hydrological models often struggle due to sparse observations and calibration limitations, and where current state-of-the-art data-driven models are constrained by lumped modeling approaches that overlook spatial heterogeneity and the inability to capture hydrological connectivity. 

By learning spatially distributed, physically meaningful runoff and routing dynamics, Bakaano-Hydro is able to generalize across diverse catchments and hydro-climatic regimes. This hybrid design enables the model to simulate streamflow more accurately and reliably—even in ungauged or poorly monitored basins—while retaining interpretability grounded in hydrological processes.

![image](https://github.com/user-attachments/assets/8cc1a447-c625-4278-924c-1697e6d10fbf)

## Key Features
- **Distributed architecture**: Captures spatial heterogeneity of hydrological processes using gridded runoff and flow routing.
- **Hybrid modeling**: Combines physically based hydrology with deep learning for enhanced accuracy and realism.
- **Scalable and generalizable**: Trains a single model across basins, regions, or continents—no need for basin-specific calibration.
- **Reliable in data-scarce regions**: Designed to perform well even with sparse observational data.
- **High-performance ready**: Compatible with GPU acceleration for fast training and inference on large-scale datasets.
- **Seamless integration**: Modular components allow for easy adaptation with other runoff models, routing schemes, or neural network architectures.
- **Automated end-to-end pipeline**: From climate data ingestion and preprocessing to runoff simulation, routing, and streamflow prediction—Bakaano-Hydro automates the entire workflow with minimal user intervention.
- **Easy deployment**: Installable via pip and designed with reproducibility in mind.
- **Versatile applications**: Suitable for streamflow forecasting, climate adaptation planning, flood risk assessment, and more.

## Installation

Bakaano-Hydro is built on TensorFlow and is designed to leverage GPU acceleration for training. This requires a system with an NVIDIA GPU installed or bundled CUDA and cuDNN runtime libraries.
GPU acceleration is strongly recommended for training deep learning components and running large-scale simulations, as it significantly improves speed and scalability.

If you have a compatible NVIDIA GPU and drivers installed, install with:

```bash
pip install bakaano-hydro[gpu]
```

This will automatically install the correct version of TensorFlow along with CUDA and cuDNN runtime libraries

If you do not have access to a GPU, you can still install and use Bakaano-Hydro in CPU mode (e.g., for inference, testing or small-scale evaluation):

```bash
pip install bakaano-hydro
```

Note: Training on CPU is supported but will be significantly slower, especially on large datasets or deep learning tasks.

## Getting started / Example notebooks

Bakaano-Hydro requires three primary data or inputs

1. Shapefile of study area or river basin
2. Observed streamflow data in NetCDF format from Global Runoff Data Center (<https://portal.grdc.bafg.de/applications/public.html?publicuser=PublicUser#dataDownload/Home>). Because Bakaano-Hydro aims to use only open-source data, it currently accepts observed streamflow data only from GRDC.
3. Registration at Google Earth Engine (<https://code.earthengine.google.com/register>). Bakaano-Hydro retrieves, NDVI, tree cover and meteorological variables from ERA5-land or CHIRPS from Google Earth Engine Data Catalog. This platform requires prior registration for subsequent authentication during execution of the model

Model execution then involves only a few guided steps. See the quick start notebook <https://github.com/confidence-duku/bakaano-hydro/blob/main/quick_start.ipynb> for guidance.

## Code architecture

![bakaanohydro-2025-04-16-132235](https://github.com/user-attachments/assets/4a98f643-b703-4352-bfd7-3d4d13e9fdfe)

## Support

For assistance, please contact Confidence Duku (<confidence.duku@wur.nl>)

## Contributing

No contributions are currently accepted.

## Authors and acknowledgment

See CITATION.cff file.

Bakaano-Hydro was developed as part of Wageningen University & Research Investment theme 'Data-driven discoveries in a changing climate' and also as part of the KB program 'Climate resilient land use'.

## License

Apache License
