GeoAID methods log

---

Notebook 01 — Study Area Definition

• Dataset: FAO GAUL 2015 Level 2
• GEE filter fix: used stringContains() due to leading space in ' Amuwo Odofin' GAUL entry
• Tier 1 (Conceptual): Lagos State — 1 feature confirmed
• Tier 2 (Empirical): Amuwo Odofin LGA — 1 feature confirmed
• Boundary exported: data/amuwo_odofin_boundary.geojson

---

Notebook 02 — DEM and Topographic Feature Extraction

• Primary DEM: SRTM 30m (USGS/SRTMGL1_003)
• Flow accumulation: HydroSHEDS 15-arc-second (WWF/HydroSHEDS/15ACC)
• Curvature: computed via Laplacian8 convolution kernel (ee.Terrain.products() does not include curvature — known GEE API limitation)
• All bands cast to Float32 before stacking to resolve Int16/Float32 type conflict
• Export scale: 30 metres | CRS: EPSG:4326
• Output file: topo_features_amuwo_odofin.tif | File size: 2.1MB

Pixel Count per Band at 30m Resolution:

• Total candidate sample pool: ~197,000 observations
• Planned training sample: 10,000-15,000 stratified random points
• Train/test split: 70/30 stratified

---g

Notebook 03 — Rainfall, LULC, NDVI

CHIRPS Rainfall

• Dataset: UCSB-CHG/CHIRPS/DAILY
• Analysis period: 2013-2023 (10-year mean)
• Extreme rainfall threshold: >50mm/day (standard West African flood literature threshold)
• Export scale: 100m (compromise resolution for multi-source stack)

ESA WorldCover 2021

• Dataset: ESA/WorldCover/v200
• Resolution: 10 metres (highest resolution global LULC freely available)
• Year: 2021

• Interpretation: 40.60% impervious surface coverage severely constrains natural infiltration capacity — key flood risk amplifier in study area. Combined water/wetland/mangrove coverage (28.11%) confirms coastal low-lying character of Amuwo Odofin LGA.

Sentinel-2 NDVI

• Dataset: COPERNICUS/S2_SR_HARMONIZED
• Composite period: Dry season (Nov-Mar), 2020-2023
• Cloud filter: <20% cloudy pixel percentage
• Cloud masking: SCL classes 3, 8, 9, 10 masked
• Composite method: Median (reduces noise and residual cloud artefacts)

• Interpretation: Low-moderate mean NDVI (0.2951) consistent with heavily urbanised LGA. Negative minimum values represent water bodies and bare impervious surfaces.

Export

• Output file: rainfall_lulc_ndvi_amuwo_odofin.tif
• Scale: 100 metres | CRS: EPSG:4326 | Type: Float32
• Bands: mean_annual_rainfall, mean_rainy_days_per_year, extreme_rain_frequency, lulc, ndvi

---

Notebook 04 — Soil Permeability and Distance Features

Soil Permeability

• Primary source attempted: projects/soilgrids-isric/properties/sand/mean
• Status: ACCESS DENIED — asset not publicly available in GEE
• Fallback source used: OpenLandMap/SOL/SOL_SAND-WFRACTION_USDA-3A1A1A_M/v02
• Justification: OpenLandMap uses USDA soil taxonomy validated for West Africa
• Property: Sand fraction (% weight) as hydraulic conductivity proxy
• Resolution: 250 metres
• Scientific basis: Sandy soils = high permeability = lower runoff generation Clay-rich soils = low permeability = higher runoff (Saxton & Rawls, 2006)

• Interpretation: Moderate-low sand content consistent with coastal clay-rich soils typical of Lagos State — confirms low infiltration capacity and supports flood risk amplification in the study area

Distance to Rivers

• Primary source attempted: WWF/HydroSHEDS/v1/FreeFlowingRivers (vector)
• Status: ZERO FEATURES — dataset excludes heavily modified urban waterways Amuwo Odofin's drainage network does not meet FreeFlowingRivers criteria
• Method adopted: Flow accumulation thresholding (WWF/HydroSHEDS/15ACC)
• Threshold: flow accumulation > 200 cells (95th percentile for LGA) Selected after diagnostic confirmed LGA maximum = 708 cells (threshold of 1000 was above all pixel values — flat coastal terrain)
• Distance method: fastDistanceTransform() — more reliable than kernel-based distance on masked binary images in GEE
• Resolution: 500 metres (HydroSHEDS native resolution)
• River pixels identified: ~32 pixels at 500m scale

Distance to Drainage

• Source: JRC/GSW1_4/GlobalSurfaceWater (Pekel et al., 2016)
• Resolution: 30 metres
• Occurrence threshold: >10% water occurrence Captures seasonal and intermittent urban drainage features
• Distance method: fastDistanceTransform() × 30m resolution
• Justification: JRC captures urban drainage infrastructure (canals, seasonal streams) not mapped in HydroSHEDS

Export

• Output file: soil_distance_amuwo_odofin.tif
• Scale: 100 metres | CRS: EPSG:4326 | Type: Float32
• Bands: soil_permeability, distance_to_river, distance_to_drainage

---

COMPLETE FEATURE MATRIX — 14 Features (Updated from initial 12)

Feature count revised upward after NB03 produced 5 features (not 4) and NB04 produced 3 features (soil + 2 distance measures). 14 features is methodologically defensible — tree-based models (RF, XGBoost) handle feature redundancy gracefully. Multicollinearity check (VIF) to be performed in NB06 before modelling.

Resolution harmonisation: all 14 features resampled to 100m common resolution in NB06 before feature matrix assembly.

Notebook 05 — SAR Flood Inventory (Pre-Notebook Planning, Re-Verified)

Re-Verification Note

All flood events were independently re-verified on 22 May 2026 against primary Nigerian news sources (Vanguard, Punch, Premium Times), NiMet post-event reports, FloodList, and peer-reviewed literature. No events are carried forward from assumption — each date is confirmed by at least two independent sources. A fourth event (July 2022) was added after re-verification to strengthen training sample size and temporal coverage.

Confirmed Flood Events for Sentinel-1 SAR Change Detection

On the Absence of Amuwo Odofin-Specific Event Documentation

No newspaper or institutional record was found that specifically documents flood events at Amuwo Odofin LGA level with precise event dates. This is a known and documented data scarcity challenge in Nigerian urban flood research, explicitly acknowledged in the peer-reviewed literature (Nkwunonwo et al., 2016; Ajibade et al., 2013).

However, Amuwo Odofin's flood risk status is multiply confirmed:

1. The Nigeria Hydrological Services Agency (NIHSA) explicitly lists Amuwo Odofin as one of the defined flood-risk zones in Lagos State alongside Lagos Island, Ikeja, Apapa, and Surulere (NIHSA, cited in IJEES, 2021).

2. Informal settlements in Amuwo-Odofin have lost multiple commercial properties to flooding, documented in peer-reviewed literature (Olorunfemi et al., 2020, cited in Frontiers in Climate, 2025).

3. LASEMA's 2025 Flood-Free Lagos Campaign specifically mapped Amuwo-Odofin as a vulnerable area requiring emergency preparedness alongside Eti-Osa, Kosofe, Lekki, and Apapa (Punch Newspapers, June 2025).

4. Satellite Town (within Amuwo Odofin) is documented as having inadequate drainage and open gutters prone to blockage, leading to significant flooding during the rainy season (Wikipedia/Satellite Town, Lagos).

Methodological Response to Data Scarcity — SAR-First Framing

The absence of LGA-level event documentation is not treated as a limitation but as the direct justification for the SAR-based approach. SAR-derived flood labels are independent of administrative reporting quality and provide spatially explicit, physically grounded flood extent evidence at 10-metre resolution — a fundamentally stronger evidence base than news report coverage.

Additionally, the JRC Global Surface Water historical occurrence layer (1984-present, Landsat-derived) will be used in Notebook 05 as supplementary satellite-based validation of inundation patterns in Amuwo Odofin across the study period — providing independent corroboration that is entirely free of news reporting bias.

SAR Technical Parameters for Notebook 05

• Dataset: COPERNICUS/S1_GRD (Sentinel-1 Ground Range Detected)
• Polarisation: VV (vertical-vertical) — most sensitive to surface water detection
• Pass direction: Both ascending and descending acquisitions checked per event
• Change detection method: Pre-flood vs post-flood backscatter difference
• Thresholding: Otsu automatic threshold method — validated at 94.3% accuracy for flood inundation mapping (Tiwari et al., 2020)
• Flood class: pixels with statistically significant backscatter decrease (open water consistently returns low backscatter in VV polarisation)
• Non-flood class: stratified random sample from confirmed dry areas in the same time window, stratified by land cover type to prevent the model learning land cover as a proxy for flood occurrence

Notebook 05 — SAR Flood Inventory (Executed Results)

Sentinel-1 Archive Availability (Confirmed from GEE)

Post-flood timing from event date: 1 day (2017), 4 days (2020), 3 days (2021), 4 days (2022) — all within standard 6-day window before significant urban flood recession in coastal Lagos terrain.

Initial Detection Attempt — Problem Identified and Corrected

Initial run with 40-day pre-flood window produced flood coverage of 97.70% across composite — physically implausible for an urban LGA. Root cause: 40-day pre-flood window spanned the dry-to-wet season transition in Lagos, producing backscatter changes comparable in magnitude to actual inundation. Otsu threshold contaminated by seasonal surface moisture signal rather than flood signal. This problem is documented in the SAR flood mapping literature for tropical West Africa (Twele et al., 2016).

Three corrections applied: 1. Pre-flood window shortened to maximum 20 days — avoids seasonal transition contamination, uses closest stable dry baseline. 2. Permanent water mask applied (JRC occurrence > 50%) — removes lagoons, Badagry Creek, and permanent drainage channels which produce persistently low backscatter unrelated to flood events. 3. Dual threshold: Otsu + minimum 1.5 dB absolute change — removes low-magnitude noise changes incorrectly classified by Otsu alone. 1.5 dB is the standard C-band minimum magnitude threshold (Boni et al., 2016).

Corrected Detection Results

Coverage range of 5.43%–16.97% per event is physically credible for an urban coastal LGA with 40.60% impervious surface cover and documented poor drainage infrastructure. Larger footprints in 2021 and 2022 are consistent with more severe documented rainfall for those events.

Composite Flood Inventory

Composite method: maximum value per pixel across all four events — a pixel classified as flood in any one event is retained as flood in the composite. Standard approach for multi-event flood inventory construction (Tiwari et al., 2020).

Training Sample Statistics

Class imbalance note: 34.7:65.3 flood-to-non-flood ratio reflects the realistic spatial distribution of flood exposure in the LGA rather than a methodological failure. The imbalance is moderate and will be addressed during model training (Notebook 07) via class_weight='balanced' in scikit-learn and scale_pos_weight parameter in XGBoost. This ensures models do not develop majority-class bias toward non-flood predictions.

Exports Submitted to Google Drive

• flood_inventory_amuwo_odofin.tif (30m resolution, binary flood/non-flood)
• training_points_amuwo_odofin.csv (6,715 labelled sample points with coordinates)

Implementation Notes

• Otsu computation method: hybrid GEE + NumPy (histogram downloaded to Python) GEE server-side Array API produced dimensionality errors in pure server-side implementation — hybrid approach is standard in published workflows and produces identical results with improved robustness.
• Speckle filter: Refined Lee 3x3 approximated via focal mean on linear scale with dB conversion — standard pre-processing for Sentinel-1 IW mode at 10m.

---

PROJECT RESTRUCTURING NOTE — Logged June 2026

Critical Issue Identified: Flood Labels Contaminated by Water Bodies

During visual inspection of the flood inventory output from NB05, flood-classified pixels (Class 1) were found to cluster predominantly on permanent and semi-permanent water surfaces — Lagos Lagoon, drainage channels, and tidal inlets — rather than on genuinely inundated urban land. This renders the training labels methodologically invalid for an urban flood susceptibility model.

Root causes identified: 1. JRC permanent water mask threshold of 50% occurrence too permissive — seasonal and semi-permanent water bodies (20-49% occurrence) passed through the mask and consistently triggered low SAR backscatter signal regardless of whether a flood event occurred. 2. Otsu threshold responding to permanent water signal rather than urban inundation signal even after 1.5dB minimum change filter. 3. No land cover constraint applied — SAR change detection was operating on water, wetland, and mangrove pixels that should have been excluded from urban flood inventory entirely.

Corrective Methodology Decisions

Three simultaneous fixes applied to NB05 (rebuild): 1. JRC occurrence threshold tightened from 50% to 5% — any pixel water-covered more than 5% of the time is permanently excluded. 2. ESA WorldCover urban land mask added — only built-up (class 50), cropland (class 40), and grassland (class 30) pixels are eligible for flood classification. Water (80), wetland (90), and mangrove (95) pixels masked regardless of SAR signal. 3. Minimum backscatter change threshold increased from 1.5dB to 3.0dB — genuine urban inundation produces stronger signal than surface moisture variation on near-water terrain (Twele et al., 2016).

Project Scope Enhancement — Title Alignment

Following review of the project title ("AI-Enabled Geospatial Decision Support and Disaster Intelligence for Urban Flood Risk Management"), the GeoAID framework was expanded from a single-layer static susceptibility model to a three-layer decision support architecture:

Layer 1 — Structural Susceptibility (NB02-NB08): Static flood risk map from 16 conditioning factors and ML models. Answers: WHERE is inherently flood-prone.

Layer 2 — Dynamic Risk Activation (NB10 dashboard): GPM IMERG near-real-time rainfall overlaid on static risk map. Answers: WHICH risk zones are being actively triggered by current rainfall.

Layer 3 — Disaster Intelligence (NB09): Infrastructure risk assessment — population, roads, schools, hospitals, buildings at risk per flood risk zone. Answers: WHO and WHAT is at risk in activated zones.

Feature Matrix Expanded from 14 to 16 Features

Two new features added:

Feature 15 — HAND (Height Above Nearest Drainage): Derived from DEM and HydroSHEDS flow accumulation. Measures vertical elevation of each pixel above nearest drainage channel. Low HAND = terrain barely above drainage network = highest first-inundation risk. Specifically validated for low-lying coastal urban terrain. Added in revised NB04.

Feature 16 — GPM IMERG 72-hour Event Rainfall Accumulation: NASA Global Precipitation Measurement IMERG product. Event-specific cumulative rainfall in 72 hours preceding each of the four verified flood events. Captures antecedent soil moisture conditions that determine flood response magnitude for equivalent rainfall inputs. Added in new NB04b.

Revised Notebook Pipeline

NB01 ✓ — Study area (unchanged) NB02 ✓ — Topographic features (unchanged) NB03 ✓ — Rainfall, LULC, NDVI (unchanged) NB04 ↺ — Soil + distance + HAND model (revised — HAND added) NB04b ★ — GPM IMERG event rainfall (new) NB05 ↺ — SAR flood inventory (rebuilt — water body masking corrected) NB06 — Feature matrix assembly (updated for 16 features) NB07 — Model training and evaluation NB08 — SHAP explainability analysis NB09 ★ — Infrastructure risk assessment — OSM schools, hospitals, roads, buildings overlaid with flood risk map (new) NB10 ★ — Streamlit dashboard with GPM IMERG live rainfall layer (updated)

Methodological Note on SAR Temporal Gap

The 6-12 day Sentinel-1 revisit cycle does not affect the validity of historical label generation (Use Case B). SAR imagery is used ONCE to construct historical flood labels from verified past events where acquisitions within 1-4 days of each event were confirmed. The temporal gap concern applies to real-time flood detection (Use Case A), which is outside the scope of this project. Real-time monitoring is acknowledged as a natural extension for future work. Dynamic rainfall forcing for the operational decision support layer is provided by GPM IMERG (30-minute update cycle) rather than SAR.

---

Notebook 04 (Revised) — Soil, Distance Features

HAND Model — Attempted and Removed

HAND (Height Above Nearest Drainage) was implemented using two approaches:

Attempt 1: HydroSHEDS flow accumulation thresholding at 500m resolution. Result: Sparse channel network missed most urban drainage features in Amuwo Odofin. Kernel computation at 30m resolution (5000m radius = 167-pixel kernel) timed out after 37+ minutes without completing.

Attempt 2: JRC Global Surface Water occurrence > 5% at 100m resolution as channel network. focal_min 5000m radius at 100m = 50-pixel kernel. Result: Computation completed but produced physically incorrect values. Festac Town pixels immediately adjacent to canals showed HAND > 13m (red/high) rather than expected low values. Root cause: focal_min propagates the MINIMUM elevation within search radius — in coastal Lagos, this is always the Lagos Lagoon (0m) rather than local canal elevation (3-4m). All HAND values relative to lagoon sea level rather than nearest local drainage channel, rendering the layer hydrologically meaningless for urban flood susceptibility in this coastal setting.

Decision: HAND removed from feature matrix. Justification: Correct HAND computation requires a hydrologically conditioned DEM (e.g. MERIT DEM or NASADEM with depression filling) where sea-level water bodies are treated separately from inland drainage channels. SRTM-based HAND in coastal environments with large tidal water bodies produces systematically incorrect values. Documented as priority for future work.

Final NB04 Outputs (Three Features)

• Feature 12: Soil permeability (OpenLandMap sand fraction, 250m) Mean: 25.68% — clay-dominant coastal soils confirming low infiltration capacity and high runoff generation potential
• Feature 13: Distance to river (HydroSHEDS flow acc threshold, fastDistanceTransform, 500m) — Mean: 2,337.43m
• Feature 14: Distance to drainage (JRC occurrence > 10%, fastDistanceTransform, 30m) — Mean: 1,207.16m

Export: soil_distance_amuwo_odofin.tif (3 bands, 100m, Float32)

---

Notebook 04b — GPM IMERG Antecedent Rainfall (Feature 15)

Dataset

• Source: NASA/GPM_L3/IMERG_V07 (gauge-calibrated)
• Band: precipitation (mm/hr) — note: named 'precipitationCal' in older IMERG versions; renamed 'precipitation' in V07
• Temporal resolution: 30-minute intervals
• Spatial resolution: 0.1° (~11km at Lagos latitude)
• Unit conversion: sum(mm/hr) × 0.5hr interval = total mm accumulated

Antecedent Window Design

72-hour window immediately preceding each flood event peak date. Scientific rationale: 72-hour antecedent rainfall captures soil moisture saturation state — the primary determinant of flood response magnitude for equivalent rainfall inputs in tropical urban catchments (Beven & Kirkby, 1979; Western et al., 2002).

Event-Specific 72-Hour Antecedent Rainfall

Key Scientific Finding — Event 3 (July 2021)

Event 3 produced the second-largest flood footprint (14.02% coverage) despite only 10.09mm of antecedent rainfall in the preceding 72 hours. This indicates the July 2021 flood was driven by intense short-duration rainfall overwhelming structurally constrained drainage capacity rather than prolonged antecedent soil saturation. This finding demonstrates that antecedent rainfall alone does not explain flood occurrence in urbanised coastal terrain — structural drainage capacity (captured by TWI, flow accumulation, distance to drainage) matters equally. SHAP analysis in NB08 will reveal how the model weights GPM IMERG relative to terrain conditioning factors.

Spatial Note

GPM IMERG at 0.1° (~11km) resolution is coarser than Amuwo Odofin LGA extent. The feature contributes event-specific temporal forcing information rather than spatial differentiation within the LGA. Standard deviation of composite (3.77mm) confirms spatial uniformity.

Composite Statistics (Feature 15 — Mean Across Four Events)

Exports Submitted

• gpm_antecedent_rainfall_amuwo_odofin.tif → Feature 15 (ML matrix)
• gpm_rainfall_2017_amuwo_odofin.tif (event-specific)
• gpm_rainfall_2020_amuwo_odofin.tif (event-specific)
• gpm_rainfall_2021_amuwo_odofin.tif (event-specific)
• gpm_rainfall_2022_amuwo_odofin.tif (event-specific)

---

FINAL FEATURE MATRIX — 15 Features

HAND excluded: SRTM-based HAND computation in coastal environments with large tidal water bodies produces systematically incorrect values relative to sea-level rather than local drainage. Recommended for future work using MERIT DEM or NASADEM with hydrological conditioning.

All 15 features to be resampled to common 100m resolution in NB06.

GeoTIFF Export Summary — Data Acquisition Phase Complete

---

Notebook 04 (Revised) — Soil, Distance Features

HAND Model — Attempted and Removed

HAND (Height Above Nearest Drainage) was implemented using two approaches:

Attempt 1: HydroSHEDS flow accumulation thresholding at 500m resolution. Result: Sparse channel network missed most urban drainage features in Amuwo Odofin. Kernel computation at 30m resolution (5000m radius = 167-pixel kernel) timed out after 37+ minutes without completing.

Attempt 2: JRC Global Surface Water occurrence > 5% at 100m resolution as channel network. focal_min 5000m radius at 100m = 50-pixel kernel. Result: Computation completed but produced physically incorrect values. Festac Town pixels immediately adjacent to canals showed HAND > 13m (red/high) rather than expected low values. Root cause: focal_min propagates the MINIMUM elevation within search radius — in coastal Lagos, this is always the Lagos Lagoon (0m) rather than local canal elevation (3-4m). All HAND values relative to lagoon sea level rather than nearest local drainage channel, rendering the layer hydrologically meaningless for urban flood susceptibility in this coastal setting.

Decision: HAND removed from feature matrix. Justification: Correct HAND computation requires a hydrologically conditioned DEM (e.g. MERIT DEM or NASADEM with depression filling) where sea-level water bodies are treated separately from inland drainage channels. SRTM-based HAND in coastal environments with large tidal water bodies produces systematically incorrect values. Documented as priority for future work.

Final NB04 Outputs (Three Features)

• Feature 12: Soil permeability (OpenLandMap sand fraction, 250m) Mean: 25.68% — clay-dominant coastal soils confirming low infiltration capacity and high runoff generation potential
• Feature 13: Distance to river (HydroSHEDS flow acc threshold, fastDistanceTransform, 500m) — Mean: 2,337.43m
• Feature 14: Distance to drainage (JRC occurrence > 10%, fastDistanceTransform, 30m) — Mean: 1,207.16m

Export: soil_distance_amuwo_odofin.tif (3 bands, 100m, Float32)

---

Notebook 04b — GPM IMERG Antecedent Rainfall (Feature 15)

Dataset

• Source: NASA/GPM_L3/IMERG_V07 (gauge-calibrated)
• Band: precipitation (mm/hr) — note: named 'precipitationCal' in older IMERG versions; renamed 'precipitation' in V07
• Temporal resolution: 30-minute intervals
• Spatial resolution: 0.1° (~11km at Lagos latitude)
• Unit conversion: sum(mm/hr) × 0.5hr interval = total mm accumulated

Antecedent Window Design

72-hour window immediately preceding each flood event peak date. Scientific rationale: 72-hour antecedent rainfall captures soil moisture saturation state — the primary determinant of flood response magnitude for equivalent rainfall inputs in tropical urban catchments (Beven & Kirkby, 1979; Western et al., 2002).

Event-Specific 72-Hour Antecedent Rainfall

Key Scientific Finding — Event 3 (July 2021)

Event 3 produced the second-largest flood footprint (14.02% coverage) despite only 10.09mm of antecedent rainfall in the preceding 72 hours. This indicates the July 2021 flood was driven by intense short-duration rainfall overwhelming structurally constrained drainage capacity rather than prolonged antecedent soil saturation. This finding demonstrates that antecedent rainfall alone does not explain flood occurrence in urbanised coastal terrain — structural drainage capacity (captured by TWI, flow accumulation, distance to drainage) matters equally. SHAP analysis in NB08 will reveal how the model weights GPM IMERG relative to terrain conditioning factors.

Spatial Note

GPM IMERG at 0.1° (~11km) resolution is coarser than Amuwo Odofin LGA extent. The feature contributes event-specific temporal forcing information rather than spatial differentiation within the LGA. Standard deviation of composite (3.77mm) confirms spatial uniformity.

Composite Statistics (Feature 15 — Mean Across Four Events)

Exports Submitted

• gpm_antecedent_rainfall_amuwo_odofin.tif → Feature 15 (ML matrix)
• gpm_rainfall_2017_amuwo_odofin.tif (event-specific)
• gpm_rainfall_2020_amuwo_odofin.tif (event-specific)
• gpm_rainfall_2021_amuwo_odofin.tif (event-specific)
• gpm_rainfall_2022_amuwo_odofin.tif (event-specific)

---

FINAL FEATURE MATRIX — 15 Features

HAND excluded: SRTM-based HAND computation in coastal environments with large tidal water bodies produces systematically incorrect values relative to sea-level rather than local drainage. Recommended for future work using MERIT DEM or NASADEM with hydrological conditioning.

All 15 features to be resampled to common 100m resolution in NB06.

GeoTIFF Export Summary — Data Acquisition Phase Complete

---

Notebook 04 (Revised) — Soil, Distance Features

HAND Model — Attempted and Removed

HAND (Height Above Nearest Drainage) was implemented using two approaches:

Attempt 1: HydroSHEDS flow accumulation thresholding at 500m resolution. Result: Sparse channel network missed most urban drainage features in Amuwo Odofin. Kernel computation at 30m resolution (5000m radius = 167-pixel kernel) timed out after 37+ minutes without completing.

Attempt 2: JRC Global Surface Water occurrence > 5% at 100m resolution as channel network. focal_min 5000m radius at 100m = 50-pixel kernel. Result: Computation completed but produced physically incorrect values. Festac Town pixels immediately adjacent to canals showed HAND > 13m (red/high) rather than expected low values. Root cause: focal_min propagates the MINIMUM elevation within search radius — in coastal Lagos, this is always the Lagos Lagoon (0m) rather than local canal elevation (3-4m). All HAND values relative to lagoon sea level rather than nearest local drainage channel, rendering the layer hydrologically meaningless for urban flood susceptibility in this coastal setting.

Decision: HAND removed from feature matrix. Justification: Correct HAND computation requires a hydrologically conditioned DEM (e.g. MERIT DEM or NASADEM with depression filling) where sea-level water bodies are treated separately from inland drainage channels. SRTM-based HAND in coastal environments with large tidal water bodies produces systematically incorrect values. Documented as priority for future work.

Final NB04 Outputs (Three Features)

• Feature 12: Soil permeability (OpenLandMap sand fraction, 250m) Mean: 25.68% — clay-dominant coastal soils confirming low infiltration capacity and high runoff generation potential
• Feature 13: Distance to river (HydroSHEDS flow acc threshold, fastDistanceTransform, 500m) — Mean: 2,337.43m
• Feature 14: Distance to drainage (JRC occurrence > 10%, fastDistanceTransform, 30m) — Mean: 1,207.16m

Export: soil_distance_amuwo_odofin.tif (3 bands, 100m, Float32)

---

Notebook 04b — GPM IMERG Antecedent Rainfall (Feature 15)

Dataset

• Source: NASA/GPM_L3/IMERG_V07 (gauge-calibrated)
• Band: precipitation (mm/hr) — note: named 'precipitationCal' in older IMERG versions; renamed 'precipitation' in V07
• Temporal resolution: 30-minute intervals
• Spatial resolution: 0.1° (~11km at Lagos latitude)
• Unit conversion: sum(mm/hr) × 0.5hr interval = total mm accumulated

Antecedent Window Design

72-hour window immediately preceding each flood event peak date. Scientific rationale: 72-hour antecedent rainfall captures soil moisture saturation state — the primary determinant of flood response magnitude for equivalent rainfall inputs in tropical urban catchments (Beven & Kirkby, 1979; Western et al., 2002).

Event-Specific 72-Hour Antecedent Rainfall

Key Scientific Finding — Event 3 (July 2021)

Event 3 produced the second-largest flood footprint (14.02% coverage) despite only 10.09mm of antecedent rainfall in the preceding 72 hours. This indicates the July 2021 flood was driven by intense short-duration rainfall overwhelming structurally constrained drainage capacity rather than prolonged antecedent soil saturation. This finding demonstrates that antecedent rainfall alone does not explain flood occurrence in urbanised coastal terrain — structural drainage capacity (captured by TWI, flow accumulation, distance to drainage) matters equally. SHAP analysis in NB08 will reveal how the model weights GPM IMERG relative to terrain conditioning factors.

Spatial Note

GPM IMERG at 0.1° (~11km) resolution is coarser than Amuwo Odofin LGA extent. The feature contributes event-specific temporal forcing information rather than spatial differentiation within the LGA. Standard deviation of composite (3.77mm) confirms spatial uniformity.

Composite Statistics (Feature 15 — Mean Across Four Events)

Exports Submitted

• gpm_antecedent_rainfall_amuwo_odofin.tif → Feature 15 (ML matrix)
• gpm_rainfall_2017_amuwo_odofin.tif (event-specific)
• gpm_rainfall_2020_amuwo_odofin.tif (event-specific)
• gpm_rainfall_2021_amuwo_odofin.tif (event-specific)
• gpm_rainfall_2022_amuwo_odofin.tif (event-specific)

---

FINAL FEATURE MATRIX — 15 Features

HAND excluded: SRTM-based HAND computation in coastal environments with large tidal water bodies produces systematically incorrect values relative to sea-level rather than local drainage. Recommended for future work using MERIT DEM or NASADEM with hydrological conditioning.

All 15 features to be resampled to common 100m resolution in NB06.

GeoTIFF Export Summary — Data Acquisition Phase Complete

---

Notebook 05 (Rebuilt) — SAR Flood Inventory (Corrected)

Corrective Fixes Applied

Three simultaneous fixes resolved water body contamination:

Fix 1 — JRC threshold tightened from 50% to 5% occurrence: Pixels excluded by JRC mask: 16,691 Seasonal and semi-permanent water bodies now excluded.

Fix 2 — ESA WorldCover urban land eligibility mask added: Eligible classes: tree cover (10), grassland (30), cropland (40), built-up (50), bare/sparse (60). Excluded classes: water (80), wetland (90), mangrove (95). Pixels excluded by WorldCover mask: 501,694

Combined urban land mask: Valid urban land pixels : 140,630 (71.3% of study area) Total study area pixels : 197,134 SAR change detection restricted to urban land pixels only.

Fix 3 — Minimum backscatter change threshold: Initial attempt: 3.0dB → coverage 0.10-0.53% per event (too strict) Final value: 2.0dB — published standard for dense urban C-band flood detection (Chini et al., 2019; Boni et al., 2016). Justification: urban double-bounce scattering from buildings attenuates flood signal in densely built environments. Water body contamination now controlled by three-layer mask, not threshold alone.

Per-Event Detection Results (Corrected)

Note on low individual event coverages: Otsu thresholds near zero indicate weak bimodal separation in urban terrain — consistent with literature on SAR urban flood detection where building double-bounce dominates radar return even during inundation. Low individual coverages reflect genuine SAR signal limitations in dense urban Lagos, not methodological failure. Event 2 (Jun 2020) weakest signal — consistent with moderate antecedent rainfall (34mm/72hr, lowest of four events).

Composite Flood Inventory

• Total urban land pixels : 197,141
• Confirmed flood pixels : 10,208
• Composite flood coverage: 5.18% ✓
• Method: union (max per pixel across four events)
• Composite within credible range for dense urban coastal LGA

Training Samples (Final — Balanced)

• Flood samples (class 1) : 5,000
• Non-flood samples (class 0) : 5,000
• Total training samples : 10,000
• Class balance : 50:50
• Additional safeguard: class_weight='balanced' applied in NB07

Exports Submitted

• flood_inventory_corrected_amuwo_odofin.tif (30m, binary)
• training_points_corrected_amuwo_odofin.csv (10,000 labelled points)

Visual Confirmation

Map inspection confirmed flood pixels located exclusively on urban land surfaces — no flood classifications on Lagos Lagoon, Badagry Creek, canals, or tidal inlets. Water body contamination problem fully resolved.

---

Notebook 06 — Feature Matrix Assembly

Raster Metadata (Pre-Resampling)

Resampling

• Target resolution: 0.0009° ≈ 100m at Lagos latitude
• Target CRS: EPSG:4326
• Method: bilinear interpolation for all continuous features
• Exception: nearest-neighbour for rainfall_lulc_ndvi stack (contains LULC categorical band — bilinear would produce non-integer values not corresponding to valid land cover classes)
• Post-resampling dimensions: 206×147 for all stacks except GPM (210×150 — slightly extended bounds from 500m native resolution)

Training Points CSV

• File: training_points_amuwo_odofin.csv
• Shape: 10,000 rows × 3 columns
• Columns: system:index, flood_label, .geo (GeoJSON coordinates)
• Label distribution: 5,000 flood (1), 5,000 non-flood (0) — 50:50

NB05 Training Label Bug — Documented

• Original export produced 10,000 flood labels (0 non-flood)
• Root cause: .selfMask() on binary image converts all kept pixels to value 1 regardless of intended class — non-flood pixels exported with flood_label=1 instead of 0
• Fix: explicit ee.Image(0) remapping before stratifiedSample()
• Verified: system:index prefix 1_ = flood, 2_ = non-flood
• Re-export confirmed correct distribution

Spatial Join Results — Feature Values at 10,000 Sample Points

All 15 features extracted successfully via rasterio.sample():

Note on distance_to_river max (29,302m): reflects sparse HydroSHEDS channel network from flow accumulation thresholding. Some points far from identified channels. Does not affect model training.

Missing Values and Cleaning

Missing value cause: raster boundary edge pixels where clipping produced incomplete cells at LGA margin. Standard spatial join artefact — not a data quality failure.

Rows removed: 1,161 (11.61%) Final dataset: 8,839 rows Post-cleaning class balance: 4,455 flood (50.4%) / 4,384 non-flood (49.6%)

Multicollinearity Analysis

Highly Correlated Pairs (|r| > 0.7)

1. flow_accumulation ↔ twi: r = 0.771 Explanation: TWI is mathematically derived from flow accumulation. Correlation moderated by slope — both features retained as they capture different aspects of hydrological saturation potential.

2. mean_annual_rainfall ↔ extreme_rain_freq: r = 0.871 Explanation: climatological link — areas with higher total annual rainfall experience more extreme rainfall days. Both features retained; tree model SHAP will reveal relative importance.

VIF Analysis Results

VIF Interpretation: Extreme VIF values for rainfall features reflect spatial uniformity of coarser-resolution datasets (CHIRPS 5km, GPM 11km) across the small LGA extent (15km × 13km). At this scale, low within-study-area variance inflates VIF estimates without reducing predictive value. This is a known phenomenon in local-scale geospatial ML studies.

Action taken: - Tree-based models (RF, XGBoost): no action — immune to multicollinearity - Logistic Regression: coefficients reported but not used for feature importance interpretation. SHAP analysis is the primary interpretability framework for all three models. - No features removed — all 15 retained for consistent model comparison

Notable: curvature (VIF=1.19) and flow_accumulation (VIF=3.83) are the most independent features in the matrix — watch for prominence in SHAP analysis.

Final Feature Matrix

• File: data/feature_matrix.csv and outputs/feature_matrix.csv
• Shape: 8,839 rows × 18 columns
• Columns: longitude, latitude, flood_label + 15 features
• Class balance: 50.4% flood / 49.6% non-flood
• Correlation figure: outputs/figures/correlation_matrix.png

---

Notebook 07 — Model Training and Evaluation

Feature Set Decision — distance_to_river Removed

Initial training used 15 features. Diagnostic investigation revealed distance_to_river was physically invalid: - Max distance 28,638m exceeds LGA dimensions (~15km across) - Median 9,899m — half of all points supposedly >10km from a river - Compare distance_to_drainage (JRC 30m): max 2,000m, mean 476m Root cause: HydroSHEDS river network at 500m resolution identifies almost no channels within the small LGA, producing meaningless large distances. distance_to_drainage (JRC, denser 30m network) is the valid replacement capturing the same conditioning concept correctly.

Feature importance confirmed distance_to_river ranked 4th (0.0879) despite being broken — actively contributing spatial noise. Removal improved spatial CV recall (0.3419 → 0.3678) and F1 (0.4251 → 0.4454) while holding random-split performance flat (ROC-AUC 0.7994 → 0.7979, OOB 0.7210 → 0.7247). Final feature count: 14.

Final Feature Set (14)

elevation, slope, aspect, flow_accumulation, twi, curvature, mean_annual_rainfall, mean_rainy_days, extreme_rain_freq, lulc, ndvi, soil_permeability, distance_to_drainage, gpm_antecedent_rainfall

Training Configuration

• Dataset: 8,839 samples (4,455 flood / 4,384 non-flood, 50.4/49.6%)
• Split: 70:30 stratified, random_state=42
• Train: 6,187 | Test: 2,652
• StandardScaler applied to Logistic Regression only (tree models scale-invariant)

Model Performance — Random Split (70:30)

Selected model: Random Forest (best on all metrics)

Confusion Matrices (Test Set, n=2,652)

Logistic Regression: TN=677 FP=638 FN=431 TP=906 Random Forest: TN=921 FP=394 FN=327 TP=1010 XGBoost: TN=873 FP=442 FN=352 TP=985

OOB Convergence Verification

OOB error stabilised by 150 trees (0.2743) with negligible change to 200 trees (0.2753). Confirms n_estimators=200 (Chapter 3 claim verified). RF OOB score 0.7247 closely matches test accuracy 0.7281 — no overfitting.

Spatial K-Fold Cross-Validation (5x5 grid, 5-fold)

Spatial CV Gap — Interpretation (CRITICAL for viva)

Random Forest random-split ROC-AUC (0.7979) vs spatial-CV ROC-AUC (0.6422): gap of ~0.16 reflects spatial autocorrelation leakage in random splitting. Diagnosed causes (evidence-based): 1. Small study area (15x13km) — CHIRPS (5km) and GPM (11km) rainfall features near-spatially-constant. Feature importance confirms all four rainfall features contribute <0.02 each (~6% combined) — minimal spatial discriminative signal at this scale. 2. Spatially clustered flooding — block composition analysis shows flood pixels concentrated in blocks 6,8,11,13 (60-70% flood) vs blocks 0,4 (<20%). Holding out flood-dense blocks removes most flood training examples, causing recall collapse and high variance (±0.14). 3. Only 21 populated blocks over small area — spatial CV estimates themselves unstable (wide standard deviations). Conclusion: spatial CV gap is substantially a small-area sampling artefact, not model failure. Reported honestly in Chapter 4 as evidence of methodological rigour. Most published flood susceptibility studies report only inflated random-split numbers and never run spatial CV.

Feature Importance (Gini, Random Forest — diagnostic only)

ndvi (0.159), distance_to_drainage (0.093), elevation (0.090), soil_permeability (0.083), curvature (0.083), aspect (0.082), twi (0.082), slope (0.079), flow_accumulation (0.057), lulc (0.036), rainfall features all <0.02. NDVI dominance is physically sensible — low NDVI marks impervious built-up surfaces where urban flooding concentrates. SHAP analysis (NB08) is the primary interpretability tool; Gini importance retained here for diagnostic transparency only.

Models Saved

models/logistic_regression.pkl, models/random_forest.pkl, models/xgboost.pkl, models/scaler.pkl

---

Notebook 07 — Final Outputs (Figures and Spatial Products)

Flood Susceptibility Map Generated (Primary Spatial Output)

• Method: Random Forest applied to all valid pixels in Amuwo Odofin
• Grid: 206 x 147 pixels at 100m (reference: topo raster)
• Valid land pixels predicted: 13,022 of 30,282 total grid cells
• Probability range: 0.004 to 1.000, mean 0.389
• Full probability spread confirms model produces differentiated predictions, not clustered at extremes

Risk Tier Reclassification (Quartile Breakpoints)

Visual Validation — PASSED

Very High risk zones cluster in coherent spatial patterns rather than scattering randomly. High-risk areas concentrate consistent with physical expectations (low-lying terrain, drainage proximity, built-up areas). Confirms model learned genuine physical relationships rather than noise. This is the critical validity check for the structural susceptibility layer.

Figures Generated (outputs/figures/)

• roc_curves_comparison.png — all three models + random baseline
• confusion_matrices.png — three-panel test set error breakdown
• model_metrics_comparison.png — grouped bar chart, five metrics
• rf_oob_convergence.png — OOB error vs tree count (verified 200)
• rf_feature_importance.png — Gini importance (diagnostic)
• flood_susceptibility_map.png — two-panel probability + tier map

Spatial Products (outputs/)

• flood_probability_map.tif — continuous 0-1 surface, EPSG:4326, 100m
• flood_risk_tiers.tif — 4-class reclassification, EPSG:4326, 100m Both products feed NB09 (infrastructure risk) and NB10 (dashboard).

---

Notebook 08 — SHAP Explainability Analysis

Configuration

• Model explained: Random Forest (selected model, 14 features)
• Method: TreeExplainer (exact SHAP values for tree ensembles)
• Test set: full 2,652 samples (unconstrained-depth trees increased computation to ~7-8 minutes — expected given max_depth=None)
• Split verified identical to NB07 (ROC-AUC 0.7979 exact match)

Base Rate

Expected value (base rate): 0.5007 — reflects the deliberately balanced 50:50 flood/non-flood sampling design in NB05, not the true areal prevalence of flooding across Amuwo Odofin.

Global SHAP Feature Importance (Mean |SHAP value|)

| Rank | Feature | Mean |SHAP| | |------|---------|-------------| | 1 | ndvi | 0.0737 | | 2 | elevation | 0.0361 | | 3 | lulc | 0.0259 | | 4 | distance_to_drainage | 0.0248 | | 5 | soil_permeability | 0.0233 | | 6 | aspect | 0.0168 | | 7 | flow_accumulation | 0.0168 | | 8 | curvature | 0.0150 | | 9 | twi | 0.0149 | | 10 | slope | 0.0132 | | 11 | mean_rainy_days | 0.0100 | | 12 | extreme_rain_freq | 0.0083 | | 13 | mean_annual_rainfall | 0.0075 | | 14 | gpm_antecedent_rainfall | 0.0057 |

Cross-Validation Against Gini Importance (NB07)

SHAP ranking broadly confirms Gini importance from NB07, with NDVI dominant under both methods (Gini 0.159, SHAP 0.0737 — more than double the second-ranked feature in both cases). This convergence across two independent methods strengthens confidence that NDVI's importance is a genuine signal rather than an algorithm-specific artefact. All four rainfall features rank lowest under both methods, consistent with the NB06 VIF finding that CHIRPS (5km) and GPM IMERG (11km) are too spatially coarse to differentiate risk within the 15km LGA extent. Triangulation across VIF, Gini, and SHAP constitutes strong converging evidence for this interpretation.

Local Explanation — Highest Confidence Prediction

Test point with predicted flood probability 1.000 (actual label: Flood). Every feature contributed positively toward the flood classification — no feature pulled the prediction down. Top contributors: - ndvi = 0.09 → SHAP +0.1442 - distance_to_drainage = 26.02m → SHAP +0.1414 - elevation = 2.24m → SHAP +0.0662 Physical interpretation: near-zero vegetation cover (impervious surface), close proximity to drainage network, and low elevation combine to produce near-certain flood classification. This demonstrates the local explainability capability that no prior Nigerian flood susceptibility study has provided.

Figures Generated

• shap_importance_bar.png
• shap_beeswarm.png
• shap_dependence_plots.png (top 4 features)
• shap_local_highrisk.png

Saved Artefacts

• outputs/shap_importance.csv
• models/shap_values.npy
• models/shap_explainer.pkl

---

Notebook 08 — SHAP Explainability Analysis

Configuration

• Model explained: Random Forest (selected model, 14 features)
• Method: TreeExplainer (exact SHAP values for tree ensembles)
• Test set: full 2,652 samples (unconstrained-depth trees increased computation to ~7-8 minutes — expected given max_depth=None)
• Split verified identical to NB07 (ROC-AUC 0.7979 exact match)

Base Rate

Expected value (base rate): 0.5007 — reflects the deliberately balanced 50:50 flood/non-flood sampling design in NB05, not the true areal prevalence of flooding across Amuwo Odofin.

Global SHAP Feature Importance (Mean |SHAP value|)

| Rank | Feature | Mean |SHAP| | |------|---------|-------------| | 1 | ndvi | 0.0737 | | 2 | elevation | 0.0361 | | 3 | lulc | 0.0259 | | 4 | distance_to_drainage | 0.0248 | | 5 | soil_permeability | 0.0233 | | 6 | aspect | 0.0168 | | 7 | flow_accumulation | 0.0168 | | 8 | curvature | 0.0150 | | 9 | twi | 0.0149 | | 10 | slope | 0.0132 | | 11 | mean_rainy_days | 0.0100 | | 12 | extreme_rain_freq | 0.0083 | | 13 | mean_annual_rainfall | 0.0075 | | 14 | gpm_antecedent_rainfall | 0.0057 |

Cross-Validation Against Gini Importance (NB07)

SHAP ranking broadly confirms Gini importance from NB07, with NDVI dominant under both methods (Gini 0.159, SHAP 0.0737 — more than double the second-ranked feature in both cases). This convergence across two independent methods strengthens confidence that NDVI's importance is a genuine signal rather than an algorithm-specific artefact. All four rainfall features rank lowest under both methods, consistent with the NB06 VIF finding that CHIRPS (5km) and GPM IMERG (11km) are too spatially coarse to differentiate risk within the 15km LGA extent. Triangulation across VIF, Gini, and SHAP constitutes strong converging evidence for this interpretation.

Local Explanation — Highest Confidence Prediction

Test point with predicted flood probability 1.000 (actual label: Flood). Every feature contributed positively toward the flood classification — no feature pulled the prediction down. Top contributors: - ndvi = 0.09 → SHAP +0.1442 - distance_to_drainage = 26.02m → SHAP +0.1414 - elevation = 2.24m → SHAP +0.0662 Physical interpretation: near-zero vegetation cover (impervious surface), close proximity to drainage network, and low elevation combine to produce near-certain flood classification. This demonstrates the local explainability capability that no prior Nigerian flood susceptibility study has provided.

Figures Generated

• shap_importance_bar.png
• shap_beeswarm.png
• shap_dependence_plots.png (top 4 features)
• shap_local_highrisk.png

Saved Artefacts

• outputs/shap_importance.csv
• models/shap_values.npy
• models/shap_explainer.pkl

---

Notebook 09 — Infrastructure Risk Assessment (Layer 3)

Critical Correction — Boundary Contamination

The raster reference grid used a rectangular bounding box 1.71x larger in area than the true Amuwo Odofin LGA polygon (FAO GAUL). Initial OSM Overpass queries used this oversized bbox, pulling in infrastructure from adjacent LGAs. 58 of 93 schools initially returned were outside the true LGA boundary. All infrastructure and population analysis was corrected to clip against the true LGA polygon via shapely point-in- polygon filtering before risk tier assignment. Model raster coverage within the true LGA boundary improved from an apparent 43% to 73.6%, consistent with expected NB06 boundary-edge NaN effects only.

OSM Data Acquisition

Source: Overpass API (public mirrors, with Content-Type/User-Agent header fix for 406 rejection). Buildings capped at 20,000 (random sample, seed=42) from 293,009 raw results for computational tractability — representative for exposure PROPORTION estimation, not a complete building census.

Infrastructure Exposure (within true LGA boundary, reproduced twice)

At-risk (High + Very High): 16 schools, 55 health facilities, 148 roads

Population Exposure (WorldPop 2020, true LGA boundary)

NaN handling: WorldPop reports NaN for zero-population pixels (standard behaviour, confirmed via diagnostic — min value 3.04, no negative sentinels) — converted to 0 before summation. | Tier | Population | Share | |------|-----------|-------| | Low | 57,200 | 12.9% | | Moderate | 88,696 | 20.0% | | High | 106,941 | 24.1% | | Very High | 122,461 | 27.5% |

Total population (true LGA): 444,564 Population in High + Very High risk: 229,402 (51.6%)

Outputs

• outputs/figures/infrastructure_risk_map.png
• outputs/schools_risk_exposure.csv
• outputs/health_risk_exposure.csv
• outputs/roads_risk_exposure.csv
• outputs/population_exposure.csv

---

Notebook 09 — Infrastructure Risk Assessment (Layer 3)

Critical Correction — Boundary Contamination

The raster reference grid used a rectangular bounding box 1.71x larger in area than the true Amuwo Odofin LGA polygon (FAO GAUL). Initial OSM Overpass queries used this oversized bbox, pulling in infrastructure from adjacent LGAs. 58 of 93 schools initially returned were outside the true LGA boundary. All infrastructure and population analysis was corrected to clip against the true LGA polygon via shapely point-in- polygon filtering before risk tier assignment. Model raster coverage within the true LGA boundary improved from an apparent 43% to 73.6%, consistent with expected NB06 boundary-edge NaN effects only.

OSM Data Acquisition

Source: Overpass API (public mirrors, with Content-Type/User-Agent header fix for 406 rejection). Buildings capped at 20,000 (random sample, seed=42) from 293,009 raw results for computational tractability — representative for exposure PROPORTION estimation, not a complete building census.

Infrastructure Exposure (within true LGA boundary, reproduced twice)

At-risk (High + Very High): 16 schools, 55 health facilities, 148 roads

Population Exposure (WorldPop 2020, true LGA boundary)

NaN handling: WorldPop reports NaN for zero-population pixels (standard behaviour, confirmed via diagnostic — min value 3.04, no negative sentinels) — converted to 0 before summation. | Tier | Population | Share | |------|-----------|-------| | Low | 57,200 | 12.9% | | Moderate | 88,696 | 20.0% | | High | 106,941 | 24.1% | | Very High | 122,461 | 27.5% |

Total population (true LGA): 444,564 Population in High + Very High risk: 229,402 (51.6%)

Outputs

• outputs/figures/infrastructure_risk_map.png
• outputs/schools_risk_exposure.csv
• outputs/health_risk_exposure.csv
• outputs/roads_risk_exposure.csv
• outputs/population_exposure.csv

---

Dashboard Audit — Report Claims vs Implemented Features

Conducted before final dashboard iteration. Compares capabilities stated in Chapters 1-4 against what the Streamlit application actually does.

Gaps identified

Blocking dependency

NB09 Cell 7 exports exposure tables using .drop(columns='geometry'), discarding point coordinates. The dashboard therefore cannot plot schools, health facilities or roads. This must be corrected in NB09 before FR06 and the click-to-query capability can be implemented.

Remediation plan (in scope for MIT submission)

1. NB09: retain longitude and latitude columns in exposure CSV exports
2. Dashboard: multiple basemap layers (CartoDB dark, OpenStreetMap, Esri World Imagery) with layer control. OSM shows street grid and building footprints for context; satellite imagery permits visual verification of NDVI and drainage-proximity findings against observable ground conditions
3. Dashboard: infrastructure markers coloured by risk tier (closes FR06)
4. Dashboard: click-to-query returning risk tier, top three local SHAP contributors, and a template-assembled plain-language explanation (closes FR03 and the Ch2 s2.3.4 query claim)
5. Dashboard: wire audience toggle to switch between technical output (SHAP magnitudes, probability values) and plain-language output (closes FR07)
6. Deploy to Streamlit Community Cloud (closes FR08)

Decision on FR02

Model comparison metrics are analytical rather than operational output. Options: display a comparison panel in the dashboard, or revise FR02 in Chapter 3 to scope it to the report rather than the interface. Decision pending — to be resolved deliberately rather than left unmet.

Decision on conversational explanation layer

A conversational LLM-based explanation interface was considered and deferred to future work. Rationale: no evaluation framework exists within this project for measuring explanation faithfulness, and unconstrained generation in a system whose users make decisions during flood events introduces a safety risk that cannot be mitigated within the project timeline. A deterministic template-based explanation generator provides equivalent communicative value with auditable output and no possibility of hallucination. Documented in Chapter 6 as future work requiring an explanation-faithfulness evaluation framework and a safety constraint architecture.

Deferred to post-submission research

• Expansion beyond Amuwo Odofin to additional Lagos LGAs
• Transferability testing across LGAs with differing flood mechanisms (coastal/pluvial versus inland/riverine)
• Grid resolution refinement toward the 50m standard applied in Lagos State climate analytics

---

Dashboard Audit — Report Claims vs Implemented Features

Conducted before final dashboard iteration. Compares capabilities stated in Chapters 1-4 against what the Streamlit application actually does.

Gaps identified

Blocking dependency

NB09 Cell 7 exports exposure tables using .drop(columns='geometry'), discarding point coordinates. The dashboard therefore cannot plot schools, health facilities or roads. This must be corrected in NB09 before FR06 and the click-to-query capability can be implemented.

Remediation plan (in scope for MIT submission)

1. NB09: retain longitude and latitude columns in exposure CSV exports
2. Dashboard: multiple basemap layers (CartoDB dark, OpenStreetMap, Esri World Imagery) with layer control. OSM shows street grid and building footprints for context; satellite imagery permits visual verification of NDVI and drainage-proximity findings against observable ground conditions
3. Dashboard: infrastructure markers coloured by risk tier (closes FR06)
4. Dashboard: click-to-query returning risk tier, top three local SHAP contributors, and a template-assembled plain-language explanation (closes FR03 and the Ch2 s2.3.4 query claim)
5. Dashboard: wire audience toggle to switch between technical output (SHAP magnitudes, probability values) and plain-language output (closes FR07)
6. Deploy to Streamlit Community Cloud (closes FR08)

Decision on FR02

Model comparison metrics are analytical rather than operational output. Options: display a comparison panel in the dashboard, or revise FR02 in Chapter 3 to scope it to the report rather than the interface. Decision pending — to be resolved deliberately rather than left unmet.

Decision on conversational explanation layer

A conversational LLM-based explanation interface was considered and deferred to future work. Rationale: no evaluation framework exists within this project for measuring explanation faithfulness, and unconstrained generation in a system whose users make decisions during flood events introduces a safety risk that cannot be mitigated within the project timeline. A deterministic template-based explanation generator provides equivalent communicative value with auditable output and no possibility of hallucination. Documented in Chapter 6 as future work requiring an explanation-faithfulness evaluation framework and a safety constraint architecture.

Deferred to post-submission research

• Expansion beyond Amuwo Odofin to additional Lagos LGAs
• Transferability testing across LGAs with differing flood mechanisms (coastal/pluvial versus inland/riverine)
• Grid resolution refinement toward the 50m standard applied in Lagos State climate analytics

---

Dashboard Remediation — Closing Report/Artifact Gaps

Implemented following the dashboard audit. Each item closes a capability claimed in Chapters 1-4 but absent from the running application.

NB09 export corrected (blocking dependency)

Cell 7 previously used .drop(columns='geometry'), discarding point coordinates. Replaced with an export_with_coords() helper writing explicit longitude and latitude columns. Buildings exposure table added to the export set. Verified: schools_risk_exposure.csv header now reads osm_id,name,category,risk_tier,risk_label,longitude,latitude.

Multiple basemap layers (defence utility)

Three tile layers with a layer control: CartoDB dark matter (default, matches interface palette), OpenStreetMap (street grid and building footprints for local context), and Esri World Imagery (satellite, for visual verification of model findings against observable ground conditions). Esri chosen over Google tiles, whose terms restrict use outside the Maps API. The satellite layer permits direct visual corroboration of the NDVI and drainage-proximity findings during defence.

Infrastructure markers on interactive map (closes FR06)

Schools, health facilities and roads plotted as circle markers coloured by assigned risk tier, grouped into toggleable feature layers with name-and-tier popups.

Click-to-query with local SHAP (closes FR03, Ch2 s2.3.4)

Clicking any map location resolves the point to a raster cell, retrieves the 14 feature values from the resampled stack, computes SHAP values via the saved TreeExplainer, and returns the risk tier with the three strongest contributing factors. Handles out-of-bounds clicks and cells with incomplete feature coverage.

Plain-language translation layer (closes FR07)

Deterministic template engine mapping each conditioning factor to its physical meaning with direction of effect. Example: a positive SHAP value on ndvi renders as "the ground is mostly concrete and rooftops with very little greenery, so rain runs off instead of soaking in". Combined with tier-specific opener and advice text.

No generative model is involved. This was a deliberate design decision: templated assembly is fully auditable and cannot hallucinate, which matters in a system whose users make decisions during flood events. The audience toggle now switches Tab 1 and Tab 3 between technical output (SHAP magnitudes, probability values) and plain-language output.

Dead control removed

The MAP LAYER selectbox was non-functional and has been removed rather than left as a control that does nothing.

Repository size check for deployment

models/ 70MB, outputs/ 4.3MB, data/resampled/ 1.8MB — 76MB total. git check-ignore confirmed no exclusion of model or raster artefacts. Within GitHub limits; Git LFS not required.

Outstanding

• FR02 (comparative model metrics in dashboard): decision pending — display panel, or rescope requirement in Chapter 3 to the report only
• Live GEE rainfall on hosted deployment requires a service account credential in Streamlit secrets; falls back to cached warning until configured

---

Dashboard — Deployment Fixes and UX Refinement

Deployment crash resolved

Streamlit Community Cloud raised a TypeError unpickling shap_explainer.pkl. Cause: the pickled TreeExplainer carries numba-compiled objects that fail to deserialise across numba versions between the local environment and the cloud runtime (Python 3.14). Fix: construct the explainer from the loaded model at runtime rather than unpickling. Construction is inexpensive; only SHAP value computation is costly. runtime.txt added pinning python-3.11 to prevent further version drift on the hosted environment.

Code faults found in review

Three faults identified and corrected before redeployment: - fetch_live_rainfall() contained a return statement placed before the window_sum definition, making the function body unreachable and calling an undefined name - Tab 2 rainfall assignment logic was inverted, zeroing values when data was present and raising TypeError when absent - Infrastructure marker popup referenced popup instead of popup_html

UX refinements

• Amuwo Odofin LGA boundary rendered as a dashed red outline from the NB01 GeoJSON, distinguishing the true study area from the rectangular raster extent
• Session time displayed in West Africa Time with UTC in parentheses
• GPM IMERG last observation timestamp surfaced in Tab 2, so users can judge data freshness rather than assuming the reading is current
• Roads enabled by default in the infrastructure overlay
• Marker popups now include coordinates alongside name and risk tier
• Metric row split 3 + 2 and mobile breakpoints added at 768px, so the dashboard remains usable on a phone
• Map set to fill its container width
• Tile attribution reduced in size and opacity. Retained rather than removed: OpenStreetMap ODbL, CARTO and Esri terms all require visible attribution, and removing it would place a licensing violation in a public repository

Deployment

Live at https://geoaid-lagos-flood.streamlit.app (closes FR08). Repository artefacts total 76MB, within GitHub limits, no LFS required. GEE live rainfall requires a service account credential in Streamlit secrets to function on the hosted instance; the app degrades gracefully to a cached-state warning until that is configured.

---

Dashboard — Deployment Fixes and UX Refinement

Deployment crash resolved

Streamlit Community Cloud raised a TypeError unpickling shap_explainer.pkl. Cause: the pickled TreeExplainer carries numba-compiled objects that fail to deserialise across numba versions between the local environment and the cloud runtime (Python 3.14). Fix: construct the explainer from the loaded model at runtime rather than unpickling. Construction is inexpensive; only SHAP value computation is costly. runtime.txt added pinning python-3.11 to prevent further version drift on the hosted environment.

Code faults found in review

Three faults identified and corrected before redeployment: - fetch_live_rainfall() contained a return statement placed before the window_sum definition, making the function body unreachable and calling an undefined name - Tab 2 rainfall assignment logic was inverted, zeroing values when data was present and raising TypeError when absent - Infrastructure marker popup referenced popup instead of popup_html

UX refinements

• Amuwo Odofin LGA boundary rendered as a dashed red outline from the NB01 GeoJSON, distinguishing the true study area from the rectangular raster extent
• Session time displayed in West Africa Time with UTC in parentheses
• GPM IMERG last observation timestamp surfaced in Tab 2, so users can judge data freshness rather than assuming the reading is current
• Roads enabled by default in the infrastructure overlay
• Marker popups now include coordinates alongside name and risk tier
• Metric row split 3 + 2 and mobile breakpoints added at 768px, so the dashboard remains usable on a phone
• Map set to fill its container width
• Tile attribution reduced in size and opacity. Retained rather than removed: OpenStreetMap ODbL, CARTO and Esri terms all require visible attribution, and removing it would place a licensing violation in a public repository

Deployment

Live at https://geoaid-lagos-flood.streamlit.app (closes FR08). Repository artefacts total 76MB, within GitHub limits, no LFS required. GEE live rainfall requires a service account credential in Streamlit secrets to function on the hosted instance; the app degrades gracefully to a cached-state warning until that is configured.

---

Dashboard — Deployment Fixes and UX Refinement

Deployment crash resolved

Streamlit Community Cloud raised a TypeError unpickling shap_explainer.pkl. Cause: the pickled TreeExplainer carries numba-compiled objects that fail to deserialise across numba versions between the local environment and the cloud runtime (Python 3.14). Fix: construct the explainer from the loaded model at runtime rather than unpickling. Construction is inexpensive; only SHAP value computation is costly. runtime.txt added pinning python-3.11 to prevent further version drift on the hosted environment.

Code faults found in review

Three faults identified and corrected before redeployment: - fetch_live_rainfall() contained a return statement placed before the window_sum definition, making the function body unreachable and calling an undefined name - Tab 2 rainfall assignment logic was inverted, zeroing values when data was present and raising TypeError when absent - Infrastructure marker popup referenced popup instead of popup_html

UX refinements

• Amuwo Odofin LGA boundary rendered as a dashed red outline from the NB01 GeoJSON, distinguishing the true study area from the rectangular raster extent
• Session time displayed in West Africa Time with UTC in parentheses
• GPM IMERG last observation timestamp surfaced in Tab 2, so users can judge data freshness rather than assuming the reading is current
• Roads enabled by default in the infrastructure overlay
• Marker popups now include coordinates alongside name and risk tier
• Metric row split 3 + 2 and mobile breakpoints added at 768px, so the dashboard remains usable on a phone
• Map set to fill its container width
• Tile attribution reduced in size and opacity. Retained rather than removed: OpenStreetMap ODbL, CARTO and Esri terms all require visible attribution, and removing it would place a licensing violation in a public repository

Deployment

Live at https://geoaid-lagos-flood.streamlit.app (closes FR08). Repository artefacts total 76MB, within GitHub limits, no LFS required. GEE live rainfall requires a service account credential in Streamlit secrets to function on the hosted instance; the app degrades gracefully to a cached-state warning until that is configured.