📉 Customer Churn Prediction

Predicts whether a telecom customer is likely to churn (leave the company) using their account, billing, and service data — with a full ML pipeline and an interactive prediction dashboard.

Overview

Customer churn is one of the most direct levers on revenue for subscription-based businesses. This project builds and compares five classification models to predict churn probability from customer attributes such as tenure, contract type, payment method, monthly charges, and subscribed services — then ships the best model behind a Streamlit dashboard for real-time, per-customer predictions.

Dataset: Telco Customer Churn — 7,043 customers, 21 features (Kaggle).

Results

Five models were trained and evaluated on a held-out 20% test set, with 5-fold stratified cross-validation for robustness:

Model	Accuracy	Precision	Recall	F1	ROC-AUC
Random Forest 🏆	0.762	0.537	0.765	0.631	0.844
Logistic Regression	0.738	0.504	0.789	0.615	0.843
LightGBM	0.750	0.519	0.778	0.623	0.841
XGBoost	0.751	0.520	0.789	0.627	0.838
Decision Tree	0.736	0.502	0.816	0.621	0.830

Random Forest was selected as the final model (highest ROC-AUC). Class imbalance (~27% churn rate) was handled via class_weight='balanced' / scale_pos_weight rather than resampling, to keep the pipeline simple and avoid synthetic data.

Top churn drivers identified via feature importance: contract type (month-to-month vs. long-term), tenure, internet service type (fiber optic), monthly charges, and payment method (electronic check).

Project Structure

churn_project/
├── data/
│   └── telco_churn.csv              # Raw dataset
├── notebook/
│   └── Customer_Churn_Prediction.ipynb   # Full pipeline: EDA → FE → modeling → evaluation
├── models/                          # Generated after running the notebook
│   ├── churn_model.pkl
│   ├── scaler.pkl
│   ├── feature_columns.pkl
│   ├── numeric_features.pkl
│   └── needs_scaling.pkl
├── app/
│   └── app.py                       # Streamlit dashboard
├── requirements.txt
├── LICENSE
└── README.md

Pipeline

1. Data Cleaning — fixed TotalCharges type coercion, handled nulls for zero-tenure customers, dropped the ID column.
2. EDA — churn distribution, churn by contract/payment method, tenure & monthly charges vs. churn, correlation heatmap.
3. Feature Engineering — tenure buckets, average monthly spend, total active services, a protection-services flag.
4. Encoding & Scaling — one-hot encoding for categoricals, StandardScaler for numeric features (used only where the model benefits, e.g. Logistic Regression).
5. Modeling — Logistic Regression, Decision Tree, Random Forest, XGBoost, LightGBM.
6. Evaluation — 5-fold stratified CV, confusion matrix, precision/recall/F1, ROC-AUC and ROC curve, feature importance.
7. Deployment — best model serialized with joblib and served through a Streamlit form.

Getting Started

1. Install dependencies

pip install -r requirements.txt

2. Run the notebook

Open notebook/Customer_Churn_Prediction.ipynb and run all cells. This reproduces the full analysis and writes the trained model artifacts to models/.

3. Launch the dashboard

cd app
streamlit run app.py

Fill in a customer's details and get:

• Churn Probability (e.g. 82%)
• Prediction: HIGH RISK / LOW RISK, with a suggested action

Using Your Own Data

Swap in your own CSV at data/telco_churn.csv — if the column names differ, only the feature-engineering and encoding cells in the notebook need adjusting; the modeling and evaluation sections work unchanged.

Tech Stack

Python · pandas · NumPy · scikit-learn · XGBoost · LightGBM · matplotlib / seaborn · Streamlit

License

MIT — see LICENSE.