Customer Churn Prediction

Abstract

1. Introduction

A production-minded customer-churn workflow for turning behavioural signals into calibrated churn probabilities, PR-AUC model selection, recall-focused threshold tuning, interpretable importances, and batch churn scoring.

This project demonstrates an end-to-end churn modelling workflow on both a synthetic dataset and the public IBM Telco churn dataset. It includes schema validation, model training and selection, threshold tuning, optional probability calibration, visual diagnostics, and a batch scoring CLI.

The goal is to show how a churn model can be turned into a decision-support tool, not just a single accuracy or AUC score.

2. Objective

Customer churn prediction with Python using synthetic datasets. Includes data generation, feature engineering, and training with Logistic Regression, Random Forest, and Gradient Boosting. Improved pipeline applies hyperparameter tuning and threshold optimization to boost recall. Outputs metrics, reports, and charts.

This project demonstrates how Python, Machine Learning can be applied to a real-world Data Science problem.

3. Key Features / Modules

• Dataset-agnostic pipeline that runs on any CSV with a binary churn target
• Synthetic data generator with a reproducible, readable churn signal
• Real-data loader for the public IBM Telco churn dataset
• PR-AUC model selection across Logistic Regression, Random Forest, and Gradient Boosting
• Threshold tuning for F2 (recall-leaning) with a precision floor
• Optional isotonic calibration with a reliability diagram and Brier score
• Permutation feature importance for model-agnostic, comparable importances
• Batch scoring CLI that reuses the model's own feature schema and tuned threshold
• Schema validation that fails fast with a clear message on bad input
• Model card documenting intended use, provenance, and limitations

4. Technology Stack

• scikit-learn
• matplotlib
• GitHub Actions

5. System Requirements

General requirements for this technology stack — check the README for exact versions.

• Python 3.8 or later
• pip / virtualenv for dependencies
• VS Code, PyCharm or Jupyter Notebook
• Git (to clone the repository)

6. Installation & Setup

git clone https://github.com/AmirhosseinHonardoust/Customer-Churn-Prediction.git
cd Customer-Churn-Prediction

pip install -r requirements.txt

pip install -r requirements-dev.txt

python data/generate_customers.py --n 10000 --seed 42 --out data/customers.csv
python src/train_models.py --input data/customers.csv --outdir outputs --seed 42

python data/fetch_telco.py --out data/telco_churn.csv
python src/train_models.py --input data/telco_churn.csv --outdir outputs --seed 42

Full setup instructions are in the project README.

7. Future Enhancements

Suggested extensions you can add to make this your own project.

• Turn the analysis into an interactive dashboard
• Automate data refresh with a scheduled job
• Add a predictive model on top of the analysis

8. Viva / Review Questions

Common questions examiners ask for projects in this domain.

1. What is the source of the dataset and how was missing data handled?
2. Which exploratory analysis steps revealed the most useful insight?
3. Why were these particular charts chosen to present the data?
4. Which statistical or ML technique supports the conclusions?
5. How could the analysis be automated or refreshed with new data?

9. Source Code & License

This project is developed by AmirhosseinHonardoust and published on GitHub under the MIT License. Please follow the license terms and credit the original author when you use or modify this code.