Skip to content

README.md

Latest commit

 

History

History
172 lines (128 loc) · 5.73 KB

README.md

File metadata and controls

172 lines (128 loc) · 5.73 KB
Raw

RVI-Kenya

Riparian Violation Index for Kenya is an open-source geospatial pipeline for quantifying riparian-zone encroachment along Kenya's drainage network and comparing it against Google Flood Hub severity signals.

The full proposal lives in RVI_Kenya_Proposal.md. This README is the operator manual.

What it does

For every 500-metre waterway segment in the analysis area, the pipeline:

  1. Buffers the OSM waterway centreline at the three legal Kenyan setbacks: 6 m, 10 m, and 30 m.
  2. Corrects for centreline-to-bank offset using a Strahler-order half-width.
  3. Spatially joins Microsoft Global ML Building Footprints into each buffer.
  4. Computes three sub-scores per segment:
    • Density: encroaching buildings per kilometre of river.
    • Coverage: fraction of buffer area covered by footprints.
    • Proximity: mean penetration of buildings into the buffer.
  5. Combines them into a raw composite RVI score in [0, 1]: RVI = alpha*D + beta*C + gamma*P, with defaults alpha=0.4, beta=0.3, gamma=0.3.
  6. Optionally emits a DEM-backed terrain-adjusted companion score (rvi_composite_hand*) when a real DEM is supplied.
  7. Optionally derives gauge catchments directly from a DEM after DEM conditioning and drainage-cell snapping.
  8. Validates the index by Spearman-correlating upstream RVI against Google Flood Hub severity.

The same pipeline produces interactive maps, per-segment GeoPackages, county summaries, and a sensitivity-analysis heatmap for the primary buffer width.

Repository layout

rvi-kenya/
|-- docs/
|   |-- CRITIQUE_AND_RECOMMENDATIONS.md
|   `-- HAND_ELEVATION_FILTERING_SPEC.md
|-- pyproject.toml
|-- README.md
|-- METHODOLOGY.md
|-- RVI_Kenya_Proposal.md
|-- .env.example
|-- src/rvi/
|   |-- config.py
|   |-- cli.py
|   |-- ingestion/
|   |   |-- osm.py
|   |   |-- floodhub.py
|   |   `-- buildings.py
|   |-- geometry/
|   |   |-- buffer.py
|   |   `-- segment.py
|   |-- analysis/
|   |   |-- encroachment.py
|   |   |-- rvi.py
|   |   `-- validation.py
|   |-- terrain/
|   |   |-- catchments.py
|   |   `-- elevation.py
|   `-- viz/
|       `-- choropleth.py
|-- tests/
`-- notebooks/

Getting started

1. Install

The pilot path is lean. The national extra adds osmium for Geofabrik PBF ingestion. The phase2 extra adds the DEM stack (pysheds, rasterio, rioxarray) used for catchment delineation and terrain-adjusted scoring.

python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
# bash / zsh
source .venv/bin/activate

pip install -e ".[dev]"
pip install -e ".[dev,national]"
pip install -e ".[dev,national,phase2]"

2. Configure

cp .env.example .env
# edit .env and set FLOODHUB_API_KEY

3. Run tests

python -m pytest -m "not network"

4. Run the Nairobi pilot

rvi pilot --area nairobi
rvi pilot --area nairobi --catchments data/processed/gauge_catchments.gpkg
rvi pilot --area nairobi --dem data/raw/copernicus_dem.tif
# expanded validation pilot using the fixed bbox in Config.nairobi_validation_bbox
rvi pilot --area nairobi_validation --bbox "36.65,-1.45,37.15,-0.40" --dem data/processed/dem/nairobi_plus_gauges_dem_30m.tif

This writes outputs under outputs/nairobi_pilot/, including:

  • rvi_segments.gpkg
  • rvi_segment_map.html
  • rvi_sensitivity_analysis.png
  • validation_summary.json
  • optionally rvi_segment_heatmap.html when GOOGLE_MAPS_API_KEY is set

5. Run the national pipeline

rvi national
rvi national --catchments data/processed/gauge_catchments.gpkg
rvi national --dem data/raw/copernicus_dem.tif

Requires pip install -e ".[national]". The national path streams the Kenya Geofabrik PBF and prefers a cached or DuckDB-assisted building path where available.

Outputs and interpretation

Each run directory can contain:

  • manifest.json: run parameters, input provenance, and summary counts.
  • correlation.json: raw Spearman results.
  • validation_summary.json: explains whether validation is usable, low-sample, DEM-out-of-coverage, no-upstream-overlap, all-NaN, or skipped.
  • encroachment_<width>m.gpkg: per-width encroachment metrics.
  • rvi_segments.gpkg or rvi_segments_kenya.gpkg: merged per-segment scores across widths.

When a DEM is supplied, the scored outputs can include terrain columns such as:

  • terrain_exposure_weight
  • elev_delta_mean_m
  • elev_delta_p75_m
  • elev_delta_max_m
  • rvi_composite_hand

The raw legal score is preserved. Terrain adjustment is additive, not a replacement. DEM metadata in manifest.json records dem_source, dem_resolution, and dem_resolution_unit.

Optional Google Maps heatmap

Setting GOOGLE_MAPS_API_KEY enables one additional output: rvi_segment_heatmap.html, a Google Maps JavaScript heatmap over scored segments.

This is additive alongside the existing Folium outputs, not a replacement.

Reproducibility

  • All numeric parameters live in src/rvi/config.py.
  • Overpass, Geofabrik, county polygons, Microsoft building artifacts, and Flood Hub responses are cached on disk.
  • Each run writes a manifest.json with key parameters, counts, loader choices, and validation mode.
  • Each run also writes validation_summary.json so low-sample validation failures are explicit instead of being inferred from NaN correlations alone.
  • validation_summary.json also distinguishes gauges inside DEM coverage from gauges that actually capture scored upstream segments.
  • When terrain attenuation is enabled, the manifest records terrain_adjustment.
  • A wider DEM alone is not enough for validation; the scored waterway/building extent must also overlap the gauges' upstream catchments.

License

MIT - see LICENSE. Source datasets retain their original licenses.