API reference

Reference for FPDE public classes, engine methods, prototype helpers, perturbation curves, result objects, and common error messages.

Import the public package as fpde.

from fpde import FPDEEngine, class_mean_prototypes, diff_fpde

This page documents the public API exported by fpde and fpde.core.

FPDEEngine

Use FPDEEngine for repeated explanations, batch explanations, Hyb-FPDE, grid search, validation-based lambda selection, and Bayesian-FPDE lambda posterior 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.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.

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.select_bayesian_lambda

engine.select_bayesian_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,
    alpha=1.0,
    beta=1.0,
    temperature=1.0,
    credible_mass=0.95,
    model=None,
)

Builds a Bayesian posterior over unique lambda_hyb candidates using the same held-out deletion and insertion validation score as select_lambda.

Parameter	Description
alpha	Positive alpha parameter for the Beta prior on lambda_hyb.
beta	Positive beta parameter for the Beta prior on lambda_hyb.
temperature	Positive likelihood temperature. Smaller values make the posterior sharper.
credible_mass	Credible interval mass in (0, 1).

Returns a BayesianFPDELambdaSelectionResult.

engine.explain_one_bayesian

engine.explain_one_bayesian(x, selection, *, model=None)

Explains one sample using selection.posterior_mean_lambda, where selection is a BayesianFPDELambdaSelectionResult. Returns (attributions, details).

The details dictionary includes the usual fixed-lambda fields plus lambda_source, posterior_mean_lambda, map_lambda, credible_interval, posterior_entropy, and effective_candidates.

engine.explain_batch_bayesian

engine.explain_batch_bayesian(
    X,
    selection,
    *,
    include_details=True,
    model=None,
)

Explains many samples with the Bayesian posterior-mean lambda_hyb. Returns (attribution_matrix, details).

engine.explain_matrix_bayesian

engine.explain_matrix_bayesian(X, selection, *, model=None)

Returns only the Bayesian-FPDE attribution matrix for a batch.

Prototype helpers

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.

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.

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.

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.
BayesianFPDELambdaSelectionResult	posterior_mean_lambda, map_lambda, credible_interval, posterior_rows, prior_alpha, prior_beta, temperature, normalize, anchor_strategy, eps, and n_eval_samples. Call sorted_rows() to inspect candidates from highest to lowest posterior probability.

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.