Telco Customer Churn Prediction

A machine learning project that predicts customer churn for a telecommunications company, comparing four classification models with threshold tuning and an interactive Streamlit dashboard for exploration and inference.

Built as part of the Machine Learning module at Frankfurt University of Applied Sciences (exchange semester).

Overview

Customer churn — when subscribers cancel their service — is one of the costliest problems in telecom. This project trains and compares multiple classifiers on the IBM Telco Customer Churn dataset, tunes decision thresholds to maximise F1 on a validation set, and provides an interactive dashboard for bulk/single prediction, model evaluation, feature importance analysis, and retention recommendations.

Models

Model	Description
Logistic Regression	Linear baseline with L2 regularisation
Random Forest	500-tree ensemble with balanced sample weighting
Gradient Boosting	Sequential boosting classifier
SVM (RBF kernel)	Support vector classifier with probability calibration

All models share a common preprocessing pipeline (median imputation + standard scaling for numeric features, mode imputation + one-hot encoding for categorical features) and are trained with balanced sample weights to handle class imbalance.

Key Techniques

• Threshold tuning: Instead of using the default 0.5 cutoff, the trainer sweeps thresholds from 0.05 to 0.95 and selects the one that maximises F1 on the validation set — important for imbalanced churn datasets where recall matters.
• Three-way split: Train (64%) / Validation (16%) / Test (20%) with stratification, ensuring threshold tuning doesn't leak into final evaluation.
• Permutation importance: The dashboard computes feature importance by measuring F1 drop when each column is shuffled, giving model-agnostic insight into churn drivers.

Project Structure

├── data/
│   └── WA_Fn-UseC_-Telco-Customer-Churn.csv
├── docs/
│   ├── Documentation.pdf
│   └── references.bib
├── models/                          # generated after training
│   ├── metadata.json
│   └── leaderboard.csv
├── outputs/                         # generated after training
│   ├── confusion_matrix.png
│   ├── roc_curve.png
│   ├── metrics.json
│   └── eval_best.json
├── src/
│   ├── train_models_compact.py      # training + evaluation pipeline
│   └── dashboard_compact.py         # Streamlit dashboard
├── requirements.txt
└── README.md

Setup

pip install -r requirements.txt

Usage

1. Train models

cd src
python train_models_compact.py

This trains all four models, tunes thresholds, exports holdout predictions, and saves plots and metadata to models/ and outputs/.

Options:

• --no-svm — skip SVM (faster training)
• --no-tune — use fixed 0.5 threshold instead of tuning
• --select-by val_f1@0.5 — select best model by F1 at 0.5 instead of tuned threshold

2. Run the dashboard

cd src
python -m streamlit run dashboard_compact.py

The dashboard provides six views: dataset overview, bulk prediction, single customer prediction, model evaluation (confusion matrix + ROC curve), permutation feature importance, and retention suggestions with email templates.

Results

The best model is selected automatically based on validation F1 at the tuned threshold. See outputs/ for confusion matrix, ROC curve, and detailed metrics after training.

Dataset

IBM Telco Customer Churn — 7,043 customers with 20 features including demographics, account information, and subscribed services. Binary target: churned (Yes/No).

Requirements

• Python 3.10+
• See requirements.txt for dependencies

License

MIT