Model Card: Churn Prediction Model
Overview
This model predicts whether a telecom customer is likely to churn (cancel their service), based on the Telco Customer Churn dataset. It is an XGBoost classifier trained on customer demographics, account details, and service usage patterns.
Files
final_xgboost_model.pkl: the trained XGBoost classifier.fitted_scaler.pkl: the fitted scaler used on the input features before prediction.
How to Use
import joblib
from huggingface_hub import hf_hub_download
model_path = hf_hub_download("JihanM/churn-prediction", "final_xgboost_model.pkl")
scaler_path = hf_hub_download("JihanM/churn-prediction", "fitted_scaler.pkl")
model = joblib.load(model_path)
scaler = joblib.load(scaler_path)
Apply the scaler to the same features used during training, then call model.predict or model.predict_proba.
Training environment: scikit-learn 1.7.2 (the scaler was saved with this version) and an xgboost version older than 3.4.1.
Loading with newer versions may print version warnings. Predictions were checked to be identical between the local and the uploaded copy on the author's machine, using xgboost 3.4.1 and scikit-learn 1.9.0.
Note: pickle files can run code when loaded. Only load files from sources you trust.
Intended Use
- Flagging customers at high risk of churning, so a retention team can proactively reach out.
- Not intended for automated decisions (for example, automatically approving discounts) without human review.
- Trained specifically on telecom industry data. Not validated for other industries without retraining.
Performance
On a held-out 20% test set:
| Metric | Class 0 (Stable) | Class 1 (Churn) |
|---|---|---|
| Precision | 0.89 | 0.49 |
| Recall | 0.72 | 0.75 |
| F1-score | 0.79 | 0.59 |
Overall accuracy: about 73%.
Why Recall Was Prioritized Over Precision
For churn prediction, missing a customer who is about to leave (false negative) is usually costlier than a false alarm (false positive). A false alarm just means an unnecessary retention offer, while a missed churner is a lost customer. The model is tuned to catch more true churners, at the cost of more false alarms.
Limitations
- Trained on a single, static dataset snapshot. Customer behavior changes over time, so the model should be retrained periodically on fresh data.
- About 49% precision on the churn class means roughly half of the "high risk" flags will be false alarms. This model should support human decision-making, not replace it.
- Not validated on customer populations outside this dataset's demographic and geographic scope.
When to Get a Human Involved
Any high-stakes action (contract changes, service cancellations, large discounts) based on this model's output should be reviewed by a person before being acted on.