Metadata-Version: 2.4
Name: fraud-detection-xy
Version: 1.0.2
Summary: Credit card fraud detection with ML/DL models and interpretability
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: kagglehub>=0.3.0
Requires-Dist: imbalanced-learn>=0.12.0
Requires-Dist: shap>=0.45.0
Requires-Dist: lime>=0.2.0
Requires-Dist: eli5>=0.13.0
Requires-Dist: xgboost>=2.0.0
Requires-Dist: lightgbm>=4.0.0
Requires-Dist: pytorch-tabnet>=4.1.0
Requires-Dist: scikit-learn>=1.4.0
Requires-Dist: seaborn>=0.13.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: pandas>=2.1.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: torch>=2.1.0

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

پروژهٔ شناسایی تقلب در تراکنش‌های کارت اعتباری با ترکیب مدل‌های یادگیری ماشین کلاسیک،
یادگیری عمیق جدولی (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](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
```

## نصب

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

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

## اجرا

```bash
conda activate myenv
python main.py
```

یا:

```bash
fraud-detection
```

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

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

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

```bash
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](docs/methodology.md) — روش‌شناسی، توضیح مدل‌ها و جریان pipeline
