Oreolluwa/churn-prediction-nigeria

# A Customer Churn Prediction Framework for Nigerian Telecom Subscribers **Using Behavioural Usage Patterns and Explainable Machine Learning** Author: Adebayo Oreoluwa Joy Department of Data Science, Miva Open University This repository is the open-access deliverable of the project. It contains the complete experimental pipeline from raw data ingestion through model outputs and SHAP visualisations, the saved result artifacts, a narrative notebook, and the written report chapters. The work is fully reproducible from a single seeded command. --- ## Research objectives The repository realises the four objectives fixed in the project proposal. 1. **Comparative modelling.** Develop and comparatively evaluate four machine learning models, Random Forest, XGBoost, LightGBM, and a heterogeneous stacking ensemble, for subscriber churn prediction. 2. **Class imbalance treatment.** Address class imbalance through pipeline-integrated application of SMOTE and ADASYN within stratified cross-validation folds, ensuring leakage-free experimental integrity. 3. **Explainability.** Apply SHAP TreeExplainer to the best-performing model to generate interpretable global and subscriber-level explanations. 4. **Open access.** Publish the complete experimental pipeline as a documented, reproducible repository. This repository is that deliverable. --- ## Headline results The best overall model was **XGBoost with SMOTE on the IBM Telco test set**. | Metric | Value | |---|---| | Recall | 0.7273 | | G-mean | 0.7595 | | AUC-ROC | 0.8441 | | F1 | 0.6326 | | MCC | 0.4835 | On the Cell2Cell test set, Random Forest with SMOTE achieved the highest recall (0.2964) and the stacking ensemble with SMOTE the best balanced performance (G-mean 0.4984, MCC 0.2041). Full per-model tables for both datasets are in `results/tables/` and the report. Evaluation prioritises **recall** and **G-mean** over raw accuracy, reflecting the operational reality that a missed churner costs more than an unnecessary …