Telecom Customer Churn Prediction

Overview

Acquiring a new customer is often much more expensive than retaining an existing one. This project develops an end-to-end Machine Learning pipeline to predict behavior and identify customers at high risk of churning from a US-based telecom company. By accurately predicting churn, the business can proactively deploy targeted customer retention programs, thereby minimizing revenue loss.

Business Objective & Model Strategy

While a high overall accuracy looks good on paper, it often masks the actual churners in an imbalanced dataset (where the baseline churn rate is only ~14.55%).

Our primary objective is to optimize for Recall.

• The Trade-off: We intentionally lower the classification threshold to catch almost everyone who might churn (high recall). This reduces our precision (we may accidentally flag some loyal customers and give them retention discounts).
• Business Justification: In the telecom industry, the cost of giving a small retention discount to a happy customer is significantly cheaper than the high cost of completely losing a subscriber to a competitor.

Dataset

The data is sourced from Kaggle's Telecom Churn Dataset by Baligh Mnassri.

• It consists of clean customer activity data with 20 features (e.g., State, Account length, Voice mail plan, Total day/eve/night minutes and charges, Customer service calls).
• Train Set: churn-bigml-80.csv (2666 rows)
• Test Set: churn-bigml-20.csv (667 rows)

Machine Learning Pipeline

Our workflow is organized sequentially within the notebooks/ directory:

1. 01_preprocessing.ipynb: Data cleaning, verifying data types, and handling missing values/outliers (clipping instead of dropping, as outliers often strongly correlate with churn).
2. 02_data_encoding.ipynb: Converting boolean/categorical columns. Churn values mapped to 1 and 0. One-Hot Encoding applied to State and Area code.
3. 03_feature_scaling.ipynb: Applying StandardScaler (z-score scaling) for linear models, ensuring outliers' significance is preserved.
4. 04_feature_engineering.ipynb:
   • Leveraged SHAP (SHapley Additive exPlanations) to extract the top 11 most impactful features.
   • Dropped redundant/weak features to build a leaner, faster model.
5. 05_modeling.ipynb:
   • Smart Model Routing: Cross-validated multiple classifiers (Logistic Regression, SVM, KNN, RF, GBC), passing scaled data to linear models and encoded (unscaled) data to tree-based models for better interpretability.
   • Hyperparameter Tuning & Early Stopping: Tuned a Gradient Boosting Classifier. Implemented validation_fraction to halt training early if validation scores stagnated, preventing overfitting.
   • Threshold Tuning: Lowered the decision threshold to 0.40 to maximize Churn Recall. Output metrics and visual dashboards (Confusion Matrix, ROC, PR curves) to the tests/ directory.

Key Technical Insights

• Tree-Based Models & Scaling: Decision trees (Gradient Boosting, Random Forest) only look for split points, making them immune to data scaling. We utilized unscaled encoded data for these models so that the SHAP values and thresholds remain in their original units (e.g., explaining churn via "Total day minutes > 150" is far more interpretable for stakeholders than "Total day minutes > 0.45").
• Gradient Boosting Outlier Sensitivity: GB builds trees sequentially to correct the prior tree's errors. Extreme outliers can force the model to over-correct. Early stopping (n_iter_no_change) was crucial to preventing this.
• SMOTE vs. Class Weights: Synthetic data generation via SMOTE led to poorer performance with Gradient Boosting trees. Relying on class weights and threshold tuning proved much more effective for this dataset.

For a deeper dive into the methodology, decision-making processes, challenges faced, and detailed insights gathered throughout the development of this pipeline, please refer to the Project Journal.

Project Structure

Telecom-Customer-Churn
 |
 |-- data
 |   |-- encoded
 |   |-- raw
 |   |-- scaled
 |
 |-- models            # Pickled model files
 |-- notebooks
 |   |-- 01_preprocessing.ipynb
 |   |-- 02_data_encoding.ipynb
 |   |-- 03_feature_scaling.ipynb
 |   |-- 04_feature_engineering.ipynb
 |   |-- 05_modeling.ipynb
 |   |-- exploration.ipynb   # Clean end-to-end pipeline using src/
 |
 |-- reports           # Generated metrics and plots
 |   |-- figures
 |   |-- metrics.csv
 |
 |-- src               # Source code and helper functions
 |   |-- data_loader.py
 |   |-- evaluate.py
 |   |-- predict.py
 |   |-- preprocess.py
 |   |-- train.py
 |
 |-- config.py         # Global configuration (paths, hyperparameters, etc.)
 |-- tests             # Legacy test scripts/metrics
 |-- JOURNAL.md        # Detailed project notes and methodology tracking
 |-- requirements.txt  # Project dependencies
 |-- README.md

Getting Started

1. Clone the repository:

   git clone https://github.com/Sri-Krishna-S/Telecom-Customer-Churn-MLClassification.git
   cd Telecom-Customer-Churn-MLClassification

2. Create a virtual environment and install dependencies:

   python -m venv venv1
   source venv1/bin/activate  # On Windows use `venv1\Scripts\activate`
   pip install -r requirements.txt

3. Explore the Notebooks: Start your Jupyter environment and navigate to the notebooks/ directory to run through the pipeline step-by-step.

   jupyter notebook

License

This project is licensed under the terms of the MIT license. See the LICENSE file for details.