An Interpretable EWQI–Stacked Ensemble Framework for Groundwater Quality Modelling and Seasonal Health Risk Assessment in a Hydrogeologically Complex Basin
Year: 2026
Type: dataset
Abstract: ================================================================================README – Integrated Groundwater Quality Modelling Framework================================================================================.This repository contains a complete workflow for groundwater quality assessment.from exploratory data analysis and water chemistry characterisation to advancedstacked ensemble machine learning, SHAP interpretability, and health‑risklinkage. The framework is designed for multi‑LGA (Awe, Doma, Keana, Lafia, Obi)and seasonal (Dry/Rainy) data. -------------------------------------------------------------------------------1. Scripts and Their Purpose------------------------------------------------------------------------------- 1.1 Preliminary Data Analysis & Visualisation------------------------------------------------- piper_trilinear.py : Generates Piper trilinear diagrams (water types).- gibbs_plots.py : Produces Gibbs plots (evaporation, rock‑weathering, precipitation dominance).- boxplots.py : Creates boxplots of water quality parameters per LGA/season.- EWQI_computation.py : Calculates Entropy‑Weighted Water Quality Index (EWQI) and classifies water quality.- correlation_analysis.py : Computes Pearson/Spearman correlation matrices and heatmaps.- PCA.py : Performs Principal Component Analysis (scree plots, biplots, factor loadings).- sankey_parallel_plots.py : Draws Sankey diagrams and parallel coordinate plots for seasonal water quality transitions and idealised flow. 1.2 Machine Learning – Stacked Ensemble Modelling----------------------------------------------------- stacked_ensemble_train.py : Main training script. Loads data (4 LGAs: Awe, Doma, Keana, Lafia), preprocesses (log‑transform, scaling), tunes base learners (XGBoost, LightGBM, CatBoost, Random Forest, GBM, SVM) using Optuna + GroupKFold, generates out‑of‑fold predictions, and trains a linear meta‑learner (stacking). Saves all models and scalers.- external_validation.py : Applies the trained stacked model to the independent Obi LGA dataset, computes metrics, and produces external validation plots. 1.3 Model Interpretation & Health Linkage-------------------------------------------- SHAP_analysis.py : Computes SHAP values for the stacked regression and classification models; creates bar and beeswarm plots.- SHAP_HQ_analysis.py : Links SHAP importance to Hazard Quotients (HQ) for ten toxic contaminants. Computes Spearman correlations (overall, per contaminant, per LGA‑season) and generates scatter plots, bar charts, and heatmaps. 1.4 Uncertainty Quantification--------------------------------- prediction_intervals.py : Implements heteroscedastic wild bootstrap to construct 95% prediction intervals for the stacked regression model. Produces coverage plots and residual diagnostics. -------------------------------------------------------------------------------2. Required Input Data (CSV files)-------------------------------------------------------------------------------- GWQ Dataset.csv : Training data (Awe, Doma, Keana, Lafia)- External validation-GWQ_Data.csv : External test data (Obi)- HQ_per_sample.csv : Hazard Quotients per sample (10 contaminants)- LGA_Season_HQ_summary.csv : Aggregated HQs by LGA and season (optional) All files must contain the columns described in the accompanying metadata file. -------------------------------------------------------------------------------3. Order of Execution (Recommended)-------------------------------------------------------------------------------1. Run preliminary plots (Piper, Gibbs, boxplots) – optional but useful for context.2. Compute EWQI and perform correlation / PCA.3. Generate Sankey and parallel plots (if season‑based flow analysis is needed).4. Execute stacked_ensemble_train.py – trains models and saves .pkl files.5. Run external_validation.py – evaluates on Obi LGA.6. Run SHAP_analysis.py – produces SHAP plots and values.7. Run SHAP_HQ_analysis.py – links SHAP to health risk.8. Run prediction_intervals.py – quantifies uncertainty. All scripts assume the same working directory and will read/write necessaryintermediate files (.pkl, .csv, .png). -------------------------------------------------------------------------------4. Dependencies (Python packages)-------------------------------------------------------------------------------numpy, pandas, matplotlib, seaborn, scikit‑learn, xgboost, lightgbm, catboost,optuna, shap, scipy, pingouin (for PCA biplots), plotly (optional for Sankey). Install with: pip install -r requirements.txt -------------------------------------------------------------------------------5. Outputs-------------------------------------------------------------------------------- Figures/ : All generated plots (PNG, high resolution, Times New Roman font)- Models/ : scaler.pkl, reg_models.pkl, cls_models.pkl, meta_reg.pkl, meta_cls.pkl- Results/ : regression_performance.csv, classification_performance.csv, SHAP_values_*.csv, LGA_Season_SHAP_HQ_*.csv -------------------------------------------------------------------------------6. Citation & License-------------------------------------------------------------------------------If you use this framework, please cite the associated publication (DOI to be added)and respect the CC‑BY‑4.0 license. For questions or contributions, contact [author email]. ================================================================================
Source: Figshare
Author: Ogbeh, Gabriel
Language: English
Subfield: Water Science and Technology
Field: Environmental Science
Domain: Physical Sciences
Open Access status: green
OpenAlex ID: W7164676343
