69 int64_t target_index, int64_t num_samples,
float sigma,
float l2_lambda,
71 if (num_samples <= 0) {
72 throw std::invalid_argument(
"LIME::explain: num_samples must be positive");
75 throw std::invalid_argument(
"LIME::explain: sigma must be positive");
78 Tensor base_output = predict(input);
80 float base_value = base_output.
read_element(target_index);
82 int64_t n_features = input.
numel();
85 std::mt19937 rng(seed);
86 std::normal_distribution<float> noise(0.0f, sigma);
88 std::vector<std::vector<float>> samples;
89 std::vector<float> targets;
90 std::vector<float> weights;
91 samples.reserve(
static_cast<size_t>(num_samples));
92 targets.reserve(
static_cast<size_t>(num_samples));
93 weights.reserve(
static_cast<size_t>(num_samples));
95 for (int64_t s = 0; s < num_samples; ++s) {
96 std::vector<float> perturbed_values(
static_cast<size_t>(n_features));
97 std::vector<float> delta(
static_cast<size_t>(n_features));
98 float squared_distance = 0.0f;
99 for (int64_t i = 0; i < n_features; ++i) {
100 float d = noise(rng);
101 delta[
static_cast<size_t>(i)] = d;
102 perturbed_values[
static_cast<size_t>(i)] = input_values[
static_cast<size_t>(i)] + d;
103 squared_distance += d * d;
105 Tensor perturbed(input.
shape(), input_backend, perturbed_values, input.
device());
107 Tensor output = predict(perturbed);
108 float centered_target = output.
read_element(target_index) - base_value;
109 float weight = std::exp(-squared_distance / (2.0f * sigma * sigma));
111 samples.push_back(std::move(delta));
112 targets.push_back(centered_target);
113 weights.push_back(weight);
118 coefficients.resize(
static_cast<size_t>(n_features));
119 const double fidelity =
local_fidelity(samples, targets, weights, coefficients);
123 {{
"target_index", std::to_string(target_index)},
124 {
"num_samples", std::to_string(num_samples)},
125 {
"sigma", std::to_string(sigma)},
126 {
"local_fidelity", std::to_string(fidelity)}}};
139 [[nodiscard]]
static double local_fidelity(
const std::vector<std::vector<float>>& samples,
140 const std::vector<float>& targets,
const std::vector<float>& weights,
141 const std::vector<float>& coefficients) {
142 double weight_sum = 0.0, mean = 0.0;
143 for (
size_t s = 0; s < samples.size(); ++s) {
144 weight_sum += weights[s];
145 mean +=
static_cast<double>(weights[s]) * targets[s];
147 if (weight_sum <= 0.0)
return 0.0;
149 double residual = 0.0, total = 0.0;
150 for (
size_t s = 0; s < samples.size(); ++s) {
152 for (
size_t i = 0; i < coefficients.size(); ++i) fit +=
static_cast<double>(coefficients[i]) * samples[s][i];
153 const double e = targets[s] - fit, d = targets[s] - mean;
154 residual += weights[s] * e * e;
155 total += weights[s] * d * d;
157 if (total == 0.0)
return residual == 0.0 ? 1.0 : 0.0;
158 return 1.0 - residual / total;
PULSATRIX_ASSERT – debug-only invariant check for programmer errors, distinct from throw (used for ca...
#define PULSATRIX_ASSERT(cond)
Aborts with a diagnostic message if cond is false. Debug-only – use for conditions that indicate a bu...
Definition assert.hpp:22
First-class explanation result type – values, method, and metadata together.
Vendor-agnostic compute/memory backend. CPUBackend, CUDABackend (Phase 1.5), and HIPBackend (Phase 1....
Definition device_backend.hpp:248
Fits a locality-weighted linear surrogate around one input: perturb x with Gaussian noise,...
Definition lime.hpp:42
static const ExplainerCapabilities & capabilities()
What it answers and needs: its ExplainerCatalog() entry.
Definition lime.hpp:45
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) aga...
Definition lime.hpp:139
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.
Definition lime.hpp:68
N-dimensional tensor. Owns its data buffer exclusively; a DeviceBackend* is injected (not owned) – th...
Definition tensor.hpp:29
DeviceType device() const
Which device this tensor's buffer conceptually resides on.
Definition tensor.hpp:122
int64_t numel() const
Total element count – shape().numel().
Definition tensor.hpp:116
const Shape & shape() const
This tensor's shape.
Definition tensor.hpp:113
float read_element(int64_t flat_index) const
Reads one element to the host through the owning backend, on any device.
std::vector< float > to_host_vector() const
Copies the whole buffer to a host vector through the owning backend, on any device.
Abstract interface isolating vendor-specific memory/compute operations from Tensor/ComputationGraph.
What each explainer answers: the nine question categories (Liao, Gruen and Miller,...
DeviceBackend * backend_beside(const Tensor &like, DeviceBackend *backend)
The backend to allocate a tensor through that must live beside like.
Definition attribution.hpp:49
Definition acquisition_functions.hpp:16
const ExplainerCapabilities & ExplainerCapabilitiesOf(std::string_view name)
The catalog entry named name.
std::vector< float > fit_weighted_linear_regression(const std::vector< std::vector< float > > &samples, const std::vector< float > &targets, const std::vector< float > &weights, float l2_lambda)
Fits w* = argmin_w sum_i weight_i*(target_i - w^T sample_i)^2 + l2_lambda*||w||^2 via the normal equa...
Definition weighted_linear_regression.hpp:38
An explanation result: the raw attribution values, the method that produced them, and any relevant me...
Definition attribution.hpp:23
One explainer's declaration: what it answers and what it needs.
Definition explainer_capabilities.hpp:99
N-dimensional tensor – owns a buffer via DeviceBackend*, RAII (Rule of Five).
Weighted least squares via normal equations – the shared fitting primitive Phase 3's LIME and KernelS...