Développement
du modèleModel
development

Un environnement virtuel par projet : les versions de vos librairies vivent dans .venv/ (ignoré par Git), pas dans le système. Activez-le au début de chaque session de travail.One virtual environment per project: your library versions live in .venv/ (ignored by Git), not in the system. Activate it at the start of every work session.

cd ~/fraud-detection
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install pandas scikit-learn matplotlib joblib jupyter
python -c "import sklearn, pandas; print(sklearn.__version__, pandas.__version__)"

Lancez Jupyter, créez un notebook nommé 01_exploration dans notebooks/, puis exécutez la première cellule. Le chemin est relatif au dossier notebooks/, d'où le ../ devant data/.Launch Jupyter, create a notebook named 01_exploration inside notebooks/, then run the first cell. The path is relative to the notebooks/ folder, hence the ../ before data/.

jupyter notebook notebooks/
# in the browser: New, then Notebook (Python 3), rename it 01_exploration

import pandas as pd
import matplotlib.pyplot as plt

df = pd.read_csv("../data/creditcard.csv")
print(df.shape)
df.head()

Le chiffre qui décide de tout : la métrique, la stratégie d'entraînement, le seuil. Comptez-le vous-même.The number that decides everything: the metric, the training strategy, the threshold. Count it yourself.

counts = df["Class"].value_counts()
print(counts)
print(f"fraud rate: {counts[1] / len(df):.3%}")

Une ligne de pandas suffit pour comparer les distributions de montants des deux classes.One line of pandas is enough to compare the amount distributions of the two classes.

df.groupby("Class")["Amount"].describe()

Time est un nombre de secondes depuis la première transaction : on le convertit en heure du jour, puis on trace le taux de fraude heure par heure.Time is a number of seconds since the first transaction: convert it to hour of day, then plot the fraud rate hour by hour.

df["hour"] = (df["Time"] // 3600) % 24
rate = df.groupby("hour")["Class"].mean() * 100
rate.plot(kind="bar", figsize=(10, 3), title="Fraud rate per hour (%)")
plt.show()

V14 et V17 sont les alliées classiques de ce dataset. Écrivez vos quatre réponses en cellules markdown, sauvegardez, puis commitez le notebook — c'est le livrable de la mission.V14 and V17 are this dataset's classic allies. Write your four answers in markdown cells, save, then commit the notebook — that's the mission's deliverable.

fig, axes = plt.subplots(1, 2, figsize=(11, 4))
for ax, col in zip(axes, ["V14", "V17"]):
    df.boxplot(column=col, by="Class", ax=ax)
    ax.set_title(col)
plt.suptitle("")
plt.show()

git add notebooks/01_exploration.ipynb
git commit -m "feat: exploration notebook answering the four data questions"

Créez le fichier src/train/train.py avec ce contenu exact. Les deux règles sacrées y sont codées : split stratifié 80/20 avec random_state=42, et scaler fitté sur le train seul.Create the file src/train/train.py with this exact content. The two sacred rules are coded in: stratified 80/20 split with random_state=42, and a scaler fitted on the train set only.

"""Fraud detection baseline: logistic regression, honestly evaluated."""
from pathlib import Path

import joblib
import pandas as pd
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import average_precision_score
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler

DATA_PATH = Path("data/creditcard.csv")
MODELS_DIR = Path("models")
RANDOM_STATE = 42


def load_data(path=DATA_PATH):
    df = pd.read_csv(path)
    X = df.drop(columns=["Class"])
    y = df["Class"]
    return X, y


def split(X, y):
    return train_test_split(
        X, y, test_size=0.2, stratify=y, random_state=RANDOM_STATE
    )


def train(X_train, y_train):
    scaler = StandardScaler()
    X_train_scaled = scaler.fit_transform(X_train)  # fit on train ONLY
    model = LogisticRegression(class_weight="balanced", max_iter=1000)
    model.fit(X_train_scaled, y_train)
    return model, scaler


def evaluate(model, scaler, X_test, y_test):
    X_test_scaled = scaler.transform(X_test)  # transform, never fit
    scores = model.predict_proba(X_test_scaled)[:, 1]
    return average_precision_score(y_test, scores)


def main():
    X, y = load_data()
    X_train, X_test, y_train, y_test = split(X, y)
    model, scaler = train(X_train, y_train)
    pr_auc = evaluate(model, scaler, X_test, y_test)
    MODELS_DIR.mkdir(exist_ok=True)
    joblib.dump(model, MODELS_DIR / "model.pkl")
    joblib.dump(scaler, MODELS_DIR / "scaler.pkl")
    print(f"PR-AUC (test): {pr_auc:.4f}")
    print("saved: models/model.pkl + models/scaler.pkl")


if __name__ == "__main__":
    main()

On lance en module (-m) depuis la racine du repo : c'est ce qui rend les imports et les chemins stables — le réflexe MLOps du jour.Run it as a module (-m) from the repo root: that's what keeps imports and paths stable — today's MLOps reflex.

cd ~/fraud-detection
source .venv/bin/activate
python -m src.train.train
ls -lh models/

Hypothèse née de l'exploration : les montants sont très asymétriques (le log les assagit) et la fraude a des horaires. Modifiez src/train/train.py : ajoutez l'import numpy, la fonction add_features, et remplacez load_data.Hypothesis born from the exploration: amounts are heavily skewed (log tames them) and fraud keeps hours. Edit src/train/train.py: add the numpy import, the add_features function, and replace load_data.

# train.py - add to the imports
import numpy as np


# train.py - add this function, and make load_data call it
def add_features(df):
    df = df.copy()
    df["amount_log"] = np.log1p(df["Amount"])
    df["hour"] = (df["Time"] // 3600) % 24
    return df


def load_data(path=DATA_PATH):
    df = pd.read_csv(path)
    df = add_features(df)
    X = df.drop(columns=["Class"])
    y = df["Class"]
    return X, y

python -m src.train.train

Créez src/train/tune_threshold.py avec ce contenu exact : la fonction cost applique la formule du cadrage — fraudes ratées × montant moyen + fausses alertes × 15 €. Zéro ré-entraînement.Create src/train/tune_threshold.py with this exact content: the cost function applies the scoping formula — missed frauds × average amount + false alerts × €15. Zero retraining.

"""Sweep decision thresholds, keep the one that minimizes business cost."""
import joblib
import numpy as np

from src.train.train import MODELS_DIR, load_data, split

FP_COST = 15.0  # cost of one false alert, in euros


def main():
    X, y = load_data()
    X_train, X_test, y_train, y_test = split(X, y)
    model = joblib.load(MODELS_DIR / "model.pkl")
    scaler = joblib.load(MODELS_DIR / "scaler.pkl")
    scores = model.predict_proba(scaler.transform(X_test))[:, 1]

    y_true = y_test.to_numpy()
    amounts = X_test["Amount"].to_numpy()
    avg_fraud_amount = amounts[y_true == 1].mean()

    def cost(threshold):
        alerts = scores >= threshold
        missed_frauds = int(((y_true == 1) & ~alerts).sum())
        false_alerts = int(((y_true == 0) & alerts).sum())
        return missed_frauds * avg_fraud_amount + false_alerts * FP_COST

    thresholds = np.arange(0.05, 0.95, 0.01)
    costs = [cost(t) for t in thresholds]
    best = float(thresholds[int(np.argmin(costs))])
    print(f"cost at threshold 0.50: {cost(0.50):,.0f} EUR")
    print(f"best threshold: {best:.2f} (cost {min(costs):,.0f} EUR)")


if __name__ == "__main__":
    main()

python -m src.train.tune_threshold

SMOTE fabrique des fraudes synthétiques entre les vraies — élégant, et dangereux si appliqué avant le split ou sur le test. Comparez toujours au simple class_weight, et gardez le gagnant.SMOTE crafts synthetic frauds between real ones — elegant, and dangerous if applied before the split or on the test set. Always compare against plain class_weight, and keep the winner.

pip install imbalanced-learn

# train.py - an alternative train() to compare against class_weight
from imblearn.over_sampling import SMOTE  # add to the imports


def train(X_train, y_train):
    scaler = StandardScaler()
    X_train_scaled = scaler.fit_transform(X_train)  # still train ONLY
    X_res, y_res = SMOTE(random_state=RANDOM_STATE).fit_resample(
        X_train_scaled, y_train
    )
    model = LogisticRegression(max_iter=1000)  # no class_weight here
    model.fit(X_res, y_res)
    return model, scaler

Un run par ligne : hypothèse, réglage, score, verdict. Les chiffres ci-dessous sont des exemples — remplacez-les par les vôtres avant de committer.One run per line: hypothesis, setting, score, verdict. The numbers below are examples — replace them with yours before committing.

mkdir -p docs
cat > docs/runs.md << 'EOF'
# Runs - block 2 (replace the example scores with yours)

| run | change                   | PR-AUC | threshold | cost (EUR) | verdict |
|-----|--------------------------|--------|-----------|------------|---------|
| 1   | baseline (class_weight)  | 0.72   | 0.50      | 41300      | ref     |
| 2   | + amount_log, hour       | 0.74   | 0.50      | 39800      | keep    |
| 3   | threshold tuned on cost  | 0.74   | 0.31      | 28750      | keep    |
| 4   | SMOTE vs class_weight    | 0.73   | 0.31      | 29900      | drop    |
EOF

git add src/ docs/runs.md
git commit -m "feat: baseline plus three iteration rounds with run log"

Créez src/train/evaluate.py avec ce contenu exact, en remplaçant THRESHOLD par le seuil retenu à l'étape 10. Trois verdicts : la matrice de confusion au seuil choisi, la courbe PR sauvegardée en image, et le top-10 des fraudes ratées triées par montant — la matière de votre analyse d'erreurs.Create src/train/evaluate.py with this exact content, replacing THRESHOLD with the threshold kept at step 10. Three verdicts: the confusion matrix at the chosen threshold, the PR curve saved as an image, and the top-10 missed frauds sorted by amount — the raw material of your error analysis.

"""Final judgment: confusion matrix, PR curve, priciest missed frauds."""
from pathlib import Path

import joblib
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
from sklearn.metrics import (
    average_precision_score,
    confusion_matrix,
    precision_recall_curve,
)

from src.train.train import MODELS_DIR, load_data, split

THRESHOLD = 0.31  # the threshold you kept at step 10
REPORTS_DIR = Path("reports")


def main():
    REPORTS_DIR.mkdir(exist_ok=True)
    X, y = load_data()
    X_train, X_test, y_train, y_test = split(X, y)
    model = joblib.load(MODELS_DIR / "model.pkl")
    scaler = joblib.load(MODELS_DIR / "scaler.pkl")
    scores = model.predict_proba(scaler.transform(X_test))[:, 1]

    # 1. confusion matrix at the chosen threshold
    preds = (scores >= THRESHOLD).astype(int)
    tn, fp, fn, tp = confusion_matrix(y_test, preds).ravel()
    print(f"TN={tn}  FP={fp}  FN={fn}  TP={tp}")

    # 2. precision-recall curve, saved as an image
    precision, recall, _ = precision_recall_curve(y_test, scores)
    pr_auc = average_precision_score(y_test, scores)
    plt.figure(figsize=(7, 5))
    plt.plot(recall, precision, color="#E6332A")
    plt.xlabel("recall")
    plt.ylabel("precision")
    plt.title(f"PR curve - AP = {pr_auc:.3f}")
    plt.grid(True, alpha=0.3)
    plt.savefig(REPORTS_DIR / "pr_curve.png", dpi=150)
    print("saved: reports/pr_curve.png")

    # 3. the ten priciest missed frauds
    test = X_test.copy()
    test["true_class"] = y_test.to_numpy()
    test["score"] = scores
    missed = test[(test["true_class"] == 1) & (test["score"] < THRESHOLD)]
    top10 = missed.sort_values("Amount", ascending=False).head(10)
    print(top10[["Time", "Amount", "score"]].to_string())


if __name__ == "__main__":
    main()

Lisez les trois sorties comme un juge : combien de fraudes ratées (FN) et à quel prix ? Les ratées ont-elles un point commun — heure, montant, profil de V ? Chaque pattern est une hypothèse pour un prochain tour de boucle.Read the three outputs like a judge: how many missed frauds (FN) and at what price? Do the missed ones share a pattern — hour, amount, V profile? Every pattern is a hypothesis for a next loop round.

python -m src.train.evaluate

git add src/train/evaluate.py
git commit -m "feat: evaluation - confusion matrix, PR curve, error analysis"
git log --oneline