lime.hpp

Go to the documentation of this file.

 
#pragma once
 
#include <cmath>
#include <functional>
#include <random>
#include <stdexcept>
#include <string>
#include <vector>
 
#include "pulsatrix/assert.hpp"
#include "pulsatrix/attribution.hpp"
#include "pulsatrix/device_backend.hpp"
#include "pulsatrix/tensor.hpp"
#include "pulsatrix/weighted_linear_regression.hpp"
 
namespace pulsatrix {
 
class LIME {
public:
    [[nodiscard]] 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 {
        if (num_samples <= 0) {
            throw std::invalid_argument("LIME::explain: num_samples must be positive");
        }
        if (sigma <= 0.0f) {
            throw std::invalid_argument("LIME::explain: sigma must be positive");
        }
 
        Tensor base_output = predict(input);
        PULSATRIX_ASSERT(target_index >= 0 && target_index < base_output.numel());
        float base_value = base_output.read_element(target_index);
 
        int64_t n_features = input.numel();
        const std::vector<float> input_values = input.to_host_vector();
        DeviceBackend* input_backend = explainer_detail::backend_beside(input, backend);
        std::mt19937 rng(seed);
        std::normal_distribution<float> noise(0.0f, sigma);
 
        std::vector<std::vector<float>> samples;
        std::vector<float> targets;
        std::vector<float> weights;
        samples.reserve(static_cast<size_t>(num_samples));
        targets.reserve(static_cast<size_t>(num_samples));
        weights.reserve(static_cast<size_t>(num_samples));
 
        for (int64_t s = 0; s < num_samples; ++s) {
            std::vector<float> perturbed_values(static_cast<size_t>(n_features));
            std::vector<float> delta(static_cast<size_t>(n_features));
            float squared_distance = 0.0f;
            for (int64_t i = 0; i < n_features; ++i) {
                float d = noise(rng);
                delta[static_cast<size_t>(i)] = d;
                perturbed_values[static_cast<size_t>(i)] = input_values[static_cast<size_t>(i)] + d;
                squared_distance += d * d;
            }
            Tensor perturbed(input.shape(), input_backend, perturbed_values, input.device());
 
            Tensor output = predict(perturbed);
            float centered_target = output.read_element(target_index) - base_value;
            float weight = std::exp(-squared_distance / (2.0f * sigma * sigma));
 
            samples.push_back(std::move(delta));
            targets.push_back(centered_target);
            weights.push_back(weight);
        }
 
        std::vector<float> coefficients = fit_weighted_linear_regression(samples, targets, weights, l2_lambda);
 
        coefficients.resize(static_cast<size_t>(n_features));
        Tensor values(input.shape(), input_backend, coefficients, input.device());
 
        return Attribution{"lime", std::move(values),
                            {{"target_index", std::to_string(target_index)},
                             {"num_samples", std::to_string(num_samples)},
                             {"sigma", std::to_string(sigma)}}};
    }
};
 
}  // namespace pulsatrix