> ## Documentation Index
> Fetch the complete documentation index at: https://fpde-80-mintlify-8d7c1d86.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Method overview

> Learn how FPDE builds class prototypes, picks target and rival contrasts, and decomposes them with Diff-FPDE, Cos-FPDE, and Hyb-FPDE.

FPDE is a post-hoc feature attribution method for classification.
It explains one input by contrasting the input with a prototype for a target class and a prototype for a rival class.

The output is an attribution vector with one value per feature.
Positive values support the target class relative to the rival class.
Negative values support the rival class relative to the target class.

## When to use FPDE

Use FPDE when you have:

* A feature matrix where each column has a consistent meaning.
* Class labels for training samples.
* A classification model, usually one that exposes `predict_proba`.
* A need to explain target-versus-rival evidence at the feature level.

FPDE does not retrain or modify the classifier.
It uses training data to build prototypes, then uses those prototypes to explain individual inputs.

## Core terms

| Term         | Meaning                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| Prototype    | A representative feature vector for a class. FPDE currently builds one class-mean prototype per class. |
| Target class | The class being explained, often the classifier's predicted class.                                     |
| Rival class  | The contrast class, often the second-highest-probability class.                                        |
| Evidence     | The scalar target-versus-rival contrast decomposed by FPDE.                                            |
| Attribution  | A per-feature contribution to the evidence value.                                                      |
| Anchor       | A reference vector used by Cos-FPDE before computing cosine contrasts.                                 |
| Baseline     | A replacement vector used for deletion and insertion perturbation curves.                              |

## Prototype construction

`class_mean_prototypes(X, y)` computes one prototype per class by averaging all training rows with that class label.
`FPDEEngine.fit(X_train, y_train, model)` builds the same prototype state and stores it for repeated explanations.

For repeated workflows, prefer `FPDEEngine` because it reuses:

* Class-mean prototypes
* Prototype labels
* Mean and zero anchors
* The baseline vector
* Label-to-prototype lookup state

## Target and rival selection

When you use `FPDEEngine` with a model, FPDE chooses the local contrast from `predict_proba`.

<Steps>
  <Step title="Select the target">
    The target class is the highest-probability class.
  </Step>

  <Step title="Select the rival">
    The rival class is the second-highest-probability class.
  </Step>

  <Step title="Map labels to prototypes">
    FPDE maps both labels to their fitted class prototypes.
  </Step>
</Steps>

When you call lower-level functions directly, pass `positive_label` and `negative_label`.
If you omit `negative_label`, FPDE selects a non-target prototype according to the selected mode.

## Diff-FPDE

Diff-FPDE decomposes the difference in squared distances from the input to the rival and target prototypes.

```text theme={null}
E_diff = ||x - p_neg||^2 - ||x - p_pos||^2
phi_j  = (x_j - p_neg_j)^2 - (x_j - p_pos_j)^2
```

The attribution values sum to the Diff-FPDE evidence.
A positive feature value means that feature moves the input closer to the target prototype than to the rival prototype under this squared-distance contrast.

## Cos-FPDE

Cos-FPDE decomposes a regularized cosine-similarity contrast.

```text theme={null}
E_cos = cos_eps(x - anchor, p_pos - anchor)
        - cos_eps(x - anchor, p_neg - anchor)
```

Cos-FPDE is an exact coordinate decomposition of the cosine contrast.
It is not a leave-one-feature-out causal effect, because the cosine denominator depends on all coordinates.

## Hyb-FPDE

Hyb-FPDE mixes Diff-FPDE and Cos-FPDE attribution vectors.

```text theme={null}
phi_hyb_j = lambda_hyb * phi_diff_j + (1 - lambda_hyb) * phi_cos_j
```

`lambda_hyb` must be in `[0, 1]`.

* `lambda_hyb=1.0` uses the Diff-FPDE endpoint.
* `lambda_hyb=0.0` uses the Cos-FPDE endpoint.
* Intermediate values blend both attribution vectors.

By default, Hyb-FPDE uses L1-normalized component attribution vectors before mixing.
Set `normalize="none"` when you want to mix the raw component scales.

## Bayesian-FPDE

Bayesian-FPDE replaces a single selected `lambda_hyb` with a posterior distribution over the lambda grid.
Use it when you want to express uncertainty about the Hyb-FPDE mixture weight, or when you want a Bayesian model-averaged attribution instead of a point-selected one.

`FPDEEngine.select_bayesian_lambda` evaluates the same held-out deletion and insertion validation score as `select_lambda`, then converts the finite lambda grid into a posterior.
The default prior is `Beta(1, 1)`, which is uniform over the candidates.

For each candidate, the unnormalized log-posterior is:

```text theme={null}
log_likelihood = n_eval_samples * validation_score / temperature
log_prior      = (alpha - 1) * log(lambda_hyb)
               + (beta - 1) * log(1 - lambda_hyb)
```

Tune `alpha` and `beta` to encode prior preferences over `lambda_hyb`.
Smaller `temperature` values make the posterior sharper around high-scoring candidates; larger values flatten it toward the prior.

The normalized posterior weights produce:

* `posterior_mean_lambda`: the Bayesian model-averaged mixture weight.
* `map_lambda`: the highest-posterior lambda candidate.
* `credible_interval`: an equal-tail credible interval on the grid for the chosen `credible_mass`.
* `posterior_rows`: candidate rows with validation metrics and posterior mass.

`engine.explain_one_bayesian`, `engine.explain_batch_bayesian`, and `engine.explain_matrix_bayesian` use `posterior_mean_lambda`.
Because Hyb-FPDE is linear in `lambda_hyb`, this is equivalent to the expected attribution vector under the lambda posterior.

## Interpreting results

An FPDE explanation contains:

* `attributions`: one contribution per feature
* `evidence`: the sum of the attribution vector for the selected contrast
* `positive_score` and `negative_score`: the target and rival side scores
* `exactness_residual`: numerical difference between summed attribution and direct evidence
* Prototype labels and prototype indices

For visualization, `FPDEExplanation.normalized_attributions` returns an L1-normalized attribution vector.
Use it for plotting, not as the raw evidence scale.