Upload README.md

README.md

@@ -67,12 +67,36 @@ All features are min-max scaled `[0,1]`.
 - **Max Depth:** 5
 - **Learning Rate:** 0.05
 
-## Evaluation
+## 📊 Performance & Interpretability
 
-### Testing Data, Factors & Metrics
+### Model Metrics 
+The model demonstrates high precision in predicting the severity score $S$, which controls civic resource allocation.
 
-Evaluated on a 20% holdout set (`N=2000`).
+| Metric | Value | Interpretation |
+| :--- | :--- | :--- |
+| **RMSE** | 0.0312 | Low average error (0.03 units on 0-1 scale) |
+| **MAE** | 0.0247 | High predictive accuracy |
+| **R² Score** | 0.8067 | 80% of variance explained by features |
 
-- **RMSE:** 0.0312
-- **MAE:** 0.0247
-- **R² Score:** 0.8067
+### Feature Importance (Gain)
+The following ranking describes how much each feature contributes to the XGBoost tree construction:
+
+1. **C (Centrality)**: 0.3585 — Central potholes pose higher collision risks.
+2. **A (Area Ratio)**: 0.2187 — Size of the defect is a primary driver.
+3. **R (Road Type)**: 0.1629 — Priority given to highways over local streets.
+4. **P (Proximity)**: 0.0937 — Closeness to critical infrastructure.
+
+### SHAP Visualizations
+We use SHAP (SHapley Additive exPlanations) to explain individual predictions and global feature influence.
+
+#### Global Feature Impact
+The bar chart below shows the mean absolute SHAP value, identifying which features consistently shift the severity score.
+
+![SHAP Bar Plot](shap_bar_plot.png)
+
+#### Detailed Impact (Beeswarm)
+The summary plot shows how high vs. low values of a feature affect out outcome. For example, high values of **C (Centrality)** push the score significantly higher.
+
+![SHAP Dot Plot](shap_dot_plot.png)
+
+## Training Details