README_OLD.md

ML-Project2: Customer Churn Analysis

A comprehensive machine learning bootcamp project focused on analyzing and predicting customer churn behavior using exploratory data analysis (EDA) and predictive modeling.

📋 Project Overview

This project analyzes customer churn patterns in a subscription-based service using the Customer Churn Dataset. The analysis includes detailed exploratory data analysis, feature engineering, and machine learning model development to predict which customers are likely to churn.

🎯 Objectives

• Perform comprehensive exploratory data analysis (EDA) on customer churn dataset
• Understand key factors influencing customer churn
• Build predictive models to identify at-risk customers
• Generate detailed reports with insights and recommendations

📊 Dataset

Files:

• customer_churn_dataset-training-master.csv - Training dataset
• customer_churn_dataset-testing-master.csv - Testing dataset

Features:

• CustomerID: Unique identifier for each customer
• Gender: Customer gender
• Age: Customer age
• Tenure: Duration (months) customer has been using the service
• Usage Frequency: Number of service uses in the last month
• Support Calls: Customer support calls made in the last month
• Payment Delay: Days of payment delay in the last month
• Subscription Type: Type of subscription chosen
• Contract Length: Duration of the signed contract
• Total Spend: Total spending on company products/services
• Last Interaction: Days since last customer interaction
• Churn: Target variable (1 = Churned, 0 = Retained)

🗂️ Project Structure

ML_101_BootCamp/
├── Notebooks/
│   └── 1_EDA.ipynb                          # Exploratory Data Analysis notebook
├── Data/
│   ├── customer_churn_dataset-training-master.csv
│   ├── customer_churn_dataset-testing-master.csv
│   └── eda_to_word.py                       # Script to generate Word report
├── eda_images_word/                         # Generated EDA visualizations
├── main.py                                  # Main entry point
├── pyproject.toml                           # Project configuration & dependencies
├── get-pip.py                               # Pip installation utility
└── README.md                                # This file

🔧 Technologies & Dependencies

• Python 3.12+
• Data Analysis: pandas, numpy
• Visualization: matplotlib, seaborn, plotly
• Machine Learning: scikit-learn, joblib
• Explainability: SHAP, LIME
• Monitoring: Streamlit (dashboard), data drift detection
• API: FastAPI, uvicorn
• Experiment Tracking: MLflow
• Notebooks: ipykernel
• Reporting: python-docx (for Word report generation)
• Data Source: kagglehub

Installation

Install all dependencies using:

pip install -r requirements.txt

Or with the project configuration:

pip install -e .

Core Dependencies:

• ipykernel >= 7.1.0
• joblib >= 1.5.2
• kagglehub >= 0.3.13
• matplotlib >= 3.10.7
• numpy >= 2.3.5
• pandas >= 2.3.3
• scikit-learn >= 1.7.2
• seaborn >= 0.13.2

📈 Analysis Overview

1. Exploratory Data Analysis (EDA)

The main EDA is performed in Notebooks/1_EDA.ipynb and includes:

• Dataset Loading: Load and initial exploration of customer churn data
• Data Types & Quality: Checking data types and null value counts
• Descriptive Statistics: Summary statistics for numeric features
• Distribution Analysis: Histograms and boxplots for numeric columns
• Categorical Analysis: Count plots for categorical features
• Correlation Analysis: Heatmaps and correlation matrices
• Univariate & Bivariate Analysis: Feature relationships with churn
• Feature Engineering: Creating new features from existing ones

2. Machine Learning Models

Models implemented in the analysis:

• Linear Regression: Baseline regression model
• Random Forest Regressor: Ensemble-based predictive model

3. Model Evaluation Metrics

• Mean Absolute Error (MAE)
• Mean Squared Error (MSE)
• R² Score

📝 Report Generation

Generate a comprehensive Word document report with:

python Data/eda_to_word.py

Report Contents:

• Dataset sample (first 5 rows)
• Summary statistics for numeric columns
• Categorical value counts (top 10)
• Correlation table
• Visualizations:
  • Distribution plots with KDE
  • Boxplots for outlier detection
  • Count plots for categorical features
  • Correlation heatmap
  • Feature vs Churn relationships
  • Pairplots for multivariate analysis
• Preprocessing suggestions
• Key insights and recommendations

Output: Customer_Churn_EDA_Report.docx

🚀 Usage

Quick Start - Launch All Services

Start MLflow, API, and Dashboard all at once:

.\start_all_services.ps1

This will open:

• MLflow UI: http://localhost:5000 (Experiment tracking)
• API Docs: http://localhost:8000/docs (Prediction API)
• Dashboard: http://localhost:8501 (Monitoring & Explanations)

Individual Services

1. MLflow Tracking Server

.\start_mlflow.ps1

Access at: http://localhost:5000

2. Prediction API

.\start_api.ps1

Access at: http://localhost:8000/docs

3. Monitoring Dashboard

.\start_dashboard.ps1

Access at: http://localhost:8501

Dashboard Features:

• 📊 Overview: Model performance metrics and confusion matrix
• 🔍 SHAP Analysis: Global and local feature importance
• 💡 LIME Explanations: Individual prediction explanations
• 📉 Data Drift: Statistical drift detection and alerts
• 🎯 Live Predictions: Interactive prediction with real-time explanations

See DASHBOARD_GUIDE.md for detailed documentation.

4. LIME Explainability Dashboard (NEW! 🎉)

.\start_lime_dashboard.ps1

Access at: http://localhost:8503

Advanced LIME Dashboard Features:

• 🎯 Single Prediction: Deep-dive explanations with 4 selection methods
• 📊 Batch Analysis: Process 10-500 samples with heatmaps & distributions
• 🔬 Feature Explorer: Impact curves and correlation analysis
• 📈 Global Statistics: Aggregated feature importance rankings
• 🎨 Custom Input: Test what-if scenarios with interactive forms
• 💾 Export Capabilities: HTML reports, CSV data, multiple formats

Quick Start:

1. Launch with .\start_lime_dashboard.ps1
2. Start with Tab 4 (Global Statistics)
3. Explore the 5 powerful tabs

Documentation:

• Quick Start: LIME_GETTING_STARTED.md - Get started in 5 minutes
• Complete Guide: LIME_DASHBOARD_README.md - Full documentation
• Quick Reference: LIME_QUICK_REFERENCE.md - Daily usage guide
• Visual Guide: LIME_VISUAL_GUIDE.md - UI layouts & colors
• Comparison: DASHBOARD_COMPARISON.md - Choose the right dashboard
• Index: LIME_DOCS_INDEX.md - Documentation navigation hub

Run the Main Script

python main.py

Explore the Notebook

Open and run the Jupyter notebook:

jupyter notebook Notebooks/1_EDA.ipynb

Generate EDA Report

python Data/eda_to_word.py

This generates a comprehensive Word document with all analyses and visualizations.

🔍 Key Insights & Findings

Based on the comprehensive analysis:

Data Analysis

• Tenure Impact: Customers with shorter tenure show higher churn rates
• Payment Delays: Notable differences in payment delays across churn groups
• Usage Patterns: Usage frequency and total spend correlate with churn behavior
• Contract Length: Subscription and contract types show distribution differences across churn classes
• Class Distribution: Analysis of churn class imbalance to inform model selection
• Feature Relationships: Multiple features show predictive potential for churn

Model Performance

• Best F1 Score: 0.999960 (Random Forest model)
• Accuracy: 99.99%
• Key Predictors (SHAP analysis):
  1. Payment Delay (strongest positive indicator)
  2. Support Calls (high calls = churn risk)
  3. Total Spend (inverse correlation)
  4. Usage Frequency
  5. Last Interaction

Explainability Insights

• SHAP: Payment delay and support calls are the most impactful features globally
• LIME: Individual predictions show consistent feature importance patterns
• Drift Monitoring: Reference vs production data comparison available in dashboard

🛠️ Preprocessing Recommendations

• Missing Values: Handle through imputation or removal as needed
• Categorical Encoding: Apply One-Hot or Ordinal encoding to categorical features
• Feature Scaling: Scale numeric features for distance-based and regularized models
• Class Imbalance: Consider resampling or class-weighted models if imbalance is detected
• Feature Engineering: Create interaction terms and polynomial features if needed

📊 Model Development Pipeline

1. Data Preparation: Load, clean, and preprocess data
2. Feature Engineering: Create and select relevant features
3. Train-Test Split: Split data (80-20 or as needed)
4. Model Training: Train Linear Regression and Random Forest models
5. Model Evaluation: Assess using MAE, MSE, R² metrics
6. Hyperparameter Tuning: Optimize model parameters (if needed)
7. Model Persistence: Save trained models with joblib for deployment

📁 Output Files

• Customer_Churn_EDA_Report.docx - Comprehensive EDA report with visualizations
• eda_images_word/ - Directory containing generated visualization images
• mlruns/ - MLflow experiment tracking artifacts
• mlruns/best_model_artifacts/ - Exported best-performing models
• Data/preprocessor.pkl - Fitted data preprocessor
• Trained models (saved via joblib when applicable)

📚 Documentation

General Project Documentation

• README.md - This file, project overview

ML Monitoring Dashboard

• DASHBOARD_GUIDE.md - Complete dashboard usage guide
• DASHBOARD_QUICK_REF.md - Quick reference card
• DASHBOARD_VISUAL.md - Visual guide with layouts

LIME Explainability Dashboard (NEW!)

• LIME_GETTING_STARTED.md - ⚡ 5-minute quick start
• LIME_DASHBOARD_README.md - 📘 Complete guide
• LIME_QUICK_REFERENCE.md - 📋 Daily reference
• LIME_VISUAL_GUIDE.md - 🎨 UI/UX layouts
• DASHBOARD_COMPARISON.md - 🆚 Choose the right tool
• LIME_DOCS_INDEX.md - 🗺️ Navigation hub
• LIME_DASHBOARD_SUMMARY.md - 📄 Project summary

Technical Guides

• DOCKER_GUIDE.md - Docker deployment guide
• CICD_DOCKER_GUIDE.md - CI/CD pipeline documentation
• MLFLOW_GUIDE.md - MLflow tracking guide

🎓 Learning Outcomes

This project covers:

• Data loading and exploration with pandas
• Statistical analysis and visualization
• Feature analysis and correlation studies
• Machine learning model implementation
• Model evaluation and comparison
• Report generation and documentation
• Best practices in data science workflow

👤 Author

Repository: ML-Project2
Owner: Dev-Kavindu
Branch: main

📅 Project Timeline

• Date: December 2025
• Status: In Development
• Latest Updates: EDA completion and model baseline implementation

📝 Notes

• The project uses the customer_churn_dataset from Kaggle via kagglehub
• All visualizations are optimized for report generation (JPEG compression at 72 DPI)
• Word report generation uses python-docx for professional formatting
• Machine learning libraries follow scikit-learn conventions for consistency

🤝 Contributing

For improvements or modifications:

1. Create a feature branch
2. Implement changes
3. Update documentation
4. Commit and push to the repository

📞 Support

For issues or questions about the analysis, refer to:

• Notebook documentation in 1_EDA.ipynb
• Generated report Customer_Churn_EDA_Report.docx
• Code comments in eda_to_word.py

---

Last Updated: December 1, 2025