Customer Account Retention & Churn Risk Terminal (ANN)

An enterprise quantitative risk framework and operational retention intelligence terminal powered by a 3-layer feedforward Artificial Neural Network (ANN) trained on 10,000 historical retail banking customer records.

---

Quick Navigation

• Abstract & Project Summary
• Research Problem & Objectives
• Scientific Methodology
• Repository Structure
• Jupyter Research Notebooks
• Dataset Provenance & Schema
• Prediction Results & Performance Benchmarks
• Embedded Research Figures
• Demonstration Video
• Reproducibility & Installation
• Running the Streamlit Application
• Deployment to Streamlit Cloud
• Hosted Frontend-Only Exploration
• Technology Stack
• Limitations & Future Research
• Academic References

---

Abstract & Project Summary

Customer attrition in retail banking represents substantial revenue leakage and elevates customer acquisition expenditures. This research project develops, trains, validates, and deploys a deep learning classification pipeline that evaluates multi-attribute demographic standing, depository balance, credit score, product utilization, and digital activity to quantify customer churn probability.

The predictive engine employs a 3-layer feedforward Artificial Neural Network (Input 12 $\rightarrow$ Dense 64 ReLU $\rightarrow$ Dense 32 ReLU $\rightarrow$ Dense 1 Sigmoid) containing 2,945 trainable parameters, optimized via Adam with binary cross-entropy loss. On an unseen validation partition of 2,000 customer accounts, the model attains 86.25% classification accuracy and a validation loss of 0.3542, demonstrating superior predictive calibration over linear baseline models. The repository bundles end-to-end research notebooks, serialized model weights and encoders, benchmark metrics, and a production-grade Streamlit interactive risk terminal.

---

Research Problem & Objectives

The Problem

Predicting retail banking attrition is challenging due to complex non-linear interactions between balance levels, customer age brackets, and account engagement tenure. Customers with high depository balances frequently churn if inactive, while multi-product holders demonstrate distinct non-linear retention dynamics that cannot be captured adequately by simple additive linear classifiers.

Central Objectives

1. Non-Linear Representation Learning: Train a multi-layer deep neural network with ReLU non-linearities to capture complex customer attrition patterns.
2. Probability Calibration: Output well-calibrated scalar posterior probabilities $\hat{y} \in [0, 1]$ mapped to discrete operational risk tiers.
3. Analyst Decision Support: Provide an institutional terminal interface for real-time scenario modeling and diagnostic risk breakdown.

---

Scientific Methodology

The feedforward network processes standardized 12-dimensional customer feature tensors $\mathbf{x} \in \mathbb{R}^{12}$ across two hidden representation stages:

$$\mathbf{a}^{[1]} = \text{ReLU}\left(\mathbf{W}^{[1]} \mathbf{x} + \mathbf{b}^{[1]}\right) \in \mathbb{R}^{64}$$ $$\mathbf{a}^{[2]} = \text{ReLU}\left(\mathbf{W}^{[2]} \mathbf{a}^{[1]} + \mathbf{b}^{[2]}\right) \in \mathbb{R}^{32}$$ $$\hat{y} = \sigma\left(\mathbf{W}^{[3]} \mathbf{a}^{[2]} + b^{[3]}\right) = \frac{1}{1 + e^{-z^{[3]}}} \in (0, 1)$$

Parameters $\mathbf{W}$ and $\mathbf{b}$ are trained by minimizing Binary Cross-Entropy loss:

$$\mathcal{L} = -\frac{1}{N} \sum_{i=1}^{N} \left[ y_i \ln \hat{y}_i + (1 - y_i) \ln (1 - \hat{y}_i) \right]$$

flowchart TD
    In["Raw Account Demographics & Financial Attributes<br/>(10 Customer Features)"] --> Enc["Categorical Encoding Stage<br/>(One-Hot Geography & Binary Label Gender)"]
    Enc --> Scale["Continuous Normalization<br/>(Z-Score StandardScaler via scaler_pickle.pkl)"]
    Scale --> Tensor["Standardized Input Tensor x in R^12"]
    Tensor --> L1["Hidden Layer 1: Dense 64 (ReLU)<br/>(832 Trainable Parameters)"]
    L1 --> L2["Hidden Layer 2: Dense 32 (ReLU)<br/>(2,080 Trainable Parameters)"]
    L2 --> Out["Output Layer: Dense 1 (Sigmoid)<br/>(33 Parameters -> Continuous Churn Probability y_hat)"]
    Out --> Action["Retention Action Tier Mapping<br/>(Low <20% | Moderate 20-50% | Elevated 50-70% | Critical >70%)"]

Loading

For detailed mathematical proofs and layer parameter dimensions, see docs/methodology.md.

---

Repository Structure

Churn_prediction_ANN/
├── README.md                           # Master project research documentation
├── requirements.txt                    # Project dependencies
├── app.py                              # Streamlit operational retention terminal
├── model.h5                            # Trained Keras Sequential neural network
├── scaler_pickle.pkl                   # StandardScaler continuous parameter matrix
├── geo_encoder.pkl                     # OneHotEncoder for Geography
├── label_encoder_gender.pkl            # LabelEncoder for Gender
│
├── notebooks/
│   ├── README.md                       # Notebook execution index
│   ├── 01_churn_ann_model_experiments.ipynb   # Model training & TensorBoard tracking
│   └── 02_churn_ann_inference_pipeline.ipynb  # End-to-end inference verification
│
├── data/
│   ├── README.md                       # Dataset documentation & provenance
│   └── raw/
│       └── Churn_Modelling.csv         # 10,000-customer historical dataset
│
├── results/
│   ├── README.md                       # Experimental benchmark summary
│   ├── figures/
│   │   ├── README.md                   # Figures catalog
│   │   ├── retention_analytics_banner.png # Attrition distributions & ROC curve
│   │   ├── ann_topology_flow.png       # High-res MLP network architecture flow
│   │   └── ann_topology_flow.svg       # Scalable vector topology diagram
│   ├── metrics/
│   │   └── ann_training_metrics.json   # Serialized training loss and accuracy logs
│   └── predictions/
│       ├── README.md                   # Prediction schemas
│       └── sample_churn_predictions.json # Calibrated archetype case studies
│
├── docs/
│   ├── methodology.md                  # Statistical & mathematical formulation
│   ├── architecture.md                 # System components & API contracts
│   └── references.md                   # Academic literature citations
│
├── logs/fit/                           # TensorBoard training event logs
└── static/                             # Terminal visual diagrams & favicons

---

Jupyter Research Notebooks

Notebook	Focus	Inputs	Outputs
notebooks/01_churn_ann_model_experiments.ipynb	Exploratory analysis, OneHotEncoding, StandardScaler calibration, Keras Sequential ANN training, TensorBoard logging, and model export	data/raw/Churn_Modelling.csv	model.h5, *.pkl encoders, event logs
notebooks/02_churn_ann_inference_pipeline.ipynb	End-to-end inference pipeline verification, artifact unpickling, and synthetic batch scoring	model.h5, *.pkl	Continuous churn probabilities $\hat{y}$

For execution details and environment setup, refer to the Notebooks Index.

---

Dataset Provenance & Schema

• Sample Size: 10,000 retail banking customers across France, Germany, and Spain.
• Attrition Distribution: Retained: 7,963 ($79.6%$), Exited: 2,037 ($20.4%$).
• Features Evaluated:
  • CreditScore: Financial creditworthiness ($350 - 850$, mean: $650.5$)
  • Geography: Operational country (France, Germany, Spain)
  • Gender: Client demographic (Female, Male)
  • Age: Client age in years ($18 - 92$, mean: $38.9$)
  • Tenure: Account duration with bank ($0 - 10$ years, mean: $5.0$)
  • Balance: Depository balance ($$0 - $250,898$, mean: $$76,485$)
  • NumOfProducts: Active account services ($1 - 4$, mean: $1.53$)
  • HasCrCard: Credit card ownership ($0 = \text{No}, 1 = \text{Yes}$)
  • IsActiveMember: Account activity indicator ($0 = \text{Inactive}, 1 = \text{Active}$)
  • EstimatedSalary: Modeled annual salary ($$11 - $199,992$, mean: $$100,090$)

Further schema details are cataloged in data/README.md.

---

Prediction Results & Performance Benchmarks

Empirical Model Performance

• Hidden Layers: Layer 1 (64 units, ReLU) $\rightarrow$ Layer 2 (32 units, ReLU)
• Trainable Parameters: 2,945 weights and biases
• Training Set (8,000 samples): Accuracy = 86.40%, Loss = 0.3320
• Validation Set (2,000 samples): Accuracy = 86.25%, Loss = 0.3542
• ROC-AUC Score: 0.852

Case Study Archetype Predictions

Archetype Profile	Geography	Age	Balance	Products	Active	Predicted Churn	Risk Category
Stable Wealth Depositor	France	38	$$125,000$	2	Yes	$4.8%$	Low Risk (<20%)
Mid-Tenure Attrition Candidate	Germany	52	$$88,000$	1	No	$54.2%$	Elevated Risk (50–70%)
Critical Outflow Flight Risk	Germany	56	$$142,000$	1	No	$89.1%$	Critical Risk (>70%)

Detailed evaluation metrics are archived in results/metrics/ann_training_metrics.json.

---

Embedded Research Figures

Figure 1: Attrition Distributions & Risk Factor Curves

Figure 1: Customer attrition rates stratified by age brackets, depository balance density distribution, active membership retention divergence, and neural network ROC curve ($AUC \approx 0.85$).

Figure 2: Multi-Layer Perceptron (MLP) Topology & Feature Flow

Figure 2: Architectural diagram tracing raw input attributes through categorical encoding, z-score standardization, and multi-layer dense transformations to the final Sigmoid retention decision neuron.

---

Demonstration Video

Watch the operational walkthrough of the Customer Retention & ANN Risk Terminal below:

churn_demo.mp4

Direct repository link: results/churn_demo.mp4

---

Reproducibility & Installation

Environment Setup

Requires Python 3.10+:

# Clone and enter directory
cd Churn_prediction_ANN

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Reproducing Training & Experiments

jupyter lab notebooks/01_churn_ann_model_experiments.ipynb

---

Running the Streamlit Application

Launch the interactive analytical terminal:

streamlit run app.py --server.port 8503

Access in browser: http://127.0.0.1:8503/

Features Included:

• Tab 1: Operational Risk Assessment Console: Interactive sliders, archetype fast presets, and instant retention risk diagnostics.
• Tab 2: Neural Network Architecture Explorer: Complete layer topology inspection, parameter matrix, and embedded flow diagram.
• Tab 3: Empirical Dataset Reference: Historical baseline demographic charts across 10,000 bank accounts.

---

Deployment to Streamlit Cloud

The retention risk terminal is configured for zero-friction continuous deployment on Streamlit Community Cloud.

Deployment Specifications:

• Runtime: Python 3.10 (configured via runtime.txt)
• Theme Configuration: Pre-configured in .streamlit/config.toml (Ubuntu typography, emerald primary #059669, light slate background #f8fafc)
• Model & Artifacts Loading: Absolute relative resolution via os.path.dirname(os.path.abspath(__file__)) ensures model model.h5, scaler_pickle.pkl, and encoders load reliably whether executed at repo root or subfolder level.
• Dependency Manifest: Configured in requirements.txt (compatible with Streamlit Cloud Debian container).

Step-by-Step Deployment Guide:

1. Push your repository to GitHub.
2. Sign in to Streamlit Community Cloud with your GitHub account.
3. Click New app in the upper right corner.
4. Specify your repository details:
   • Repository: your-username/your-repo
   • Branch: main
   • Main file path:
     • If deploying from the multi-project repository: Churn_prediction_ANN/app.py
     • If deploying from a standalone project repository: app.py
5. Click Advanced settings (optional):
   • Python Version: Select 3.10
6. Click Deploy!. Streamlit Cloud will install dependencies from requirements.txt, launch the container, and provide a publicly accessible HTTPS link.

---

Hosted Frontend-Only Exploration

• Interactive Sliders & Presets: Streamlit maintains instant reactive recomputation when parameters are modified.
• Pre-Calculated Archetypes: Analysts can test typical institutional customer profiles with one-click presets without configuring all 10 feature values manually.

---

Technology Stack

• Runtime & Language: Python 3.10
• Deep Learning Framework: TensorFlow 2.x, Keras
• Machine Learning & Encoders: Scikit-Learn (StandardScaler, OneHotEncoder, LabelEncoder)
• Data Manipulation: NumPy, Pandas
• Experiment Tracking: TensorBoard
• User Interface Engine: Streamlit
• Design & Typography: Canonical Ubuntu font family, high-contrast quantitative risk styling

---

Limitations & Future Research

1. Temporal Sequences: The dataset represents static cross-sectional snapshots; future research will explore Recurrent Neural Networks (LSTM/GRU) or Temporal Fusion Transformers (TFT) on sequential transaction logs.
2. Class Imbalance Handling: The natural $80/20$ retention imbalance was modeled directly; applying focal loss or synthetic minority oversampling (SMOTE) may further enhance minority recall.

---

Academic References

1. De Caigny, A., Coussement, K., & De Bock, K. W. (2018). A new hybrid classification algorithm for customer churn prediction. EJOR, 269(2), 760–772.
2. Kingma, D. P., & Ba, J. (2014). Adam: A method for stochastic optimization. arXiv:1412.6980.
3. Goodfellow, I., Bengio, Y., & Courville, A. (2016). Deep Learning. MIT Press.