pulsatrix 1.1.0
Loading...
Searching...
No Matches
surrogate_tree.hpp
Go to the documentation of this file.
1
24#pragma once
25
26#include <cstdint>
27#include <functional>
28#include <string>
29#include <vector>
30
32#include "pulsatrix/json.hpp"
33#include "pulsatrix/tensor.hpp"
34
35namespace pulsatrix {
36
38enum class SurrogateTask {
43};
44
59
62 int64_t feature = -1;
64 double threshold = 0.0;
65 int left = -1;
66 int right = -1;
68 int64_t samples = 0;
70 double impurity = 0.0;
72 double value = 0.0;
74 std::vector<int64_t> class_counts;
75
76 [[nodiscard]] bool is_leaf() const { return feature < 0; }
77};
78
82 int64_t num_features = 0;
84 int64_t num_classes = 0;
85 std::vector<SurrogateNode> nodes;
86
88 [[nodiscard]] int leaf(const std::vector<float>& x) const;
90 [[nodiscard]] double predict(const std::vector<float>& x) const;
91 [[nodiscard]] int depth() const;
92 [[nodiscard]] int64_t leaves() const;
93};
94
98 double train = 0.0;
100 double test = 0.0;
101 int64_t train_size = 0;
102 int64_t test_size = 0;
103};
104
113
122[[nodiscard]] SurrogateTree FitDecisionTree(const std::vector<std::vector<float>>& x, const std::vector<double>& y,
123 SurrogateTask task, int64_t num_classes, const SurrogateTreeOptions& options);
124
126[[nodiscard]] std::vector<double> FeatureImportance(const SurrogateTree& tree);
127
136[[nodiscard]] SurrogateTreeResult FitSurrogateTree(const std::function<Tensor(const Tensor&)>& predict,
137 const std::vector<Tensor>& instances,
138 const SurrogateTreeOptions& options = {});
139
145[[nodiscard]] std::string DescribeSurrogateTree(const SurrogateTree& tree,
146 const std::vector<std::string>& feature_names = {});
147
149[[nodiscard]] JsonValue ToJson(const SurrogateTreeResult& result, const std::vector<std::string>& feature_names = {});
150
151[[nodiscard]] std::string_view to_string(SurrogateTask task);
152
153} // namespace pulsatrix
One JSON value: null, a boolean, a number, a string, an array or an object.
Definition json.hpp:22
N-dimensional tensor. Owns its data buffer exclusively; a DeviceBackend* is injected (not owned) – th...
Definition tensor.hpp:29
What each explainer answers: the nine question categories (Liao, Gruen and Miller,...
A small strict JSON value, parser and deterministic writer (RFC 8259).
Definition acquisition_functions.hpp:16
std::vector< double > FeatureImportance(const SurrogateTree &tree)
Each feature's share of the tree's impurity decrease (scikit-learn's feature_importances_).
SurrogateTree FitDecisionTree(const std::vector< std::vector< float > > &x, const std::vector< double > &y, SurrogateTask task, int64_t num_classes, const SurrogateTreeOptions &options)
Fits CART to rows x and targets y: class indices for classification, values for regression....
JsonValue ToJson(const AttackResult &result, const AttackOptions &options)
The result as a pulsatrix.attack.v1 document, without the adversarial inputs.
std::string DescribeSurrogateTree(const SurrogateTree &tree, const std::vector< std::string > &feature_names={})
The tree as nested if/else rules, one node per line: if income <= 41.5: ... class 1 (40 inputs,...
SurrogateTreeResult FitSurrogateTree(const std::function< Tensor(const Tensor &)> &predict, const std::vector< Tensor > &instances, const SurrogateTreeOptions &options={})
Labels instances with the model, holds out options.test_fraction of them, fits a tree to the rest and...
std::string_view to_string(XaiQuestion question)
SurrogateTask
What the surrogate imitates.
Definition surrogate_tree.hpp:38
@ Classification
The model's class: the index of its largest output. Fidelity is agreement.
@ Regression
One output's value. Fidelity is R².
How well the tree imitates the model.
Definition surrogate_tree.hpp:96
double test
On the held-out inputs; the number to report. NaN when nothing was held out.
Definition surrogate_tree.hpp:100
double train
On the inputs the tree was fitted to.
Definition surrogate_tree.hpp:98
int64_t test_size
Definition surrogate_tree.hpp:102
int64_t train_size
Definition surrogate_tree.hpp:101
One node. A leaf has feature -1.
Definition surrogate_tree.hpp:61
std::vector< int64_t > class_counts
Classification: how many training inputs of each class reached the node.
Definition surrogate_tree.hpp:74
double value
The mean target, or the majority class (lowest index on a tie).
Definition surrogate_tree.hpp:72
int64_t samples
Training inputs that reached the node.
Definition surrogate_tree.hpp:68
double impurity
Gini impurity, or the variance of the target.
Definition surrogate_tree.hpp:70
int left
Definition surrogate_tree.hpp:65
bool is_leaf() const
Definition surrogate_tree.hpp:76
int64_t feature
Definition surrogate_tree.hpp:62
double threshold
Inputs with x[feature] <= threshold go to left.
Definition surrogate_tree.hpp:64
int right
Definition surrogate_tree.hpp:66
How the tree is grown.
Definition surrogate_tree.hpp:46
int64_t target
Regression: the output (flat index) imitated.
Definition surrogate_tree.hpp:49
int max_depth
The deepest a leaf may be; the root is depth 0. Three or four levels stay readable.
Definition surrogate_tree.hpp:51
double test_fraction
FitSurrogateTree: the share of the inputs held out to measure fidelity, in [0, 1).
Definition surrogate_tree.hpp:55
int64_t min_samples_leaf
The fewest inputs a leaf may hold.
Definition surrogate_tree.hpp:53
uint64_t seed
FitSurrogateTree: seeds the held-out split.
Definition surrogate_tree.hpp:57
SurrogateTask task
Definition surrogate_tree.hpp:47
FitSurrogateTree()'s result.
Definition surrogate_tree.hpp:106
SurrogateFidelity fidelity
Definition surrogate_tree.hpp:108
std::vector< double > feature_importance
Each feature's total impurity decrease, weighted by the inputs it split, summing to 1 (scikit-learn's...
Definition surrogate_tree.hpp:111
SurrogateTree tree
Definition surrogate_tree.hpp:107
A fitted tree. nodes[0] is the root.
Definition surrogate_tree.hpp:80
int64_t num_classes
Classification: the number of classes (the model's output size).
Definition surrogate_tree.hpp:84
int64_t leaves() const
SurrogateTask task
Definition surrogate_tree.hpp:81
double predict(const std::vector< float > &x) const
The leaf's value: a class index, or the predicted target.
std::vector< SurrogateNode > nodes
Definition surrogate_tree.hpp:85
int64_t num_features
Definition surrogate_tree.hpp:82
int leaf(const std::vector< float > &x) const
The leaf x falls in.
N-dimensional tensor – owns a buffer via DeviceBackend*, RAII (Rule of Five).