💳⚡ Credit Card Fraud Detection — XGBoost + Simulated Annealing

A concise and reproducible project for credit card fraud detection using XGBoost and Simulated Annealing (SA) for hyperparameter optimization.

---

🚀 Overview

This project explores three complementary approaches:

• ✅ Baseline — 5-fold Cross-Validation with OOF (Out-of-Fold) metrics + confusion matrix
• 🔥 SA Tuner — Simulated Annealing on a continuous search space
• 🧊 Grid-SA — Simulated Annealing on a discretized, finite grid
• 📊 Compare_Models.ipynb — visual comparison of metrics & feature importances
• 🔍 EDA.ipynb — exploratory data analysis on the dataset

---

🗂️ Project Structure

fraud_detection/
├─ data/                         # place creditcard.csv here
├─ Notebooks/
│  ├─ EDA.ipynb                  # Exploratory Data Analysis
│  └─ Compare_Models.ipynb       # compare metrics & feature importances
├─ models/
│  ├─ model_pipeline_baseline.joblib
│  ├─ xgb_sa_best.pkl
│  └─ xgb_grid_sa_best.pkl
├─ runs/
│  ├─ metrics_cv.json            # baseline metrics
│  ├─ sa_best.json               # SA best model metrics
│  ├─ grid_sa_best.json          # Grid-SA best model metrics
│  ├─ sa_history.json            # SA iterations
│  └─ grid_sa_history.json       # Grid-SA iterations
├─ utils_data.py                 # loading & preprocessing
├─ train.py                      # 5-fold CV baseline
├─ sa_tuner.py                   # Simulated Annealing tuner
└─ grid_sa_tuner.py              # Discretized SA tuner

⚙️ Setup

conda create -n fraud_env python=3.10 -y
conda activate fraud_env
conda install -y numpy pandas scikit-learn scipy matplotlib
pip install xgboost joblib tqdm statsmodels jupyter ipywidgets

🧠 Run the Models

1️⃣ Baseline (5-fold CV)

python train.py --data creditcard.csv --cv 5 \
  --n-estimators 300 --max-depth 6 --learning-rate 0.1 \
  --subsample 0.8 --colsample-bytree 0.8

📁 Outputs:

- `runs/metrics_cv.json` — metrics (`f1`, `precision`, `recall`, `pr_auc`, `roc_auc`, `confusion_matrix`, etc.)  
- `models/model_pipeline_baseline.joblib` — full trained pipeline  

---

2️⃣ Simulated Annealing Tuner

python sa_tuner.py --data creditcard.csv --iters 60 --cv 3 --t0 1.0 --alpha 0.95

📁 Outputs:

- `runs/sa_best.json`  
- `runs/sa_history.json`  
- `models/xgb_sa_best.pkl`  

---

3️⃣ Grid-SA (Discretized)

python grid_sa_tuner.py --data creditcard.csv --iters 80 --cv 3 --t0 1.0 --alpha 0.95

📁 Outputs:

- `runs/grid_sa_best.json`  
- `runs/grid_sa_history.json`  
- `models/xgb_grid_sa_best.pkl`  

---

4️⃣ Compare & Visualize

jupyter notebook Notebooks/Compare_Models.ipynb

📊 Compare all results, visualize metrics, and inspect feature importances.

---

🎯 Notes

• Primary metric: PR-AUC (Average Precision) — best for heavy imbalance
• Only Time and Amount are scaled; V1–V28 are used as-is
• Class imbalance handled with scale_pos_weight = #neg / #pos
• All preprocessing and training wrapped in a Pipeline(pre, XGB) to avoid data leakage

---

✨ Built with love, curiosity, and way too many folds of cross-validation.