---
language:
- en
license: mit
tags:
- xgboost
- tabular-regression
- flash-flood
- weather
- environmental
- malaysia
metrics:
- rmse
- mae
- r2
pipeline_tag: tabular-regression
---

# Flash Flood Probability Predictor (XGBoost)

## Model Description
This repository contains a lightweight **XGBoost Regressor** trained to predict the probability of flash floods (from `0` to `100`%) based on simulated Malaysian hydrological data. The model analyzes historical and current hourly rainfall (mm) and river water levels (m) to calculate short-term flooding risks, capturing the delayed response of river runoff to heavy monsoonal storms.

This model (`flash_flood_predictor.joblib`) was trained on a 10-year simulated dataset (2015-2025) which provides the best balance of variance and generalization.

## Intended Use
- **Flash Flood Early Warning**: Calculating real-time risk scores using sensor streams of river levels and rainfall.
- **Hydrological Simulations**: Estimating the impact of varying rainfall intensities on flood probabilities.

## Model Performance

The model's performance metrics on the test dataset are:
- **Test RMSE:** 2.7202
- **Test MAE:** 2.1971
- **Test R²:** 0.9927

## Feature Engineering
The model requires raw rainfall and river level data to be pre-processed into temporal features, including:
1. **Lags**: `river_level_lag_1h`, `river_level_lag_2h`, `rainfall_1h_lag_1h`
2. **Rolling Rates**: `river_change_1h`, `river_change_3h`, `river_change_6h`
3. **Interactions**: Compounding risk features like `rain_river_interaction_24h` (Rainfall 24h × River Level)
4. **Seasonal**: `hour`, `month`

The most critical features driving the model's predictions are the **Current River Water Level** (45% importance) and the **River Water Level 1 Hour Ago** (40% importance).

## How to Use

You can load and use the model in Python via `joblib`:

```python
import joblib
import pandas as pd
import numpy as np

# 1. Load the model artifact
model_data = joblib.load("flash_flood_predictor.joblib")
model = model_data['model']
expected_features = model_data['features']

# 2. Prepare your feature dictionary (must be pre-engineered)
sample_features = {
    'rainfall_1h_mm': 15.0,
    'rainfall_3h_mm': 45.0,
    'rainfall_6h_mm': 60.0,
    'rainfall_24h_mm': 90.0,
    'cumulative_rainfall_3day_mm': 120.0,
    'river_water_level_m': 4.2,
    'river_change_1h': 0.3,
    'river_change_3h': 0.8,
    'river_change_6h': 1.2,
    'river_level_lag_1h': 3.9,
    'river_level_lag_2h': 3.6,
    'rainfall_1h_lag_1h': 20.0,
    'rainfall_1h_lag_2h': 10.0,
    'rain_river_interaction_3h': 45.0 * 4.2,
    'rain_river_interaction_24h': 90.0 * 4.2,
    'hour': 21,
    'month': 5
}

# 3. Convert to DataFrame and Predict
X_single = pd.DataFrame([sample_features])[expected_features]
prediction = model.predict(X_single)[0]

# Clamp to 0-100% probability
flood_probability = np.clip(prediction, 0.0, 100.0)
print(f"Predicted Flash Flood Probability: {flood_probability:.1f}%")
```

## Limitations
- **Synthetic Data**: This model was trained on *synthetic* data meant to closely mimic Malaysian hydrology. For production deployment, it must be retrained on real local telemetry.
- **Geographic Specificity**: The generated weather patterns assume tropical monsoonal climates.