floodpath 0.1.0

Modular Python pipeline for HAND-based flood inundation and damage estimation.

floodpath

A modular Python pipeline for HAND-based flood inundation and damage estimation.

floodpath chains together everything you need to go from a (lat, lon) point to a per-cell flood damage estimate:

DEM → flow direction → streams → HAND
                                  ↓
                  + GHSL built-up + WorldPop + OSM buildings
                                  ↓
              + JRC Huizinga 2017 depth-damage curves
                                  ↓
                          → 2D damage map

Each layer is a small, well-tested module. Plug in the parts you need, swap in your own data, or extend with new sources.

Install

pip install floodpath

floodpath depends on rasterio and pyflwdir, both of which install cleanly via pip on Linux. On macOS arm64, conda-forge is the smoother path:

conda install -c conda-forge rasterio pyflwdir numpy
pip install floodpath

Quickstart

from floodpath.dem import get_dem
from floodpath.hydrology import build_flow_grid, extract_streams, compute_hand
from floodpath.exposure import get_ghsl_built
from floodpath.damage import (
    JRC_AFRICA_RESIDENTIAL,
    compute_inundation_depth,
    compute_damage,
)

# 1. Fetch a DEM patch (Copernicus GLO-30, ~30 m, no auth)
dem = get_dem(lat=11.805, lon=37.5625, buffer_deg=0.0375)

# 2. Terrain hydrology
grid = build_flow_grid(dem)
streams = extract_streams(grid, threshold=200)
hand = compute_hand(grid, streams, dem)

# 3. Exposure (GHS-BUILT-S, ~90 m built-up surface per cell)
exposure = get_ghsl_built(lat=11.805, lon=37.5625, buffer_deg=0.0375, epoch=2020)

# 4. Damage at a 5 m water level
depth = compute_inundation_depth(hand, water_level=5.0)
damage = compute_damage(depth, exposure, JRC_AFRICA_RESIDENTIAL)

print(f"Total damaged built-up: {damage.values.sum():,.0f} m²")

Modules

Module	Source	What it provides
floodpath.dem	Copernicus GLO-30 (AWS Open Data, COG)	Elevation patch around any (lat, lon)
floodpath.hydrology	derived from DEM via pyflwdir	Flow direction + accumulation, stream networks (with Strahler order), basin delineation, HAND
floodpath.exposure	GHSL R2023A, WorldPop, OpenStreetMap (Overpass)	Built-up surface, population, building footprints
floodpath.damage	JRC Huizinga 2017 + DEM/HAND/GHSL	Per-cell flood depth and damage in m² of built-up surface

Depth-damage curves

floodpath.damage ships 26 continental-average curves from JRC's Huizinga et al. 2017 Global flood depth-damage functions report — covering residential, commerce, industry, transport, infrastructure and agriculture asset classes across up to six continents.

from floodpath.damage import jrc_curve

curve = jrc_curve(asset_class="residential", continent="north_america")
fractions = curve(depths_m=np.array([0.0, 0.5, 1.0, 2.0, 5.0]))

Coverage gaps from the original report are preserved: jrc_curve("commerce", "africa") raises KeyError rather than fabricating data.

Test fixtures and offline development

floodpath ships with a small set of committed test fixtures (Robit Bata watershed, northern Ethiopia) so contributors can iterate without hitting the network:

pytest -m "not integration"   # ~0.1 s, no network
pytest                        # full suite, ~1 minute (downloads ~25 MB)

The fixtures (committed binaries totalling ~330 KB) are regenerated by scripts under tests/fixtures/_generate_*.py whenever an upstream source changes.

Status

floodpath is alpha. The pipeline produces sensible flood/damage maps for static water-level scenarios, but does not yet model:

• Time-resolved hydraulics (no Saint-Venant solver)
• Rainfall → runoff routing (planned for v0.2)
• Soil moisture / infiltration (planned for v0.2)
• 2D shallow-water dynamics (not planned yet!)

If you need those, look at LISFLOOD-FP, HEC-RAS 2D, or WFlow.

Citation

If you use floodpath in academic work, please cite the underlying datasets too:

• DEM: Copernicus DEM GLO-30, ESA / Airbus, doi:10.5270/ESA-c5d3d65
• Built-up surface: GHSL Data Package 2023, JRC, doi:10.2760/098587
• Population: WorldPop, University of Southampton, doi:10.5258/SOTON/WP00674
• Damage curves: Huizinga, J., de Moel, H. and Szewczyk, W. (2017). Global flood depth-damage functions: Methodology and the database with guidelines. JRC Technical Report EUR 28552 EN, doi:10.2760/16510

License

MIT — see LICENSE.