pulsatrix 1.1.0
Loading...
Searching...
No Matches
counterfactual.hpp
Go to the documentation of this file.
1
7#pragma once
8
9#include <cstdint>
10#include <functional>
11#include <vector>
12
14#include "pulsatrix/tensor.hpp"
15
16namespace pulsatrix {
17
20 enum class Kind {
22 Class,
24 Range,
25 };
27 int64_t index = 0;
28 float margin = 0.0f;
29 float low = 0.0f;
30 float high = 0.0f;
31
32 [[nodiscard]] static CounterfactualTarget ToClass(int64_t class_index, float margin = 0.0f) {
33 return {Kind::Class, class_index, margin, 0.0f, 0.0f};
34 }
35 [[nodiscard]] static CounterfactualTarget ToRange(int64_t output_index, float low, float high) {
36 return {Kind::Range, output_index, 0.0f, low, high};
37 }
38};
39
44 std::vector<float> scale;
46 std::vector<int64_t> immutable;
48 std::vector<float> lower;
49 std::vector<float> upper;
51 std::vector<int64_t> integer;
55 std::vector<std::vector<int64_t>> one_hot_groups;
56};
57
61 float lambda = 0.1f;
63 float lambda_growth = 10.0f;
64 int max_rounds = 5;
65 int steps_per_round = 500;
66 float learning_rate = 0.05f;
68 float change_tolerance = 1e-3f;
69};
70
76 bool valid = false;
78 float output_before = 0.0f;
79 float output_after = 0.0f;
81 float distance = 0.0f;
83 float l2 = 0.0f;
85 int64_t num_changed = 0;
86 int rounds = 0;
87 float final_lambda = 0.0f;
88};
89
96[[nodiscard]] std::vector<float> MedianAbsoluteDeviation(const std::vector<Tensor>& background);
97
120 const CounterfactualTarget& target,
121 const CounterfactualConstraints& constraints = {},
122 const CounterfactualOptions& options = {});
123
128 float initial_radius = 1.0f;
130 int max_layers = 100;
133 uint64_t seed = 0;
134 float change_tolerance = 1e-3f;
135};
136
153[[nodiscard]] CounterfactualResult GrowingSpheresCounterfactual(const std::function<Tensor(const Tensor&)>& predict,
154 const Tensor& input, const CounterfactualTarget& target,
155 const CounterfactualConstraints& constraints = {},
156 const GrowingSpheresOptions& options = {});
157
161 int count = 4;
163 float proximity_weight = 0.5f;
165 float diversity_weight = 1.0f;
166 float learning_rate = 0.05f;
167 int max_steps = 2000;
170 float initial_spread = 0.5f;
171 uint64_t seed = 0;
172 float change_tolerance = 1e-3f;
173};
174
177 std::vector<CounterfactualResult> counterfactuals;
179 float validity = 0.0f;
181 float diversity = 0.0f;
184 float count_diversity = 0.0f;
185};
186
203 const CounterfactualTarget& target,
204 const CounterfactualConstraints& constraints = {},
205 const DiverseCounterfactualOptions& options = {});
206
215[[nodiscard]] float Plausibility(const Tensor& counterfactual, const std::vector<Tensor>& background,
216 const std::vector<float>& scale = {}, int k = 5);
217
218} // namespace pulsatrix
Wraps an ordered chain of Modules, running them via Module::forward_traced to build a real Computatio...
Definition explainer_context.hpp:67
N-dimensional tensor. Owns its data buffer exclusively; a DeviceBackend* is injected (not owned) – th...
Definition tensor.hpp:29
Stable interface every explainer gets, regardless of type (charter Part 2 SS2).
Definition acquisition_functions.hpp:16
float Plausibility(const Tensor &counterfactual, const std::vector< Tensor > &background, const std::vector< float > &scale={}, int k=5)
How typical a counterfactual is of real data: its mean scaled L1 distance to its k nearest instances ...
std::vector< float > MedianAbsoluteDeviation(const std::vector< Tensor > &background)
Each feature's median absolute deviation over background (flat order), the distance scale Wachter et ...
CounterfactualResult GrowingSpheresCounterfactual(const std::function< Tensor(const Tensor &)> &predict, const Tensor &input, const CounterfactualTarget &target, const CounterfactualConstraints &constraints={}, const GrowingSpheresOptions &options={})
A counterfactual for any prediction function, with no gradients (growing spheres, Laugel et al....
CounterfactualResult FindCounterfactual(ExplainerContext &ctx, const Tensor &input, const CounterfactualTarget &target, const CounterfactualConstraints &constraints={}, const CounterfactualOptions &options={})
Finds a nearby input that reaches target (Wachter, Mittelstadt and Russell 2017): minimizes ‘lambda *...
DiverseCounterfactualResult FindDiverseCounterfactuals(ExplainerContext &ctx, const Tensor &input, const CounterfactualTarget &target, const CounterfactualConstraints &constraints={}, const DiverseCounterfactualOptions &options={})
Several counterfactuals found together so that they differ from each other (DiCE, Mothilal,...
Which changes are allowed, and how changes are measured.
Definition counterfactual.hpp:41
std::vector< std::vector< int64_t > > one_hot_groups
Groups of features that one-hot encode one categorical feature: at the end, each group is set to 1 at...
Definition counterfactual.hpp:55
std::vector< float > lower
Per-feature [lower, upper] limits (flat order), or empty for none.
Definition counterfactual.hpp:48
std::vector< int64_t > immutable
Features that must not change, for example age or a protected attribute.
Definition counterfactual.hpp:46
std::vector< int64_t > integer
Features rounded to whole numbers at the end (counts, ordinal codes).
Definition counterfactual.hpp:51
std::vector< float > scale
Per-feature distance scale (flat order); a change of scale[j] costs 1. Usually MedianAbsoluteDeviatio...
Definition counterfactual.hpp:44
std::vector< float > upper
Definition counterfactual.hpp:49
Search settings. Defaults suit standardized tabular inputs.
Definition counterfactual.hpp:59
float lambda
Weight of the prediction loss against the distance at the start of the search.
Definition counterfactual.hpp:61
int steps_per_round
Definition counterfactual.hpp:65
int max_rounds
Definition counterfactual.hpp:64
float lambda_growth
lambda is multiplied by this whenever a round ends without a valid counterfactual.
Definition counterfactual.hpp:63
float change_tolerance
A feature counts as changed when it moves by more than this times its scale.
Definition counterfactual.hpp:68
float learning_rate
Definition counterfactual.hpp:66
A counterfactual and how good it is (the DiCE metrics, for one counterfactual).
Definition counterfactual.hpp:72
int64_t num_changed
Number of features that changed (sparsity).
Definition counterfactual.hpp:85
float l2
Euclidean length of the raw change.
Definition counterfactual.hpp:83
float distance
Sum over features of |change| / scale: the objective's distance (proximity).
Definition counterfactual.hpp:81
bool valid
True when the counterfactual reaches the target, after rounding and one-hot projection.
Definition counterfactual.hpp:76
Tensor counterfactual
Definition counterfactual.hpp:73
float final_lambda
Definition counterfactual.hpp:87
float output_before
The target output (CounterfactualTarget::index) before and after.
Definition counterfactual.hpp:78
int rounds
Definition counterfactual.hpp:86
float output_after
Definition counterfactual.hpp:79
What the counterfactual must achieve.
Definition counterfactual.hpp:19
Kind kind
Definition counterfactual.hpp:26
static CounterfactualTarget ToRange(int64_t output_index, float low, float high)
Definition counterfactual.hpp:35
int64_t index
Definition counterfactual.hpp:27
Kind
Definition counterfactual.hpp:20
static CounterfactualTarget ToClass(int64_t class_index, float margin=0.0f)
Definition counterfactual.hpp:32
float high
Definition counterfactual.hpp:30
float margin
Definition counterfactual.hpp:28
float low
Definition counterfactual.hpp:29
Settings for FindDiverseCounterfactuals.
Definition counterfactual.hpp:159
float initial_spread
The counterfactuals start at the input plus uniform noise of this size, in scale units,...
Definition counterfactual.hpp:170
uint64_t seed
Definition counterfactual.hpp:171
float change_tolerance
Definition counterfactual.hpp:172
int max_steps
Definition counterfactual.hpp:167
int count
How many counterfactuals to find together, >= 1.
Definition counterfactual.hpp:161
float learning_rate
Definition counterfactual.hpp:166
float proximity_weight
Weight of the mean scaled L1 distance to the input (DiCE's proximity_weight).
Definition counterfactual.hpp:163
float diversity_weight
Weight of the diversity term (DiCE's diversity_weight).
Definition counterfactual.hpp:165
A set of counterfactuals and DiCE's set-level metrics (Mothilal et al. 2020).
Definition counterfactual.hpp:176
float count_diversity
Mean fraction of features that differ between pairs of valid counterfactuals (DiCE's count diversity)...
Definition counterfactual.hpp:184
float diversity
Mean scaled L1 distance between pairs of valid counterfactuals (DiCE's diversity).
Definition counterfactual.hpp:181
std::vector< CounterfactualResult > counterfactuals
Definition counterfactual.hpp:177
float validity
Fraction of the counterfactuals that reach the target.
Definition counterfactual.hpp:179
Settings for GrowingSpheresCounterfactual. Radii are in units of the constraints' scale.
Definition counterfactual.hpp:125
float initial_radius
Definition counterfactual.hpp:128
uint64_t seed
The same seed gives the same result on one platform. Directions are drawn with std::log and std::cos,...
Definition counterfactual.hpp:133
float change_tolerance
Definition counterfactual.hpp:134
int max_layers
Balls and shells drawn before giving up.
Definition counterfactual.hpp:130
int samples_per_layer
Points drawn in each ball or shell.
Definition counterfactual.hpp:127
N-dimensional tensor – owns a buffer via DeviceBackend*, RAII (Rule of Five).