This repository contains implementation of a framework that integrates churn prediction and customer segmentation process to provide telco operators with a complete churn analysis to better manage customer churn.

Dataset: https://www.kaggle.com/datasets/jpacse/datasets-for-churn-telecom

• Loaded the original cell2celltrain.csv file
• The original dataset has 58 columns.
• Target Variable: Churn (Binary: Yes/No)

• Filled 35 categorical missing values with mode (most frequent value)
• Filled 23 numerical missing values with mean

• Applied label encoding to categorical variables

• Applied Min-Max scaling to normalize numerical features

• Reduces the dimensionality of the dataset.
• Dropped columns before performing: Churn, CustomerID, ServiceArea
• Total of 20 attributes selected for churn prediction.
• Features: MadeCallToRetentionTeam, CreditRating, HandsetPrice, RetentionCalls, CurrentEquipmentDays, HandsetRefurbished, RetentionOffersAccepted, HandsetWebCapable, RespondsToMailOffers, BuysViaMailOrder, MonthlyMinutes, HandsetModels, OffPeakCallsInOut, AgeHH1, ReceivedCalls, Homeownership, Handsets, PeakCallsInOut, TotalRecurringCharge, AgeHH2

Six classification models were trained and evaluated:

• Logistic Regression
• Decision Tree
• Random Forest
• Naive Bayes
• AdaBoost
• XGBoost

In churn prediction, the primary metrics should be

• Recall on the churn class (catch as many churners as possible)
• F1-score (balance between precision and recall)
• AUC-PR (Precision-Recall AUC)

• Imbalanced dataset: Ensemble models (XGBoost, Random Forest, and AdaBoost) performed best in terms of AUC and precision, while Naïve Bayes and Decision Tree showed better recall, indicating different trade-offs in churn prediction.
• SMOTEd dataset: Overall, ensemble models (XGBoost, Random Forest, and AdaBoost) outperformed traditional methods, with XGBoost emerging as the best-performing classifier.

• After performing the churn prediction, Bayesian Logistic Regression is used to conduct the factor analysis, aiming to find the reason behind churn, and provide some important factors for churn customer segmentation.
• Top 16 features: CurrentEquipmentDays, RetentionCalls, MadeCallToRetentionTeam, Handsets, TotalRecurringCharge, HandsetModels, RetentionOffersAccepted, ReceivedCalls, AgeHH1, MonthlyMinutes, HandsetRefurbished, RespondsToMailOffers, HandsetWebCapable, OffPeakCallsInOut, PeakCallsInOut, CreditRating

• K-means clustering is an unsupervised machine learning algorithm used to group data points into clusters based on their similarity, aiming to minimize the distances between data points and their respective cluster centroids.
• Elbow method: It is a heuristic used to determine the optimal number of clusters (k) for K-means clustering.
• Silhoutte score: It is a metric used to evaluate the quality of clusters in clustering algorithms. A higher Silhouette Score indicates better clustering, with clear separation between clusters and strong cohesion within each cluster.

• Optimal K=3
• Cluster 1: 10626 samples (72.23%)
• Cluster 2: 780 samples (5.30%)
• Cluster 3: 3305 samples (22.47%)

The heatmap below visualizes the top 10 features influencing churn, highlighting how each customer cluster differs in behavior and how those behaviors impact churn likelihood. The color represents the normalized average value of each feature within a cluster, while the annotation shows the corresponding Bayesian effect on churn odds (% change).

• Cluster 0 appears to have the highest churn risk:

  • Customers tend to have older equipment (+292% effect on churn), more handsets, and more handset models — all strong churn drivers.
  • They also accept fewer retention offers and receive fewer calls, further increasing churn likelihood.

• Cluster 2 shows similar churn risk to Cluster 0, with:

  • High values for CurrentEquipmentDays, Handsets, and HandsetModels, all of which are positively associated with churn.
  • Lower engagement with the retention team and fewer accepted offers, reinforcing churn propensity.

• Cluster 1 is likely the lowest-risk cluster:

  • This group shows high retention engagement — more calls to and from the retention team, and more offers accepted — features associated with lower churn probability.
  • They also tend to have newer equipment and fewer handsets, both contributing to churn reduction.

• Rows: Top churn-driving features selected from a Bayesian logistic regression model.
• Columns: Clusters generated using KMeans on churned customers.
• Cell Color: Normalized feature mean (red = high, blue = low).
• Annotations: Feature's average z-score in the cluster + its % effect on churn (positive = increases churn, negative = decreases churn).

The logistic regression model was trained and used to predict churn probabilities for the subset of customers who had already churned. The predicted churn probabilities were subsequently averaged across predefined customer segments.

• Cluster 1: 30.92%
• Cluster 2: 46.90%
• Cluster 3: 25.49%

Create a file named .env.local inside the frontend/ directory with the following content:

NEXT_PUBLIC_BACKEND_URL=http://localhost:8000

Adjust the URL if your FastAPI backend is running on a different address.

cd frontend
npm install
npm run dev

This starts the frontend at http://localhost:3000.

cd backend
python -m venv env
source env/bin/activate
pip install -r requirements.txt
python api/main.py

This starts the FastAPI backend at http://localhost:8000.