pulsatrix 1.1.0
Loading...
Searching...
No Matches
lime.hpp
Go to the documentation of this file.
1
6#pragma once
7
8#include <cmath>
9#include <functional>
10#include <random>
11#include <stdexcept>
12#include <string>
13#include <vector>
14
15#include "pulsatrix/assert.hpp"
19#include "pulsatrix/tensor.hpp"
21
22namespace pulsatrix {
23
42class LIME {
43public:
45 [[nodiscard]] static const ExplainerCapabilities& capabilities() { return ExplainerCapabilitiesOf("LIME"); }
46
68 [[nodiscard]] Attribution explain(const std::function<Tensor(const Tensor&)>& predict, const Tensor& input,
69 int64_t target_index, int64_t num_samples, float sigma, float l2_lambda,
70 unsigned seed, DeviceBackend* backend) const {
71 if (num_samples <= 0) {
72 throw std::invalid_argument("LIME::explain: num_samples must be positive");
73 }
74 if (sigma <= 0.0f) {
75 throw std::invalid_argument("LIME::explain: sigma must be positive");
76 }
77
78 Tensor base_output = predict(input);
79 PULSATRIX_ASSERT(target_index >= 0 && target_index < base_output.numel());
80 float base_value = base_output.read_element(target_index);
81
82 int64_t n_features = input.numel();
83 const std::vector<float> input_values = input.to_host_vector();
84 DeviceBackend* input_backend = explainer_detail::backend_beside(input, backend);
85 std::mt19937 rng(seed);
86 std::normal_distribution<float> noise(0.0f, sigma);
87
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));
94
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;
104 }
105 Tensor perturbed(input.shape(), input_backend, perturbed_values, input.device());
106
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));
110
111 samples.push_back(std::move(delta));
112 targets.push_back(centered_target);
113 weights.push_back(weight);
114 }
115
116 std::vector<float> coefficients = fit_weighted_linear_regression(samples, targets, weights, l2_lambda);
117
118 coefficients.resize(static_cast<size_t>(n_features));
119 const double fidelity = local_fidelity(samples, targets, weights, coefficients);
120 Tensor values(input.shape(), input_backend, coefficients, input.device());
121
122 return Attribution{"lime", std::move(values),
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)}}};
127 }
128
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];
146 }
147 if (weight_sum <= 0.0) return 0.0;
148 mean /= weight_sum;
149 double residual = 0.0, total = 0.0;
150 for (size_t s = 0; s < samples.size(); ++s) {
151 double fit = 0.0;
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;
156 }
157 if (total == 0.0) return residual == 0.0 ? 1.0 : 0.0;
158 return 1.0 - residual / total;
159 }
160};
161
162} // namespace pulsatrix
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...