Quickstart

Train a scikit-learn classifier and explain one prediction with FPDE

This tutorial trains a scikit-learn classifier, fits FPDE prototypes from the training data, and explains one test sample. The example uses the breast cancer dataset bundled with scikit-learn.

Prerequisites

• Python 3.12 or newer
• fpde
• A classifier that exposes predict_proba and classes_

1. Install FPDE

   Install the stable package from PyPI.

   python -m pip install fpde
   
2. Train a classifier

   Train the model on the same feature space you will explain.

   from sklearn.datasets import load_breast_cancer
   from sklearn.linear_model import LogisticRegression
   from sklearn.model_selection import train_test_split
   from sklearn.preprocessing import StandardScaler
   
   data = load_breast_cancer()
   X_train, X_test, y_train, _ = train_test_split(
       data.data,
       data.target,
       test_size=0.25,
       random_state=7,
       stratify=data.target,
   )
   
   scaler = StandardScaler()
   X_train = scaler.fit_transform(X_train)
   X_test = scaler.transform(X_test)
   
   model = LogisticRegression(max_iter=2000, random_state=7)
   model.fit(X_train, y_train)
   
3. Fit FPDE

   Fit reusable class-mean prototypes from the training data.

   from fpde import FPDEEngine
   
   engine = FPDEEngine.fit(X_train, y_train, model=model)
   
4. Explain one sample

   Compute a Hyb-FPDE explanation with a fixed lambda_hyb.

   import numpy as np
   
   attributions, details = engine.explain_one(X_test[0], lambda_hyb=0.5)
   
   print(np.asarray(attributions))
   print(details["target_label"], details["rival_label"], details["evidence"])
   

Complete example

import numpy as np
from sklearn.datasets import load_breast_cancer
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler

from fpde import FPDEEngine

data = load_breast_cancer()
X_train, X_test, y_train, _ = train_test_split(
    data.data,
    data.target,
    test_size=0.25,
    random_state=7,
    stratify=data.target,
)

scaler = StandardScaler()
X_train = scaler.fit_transform(X_train)
X_test = scaler.transform(X_test)

model = LogisticRegression(max_iter=2000, random_state=7)
model.fit(X_train, y_train)

engine = FPDEEngine.fit(X_train, y_train, model=model)
attributions, details = engine.explain_one(X_test[0], lambda_hyb=0.5)

print(np.asarray(attributions))
print(details["target_label"], details["rival_label"], details["evidence"])

Interpret the output

details["target_label"] is the model’s highest-probability class. details["rival_label"] is the second-highest-probability class. details["evidence"] is the target-versus-rival contrast decomposed by FPDE.

Positive attribution values support the target class. Negative attribution values support the rival class.

Next steps

• Use Explain one sample for a slower walkthrough of the result fields.
• Use Explain batches when you need an attribution matrix.
• Use Select lambda_hyb to choose a fixed Hyb-FPDE mixture with validation data.