diff --git a/api-reference.mdx b/api-reference.mdx index 471a08b..9d9fb8e 100644 --- a/api-reference.mdx +++ b/api-reference.mdx @@ -1,6 +1,6 @@ --- title: "API reference" -description: "Public FPDE classes, functions, parameters, and result objects" +description: "Reference for FPDE public classes, engine methods, prototype helpers, perturbation curves, result objects, and common error messages." --- Import the public package as `fpde`. @@ -13,7 +13,7 @@ This page documents the public API exported by `fpde` and `fpde.core`. ## `FPDEEngine` -Use `FPDEEngine` for repeated explanations, batch explanations, Hyb-FPDE, grid search, and validation-based lambda selection. +Use `FPDEEngine` for repeated explanations, batch explanations, Hyb-FPDE, grid search, validation-based lambda selection, and Bayesian-FPDE lambda posterior selection. ### `FPDEEngine.fit` @@ -127,6 +127,71 @@ engine.select_lambda( Selects `lambda_hyb` by held-out deletion and insertion validation. Returns a `HybFPDEValidationSelectionResult`. +### `engine.select_bayesian_lambda` + +```python +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 +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 +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 +engine.explain_matrix_bayesian(X, selection, *, model=None) +``` + +Returns only the Bayesian-FPDE attribution matrix for a batch. + ## Prototype helpers ### `class_mean_prototypes` @@ -276,6 +341,7 @@ Features are ranked by signed positive attribution in descending order. | `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 diff --git a/examples.mdx b/examples.mdx index 65bde4d..36b343f 100644 --- a/examples.mdx +++ b/examples.mdx @@ -1,6 +1,6 @@ --- title: "Examples" -description: "Common FPDE usage patterns for single samples, batches, and lambda selection" +description: "FPDE usage examples for single-sample explanations, batch explanations, lambda selection, Bayesian-FPDE posteriors, and grid search." --- Use `FPDEEngine` for most workflows. @@ -61,6 +61,39 @@ attributions, details = engine.explain_batch(X_test, lambda_hyb=best_lambda) Save `selection.rows` with your experiment results so you can inspect the score for each candidate later. +## Build a Bayesian-FPDE posterior over `lambda_hyb` + +Use `select_bayesian_lambda` when you want a posterior over the Hyb-FPDE mixture weight instead of a single selected value. +The posterior is built on the same held-out deletion and insertion score as `select_lambda`, with a `Beta(alpha, beta)` prior and a likelihood temperature. + +```python +selection = engine.select_bayesian_lambda( + X_val, + lambda_hyb_grid=(0.0, 0.25, 0.5, 0.75, 1.0), + alpha=1.0, + beta=1.0, + temperature=1.0, + credible_mass=0.95, +) + +print(selection.posterior_mean_lambda) +print(selection.map_lambda) +print(selection.credible_interval) +``` + +Then explain samples with the posterior-mean `lambda_hyb`: + +```python +attributions, details = engine.explain_one_bayesian(X_test[0], selection) + +print(details["posterior_mean_lambda"]) +print(details["credible_interval"]) +print(details["posterior_entropy"]) +``` + +Use `explain_batch_bayesian` or `explain_matrix_bayesian` for many samples. +Inspect `selection.sorted_rows()` to see candidates from highest to lowest posterior mass. + ## Run grid search Use `grid_search` to compare Diff-FPDE, Cos-FPDE, and Hyb-FPDE candidate settings. diff --git a/index.mdx b/index.mdx index f7e459d..93030b8 100644 --- a/index.mdx +++ b/index.mdx @@ -1,6 +1,6 @@ --- title: "Introduction" -description: "Explain classification results with prototype-contrast feature attribution" +description: "FPDE is a Python package that explains classifier predictions with prototype-contrast feature attribution for tabular feature vectors." --- Feature Prototype Direction Explainer (FPDE) is a Python package for prototype-contrast feature attribution. @@ -16,6 +16,7 @@ Use FPDE when you need a lightweight, post-hoc explanation method for tabular-st - Explain batches while reusing fitted prototype state. - Search Diff, Cos, and Hyb-FPDE candidate settings. - Select `lambda_hyb` with held-out deletion and insertion validation. +- Build a Bayesian-FPDE posterior over `lambda_hyb` candidates and explain with the posterior mean. - Compute deletion and insertion perturbation curves for an attribution vector. ## How FPDE explains a prediction diff --git a/method-overview.mdx b/method-overview.mdx index aa05023..1593f1a 100644 --- a/method-overview.mdx +++ b/method-overview.mdx @@ -1,6 +1,6 @@ --- title: "Method overview" -description: "Understand prototypes, target-rival contrasts, and FPDE variants" +description: "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. @@ -107,6 +107,35 @@ phi_hyb_j = lambda_hyb * phi_diff_j + (1 - lambda_hyb) * phi_cos_j 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 +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: