> ## 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. # 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`. ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} engine.explain_matrix_bayesian(X, selection, *, model=None) ``` Returns only the Bayesian-FPDE attribution matrix for a batch. ## Prototype helpers ### `class_mean_prototypes` ```python theme={null} class_mean_prototypes(X, y) ``` Builds one mean prototype per class. Returns `(prototypes, labels)`. ### `select_prototype_pair` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} 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` ```python theme={null} regularized_cosine(u, v, eps=1e-12) ``` Returns cosine similarity with epsilon-regularized norms. ### `top_two_labels` ```python theme={null} 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` ```python theme={null} predict_proba_for_label(model, X, label) ``` Returns the `predict_proba(X)` column for `label`. ### `perturbation_curves` ```python theme={null} 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`. |