Laaroyussuf/flood-ews-lokoja

Flood early warning system for Lokoja, Nigeria. LSTM forecasts Niger-Benue river discharge from free satellite and reanalysis data, served through a FastAPI app and dashboard. # Niger-Benue Flood Early Warning System A streamflow forecasting and flood alert system for Lokoja, Nigeria, where the Niger and Benue rivers meet. An LSTM forecasts river discharge 3 and 7 days ahead and flags flood alerts, served through a FastAPI app with a small web dashboard. This covers Lokoja only, not other Nigerian rivers or cities. See Scope. **Status**: data pipeline, EDA, and the trained model are done and wired into the API and dashboard. Real numbers are in Results. A separately trained classification head and SHAP explanations (originally planned for weeks 8-9) aren't built yet. A correctness audit on 2026-08-04 found two real bugs (a coordinate error and an undersized catchment box), both fixed and re-verified. Details are in Limitations. ## Why Lokoja The Niger and Benue meet at Lokoja (7.80194°N, 6.74417°E). The 2022 flood there, worsened by an emergency release from the Lagdo Dam in Cameroon, is remembered as the worst flood in the confluence's living memory and is used as a stress test for the model (GloFAS's own naturalized discharge series ranks it differently, see Limitations). Data-driven flood forecasting is common globally but still rare in Nigeria. This project is an attempt to close that gap for one real, high-stakes location. ## Scope Niger-Benue is a system of two rivers; Lokoja is where they merge, and it's the only place this project models. There's no national coverage and none planned. The model, API, and every number below are specific to this one gauge. Extending to other locations (Makurdi and Onitsha were mentioned in the original brief) would mean repeating the whole pipeline and retraining per location. ## Architecture ``` CHIRPS (precipitation) ──────────┐ ERA5-Land (temp, soil moisture) ─┼─► LSTM (PyTorch) ─► Flood Alert API (FastAPI) GloFAS-ERA5 (discharge) ─────────┘ ``` - **Precipitation**: CHIRPS, daily, 0.05°, averaged over the Niger-Benue catchment box. - **Discharge (target)**: GloFAS-ERA5 reanalysis, snap …