A Machine Learning-Based Decision Support System for Predicting Customer Attrition and Quantifying Revenue Risk in Subscription Businesses
An end-to-end customer churn analytics system that transforms raw business data into executive-grade intelligence — zero configuration required — works out-of-the-box with raw, unstructured business data.
- Overview
- Quick Start
- Key Features
- How It Works
- Installation
- Usage
- Supported File Formats
- Column Auto-Detection
- Machine Learning Pipeline
- Output Report Structure
- Feature Engineering
- Customer Segmentation
- Methodology & Limitations
- Build EXE
- Project Structure
- Dependencies
- Author
- License
The Customer Churn Intelligence Platform is a fully automated, GUI-driven analytics tool built for business analysts and data professionals. It accepts raw customer data in virtually any tabular format, intelligently detects relevant columns, trains a machine learning model, and produces a polished, multi-sheet Excel report — all without writing a single line of code.
The platform is designed around a core business question:
"Which customers are about to leave, and how much revenue is at risk?"
Raw Data File → Auto-Clean → ML Model → Segmentation → Executive Excel Report
(any format) + Repair Training + CLV Calc (12 sheets + 6 charts)
# 1. Clone the repository
git clone https://github.com/ABHISHEKKKKK12345/Customer-Churn-Intelligence-Platform.git
# 2. Navigate to the project folder
cd Customer-Churn-Intelligence-Platform
# 3. Install dependencies
pip install -r requirements.txt
# 4. Run the tool
python customer_churn_intelligence_system.pyA GUI window will guide you through the rest — no configuration files, no command-line arguments required.
| Feature | Description |
|---|---|
| 🗂️ Universal File Ingestion | Supports CSV, Excel (.xlsx, .xls, .xlsm, .xlsb), ODS, and TSV — auto-tries 6 encodings and 6 delimiters |
| 🧹 Intelligent Data Cleaning | Removes duplicates, blank rows/columns, and unnamed Pandas artefacts; repairs currency symbols, US/EU/Indian locale numbers, and logical inconsistencies |
| 🔍 Smart Column Detection | Automatically identifies Churn, Revenue, Tenure, and Customer ID columns using keyword normalisation with conflict resolution |
| 🤖 Dual ML Models | Random Forest (primary, 300 trees) → Gradient Boosting (fallback, 150 estimators) → heuristic percentile score (last resort) |
| 📊 Synthetic Label Fallback | When no real churn column exists, labels are generated via a weighted percentile risk-score formula; ML metrics are suppressed and clearly flagged |
| 🧮 CLV Prediction | Retention-weighted historical customer value proxy: TotalCharges × (1 – Churn_Prob) |
| 🎯 2×2 Segmentation Matrix | Classifies every customer into High/Low Risk × High/Low Value for action prioritisation |
| 📈 Executive Excel Report | 12-sheet workbook with 14 KPI cards, 6 embedded charts, colour-coded risk indicators, and a full pipeline audit trail |
| 🔒 Safe File Saving | Retry logic (up to 3 attempts) with automatic timestamp-based renaming when the target file is locked or already open |
| Prominently flags synthetic labels throughout the report and suppresses misleading ML metrics for ethical, auditable reporting |
┌─────────────────────────────────────────────────────────────────┐
│ PIPELINE OVERVIEW │
├──────────────┬──────────────┬──────────────┬────────────────────┤
│ INGEST │ PREPARE │ ANALYSE │ REPORT │
├──────────────┼──────────────┼──────────────┼────────────────────┤
│ GUI file │ Strip bad │ Train Random │ Executive │
│ picker │ rows/cols │ Forest or │ Dashboard │
│ │ │ Gradient │ │
│ 6 encodings │ Detect col │ Boosting │ Segment Summary │
│ tried │ types │ │ │
│ │ │ Score every │ High-Risk Action │
│ 6 separators │ Currency / │ customer │ List │
│ tried │ locale fixes │ 0.0 → 1.0 │ │
│ │ │ │ Processed Data │
│ Excel, CSV, │ Label encode │ Segment into │ │
│ ODS, TSV │ categoricals │ 4 groups │ Raw Data │
│ │ │ │ │
│ │ Engineer │ Compute CLV │ Data Quality │
│ │ features │ & KPIs │ Audit Report │
└──────────────┴──────────────┴──────────────┴────────────────────┘
- Python 3.8 or higher
pippackage manager- Tkinter (included with most Python distributions)
git clone https://github.com/ABHISHEKKKKK12345/Customer-Churn-Intelligence-Platform.git
cd Customer-Churn-Intelligence-Platformpip install -r requirements.txtOr install manually:
pip install pandas numpy scikit-learn xlsxwriter openpyxl xlrd odfpypython customer_churn_intelligence_system.py💡 Linux users: If Tkinter is missing, install it via your system package manager:
- Ubuntu/Debian:
sudo apt-get install python3-tk- Fedora/RHEL:
sudo dnf install python3-tkinter
The tool is entirely GUI-driven — no command-line arguments or configuration files required.
Step 1 — Welcome Screen Click OK when the welcome dialog appears.
Step 2 — Select Your Dataset A file picker opens. Navigate to your customer data file (see Supported File Formats).
Step 3 — Automatic Processing The tool will:
- Load and clean your data
- Auto-detect all relevant columns
- Train the ML model (or fall back to heuristic scoring)
- Compute KPIs, CLV, segmentation, and revenue-at-risk
Step 4 — Review the Summary A results dialog shows:
- Detected churn column (or synthetic fallback notification)
- Model accuracy and AUC-ROC (suppressed if synthetic labels were used)
- Key findings: churn rate, high-risk customer count, annualised revenue at risk
Step 5 — Save the Report
Choose a save location and filename. The fully formatted .xlsx report is generated immediately.
💡 Tip: If your Excel file is already open, the tool will offer to auto-save with a timestamped filename to avoid a
PermissionError.
| Format | Extensions | Notes |
|---|---|---|
| CSV | .csv |
Auto-detects separator (, ; \t | :) |
| Excel (modern) | .xlsx .xlsm .xlsb |
Uses openpyxl engine |
| Excel (legacy) | .xls |
Uses xlrd engine |
| OpenDocument | .ods |
Read using the odfpy library |
| Text / TSV | .txt .tsv |
Same separator auto-detection as CSV |
Encodings tried automatically: utf-8-sig, utf-8, latin1, cp1252, iso-8859-1, utf-16
Minimum requirement: At least 1 data row and 2 columns.
The tool normalises all column names (lowercase, alphanumeric only) and searches for keywords in priority order. The most specific keyword wins, and no column can serve two roles simultaneously.
| Role | Keywords Searched (priority order) |
|---|---|
| Churn | churn, attrition, churned, leave, exit, cancel, left, status |
| Tenure | tenure, seniority, duration, period, months, age |
| Monthly Revenue | monthlycharge, monthlyfee, monthly, charge, rate, fee, price, subscription |
| Total Revenue | totalcharge, totalrevenue, lifetimevalue, total, revenue, bill, spend, amount, sales, ltv |
| Customer ID | customerid, custid, userid, accountid, clientid, memberid, id |
Fallback behaviour: If a column is not found, the tool falls back to numeric columns by index position, or uses sensible defaults (e.g., median tenure = 12 months, median monthly charge = Rs. 500).
String values in the churn column are mapped to binary labels automatically:
Churned → 1 |
Retained → 0 |
|---|---|
Yes, Y, True, 1, Churned, Left, Cancelled, Cancel, Exit, Quit, Inactive, Lost, Gone, Departed, Attrited, Closed |
No, N, False, 0, Active, Retained, Stay, Stayed, Current, Existing, Ongoing, Present, Alive, Good, Loyal |
⚠️ If more than 60% of values cannot be mapped to either side, synthetic labels are generated instead (see Methodology & Limitations).
The tool attempts models in this priority order, stopping at the first that succeeds:
| Priority | Model | Configuration |
|---|---|---|
| 1 | Random Forest | 300 trees, max depth 12, balanced class weights, random_state=42, n_jobs=-1 |
| 2 | Gradient Boosting | 150 estimators, max depth 5, random_state=42 |
| 3 | Heuristic Score | Percentile rank formula — no training required |
All 7 features below are used for model training:
| Feature | Formula / Source | Description |
|---|---|---|
tenure |
Raw column | Months the customer has been with the company |
MonthlyCharges |
Raw column | Current monthly billing amount |
TotalCharges |
Raw column | Cumulative historical charges |
AvgMonthlySpend |
TotalCharges / (tenure + 1) |
Normalised spend over customer lifetime |
ValueScore |
log(1 + TotalCharges) |
Log-transformed total value — reduces right skew |
LoyaltyScore |
tenure × (TotalCharges / (MonthlyCharges + 1)) |
Combined tenure-spend loyalty indicator |
SpendVariance |
|MonthlyCharges – AvgMonthlySpend| / (AvgMonthlySpend + 1) |
Billing instability signal — flags volatile payers |
ML training is attempted only when:
- Dataset has ≥ 20 rows (constant
MIN_ROWS_FOR_ML) - Churn column has ≥ 2 unique values (not all churned or all retained)
- An 80/20 stratified train/test split is applied when both classes have sufficient samples; falls back to a non-stratified split otherwise
All features are imputed with median strategy (sklearn.impute.SimpleImputer) before training. Categorical columns with 2–20 unique values are label-encoded; columns with more unique values are dropped from the numeric feature set.
⚠️ When churn labels are synthetic, model accuracy and AUC-ROC are intentionally suppressed. Reporting these metrics on synthetic labels would only measure how well the model reproduced the tool's own risk-score formula — not real customer behaviour. This is clearly flagged with a warning banner on the Dashboard and in the Data Quality Report.
The generated .xlsx file always contains 12 sheets:
-
Title banner — file name, model used, accuracy, AUC-ROC, and customer count
-
Synthetic labels warning banner (shown only when applicable)
-
14 KPI Cards across 2 rows:
Row KPIs Row 1 Total Customers · Churn Rate · Retention Rate · High Risk (≥60%) · Medium Risk (30–60%) · Low Risk (<30%) · Avg Tenure Row 2 Avg Customer CLV · Annualised Risk Revenue · Total CLV Portfolio · Avg Monthly Charge · ML Model · Model Accuracy · AUC-ROC Score -
6 Embedded Charts:
# Chart Title Type 1 Customer Segments by Count Column 2 Risk Tier Breakdown Doughnut 3 Churn Probability Distribution Column 4 Predicted CLV Distribution Bar 5 Customer Tenure Distribution Column 6 Monthly Charges Distribution Column
One row per customer segment with colour-coded churn rate:
- 🔴 RED — Churn Rate > 60%
- 🟡 AMBER — Churn Rate 30–60%
- 🟢 GREEN — Churn Rate < 30%
Columns: Segment · Customers · Churned · Churn Rate · Avg CLV · Total CLV · Avg Tenure · Avg Monthly Charge · Avg Risk Score
Top 1,000 customers with Churn_Prob ≥ 60%, sorted highest-risk first.
Columns: Customer ID (if detected) · Tenure · Monthly Charges · Total Charges · Predicted CLV · Churn Probability · Segment · Risk Tier
Auto-filter and frozen header row enabled.
Full dataset with all engineered features and ML outputs. Per-column numeric formatting applied (decimals, currency, percentages). Auto-filter and frozen header row enabled.
Original file content, completely untouched — preserved for audit and data lineage.
Full pipeline audit trail including:
- File information (name, path, original vs cleaned row counts, rows removed)
- Column detection results and all fallback decisions
- ML model details, features used, and metrics (or suppression reason)
- Methodology notes and formula explanations
- All output KPIs with their calculation basis
Data – Segments · Data – Risk Tiers · Data – Churn Prob · Data – CLV · Data – Tenure · Data – Monthly
These sheets directly feed the dashboard charts. They are accessible for reference but are not the primary deliverable.
| Engineered Column | Formula | Business Meaning |
|---|---|---|
AvgMonthlySpend |
TotalCharges / (tenure + 1) |
Normalised monthly spend over customer lifetime |
ValueScore |
log(1 + TotalCharges) |
Log-transformed total value — reduces right skew |
LoyaltyScore |
tenure × TotalCharges / (MonthlyCharges + 1) |
Combined tenure-spend loyalty indicator |
SpendVariance |
|Monthly – AvgMonthlySpend| / (AvgMonthlySpend + 1) |
Billing instability — flags volatile payers |
Churn_Prob |
ML model output (or heuristic rank) | Predicted probability of churning — range 0.0 to 1.0 |
Predicted_CLV |
TotalCharges × (1 – Churn_Prob) |
Retention-weighted historical value proxy |
Data integrity fix: Where TotalCharges < MonthlyCharges (logically impossible for any active customer), TotalCharges is automatically recomputed as tenure × MonthlyCharges.
Every customer is placed into one of four segments using a 2×2 Risk × Value matrix:
HIGH VALUE (Predicted_CLV ≥ median) |
LOW VALUE (Predicted_CLV < median) |
|
|---|---|---|
HIGH RISK (Churn_Prob ≥ 0.60) |
🔴 High Risk – High Value · PRIORITY 1 | 🟠 High Risk – Low Value · PRIORITY 2 |
LOW RISK (Churn_Prob < 0.60) |
🟢 Low Risk – High Value · NURTURE | ⚪ Low Risk – Low Value · MONITOR |
Risk Tiers (also stored as Risk_Tier column):
| Tier | Churn Probability Range |
|---|---|
| Low Risk | 0% – 30% |
| Medium Risk | 30% – 60% |
| High Risk | 60% – 100% |
Predicted_CLV is a retention-weighted historical proxy, not a true Customer Lifetime Value:
Predicted_CLV = TotalCharges × (1 – Churn_Prob)
This represents the portion of historical spend expected to be retained. It is not a survival model, discounted cash flow (DCF) CLV, or forward-looking revenue projection. Use for relative ranking purposes only.
Annualised revenue at risk is the forward-looking run-rate for high-risk customers:
Risk Revenue = Σ (MonthlyCharges × 12) for all customers where Churn_Prob ≥ 0.60
The historical TotalCharges for the same group is also separately reported in the Data Quality sheet.
When no real churn column is detected (or >60% of values cannot be mapped), labels are generated using:
Risk Score = tenure_rank (ascending)↓ × 0.40
+ monthly_charges_rank (ascending)↑ × 0.30
+ spend_variance_rank (ascending)↑ × 0.20
+ total_charges_rank (ascending)↓ × 0.10
Top 35% by Risk Score → Churned (1)
Remaining 65% → Retained (0)
ML accuracy and AUC-ROC are suppressed whenever synthetic labels are in use.
When ML cannot run (dataset too small, single-class labels), churn probability is estimated as:
Heuristic Score = tenure_rank↓ × 0.55
+ monthly_charges_rank↑ × 0.25
+ spend_variance_rank↑ × 0.20
Convert the tool into a standalone Windows .exe that requires no Python installation on the target machine.
- All dependencies from
requirements.txtmust be installed - A clean virtual environment is strongly recommended
- Build on the same OS as the target machine (Windows → Windows)
pip install pyinstallerpyinstaller --onefile --windowed --noconsole \
--name "Customer_Churn_Intelligence_Platform" \
--collect-all sklearn \
--collect-all openpyxl \
--collect-all xlsxwriter \
--collect-all odf \
--collect-all xlrd \
customer_churn_intelligence_system.pydist/Customer_Churn_Intelligence_Platform.exe
| Issue | Fix |
|---|---|
| EXE not opening or crashing | Ensure all dependencies were installed before building; rebuild in a clean venv |
| Missing module errors | Add the missing package with --collect-all <package> |
| GUI not showing | Ensure --windowed flag is present |
| Antivirus blocking EXE | Add an exception, or rebuild with a different --name value |
Customer-Churn-Intelligence-Platform/
│
├── customer_churn_intelligence_system.py # Main application — single self-contained file
├── requirements.txt # All Python dependencies
├── README.md # This documentation
└── .gitignore # Excludes build/, dist/, __pycache__/, *.spec
💡
dist/,build/, and.specfiles are excluded via.gitignore. To generate the.exe, follow the Build EXE section above.
pip install -r requirements.txt| Package | Purpose | Min Version |
|---|---|---|
pandas |
Data loading, cleaning, and manipulation | ≥ 1.3.0 |
numpy |
Numerical operations and array handling | ≥ 1.21.0 |
scikit-learn |
ML models, imputation, and label encoding | ≥ 0.24.0 |
xlsxwriter |
Excel report generation with charts and formatting | ≥ 3.0.0 |
openpyxl |
Reading .xlsx, .xlsm, .xlsb files |
≥ 3.0.0 |
xlrd |
Reading legacy .xls files |
≥ 2.0.0 |
odfpy |
Reading .ods OpenDocument spreadsheets |
≥ 1.4.0 |
tkinter |
GUI file dialogs and message boxes | Built-in (stdlib) |
| Field | Detail |
|---|---|
| Name | Abhishek |
| Project | Customer Churn Intelligence Platform |
This project is released under the MIT License. You are free to use, modify, and distribute it with attribution.
Built with ❤️ to transform raw customer data into actionable business intelligence.