2kthekid04/e-lightgbm-focal-telecom-ghana

An Engineered LightGBM-Focal Loss Model with SHAP Explainability for Intermittent Diesel Pilferage Detection at Off-Grid Telecom Tower Sites in Ghana: E-LightGBM-Focal # e-lightgbm-focal-telecom-ghana A reproducible starter repository for **imbalanced telecom churn modeling** using: - a locked LightGBM baseline, - feature engineering for a Ghana telecom use case, - and a **custom focal loss objective** for LightGBM. The project is designed to work with a real dataset placed at `data/raw/telecom_ghana.csv`. If that file is missing, the notebooks automatically generate a realistic **synthetic telecom Ghana dataset** so the workflow still runs end-to-end. ## Contents - `README.md` - `requirements.txt` - `notebooks/00_gradient_check_focal.ipynb` - `notebooks/01_baseline_locked.ipynb` - `notebooks/02_engineered_focal.ipynb` - `data_dictionary.csv` - `audit_confirmation_sheet_template.pdf` ## Problem framing **Target:** `churn_30d` - `0` = subscriber remains active - `1` = subscriber churns in the next 30 days This target is intentionally modeled as an **imbalanced binary classification** problem. In such settings, focal loss can help the model focus more on difficult minority-class examples. ## Repository structure ```text e-lightgbm-focal-telecom-ghana/ ├── README.md ├── requirements.txt ├── data_dictionary.csv ├── audit_confirmation_sheet_template.pdf ├── artifacts/ ├── data/ │ └── raw/ │ └── telecom_ghana.csv # optional, user-supplied └── notebooks/ ├── 00_gradient_check_focal.ipynb ├── 01_baseline_locked.ipynb └── 02_engineered_focal.ipynb ``` ## Quick start ```bash python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt jupyter lab ``` Then open the notebooks in this order: 1. `notebooks/00_gradient_check_focal.ipynb` 2. `notebooks/01_baseline_locked.ipynb` 3. `notebooks/02_engineered_focal.ipynb` ## What each notebook does ### 00_gradient_check_focal.ipynb - derives the custom focal loss implementation, - computes analytical gradients and Hessians, - checks them against numerical finite differences. ### 01_baseline_locked.ipynb - loads real o …