🌊 Hybrid GRU-XGBoost Flood Predictor
This repository hosts a high-precision, production-grade hybrid Machine Learning pipeline designed to predict river water levels and issue automated flood warnings. By combining sequential feature extraction with non-linear gradient boosting, the model achieves exceptional generalization and robustness.
🛠️ Model Architecture
The pipeline utilizes a sequential hybrid layout:
- Deep Sequential Feature Extraction (GRU): A gated recurrent unit network processes scaled hydrological time-series inputs to extract temporal dynamics and hidden states.
- Non-Linear Residual Regressor (XGBoost): The raw features are combined with the GRU's hidden states to form a fused feature matrix. A highly tuned XGBoost regressor processes this matrix to produce the final water level prediction.
- ONNX Optimization: The deep GRU feature extractor is compiled to the ONNX format, eliminating heavy PyTorch/TensorFlow dependencies and enabling instant CPU inference.
📊 Features & Preprocessing
Using Recursive Feature Elimination with Cross-Validation (RFECV), the optimal feature set was minimized to two critical real-time features:
fused_rainfall_mm: Spatially and temporally aggregated rainfall observations.river_flow_rate_m3_s: Upstream volumetric water flow rate.
Signal Processing & Preprocessing
- Variational Mode Decomposition (VMD): Used during signal analysis to denoise inputs and target records.
- Standardization: Features and target variables are scaled independently using a
StandardScalerfitted exclusively on historical training data to prevent temporal data leakage.
📈 Performance Benchmarks
Both models were validated on an independent unseen test set (15% split), evaluated across standard regression metrics and binary classification equivalents (Flood vs No-Flood based on the 80th percentile threshold):
| Model | Train R² | Test R² | RMSE | MAE | NSE (Nash-Sutcliffe) | Flood Detection F1-Score |
|---|---|---|---|---|---|---|
| Standalone GRU (Baseline) | 0.953 | 0.976 | 0.108m | 0.084m | 0.976 | 0.846 |
| Standalone XGBoost (Baseline) | 0.989 | 0.985 | 0.087m | 0.070m | 0.985 | 0.750 |
| Hybrid GRU-XGBoost | 0.996 | 0.987 | 0.079m | 0.064m | 0.987 | 0.846 |
Statistical Validation
- Residual Diagnostics: Residuals show zero autocorrelation with a Durbin-Watson score of 1.85, confirming that sequential dependencies were fully resolved.
- Diebold-Mariano Test (GRU vs Hybrid): Confirms statistically reliable prediction capability compared to standalone architectures (p-value = 0.029).
🚀 How to Run Inference
You can load the pipeline and perform inference in Python using onnxruntime, xgboost, and joblib:
import joblib
import json
import numpy as np
import onnxruntime as ort
import xgboost as xgb
# 1. Load artifacts
scaler_X = joblib.load('scaler_X.pkl')
scaler_y = joblib.load('scaler_y.pkl')
ort_session = ort.InferenceSession('gru_model.onnx')
hybrid_xgb = xgb.XGBRegressor()
hybrid_xgb.load_model('xgb_flood_model.json')
# 2. Input values (e.g., rainfall, flow rate)
raw_inputs = np.array([[12.5, 145.2]]) # Shape: (1, 2)
# 3. Transform inputs
scaled_inputs = scaler_X.transform(raw_inputs)
gru_inputs = scaled_inputs.reshape(1, 1, 2).astype(np.float32)
# 4. Extract GRU temporal embeddings
onnx_inputs = {ort_session.get_inputs()[0].name: gru_inputs}
hidden_states = ort_session.run(None, onnx_inputs)[0]
# 5. Combine and Predict
fused_features = np.hstack((scaled_inputs, hidden_states))
scaled_prediction = hybrid_xgb.predict(fused_features)
# 6. Inverse Transform output
water_level = scaler_y.inverse_transform(scaled_prediction.reshape(-1, 1)).item()
print(f"Predicted River Level: {water_level:.2f} meters")
📜 License
This project is licensed under the MIT License.