pulsatrix 1.1.0
Loading...
Searching...
No Matches
surrogate_tree.hpp File Reference

A global surrogate: a shallow decision tree fitted to a model's predictions, with its fidelity to the model on held-out inputs (XAI-4; TREPAN, Craven and Shavlik 1996). More...

#include <cstdint>
#include <functional>
#include <string>
#include <vector>
#include "pulsatrix/explainer_capabilities.hpp"
#include "pulsatrix/json.hpp"
#include "pulsatrix/tensor.hpp"
Include dependency graph for surrogate_tree.hpp:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  pulsatrix::SurrogateTreeOptions
 How the tree is grown. More...
 
struct  pulsatrix::SurrogateNode
 One node. A leaf has feature -1. More...
 
struct  pulsatrix::SurrogateTree
 A fitted tree. nodes[0] is the root. More...
 
struct  pulsatrix::SurrogateFidelity
 How well the tree imitates the model. More...
 
struct  pulsatrix::SurrogateTreeResult
 FitSurrogateTree()'s result. More...
 

Namespaces

namespace  pulsatrix
 

Enumerations

enum class  pulsatrix::SurrogateTask { pulsatrix::Classification , pulsatrix::Regression }
 What the surrogate imitates. More...
 

Functions

SurrogateTree pulsatrix::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. FitSurrogateTree() calls this on the model's predictions; it is public so the tree can be checked on its own.
 
std::vector< double > pulsatrix::FeatureImportance (const SurrogateTree &tree)
 Each feature's share of the tree's impurity decrease (scikit-learn's feature_importances_).
 
SurrogateTreeResult pulsatrix::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 measures its fidelity on both parts.
 
std::string pulsatrix::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, 95%).
 
JsonValue pulsatrix::ToJson (const SurrogateTreeResult &result, const std::vector< std::string > &feature_names={})
 The result as a pulsatrix.surrogate_tree.v1 document.
 
std::string_view pulsatrix::to_string (SurrogateTask task)
 

Detailed Description

A global surrogate: a shallow decision tree fitted to a model's predictions, with its fidelity to the model on held-out inputs (XAI-4; TREPAN, Craven and Shavlik 1996).

A surrogate answers "how does the model work overall?" with rules a person can read, and its fidelity says how far to trust them: a tree that agrees with the model on 70% of new inputs describes a different model 30% of the time. Below about 85% at a readable depth, the tree isn't a description of the model (the falsifier in the roadmap's research notes).

The tree is CART as scikit-learn builds it (DecisionTreeClassifier and DecisionTreeRegressor with splitter="best"): Gini or squared-error impurity, thresholds halfway between consecutive distinct values, x <= threshold going left, nodes numbered depth first. Ties between features go to the lower index, where scikit-learn breaks them at random.

SurrogateTreeOptions options;
options.max_depth = 3;
SurrogateTreeResult s = FitSurrogateTree(predict, background, options);
std::cout << DescribeSurrogateTree(s.tree, feature_names);
// s.fidelity.test: the share of held-out inputs where the tree's class is the model's