Metadata-Version: 2.4
Name: floodpath
Version: 0.1.0
Summary: Modular Python pipeline for HAND-based flood inundation and damage estimation.
Author-email: Reza Ehsani <rezaa.ehsaani@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/rehsani/floodpath
Project-URL: Repository, https://github.com/rehsani/floodpath
Project-URL: Issues, https://github.com/rehsani/floodpath/issues
Keywords: flood,hydrology,geospatial,DEM,HAND,inundation,damage,remote-sensing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: rasterio>=1.3
Requires-Dist: pyflwdir>=0.5
Dynamic: license-file

# floodpath

[![tests](https://github.com/rehsani/floodpath/actions/workflows/tests.yml/badge.svg)](https://github.com/rehsani/floodpath/actions/workflows/tests.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

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

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

## Quickstart

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

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

```bash
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](https://www.bristol.ac.uk/geography/research/hydrology/models/lisflood/), [HEC-RAS 2D](https://www.hec.usace.army.mil/software/hec-ras/), or [WFlow](https://github.com/Deltares/Wflow.jl).

## 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](LICENSE).
