Umair1710/customer-churn-prediction

Telco Customer Churn Prediction: End-to-End Machine Learning Journey

An end-to-end classification system designed to predict customer churn risk for telecommunications providers. This project details the full lifecycle from raw data processing to baseline modeling, handling class imbalance, and hyperparameter tuning to deliver an optimized XGBoost model calibrated for Recall.

---

1. Project Overview & Business Goal

• Goal: Identify subscribers at high risk of canceling their service before they churn.
• Primary Metric: Recall (0.8102). Losing a subscriber incurs a high loss in Customer Lifetime Value (LTV), whereas sending a retention offer to a non-churning customer (False Positive) carries minimal operational cost.

---

2. Dataset Overview & Feature Engineering

• Source Dataset: Kaggle Telco Customer Churn (7,043 instances, 21 features).
• Data Cleaning: Coerced TotalCharges to numeric and imputed missing values with 0.
• Feature Engineering: Created AvgMonthlySpend = TotalCharges / max(tenure, 1).
• Preprocessing: Applied One-Hot Encoding (pd.get_dummies(drop_first=True)) and scaled numerical features using StandardScaler fit strictly on X_train to prevent data leakage.
• Target Distribution: 73.5% non-churn (0) vs. 26.5% churn (1).

---

3. Model Progression & Results

Phase 1: Baseline Models (Unweighted Loss)

Standard models struggled with minority class detection due to the default 0.50 threshold:

• Logistic Regression: Accuracy: 80.70% | Recall: 56.68% | F1: 0.6115 | ROC-AUC: 0.8423
• Random Forest: Accuracy: 78.42% | Recall: 49.47% | F1: 0.5522 | ROC-AUC: 0.8271
• XGBoost (Baseline): Accuracy: 77.86% | Recall: 50.53% | F1: 0.5401 | ROC-AUC: 0.8173

Phase 2: Class Imbalance Optimization

Applied class weighting (class_weight='balanced' and scale_pos_weight = 2.77):

• Logistic Regression (Balanced): Accuracy: 73.81% | Recall: 78.34% | F1: 0.6136 | ROC-AUC: 0.8417
• XGBoost (Balanced): Accuracy: 76.22% | Recall: 66.04% | F1: 0.5959 | ROC-AUC: 0.8173
• Random Forest (Balanced): Accuracy: 79.06% | Recall: 49.47% | F1: 0.5564 | ROC-AUC: 0.8227

Phase 3: Fine-Tuned XGBoost (Final Selected Model)

Tuned hyperparameters via GridSearchCV (learning_rate=0.05, max_depth=3, n_estimators=100, subsample=0.8):

Metric	Score	Business Impact
Recall	81.02%	Successfully captures 303 out of 374 actual churners in test evaluation
ROC-AUC	0.8457	Highest class separation and ranking ability
F1 Score	0.6254	Best balance between precision and recall
Accuracy	74.80%	Robust overall performance
Precision	51.01%	Acceptable trade-off to capture 81%+ of churn risk

---

4. Repository Files

• xgboost_churn_model.pkl: Fine-tuned XGBoost classifier weights.
• scaler.pkl: StandardScaler trained on feature set.
• telco_churn_preprocessed.csv: Encoded preprocessed dataset.
• README.md: Complete documentation and model card.

---

5. Inference Usage Example

import joblib
import pandas as pd
from huggingface_hub import hf_hub_download

# Load model and scaler from Hugging Face
model_path = hf_hub_download(repo_id='Umair1710/customer-churn-prediction', filename='xgboost_churn_model.pkl')
scaler_path = hf_hub_download(repo_id='Umair1710/customer-churn-prediction', filename='scaler.pkl')

model = joblib.load(model_path)
scaler = joblib.load(scaler_path)