API reference

Import public APIs from fpde. The fpde.core module also aggregates the same public API for compatibility.

from fpde import FPDEEngine, class_mean_prototypes, diff_fpde

This page documents stable public APIs for fpde 0.1.0.

FPDEEngine

Use FPDEEngine for repeated explanations, batch explanations, Hyb-FPDE, grid search, and validation-based lambda_hyb selection.

`FPDEEngine.fit`

FPDEEngine.fit(X_train, y_train, model=None, baseline=None)

Fits reusable FPDE state from training data.

Parameter	Description
`X_train`	Training feature matrix with shape `(n_samples, n_features)`.
`y_train`	Training labels with one label per row in `X_train`.
`model`	Optional classifier. Required later when an operation needs `predict_proba`.
`baseline`	Optional replacement vector for perturbation curves. Defaults to the training mean.

Returns an FPDEEngine.

`engine.explain_one`

engine.explain_one(
    x,
    *,
    lambda_hyb,
    normalize="l1",
    anchor_strategy="mean",
    eps=1e-12,
    model=None,
)

Explains one sample with fixed-lambda Hyb-FPDE. Returns (attributions, details). The details dictionary includes target_label, rival_label, target_probability, lambda_hyb, evidence, exactness_residual, positive_score, and negative_score.

`engine.explain_batch`

engine.explain_batch(
    X,
    *,
    lambda_hyb,
    normalize="l1",
    anchor_strategy="mean",
    include_details=True,
    eps=1e-12,
    model=None,
)

Explains many samples with fixed-lambda Hyb-FPDE. Returns (attribution_matrix, details). If include_details=False, details is an empty list.

`engine.explain_matrix`

engine.explain_matrix(
    X,
    *,
    lambda_hyb,
    normalize="l1",
    anchor_strategy="mean",
    eps=1e-12,
    model=None,
)

Returns only the attribution matrix for a batch.

`engine.select_lambda`

engine.select_lambda(
    X_val,
    *,
    lambda_hyb_grid=...,
    fractions=(0.0, 0.05, 0.1, 0.2, 0.3, 0.5, 0.7, 1.0),
    normalize="l1",
    anchor_strategy="mean",
    eps=1e-12,
    max_working_bytes=268435456,
    model=None,
)

Selects lambda_hyb by held-out deletion and insertion validation. Returns a HybFPDEValidationSelectionResult.

`engine.grid_search`

engine.grid_search(
    X_eval,
    *,
    predictor=None,
    objective="blackbox_agreement",
    fpde_mode_grid=("diff", "cos", "hyb_grid"),
    normalize_grid=("l1",),
    lambda_hyb_grid=...,
    anchor_strategy_grid=("mean",),
    include_explicit_diff_cos=True,
    max_eval_samples=None,
    eps=1e-12,
    verbose=False,
)

Searches Diff-FPDE, Cos-FPDE, and Hyb-FPDE candidate settings. Returns a HybFPDEGridSearchResult.

Shared parameters

Parameter	Values	Description
`lambda_hyb`	Float in `[0, 1]`	Hyb-FPDE mixture weight. `1.0` is Diff-FPDE. `0.0` is Cos-FPDE.
`normalize`	`"l1"` or `"none"`	Whether to L1-normalize component attribution vectors before Hyb-FPDE mixing.
`anchor_strategy`	`"mean"`, `"zero"`, or `"none"`	Anchor source for Cos-FPDE.
`eps`	Positive float	Regularization value for cosine norms.
`model`	Classifier	Overrides the engine model for the call. Must support `predict_proba` and `classes_` when probabilities are needed.

Prototype helpers

Use these functions when you want manual control over prototype state.

`class_mean_prototypes`

class_mean_prototypes(X, y)

Builds one mean prototype per class. Returns (prototypes, labels).

`select_prototype_pair`

select_prototype_pair(
    x,
    prototypes,
    prototype_labels,
    *,
    positive_label,
    negative_label=None,
    mode="diff",
    anchor=None,
    eps=1e-12,
)

Selects the positive and negative prototype indices for a local contrast. Returns (positive_index, negative_index).

`prepare_fpde_context`

prepare_fpde_context(X_train, y_train, *, baseline=None)

Precomputes reusable prototypes, anchors, baseline, and feature metadata. Returns an FPDEContext.

Explanation functions

Use these functions when you want direct control over prototypes and labels.

`diff_fpde`

diff_fpde(
    x,
    p_pos,
    p_neg,
    *,
    positive_label="positive",
    negative_label="negative",
    positive_prototype_index=-1,
    negative_prototype_index=-1,
)

Computes a Diff-FPDE explanation for one target/rival prototype pair. Returns an FPDEExplanation.

`cos_fpde`

cos_fpde(
    x,
    p_pos,
    p_neg,
    *,
    anchor=None,
    eps=1e-12,
    positive_label="positive",
    negative_label="negative",
    positive_prototype_index=-1,
    negative_prototype_index=-1,
)

Computes a Cos-FPDE explanation for one target/rival prototype pair. Returns an FPDEExplanation.

`explain_with_selected_prototypes`

explain_with_selected_prototypes(
    x,
    prototypes,
    prototype_labels,
    *,
    positive_label,
    negative_label=None,
    mode="diff",
    anchor=None,
    eps=1e-12,
)

Selects prototypes and computes a public Diff-FPDE or Cos-FPDE explanation. Use FPDEEngine for Hyb-FPDE.

Metrics and probability helpers

`regularized_cosine`

regularized_cosine(u, v, eps=1e-12)

Returns cosine similarity with epsilon-regularized norms.

`top_two_labels`

top_two_labels(model, x)

Returns (target_label, rival_label, probability_vector) for one sample. model must implement predict_proba and expose classes_.

`predict_proba_for_label`

predict_proba_for_label(model, X, label)

Returns the predict_proba(X) column for label.

`perturbation_curves`

perturbation_curves(
    model,
    x,
    attributions,
    target_label,
    baseline,
    fractions=(0.0, 0.05, 0.1, 0.2, 0.3, 0.5, 0.7, 1.0),
)

Computes deletion and insertion curves for one attribution vector. Features are ranked by signed positive attribution in descending order.

`parse_float_grid`

parse_float_grid(value)

Parses a float grid helper value. Use it when you need the same grid-parsing behavior as FPDE command or workflow code.

Result objects

Object	Contains
`FPDEExplanation`	`mode`, `evidence`, `attributions`, `positive_score`, `negative_score`, labels, prototype indices, `exactness_residual`, and method details.
`FPDEContext`	Prototypes, prototype labels, mean anchor, zero anchor, baseline, and feature count.
`HybFPDEGridSearchResult`	`best_config`, `best_score`, `rows`, `objective`, `n_candidates`, and `n_eval_samples`.
`HybFPDEValidationSelectionResult`	`best_lambda`, `best_config`, `rows`, and `n_eval_samples`.

Common errors

Error	Cause	Fix
`model must implement predict_proba`	A model-dependent operation was called without probability support.	Pass a fitted classifier with `predict_proba`.
`model must expose classes_`	The model does not expose class labels.	Use a scikit-learn-style classifier or add compatible `classes_` metadata.
`feature dimension mismatch`	Input vectors do not match the fitted training feature count.	Apply the same preprocessing pipeline to training, validation, and explanation data.
`lambda_hyb must be in [0, 1]`	The Hyb-FPDE mixture weight is outside the valid range.	Pass a finite value from 0.0 to 1.0.
`eps must be positive`	Cosine regularization was zero or negative.	Use a positive `eps`, such as `1e-12`.

For a guided version of these fixes, see Troubleshooting.

Getting started

Guides

Concepts

Reference

Changelog

API reference

FPDEEngine

`FPDEEngine.fit`

`engine.explain_one`

`engine.explain_batch`

`engine.explain_matrix`

`engine.select_lambda`

`engine.grid_search`

Shared parameters

Prototype helpers

`class_mean_prototypes`

`select_prototype_pair`

`prepare_fpde_context`

Explanation functions

`diff_fpde`

`cos_fpde`

`explain_with_selected_prototypes`

Metrics and probability helpers

`regularized_cosine`

`top_two_labels`

`predict_proba_for_label`

`perturbation_curves`

`parse_float_grid`

Result objects

Common errors

​FPDEEngine

​FPDEEngine.fit

​engine.explain_one

​engine.explain_batch

​engine.explain_matrix

​engine.select_lambda

​engine.grid_search

​Shared parameters

​Prototype helpers

​class_mean_prototypes

​select_prototype_pair

​prepare_fpde_context

​Explanation functions

​diff_fpde

​cos_fpde

​explain_with_selected_prototypes

​Metrics and probability helpers

​regularized_cosine

​top_two_labels

​predict_proba_for_label

​perturbation_curves

​parse_float_grid

​Result objects

​Common errors

FPDEEngine

`FPDEEngine.fit`

`engine.explain_one`

`engine.explain_batch`

`engine.explain_matrix`

`engine.select_lambda`

`engine.grid_search`

Shared parameters

Prototype helpers

`class_mean_prototypes`

`select_prototype_pair`

`prepare_fpde_context`

Explanation functions

`diff_fpde`

`cos_fpde`

`explain_with_selected_prototypes`

Metrics and probability helpers

`regularized_cosine`

`top_two_labels`

`predict_proba_for_label`

`perturbation_curves`

`parse_float_grid`

Result objects

Common errors