Quickstart

Install FPDE from PyPI, fit an engine on training data, and explain one scikit-learn classifier prediction with Hyb-FPDE attributions.

This guide trains a scikit-learn classifier, fits an FPDE engine on the training data, and explains one test sample.

The example uses the breast cancer dataset bundled with scikit-learn.

Prerequisites

Before you begin, install:

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

Get started

1. Install

   Install FPDE from PyPI.

   python -m pip install fpde
   

   To use the optional plotting helpers, install the plot extra, which adds matplotlib:

   python -m pip install "fpde[plot]"
   
2. Train a classifier

   Train a classifier on the same feature space you want to 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 FPDE state from the training data and labels.

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

   Explain one test sample with a fixed Hyb-FPDE mixture.

   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"])

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

Scale features before using distance-based explanations when feature units differ. FPDE expects training, validation, and explanation inputs to share the same feature space.

Run the repository example

Clone the repository and run the minimal example.

git clone https://github.com/fpde-xai/fpde.git
cd fpde
python -m pip install -e .
python examples/minimal_fpde_example.py