> ## Documentation Index > Fetch the complete documentation index at: https://fpde-80-mintlify-48090872.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # API reference > Stable public FPDE 0.1.0 classes, functions, parameters, and result objects Import public APIs from `fpde`. The `fpde.core` module also aggregates the same public API for compatibility. ```python theme={null} 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` ```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.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.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`. ## 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` ```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. Returns an `FPDEExplanation`. ### `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. Returns an `FPDEExplanation`. ### `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. ### `parse_float_grid` ```python theme={null} 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](/troubleshooting).