Bakaano-Hydro Documentation

Introduction

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.

The name Bakaano comes from Fante, a language spoken along the southern coast of Ghana. Loosely translated as “by the river side” or “stream-side”, it reflects the lived reality of many vulnerable riverine communities across the Global South - those most exposed to flood risk and often least equipped to adapt.

Bakaano-Hydro consists of three tightly coupled components:

1. Distributed runoff generation Vegetation, soil, and meteorological drivers are used to compute grid-cell runoff using a VegET-based approach.

2. Physically informed routing Runoff is routed through the river network using flow-direction-based routing (e.g. MFD/WFA), preserving spatial connectivity.

3. Neural network A Temporal Convolutional Network (TCN), conditioned on static catchment descriptors, learns hydrological dynamics from physically routed runoff, enabling robust generalization across diverse basins.

The neural network augments hydrology, it does not replace it.

Conceptual overview of the Bakaano-Hydro pipeline.

Contents

Start with Colab

Recommended entry point for new users:

• Open in Colab

• Notebook source on GitHub

Getting Started

• Installation
  • Requirements
  • Create a new environment
  • Install (GPU)
  • Install (CPU)
  • Data requirements
• Quick Start
  • Colab Notebook (Recommended)
  • 1) Setup working directory and study area
  • 2) Download and preprocess input data
  • 3) Computing runoff and routing to river network
  • 4) Explore input data, river networks and stations interactively
  • 5) Training, evaluating and applying Bakaano-Hydro
• Inputs and Outputs
  • Global assumptions
  • Observed streamflow CSV schema
  • Predicted streamflow units
  • Module reference
• Model Configuration
  • User-defined inputs
  • Recommended settings
• Troubleshooting
  • Google Earth Engine authentication
  • No stations found inside the basin
  • Missing columns in CSVs
  • Predictions are all zeros or flatlines
  • Missing or empty raster inputs
  • Observed streamflow dates out of range
  • Mismatched routing method
  • Unsupported climate data source
  • AlphaEarth scaling or missing scaler
  • Model outputs in unexpected units

Reference

• API Structure
  • High-level entry points
  • Data preparation modules
  • Hydrology modules
  • Plotting helpers
• API Reference
  • Core modules

Indices and tables

• Index

• Module Index

• Search Page