pulsatrix 1.1.0
Loading...
Searching...
No Matches
kernel_shap.hpp
Go to the documentation of this file.
1
7#pragma once
8
9#include <cstdint>
10#include <functional>
11#include <stdexcept>
12#include <string>
13#include <vector>
14
15#include "pulsatrix/assert.hpp"
19#include "pulsatrix/tensor.hpp"
21
22namespace pulsatrix {
23
24namespace detail {
25
27inline double BinomialCoefficient(int64_t n, int64_t k) {
28 double result = 1.0;
29 for (int64_t i = 1; i <= k; ++i) {
30 result = result * static_cast<double>(n - k + i) / static_cast<double>(i);
31 }
32 return result;
33}
34
40inline float ShapKernelWeight(int64_t n, int64_t coalition_size) {
41 double denominator =
42 BinomialCoefficient(n, coalition_size) * static_cast<double>(coalition_size) * static_cast<double>(n - coalition_size);
43 return static_cast<float>(static_cast<double>(n - 1) / denominator);
44}
45
46} // namespace detail
47
67public:
69 [[nodiscard]] static const ExplainerCapabilities& capabilities() { return ExplainerCapabilitiesOf("KernelSHAP"); }
70
81 [[nodiscard]] Attribution explain(const std::function<Tensor(const Tensor&)>& predict, const Tensor& input,
82 const Tensor& baseline, int64_t target_index, DeviceBackend* backend) const {
83 // External boundary (Mission 2, finding 15 systemic sweep) -- escalated from
84 // PULSATRIX_ASSERT-only.
85 if (input.numel() != baseline.numel()) {
86 throw std::invalid_argument("KernelSHAP::explain: input and baseline must have the same numel");
87 }
88 const int64_t n = input.numel();
89 if (n < 1 || n > 20) { // full 2^n enumeration -- this campaign's small-n scope
90 throw std::invalid_argument("KernelSHAP::explain: input feature count must be in [1, 20]");
91 }
92
93 const std::vector<float> input_values = input.to_host_vector();
94 const std::vector<float> baseline_values = baseline.to_host_vector();
95 DeviceBackend* input_backend = explainer_detail::backend_beside(input, backend);
96 std::vector<float> z_values(static_cast<size_t>(n));
97
98 auto coalition_value = [&](uint64_t mask) {
99 for (int64_t i = 0; i < n; ++i) {
100 bool active = ((mask >> i) & 1u) != 0;
101 const auto idx = static_cast<size_t>(i);
102 z_values[idx] = active ? input_values[idx] : baseline_values[idx];
103 }
104 Tensor z(input.shape(), input_backend, z_values, input.device());
105 Tensor out = predict(z);
106 return out.read_element(target_index);
107 };
108
109 const float f_baseline = coalition_value(0);
110 const uint64_t full_mask = (n == 64) ? ~0ULL : ((1ULL << n) - 1);
111 const float total_diff = coalition_value(full_mask) - f_baseline;
112
113 std::vector<float> phi(static_cast<size_t>(n), 0.0f);
114
115 if (n == 1) {
116 phi[0] = total_diff;
117 } else {
118 std::vector<std::vector<float>> reduced_samples;
119 std::vector<float> reduced_targets;
120 std::vector<float> weights;
121
122 for (uint64_t mask = 1; mask < full_mask; ++mask) {
123 int64_t coalition_size = 0;
124 for (int64_t i = 0; i < n; ++i) {
125 if ((mask >> i) & 1u) {
126 ++coalition_size;
127 }
128 }
129 bool z_last = ((mask >> (n - 1)) & 1u) != 0;
130 float value = coalition_value(mask) - f_baseline;
131 float reduced_target = value - (z_last ? total_diff : 0.0f);
132
133 std::vector<float> reduced_row(static_cast<size_t>(n - 1));
134 for (int64_t i = 0; i < n - 1; ++i) {
135 bool z_i = ((mask >> i) & 1u) != 0;
136 reduced_row[static_cast<size_t>(i)] = (z_i ? 1.0f : 0.0f) - (z_last ? 1.0f : 0.0f);
137 }
138
139 reduced_samples.push_back(std::move(reduced_row));
140 reduced_targets.push_back(reduced_target);
141 weights.push_back(detail::ShapKernelWeight(n, coalition_size));
142 }
143
144 std::vector<float> reduced_phi =
145 fit_weighted_linear_regression(reduced_samples, reduced_targets, weights, 0.0f);
146
147 float sum_reduced = 0.0f;
148 for (int64_t i = 0; i < n - 1; ++i) {
149 phi[static_cast<size_t>(i)] = reduced_phi[static_cast<size_t>(i)];
150 sum_reduced += reduced_phi[static_cast<size_t>(i)];
151 }
152 phi[static_cast<size_t>(n - 1)] = total_diff - sum_reduced;
153 }
154
155 Tensor values(input.shape(), input_backend, phi, input.device());
156
157 return Attribution{"kernel_shap", std::move(values), {{"target_index", std::to_string(target_index)}}};
158 }
159};
160
161} // namespace pulsatrix
PULSATRIX_ASSERT – debug-only invariant check for programmer errors, distinct from throw (used for ca...
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
Approximates Shapley values via full coalition enumeration + SHAP-kernel-weighted linear regression,...
Definition kernel_shap.hpp:66
Attribution explain(const std::function< Tensor(const Tensor &)> &predict, const Tensor &input, const Tensor &baseline, int64_t target_index, DeviceBackend *backend) const
Computes Shapley value approximations for one output index.
Definition kernel_shap.hpp:81
static const ExplainerCapabilities & capabilities()
What it answers and needs: its ExplainerCatalog() entry.
Definition kernel_shap.hpp:69
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,...
float ShapKernelWeight(int64_t n, int64_t coalition_size)
The SHAP kernel pi(z') = (n-1) / [C(n,|z'|) * |z'| * (n-|z'|)], for 1 <= |z'| <= n-1.
Definition kernel_shap.hpp:40
double BinomialCoefficient(int64_t n, int64_t k)
Binomial coefficient C(n,k), computed iteratively to avoid factorial overflow.
Definition kernel_shap.hpp:27
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...