pulsatrix 1.1.0
Loading...
Searching...
No Matches
pulsatrix::LIME Class Reference

Fits a locality-weighted linear surrogate around one input: perturb x with Gaussian noise, weight each perturbed sample by an exponential locality kernel pi(z) = exp(-||z-x||^2 / (2*sigma^2)), fit w* = argmin_w sum_i pi_i*(f(z_i) - f(x) - w^T(z_i-x))^2 + l2_lambda*||w||^2 via fit_weighted_linear_regression. More...

#include <lime.hpp>

Public Member Functions

Attribution explain (const std::function< Tensor(const Tensor &)> &predict, const Tensor &input, int64_t target_index, int64_t num_samples, float sigma, float l2_lambda, unsigned seed, DeviceBackend *backend) const
 Computes the LIME local surrogate explanation for one output index.
 

Static Public Member Functions

static const ExplainerCapabilities & capabilities ()
 What it answers and needs: its ExplainerCatalog() entry.
 
static double local_fidelity (const std::vector< std::vector< float > > &samples, const std::vector< float > &targets, const std::vector< float > &weights, const std::vector< float > &coefficients)
 How well the surrogate fits the model where it was fitted: the locality-weighted R² of w^T(z - x) against f(z) - f(x) over the perturbed samples, as the reference LIME implementation's score (Ribeiro et al. 2016). 1 is a perfect local fit; at 0 the surrogate explains none of the model's variation around the input, and the coefficients shouldn't be read as the model's local behaviour.
 

Detailed Description

Fits a locality-weighted linear surrogate around one input: perturb x with Gaussian noise, weight each perturbed sample by an exponential locality kernel pi(z) = exp(-||z-x||^2 / (2*sigma^2)), fit w* = argmin_w sum_i pi_i*(f(z_i) - f(x) - w^T(z_i-x))^2 + l2_lambda*||w||^2 via fit_weighted_linear_regression.

Note
Takes a forward-pass callable, not ExplainerContext& – makes model-agnosticism true by construction (there is nothing else in the type signature to call), per campaign_exai_dl_library_phase3_surrogate_explainers.md's Context section. Works with any callable a caller provides, including but not limited to an ExplainerContext::forward_pass wrapped in a lambda.
Targets are centered on f(x) (not fit with a separate intercept term) – the local linear model is g(z) = f(x) + w^T(z-x), so g(x) = f(x) trivially; only w (the local sensitivity, this method's actual Attribution) needs fitting.
A pure graph-free explainer – no core (Tensor/ComputationGraph/Autograd/Module) or ExplainerContext changes needed.
Device-generic host boundary: perturbation and the surrogate fit run on the host; each perturbed sample is uploaded beside the input and only f(z)[target] is read back.

Member Function Documentation

◆ capabilities()

static const ExplainerCapabilities & pulsatrix::LIME::capabilities ( )
inlinestatic

What it answers and needs: its ExplainerCatalog() entry.

◆ explain()

Attribution pulsatrix::LIME::explain ( const std::function< Tensor(const Tensor &)> &  predict,
const Tensor &  input,
int64_t  target_index,
int64_t  num_samples,
float  sigma,
float  l2_lambda,
unsigned  seed,
DeviceBackend *  backend 
) const
inline

Computes the LIME local surrogate explanation for one output index.

Parameters
predictForward-pass callable: input Tensor in, output Tensor out.
inputInput to explain.
target_indexWhich output element to explain (0-based, flat index).
num_samplesHow many perturbed samples to draw.
sigmaPerturbation std. dev. and locality-kernel width (charter/LIME convention: a single sigma controls both, per technique_lime.md's own default-heuristic framing).
l2_lambdaRidge regularization strength for the surrogate fit.
seedRNG seed, for reproducibility.
backendBackend to allocate intermediate tensors through.
Returns
An Attribution with method "lime", values = the local linear coefficients (same shape as input), and metadata recording the sampling parameters used and the surrogate's "local_fidelity" (see local_fidelity()).
Exceptions
std::invalid_argumentif num_samples <= 0 or sigma <= 0 – external boundary (campaign_exai_dl_library_adversarial_hardening.md, Mission 2, finding 11): escalated from PULSATRIX_ASSERT-only, which in Release left num_samples<=0 reaching vector::reserve as a huge (wrapped) size_t, throwing an unhelpful std::length_error instead of a clear, actionable error.

◆ local_fidelity()

static double pulsatrix::LIME::local_fidelity ( const std::vector< std::vector< float > > &  samples,
const std::vector< float > &  targets,
const std::vector< float > &  weights,
const std::vector< float > &  coefficients 
)
inlinestatic

How well the surrogate fits the model where it was fitted: the locality-weighted R² of w^T(z - x) against f(z) - f(x) over the perturbed samples, as the reference LIME implementation's score (Ribeiro et al. 2016). 1 is a perfect local fit; at 0 the surrogate explains none of the model's variation around the input, and the coefficients shouldn't be read as the model's local behaviour.

Note
No intercept, as in explain(): the surrogate passes through f(x). So the score can be negative, when the samples sit mostly to one side of f(x), as at a minimum.
Returns
1 when the targets don't vary and the fit is exact, 0 when they don't vary and it isn't.

The documentation for this class was generated from the following file: