iloveass/kompon-ground-failure-model

Model Card: Kompon Scenario Ground-Failure Model (Model 3)

This model card describes the architecture, performance, and limitations of the Kompon scenario-adjusted ground-failure and liquefaction concern model (Model 3).

Model Details

• Developed by: Kompon Geospatial Pipeline Team
• Model Type: LightGBM-based multi-stage classification and regression system (V4 Architecture)
• Language(s): Python / LightGBM
• Task: Regression (predicting continuous concern scores $0 - 100$) + classification into risk classes.
• Scope: National level in Bangladesh.

Model Architecture (V4)

To maximize precision and recall on high-risk cases, the V4 pipeline uses a multi-stage gated structure:

1. Stage 1 (Gate Classifier): A binary classifier trained to detect if the target score is $\ge 1.0$.
2. Stage 2a (Tier Classifiers): Four separate binary classifiers trained on positive-risk rows to predict if the score exceeds thresholds of $10, 20, 40,$ and $60$.
3. Stage 2b (Regressor): A LightGBM regressor trained on positive-risk rows using heavy sample weights ($20\times, 40\times, 60\times$) for higher risk brackets.
4. Reconciliation: Gated inference applies the Regressor to estimate the raw score, which is then bounded/clamped according to the thresholds flagged by the Tier Classifiers at a $0.10$ probability threshold.

---

Intended Use

Primary Applications

• What-If Simulation: Simulating scenario-adjusted liquefaction and ground-failure concern under a given earthquake shaking scenario at Bangladesh grid points.
• Screening Gating: Helping prioritize and screen buildings based on soil, terrain, and dynamic shaking inputs when combined with visual damage (Model 2) and RVS scores.

Out-of-Scope & Limitations

• No Structural Safety Certification: This model is a geospatial screening tool. It does not predict structural collapse, declare a building "safe" or "unsafe," or replace on-site geotechnical engineering (SPT/CPT/boreholes).
• Magnitude Limitations: The model was trained on earthquakes of magnitudes M5.0 to M6.9. It has not been validated on smaller ($M < 5.0$) or larger ($M \ge 7.0$) earthquakes.
• Aftershock Warning: Do not use this model to predict aftershocks or real-time earthquake occurrences.

---

Data & Features

The model is trained on bangladesh_usgs_ground_failure_scenarios.csv (~4.5M rows, ~3.9 GB) filtering to valid training rows only (scenario_training_valid == True).

Feature Columns

Feature Name	Type	Description
vs30	Numerical	Time-average shear-wave velocity in the upper 30m (USGS Mosaic)
elevation_m	Numerical	DEM Elevation in meters (SRTM)
slope_deg	Numerical	Terrain slope in degrees
dist_water_m	Numerical	Distance to surface water in meters (JRC Surface Water)
water_occurrence_pct	Numerical	Water occurrence percentage (JRC)
geology_class	Categorical	Categorical geological classification of Bangladesh
hand_m	Numerical	Height Above Nearest Drainage (MERIT Hydro)
water_max_extent	Numerical	Maximum surface water extent
dynamic_label_name	Categorical	Dynamic World land-cover classification
magnitude	Numerical	Earthquake magnitude
depth_km	Numerical	Depth of earthquake epicenter in km
dist_epicenter_km	Numerical	Distance to the epicenter in km
pga_g_filled	Numerical	Peak Ground Acceleration (in g), filled from USGS ShakeMap grids/attenuation
pgv_cms_filled	Numerical	Peak Ground Velocity (in cm/s), filled from USGS ShakeMap grids/attenuation
mmi_filled	Numerical	Modified Mercalli Intensity, filled from USGS ShakeMap grids/attenuation

Target Column

• scenario_liquefaction_score: Continuous ground-failure/liquefaction concern score ($0 - 100$).
• Output classes are derived from the predicted score:
  • Very Low: $\text{Score} < 20$
  • Low: $20 \le \text{Score} < 40$
  • Moderate: $40 \le \text{Score} < 60$
  • High: $60 \le \text{Score} < 80$
  • Very High: $\text{Score} \ge 80$

---

Validation & Evaluation

Validation uses a rigorous Leave-One-Event-Out (LOEO) strategy across 8 distinct earthquakes to avoid spatial/event leakage.

The 8 Training Events

• M6.9 Triyuga, Nepal (usp0003k6t)
• M6.2 Falam, Myanmar (us7000fx45)
• M6.0 Dhekiajuli, India (us7000dy3b)
• M5.5 Ramganj, Bangladesh (us7000lfaa)
• M5.4 Tungi, Bangladesh (us6000rpht)
• M5.3 Sapatgram, India (us2000hd8v)
• M5.3 Gyalshing, India (usp000ea1q)
• M5.0 Satkhira, Bangladesh (us7000s0pc)

Performance Metrics (LOEO V3 Baseline)

Refer to outputs/serving_v3/loeo_report_v3.csv and outputs/serving_v2/loeo_report_v2.csv for detailed cross-validation histories.

• For events with high-risk targets (like Ramganj M5.5 and Tungi M5.4), the V3 architecture shows high recall on high-risk tiers ($\ge 20$ and $\ge 40$).
• The V4 architecture builds upon this by adding gated threshold clamping to minimize high-risk false negatives.