Customer Churn Prediction

A machine learning system that predicts telecom customer churn using a tuned Random Forest classifier, with an interactive Streamlit dashboard for real-time predictions and SHAP-based model explainability.

---

Overview

Customer churn is one of the most costly problems in the telecom industry. This project builds an end-to-end pipeline — from raw data to a deployed interactive UI — that identifies high-risk customers and surfaces actionable retention recommendations.

Dataset: IBM Telco Customer Churn (~7,000 customers, 21 features)
Best Model: Tuned Random Forest
Key Metric: ROC-AUC (optimized over accuracy due to class imbalance)

---

Results

Model	ROC-AUC	Recall	F1-Score
Logistic Regression	~0.84	~0.78	~0.61
Gradient Boosting	~0.85	~0.77	~0.62
Random Forest (Tuned)	~0.86	~0.80	~0.63

Tuned with GridSearchCV using StratifiedKFold (k=5), scoring on roc_auc.

---

Project Structure

customer-churn-prediction/
│
├── app.py                        # Streamlit dashboard
├── churn_analysis.ipynb          # Full analysis notebook
├── requirements.txt
├── README.md
│
├── data/
│   └── telco_churn.csv           # Source dataset (Kaggle)
│
├── models/
│   ├── churn_model.pkl           # Trained Random Forest
│   └── scaler.pkl                # StandardScaler
│
└── visuals/
    ├── eda_overview.png
    ├── correlation_heatmap.png
    ├── churn_by_category.png
    ├── evaluation.png
    ├── feature_importance.png
    ├── shap_bar.png
    └── shap_beeswarm.png

---

Features

Notebook (churn_analysis.ipynb)

• Exploratory data analysis with 6 visualizations
• Proper preprocessing — One-Hot Encoding for multi-class categoricals, StandardScaler for numerics
• Class imbalance handling via class_weight='balanced'
• Three models trained and compared
• GridSearchCV hyperparameter tuning with StratifiedKFold
• SHAP feature importance — global bar plot and beeswarm plot
• Business insights extracted from model outputs

Dashboard (app.py)

• 19-field customer input sidebar
• Real-time churn probability with risk gauge
• Per-customer SHAP explanation chart
• Personalized retention recommendations generated dynamically
• EDA dashboard with live dataset stats
• Business insights tab with revenue impact estimates

---

Key Findings

• Contract type is the strongest churn predictor — month-to-month customers churn at ~42% vs ~3% for two-year contracts
• Tenure is a strong negative predictor — customers in their first 12 months are the highest-risk group
• Electronic check payment users churn significantly more than auto-pay users
• Fiber optic users churn more than DSL users despite faster speeds — likely price-driven
• Customers without tech support churn at nearly 2x the rate of supported users

---

Tech Stack

Layer	Tools
Data	Pandas, NumPy
Visualization	Matplotlib, Seaborn
Machine Learning	Scikit-learn
Explainability	SHAP
UI	Streamlit
Persistence	Pickle

---

Setup

1. Clone the repo

git clone https://github.com/YOUR_USERNAME/customer-churn-prediction.git
cd customer-churn-prediction

2. Install dependencies

pip install -r requirements.txt

3. Download the dataset

Get telco_churn.csv from Kaggle and place it in the data/ folder.

4. Run the notebook

Open churn_analysis.ipynb and run all cells. This generates the model files and visuals.

5. Launch the dashboard

streamlit run app.py

---

Dataset

IBM Telco Customer Churn dataset available on Kaggle.
~7,043 rows · 21 columns · Binary classification target (Churn: Yes / No)

---

License

MIT License — free to use, modify, and distribute.