Customer Churn Scoring with Explainability

The Problem

Banks lose customers every day without knowing who is at risk or why.

This is a production-grade pipeline for predicting customer churn in banking, with automated feature engineering, Bayesian hyperparameter optimization, and SHAP-based explainability. It scores every customer by churn probability, ranks them by risk, and explains the exact factors driving each prediction so retention teams know who to prioritize and what to address.

Built to work with any tabular churn dataset. Swap the CSV, adjust the target column, and the pipeline handles the rest from raw data to a scored, explainable model.

What It Delivers

Automatic feature engineering

PolynomialFeatures generates candidate interactions automatically, then RandomForest importance decides which ones matter — reusable across different churn datasets without code changes.

Bayesian optimization

Optuna finds strong hyperparameters in far fewer trials than exhaustive grid search. The search space lives in config/xgb_params.py, so tuning depth is a configuration change, not a code change.

Business-first metrics

KS statistic and LIFT by decile instead of raw accuracy, which is misleading on imbalanced churn data. LIFT tells the business exactly how much better than random the model performs at each decile.

Saved artifacts

Label encoders, scaler, polynomial transformer, and selected feature list are all saved during training, allowing new customers to be scored with the exact same transformations, without retraining.

Metrics Explained

AUC-ROC

Overall discrimination power. 0.87+ is strong for churn.

Gini

Derived from AUC. 0.70+ is considered very good in banking.

KS

Maximum separation between churner and non-churner distributions. 0.50+ is a strong model.

LIFT

How many times more churners are found in a decile compared to random selection. A decile 10 LIFT of 4x means targeting the top 10% of scores finds 4 times more churners than reaching out randomly.

Pipeline Overview

Fig. 1 · Raw data to scored, explainable model. Every step saves its output to data/, models/, or outputs/, so the pipeline can be run in full or resumed from any step.

Key Decisions

01 · EDA

Summary report and initial cleaning, producing churn_clean.parquet.

02 · Target Analysis

Distribution and class balance check before any modeling decision is made.

03 · Preprocessing

Label encoding and standard scaling applied consistently across train and inference.

04 · Feature Engineering

PolynomialFeatures generates candidate interactions and powers automatically.

05 · Feature Selection

RandomForest importance selects the top N features from the generated candidates.

06 · Training

XGBoost combined with Optuna Bayesian optimization for hyperparameter tuning.

07 · Evaluation

AUC-ROC, Gini, KS statistic, and LIFT curve by decile.

08 · Explainability

SHAP values for global importance and per-customer drivers.

Repository

risk-001-customer-churn-scoring github.com →

churn-scoring-pipeline/
├── README.md
├── requirements.txt
├── .gitignore
├── config/
│ └── xgb_params.py
├── src/
│ ├── __init__.py
│ ├── eda.py
│ ├── target_analysis.py
│ ├── preprocessing.py
│ ├── feature_engineering.py
│ ├── feature_selection.py
│ ├── training.py
│ ├── evaluation.py
│ └── explainability.py
├── data/
│ ├── bank_customer_churn.csv
│ ├── churn_clean.parquet
│ ├── churn_preprocessed.parquet
│ ├── churn_features.parquet
│ └── churn_selected.parquet
├── models/
│ ├── xgb_churn.pkl
│ ├── label_encoders.pkl
│ ├── scaler.pkl
│ ├── polynomial.pkl
│ └── selected_features.pkl
├── outputs/
│ ├── ks_curve.png
│ ├── lift_curve.png
│ ├── shap_summary.png
│ ├── shap_bar.png
│ └── shap_waterfall.png
└── notebooks/
├── quickstart.ipynb
└── test_predict.ipynb

Stack: XGBoost, Optuna, SHAP, scikit-learn. Python 3.13. Works with any tabular churn dataset with a binary target column and minimal configuration changes.