credit-card-fraud-xgboost

credit-card-fraud-xgboost

Clasificador binario de fraude en transacciones con tarjeta de crédito. Entrenado sobre gusdelact/credit-card-fraud-curated (curación de alenc123/credit-card-fraud).

Información del modelo

• Tipo: XGBClassifier
• Framework: XGBoost logloss
• Autor: gusdelact
• Fecha de entrenamiento: 2026-05-18T03:18:43.456558
• Tarea: clasificación binaria (fraude vs no fraude)
• Variable objetivo: is_fraud

Datos de entrenamiento

• Fuente original: alenc123/credit-card-fraud (1.3M filas).
• Subsample estratificado: 240000 filas (train) + 60000 (test).
• Tasa de fraude: ~0.58%.
• Features: 74 tras One-Hot Encoding.

Hiperparámetros (resultado de RandomizedSearchCV con CV=5, scoring=F1)

{
  "subsample": 0.8,
  "n_estimators": 400,
  "max_depth": 6,
  "learning_rate": 0.05,
  "colsample_bytree": 0.7
}

• scale_pos_weight = 171.66 (≈ n_neg / n_pos), en lugar de SMOTE.
• tree_method = "hist" para eficiencia en CPU.

Métricas en test

El umbral óptimo se calibra por F1 sobre la curva precision-recall del test set. La elección final del umbral en producción depende del costo relativo entre falsos negativos (fraude no detectado) y falsos positivos (transacción legítima rechazada).

Cómo usar

import joblib
import json
import pandas as pd
from huggingface_hub import hf_hub_download

REPO = "gusdelact/credit-card-fraud-xgboost"
model = joblib.load(hf_hub_download(REPO, "model.joblib"))
preprocessor = joblib.load(hf_hub_download(REPO, "preprocessor.joblib"))
schema = json.load(open(hf_hub_download(REPO, "feature_schema.json")))

# Preparar features crudas (debe incluir trans_date_trans_time, dob, lat, long,
# merch_lat, merch_long, amt, category, gender, state, city_pop)
# y derivar hour/day_of_week/month/age/distance_km como en el pipeline original.
# Ver app_inference/app_inference.py para un ejemplo completo.

Fundamento teórico (resumen)

El diseño completo está en notes/0[1-3]_design_*.md del repositorio. En síntesis:

• Boosting con shrinkage: ISLP §8.2.3 — learning_rate pequeño + muchos árboles equivale a una regularización L1 monótona en el espacio de árboles (ESL §16.2.2). Con esta estructura el sobreajuste tiende a aparecer lentamente.
• Costos asimétricos vía pesos: ESL §9.2 — ponderar la clase minoritaria por L_kk' = n_neg / n_pos desplaza la frontera de Bayes hacia mayor recall, equivalente a scale_pos_weight en XGBoost.
• Calibración del umbral: ISLP §4.4.3 — el umbral 0.5 minimiza el error global pero ignora costos asimétricos; mover el umbral por la curva PR permite optimizar F1 directamente sobre la clase de interés.

Limitaciones

• Split aleatorio (no temporal): si el patrón de fraude evoluciona, el desempeño en producción puede degradarse. Mitigación: monitoreo y reentrenamiento periódico.
• Posible leakage por cc_num: el split actual no agrupa por tarjeta. Una versión futura debería usar GroupKFold(groups=cc_num).
• Categorías geográficas limitadas a EE. UU.: state es un campo de estados americanos.
• category es OneHot fijo: categorías no vistas en train se ignoran (handle_unknown="ignore").

Cómo citar

@model{credit-card-fraud-xgboost,
  author = {gusdelact},
  title  = {credit-card-fraud-xgboost},
  year   = {2026},
  publisher = {Hugging Face Hub}
}