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

Counterfactual explanations: gradient-based (Wachter et al. 2017, CFS-5) and model-agnostic (growing spheres, Laugel et al. 2018, CFS-6), and diverse sets with a plausibility score (DiCE, Mothilal et al. 2020, CFS-7). More...

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

Go to the source code of this file.

Classes

struct  pulsatrix::CounterfactualTarget
 What the counterfactual must achieve. More...
 
struct  pulsatrix::CounterfactualConstraints
 Which changes are allowed, and how changes are measured. More...
 
struct  pulsatrix::CounterfactualOptions
 Search settings. Defaults suit standardized tabular inputs. More...
 
struct  pulsatrix::CounterfactualResult
 A counterfactual and how good it is (the DiCE metrics, for one counterfactual). More...
 
struct  pulsatrix::GrowingSpheresOptions
 Settings for GrowingSpheresCounterfactual. Radii are in units of the constraints' scale. More...
 
struct  pulsatrix::DiverseCounterfactualOptions
 Settings for FindDiverseCounterfactuals. More...
 
struct  pulsatrix::DiverseCounterfactualResult
 A set of counterfactuals and DiCE's set-level metrics (Mothilal et al. 2020). More...
 

Namespaces

namespace  pulsatrix
 

Functions

std::vector< float > pulsatrix::MedianAbsoluteDeviation (const std::vector< Tensor > &background)
 Each feature's median absolute deviation over background (flat order), the distance scale Wachter et al. recommend for tabular data. A feature with zero MAD gets 1, as in DiCE, so it can still move.
 
CounterfactualResult pulsatrix::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 * loss(f(x’), target) + sum_j |x'_j - x_j| / scale_j` by proximal gradient descent, so features the prediction doesn't need stay exactly unchanged. If a round ends without reaching the target, lambda grows and the search continues from where it was.
 
CounterfactualResult pulsatrix::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. 2018): draws points uniformly in a ball around the input, halving its radius while it still contains a point that reaches the target, then in ever larger shells until one does; takes the nearest such point and puts features back to their original values, smallest change first, while it still reaches the target.
 
DiverseCounterfactualResult pulsatrix::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, Sharma and Tan 2020): one person may be able to raise their income, another to pay down debt, and a single counterfactual shows only one of those routes.
 
float pulsatrix::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 in background (lower is more plausible), the kNN measure of the CARLA benchmark. A counterfactual far from every real instance may be valid but describe nobody.
 

Detailed Description

Counterfactual explanations: gradient-based (Wachter et al. 2017, CFS-5) and model-agnostic (growing spheres, Laugel et al. 2018, CFS-6), and diverse sets with a plausibility score (DiCE, Mothilal et al. 2020, CFS-7).