A Jupyter notebook for basin-scale water accounting using the WA+ Hyperloop framework. Produces monthly and annual water balance sheets (Sheet 1–5) from remote sensing data.
This repository contains patched versions of IHEWAEngine and WA_Hyperloop updated for Python 3.10+ and current library versions (NumPy 2.x, pandas 2.x, matplotlib 3.5+). All changes are documented in SETUP_GUIDE_v2.md.
The notebook runs a four-phase water accounting workflow for any river basin:
| Phase | Description | Key outputs |
|---|---|---|
| 1 | Download remote sensing data | CHIRPS, MODIS ET/LAI/GPP, GLDAS, GLEAM GeoTIFFs |
| 2 | Land use classification | WA+ LULC map from MODIS MCD12Q1 |
| 3 | WaterPix hydrological model | Monthly water balance NetCDF |
| 4 | WA+ Hyperloop sheet generation | Sheet 1–5 monthly PDFs |
# 1. Clone this repository
git clone https://github.com/nsashi/water-accounting.git
cd water-accounting
# 2. Install wheels (Windows only -- skip on Linux/macOS, use conda instead)
pip install wheels/GDAL-3.12.2-cp313-cp313-win_amd64.whl
pip install wheels/fiona-1.10.1-cp313-cp313-win_amd64.whl
pip install wheels/netcdf4-1.7.4-cp313-cp313-win_amd64.whl
# 3. Install Python dependencies
pip install -r setup_package/requirements.txt
pip install IHEWAcollect
pip install -e IHEWAEngine
# 4. Patch IHEWAcollect (IHEWAEngine is already patched in this repo)
python setup_package/apply_patches.py
# 5. Add your credentials
cp config/accounts.yml.template config/accounts.yml
# Edit config/accounts.yml -- add NASA Earthdata and GLEAM passwords
# 6. Verify and launch
python test_setup.py
jupyter lab Water_Accounting_Interface_v2.ipynbFor full instructions including Linux/macOS setup, virtual environments, and global static data sources, see SETUP_GUIDE_v2.md.
- Python 3.10, 3.11, or 3.13 (3.13 tested)
- Windows 10/11 64-bit (Linux/macOS supported via conda -- see setup guide)
- 8 GB RAM minimum; 16 GB recommended
- 20 GB free disk space
Free data provider accounts required:
| Service | URL | Used for |
|---|---|---|
| NASA Earthdata | https://urs.earthdata.nasa.gov/ | MODIS, GLDAS, GRACE |
| GLEAM | https://www.gleam.eu/ | Evapotranspiration |
| Copernicus CDS | https://cds.climate.copernicus.eu/ | ERA5 (optional) |
CHIRPS precipitation does not require an account.
water-accounting/
|-- Water_Accounting_Interface_v2.ipynb # main notebook
|-- IHEWAEngine/ # patched IHEWAEngine (see below)
|-- setup_package/
| |-- apply_patches.py # patches IHEWAcollect after pip install
| `-- requirements.txt # pip dependencies
|-- wheels/ # pre-built Windows wheels (GDAL, Fiona, NetCDF4)
|-- config/
| `-- accounts.yml.template # credential template (copy to accounts.yml)
|-- shapefiles/ # example basin boundary
|-- test_setup.py # installation check
`-- SETUP_GUIDE_v2.md # full setup documentation
Not included (must be downloaded -- see SETUP_GUIDE_v2.md §8):
data/global_static/-- population (WorldPop), cattle density (FAO GLW3), DEM and flow direction (HydroSHEDS) -- files are too large for GitHubconfig/accounts.yml-- your credentials (gitignored)test_data/andoutput/-- generated during notebook run (gitignored)
The original IHEWA packages require several fixes to run on Python 3.10+ with
current library versions. This repository includes a pre-patched IHEWAEngine/.
IHEWAcollect is installed from PyPI and patched in-place by apply_patches.py.
| File | Patch |
|---|---|
__init__.py |
pkg_resources -> importlib.metadata; NumPy 2.x type alias restoration |
download.py |
os.rmdir() wrapped in try/except OSError (cloud sync compatibility) |
templates/USGS/MODIS_products.py |
cores=0 (serial mode); log_file.Log.write -> log_file.write |
templates/download_tiles_test.py |
Added _EarthdataSession class for NASA auth redirects |
| File | Patch |
|---|---|
src/IHEWAengine/__init__.py |
pkg_resources -> importlib.metadata |
engine1/WaterPix/main.py |
Remove pd.np; fix list(range()); filter months to NetCDF contents |
engine1/WaterPix/functions.py |
Remove pd.np; set_value -> .at[]; rpy2 optional; .apply() axis fix |
engine2/Hyperloop/sheet1-7.py |
_svg_to_pdf() wrapper (cairosvg or svglib fallback); plt.grid(b=) fix |
engine2/Hyperloop/sheet4.py |
np.string_ -> np.bytes_; pd.np. -> np.; getchildren() fix; margin=100.0; dynamic sort |
engine2/Hyperloop/sheet5.py |
WaterPix dot-format filenames (2020.01); rmtree guard |
engine2/Hyperloop/hyperloop.py |
pd.np. -> np.; np.float -> float; np.str -> str |
engine2/Hyperloop/temporal/basic.py |
Year range 1900-2100; include December in month range |
engine2/Hyperloop/WA_Hyperloop/find_possible_dates.py |
Year range 1900-2100 |
engine2/Hyperloop/spatial/basic.py |
GDAL dtype fallback; float32 cast before NaN assignment |
Full patch rationale is in SETUP_GUIDE_v2.md §5-6 and in the developer reference block at the bottom of setup_package/apply_patches.py.
Open Water_Accounting_Interface_v2.ipynb and edit Cell 2 (master config):
BASIN_NAME = "YourBasin" # used for output folder names
BBOX = {w: .., n: .., e: .., s: ..} # bounding box in decimal degrees
START_DATE = "2020-01-01"
END_DATE = "2020-12-31"
SHAPEFILE_PATH = "shapefiles/your_basin.shp"
DOWNLOAD_CHIRPS = True # set False after first download
DOWNLOAD_MODIS = True
# ... other DOWNLOAD_* flagsThen run cells in order (Phase 1 -> 2 -> 3 -> 4).
| Dataset | Source | Notes |
|---|---|---|
| Population density | https://hub.worldpop.org/geodata/listing?id=75 | Download UN-adjusted GeoTIFF for your country/year |
| Cattle density | https://www.fao.org/livestock-systems/global-distributions/en/ | FAO GLW3, Cattle Dasymetric raster |
| HydroSHEDS DEM (15s) | https://www.hydrosheds.org/products/hydrosheds | DEM and Flow Direction for your continent |
Place downloaded files in data/global_static/ as described in
SETUP_GUIDE_v2.md §8.
This work builds on the IHE Delft Water Accounting tools:
- IHEWAcollect: https://github.com/wateraccounting/IHEWAcollect
- IHEWAEngine: https://github.com/wateraccounting/IHEWAEngine
- WA_Hyperloop: https://github.com/wateraccounting/WA_Hyperloop
WA+ framework: https://www.wateraccounting.org/
Remote sensing data sources: NASA Earthdata (MODIS, GLDAS, GRACE), GLEAM, UCSB CHIRPS, WorldPop, FAO GLW3, HydroSHEDS.
The patches and notebook in this repository are released under the Apache 2.0 License, consistent with the upstream IHEWAEngine license. The original IHEWAEngine and WA_Hyperloop source code retains its original license.