fraud-detection-xy 1.0.1

Credit card fraud detection with ML/DL models and interpretability

تحلیل و شناسایی تقلب در معاملات مالی با یادگیری ماشین و یادگیری عمیق

پروژهٔ شناسایی تقلب در تراکنش‌های کارت اعتباری با ترکیب مدل‌های یادگیری ماشین کلاسیک، یادگیری عمیق جدولی (TabNet) و مدل‌های ترکیبی XGBoost + TabNet و LightGBM + TabNet.

• مجموعه‌داده: Credit Card Fraud (ULB) — ۲۸۴٬۸۰۷ تراکنش، ۴۹۲ تقلب (۰٫۱۷۲٪)
• تقسیم داده: ۸۰٪ آموزش / ۱۵٪ اعتبارسنجی / ۵٪ آزمون
• تفسیرپذیری: SHAP، LIME، ELI5

روش کلی

1. بارگذاری و تحلیل اکتشافی داده (EDA)
2. پیش‌پردازش (RobustScaler) و SMOTE روی دادهٔ آموزش
3. آموزش مدل‌های پایه: Logistic Regression، Random Forest، XGBoost، LightGBM، SVM
4. آموزش TabNet (شبکهٔ عمیق جدولی)
5. ترکیب XGBoost+TabNet و LightGBM+TabNet با میانگین وزن‌دار و Stacking
6. ارزیابی، مقایسه و تفسیرپذیری
7. ذخیرهٔ نتایج در results/<timestamp>/

جزئیات مدل‌ها: docs/methodology.md

ساختار پروژه

creditcard-fraud-xgb-tabnet/
├── main.py                    # نقطه ورود
├── src/                       # کد پکیج fraud_detection
│   ├── config.py
│   ├── pipeline.py
│   ├── output.py
│   ├── data/                  # بارگذاری و پیش‌پردازش
│   ├── eda/
│   ├── models/
│   ├── evaluation/
│   ├── visualization/
│   └── interpretability/
├── dataset/                   # creditcard.csv (دانلود خودکار)
├── docs/
│   └── methodology.md
├── results/                   # خروجی هر اجرا
│   └── YYYYMMDD_HHMMSS/
│       ├── run_info.json
│       ├── figures/
│       └── metrics/
├── requirements.txt
└── pyproject.toml

نصب

conda activate myenv
pip install -r requirements.txt
pip install -e .

پس از pip install -e . پوشهٔ fraud_detection.egg-info/ ساخته می‌شود (artifact نصب؛ در .gitignore است و نیازی به commit ندارد).

اجرا

conda activate myenv
python main.py

یا:

fraud-detection

هر اجرا یک پوشهٔ جدید با نام timestamp (مثلاً results/20250726_183045/) می‌سازد.

گزارش PDF از نتایج یک ران

برای دیدن همهٔ جداول و شکل‌ها در یک فایل (به‌ترتیب پایپلاین):

conda activate myenv
python -m fraud_detection.reporting.generate_report --run 20260726_194158

خروجی‌ها:

• results/<run>/report/report.tex
• results/<run>/report/report.pdf
• کپی آسان‌دسترس: reports/report_<run>.pdf

GPU

TabNet در صورت وجود CUDA روی GPU آموزش می‌بیند؛ در غیر این صورت روی CPU اجرا می‌شود.

داده

ترتیب بارگذاری در load_creditcard_dataset():

1. CREDITCARD_CSV یا dataset/creditcard.csv
2. kagglehub (نیاز به احراز هویت Kaggle)
3. آینهٔ Zenodo

خروجی‌ها

هر run در results/<timestamp>/ ذخیره می‌شود:

مسیر	توضیح
run_info.json	اطلاعات اجرا (timestamp و مسیرها)
figures/*.png	نمودارها
metrics/*.csv, metrics.json	نتایج عددی و LaTeX

مستندات

• docs/methodology.md — روش‌شناسی، توضیح مدل‌ها و جریان pipeline