📡 Customer Churn Prediction System

Link to the project [ https://imhs14-customer-churn-prediction-app-gywhp6.streamlit.app/ ] A fully local, production-ready machine learning app that predicts customer churn.
Built with Scikit-Learn, Streamlit, and Plotly

---

Project Structure

churn_system/
│
├── data_setup.py        ← Step 1: generate synthetic dataset
├── model_trainer.py     ← Step 2: train & save the model
├── app.py               ← Step 3: run the Streamlit dashboard
│
├── requirements.txt
├── README.md
│
│── (generated after running scripts)
├── churn_data.csv
├── churn_model.joblib
└── churn_preprocessor.joblib

---

Quick Start (Terminal Commands)

1 — Create & activate a virtual environment

# Navigate to your project folder
cd ~/Desktop/churn_system        # adjust path as needed

# Create the virtual environment (Python 3.11+ recommended)
python3 -m venv .venv

# Activate it (macOS / Linux)
source .venv/bin/activate

Tip: Your terminal prompt will change to (.venv) … to confirm it's active.

2 — Install dependencies

pip install --upgrade pip
pip install -r requirements.txt

All packages ship with native Apple Silicon (arm64) wheels from PyPI, so no Rosetta translation is needed.

3 — Generate the dataset

python data_setup.py

This creates churn_data.csv (1,200 rows) with realistic, synthetic customer data.

4 — Train the model

python model_trainer.py

This will:

• Pre-process the data (impute nulls → scale numerics → one-hot encode categoricals)
• Train a Random Forest classifier with n_jobs=-1 (uses all M4 cores)
• Print a classification report, ROC-AUC score, and top feature importances
• Save churn_model.joblib and churn_preprocessor.joblib

Expected output (approximate):

Loaded 1,200 rows. Churn rate: 30.5%
Training Random Forest …
Training complete.

── Classification Report ──────────────────────────────
              precision    recall  f1-score   support
    No Churn       0.88      0.91      0.89       168
       Churn       0.79      0.73      0.76        72

ROC-AUC : 0.9012

5-Fold CV ROC-AUC : 0.8934 ± 0.0121

5 — Launch the dashboard

streamlit run app.py

Streamlit will open http://localhost:8501 in your browser automatically.

---

Dashboard Features

🔍 Sidebar — Single Customer Prediction

• Enter customer details using sliders and dropdowns
• Click Predict Churn to see the churn probability
• A colour-coded gauge chart shows risk at a glance (green = low risk, red = high risk)

📊 Feature Importance Tab

• Interactive horizontal bar chart (Plotly) showing which features drive churn most
• Hover over bars for exact importance scores
• Expandable explanation section

📂 Batch Prediction Tab

• Drag and drop any CSV with the required columns
• Download a sample CSV template if you need one
• Results table with colour gradient on churn probability
• Histogram showing the distribution of predicted probabilities across your dataset
• Download the annotated results as a new CSV

---

Input Features Reference

Feature	Type	Example Values
Tenure	Integer (months)	1 – 72
MonthlyCharges	Float ($)	20.0 – 120.0
TotalCharges	Float ($)	0.0 – 8,640.0
SeniorCitizen	Integer (0/1)	0, 1
ContractType	Categorical	Month-to-month, One year, Two year
TechSupport	Categorical	Yes, No
InternetService	Categorical	DSL, Fiber optic, No
PaymentMethod	Categorical	Electronic check, Mailed check, Bank transfer, Credit card
PaperlessBilling	Categorical	Yes, No

---

ML Pipeline Architecture

Raw CSV
  │
  ▼
ColumnTransformer
  ├── Numeric columns  → SimpleImputer(median) → StandardScaler
  └── Categorical cols → SimpleImputer(most_frequent) → OneHotEncoder
  │
  ▼
RandomForestClassifier
  (n_estimators=300, class_weight='balanced', n_jobs=-1)
  │
  ▼
churn_model.joblib  +  churn_preprocessor.joblib

class_weight='balanced' compensates for the natural class imbalance between churned and non-churned customers.

---

Deactivating the Virtual Environment

When you're done:

deactivate

---

Troubleshooting

Problem	Fix
ModuleNotFoundError	Make sure .venv is activated (source .venv/bin/activate)
Model not found error in app	Run python model_trainer.py first
Port 8501 already in use	streamlit run app.py --server.port 8502
Slow first load	Normal — Streamlit compiles on first run; subsequent loads are fast

---

License

MIT — use freely for personal and commercial projects.