wildboar.explain.counterfactual

Package Contents

Classes

KNeighborsCounterfactual	Fit a counterfactual explainer to a k-nearest neighbors classifier
PrototypeCounterfactual	Model agnostic approach for constructing counterfactual explanations
ShapeletForestCounterfactual	Counterfactual explanations for shapelet forest classifiers

Functions

counterfactuals(estimator, x, y, *[, train_x, ...])	Compute a single counterfactual example for each sample
proximity(x_true, x_counterfactuals[, metric, ...])	Compute the proximity of the counterfactuals.
score(x_true, x_counterfactuals[, metric, success])

class wildboar.explain.counterfactual.KNeighborsCounterfactual(random_state=None)

Bases: wildboar.base.CounterfactualMixin, wildboar.base.ExplainerMixin, wildboar.base.BaseEstimator

Fit a counterfactual explainer to a k-nearest neighbors classifier

explainer_

The explainer for each label

Type:

dict

References

Karlsson, I., Rebane, J., Papapetrou, P., & Gionis, A. (2020).

Locally and globally explainable time series tweaking. Knowledge and Information Systems, 62(5), 1671-1700.

explain(x, y)

fit(estimator, x=None, y=None)

class wildboar.explain.counterfactual.PrototypeCounterfactual(metric='euclidean', *, r=1.0, g=0.05, max_iter=100, step_size=0.1, n_prototypes='auto', target='auto', method='sample', min_shapelet_size=0.0, max_shapelet_size=1.0, random_state=None, verbose=False)

Bases: wildboar.base.CounterfactualMixin, wildboar.base.ExplainerMixin, wildboar.base.BaseEstimator

Model agnostic approach for constructing counterfactual explanations

estimator_

The estimator for which counterfactuals are computed

Type:

object

classes_

The classes

Type:

ndarray

partitions_

Dictionary of classes and PrototypeSampler

Type:

dict

target_

The target evaluator

Type:

TargetEvaluator

References

Samsten, Isak (2020).

Model agnostic time series counterfactuals

Crate a new model agnostic counterfactual explainer.

Parameters:

• metric ({'euclidean', 'dtw', 'wdtw'}, optional) – The metric used to move the samples

• r (float, optional) – The warping window size, if metric=’dtw’ or metric=’wdtw’

• g (float, optional) – Penalty control for weighted DTW, if metric=’wdtw’

• max_iter (int, optional) – The maximum number of iterations

• step_size (float, optional) – The step size when moving samples toward class prototypes

• n_prototypes (int, float or str, optional) – The number of initial prototypes to sample from

• target (float or str, optional) –

  The target evaluation of counterfactuals:

  • if ‘auto’ the counterfactual prediction must return the correct label

  • if float, the counterfactual prediction probability must exceed target value

• method ({'sample', 'shapelet', 'nearest', 'nearest_shapelet'}, optional) –

  Method for selecting prototypes

  • if ‘sample’ a prototype is sampled among the initial prototypes

  • if ‘shapelet’ a prototype shapelet is sampled among the initial prototypes

  • if ‘nearest’ a prototype is sampled from the closest n prototypes

  • if ‘nearest_shapelet’ a prototype shapelet is sampled from the closest n prototypes

• min_shapelet_size (float, optional) – Minimum shapelet size, if method=’shapelet’ or ‘nearest_shapelet’

• max_shapelet_size (float, optional) – Maximum shapelet size, if method=’shapelet’ or ‘nearest_shapelet’

• random_state (RandomState or int, optional) – Pseudo-random number for consistency between different runs

explain(x, y)

fit(estimator, x, y)

class wildboar.explain.counterfactual.ShapeletForestCounterfactual(*, cost='euclidean', aggregation='mean', epsilon=1.0, batch_size=0.1, max_paths=1.0, verbose=False, random_state=None)

Bases: wildboar.base.CounterfactualMixin, wildboar.base.ExplainerMixin, wildboar.base.BaseEstimator

Counterfactual explanations for shapelet forest classifiers

paths_

A dictionary of prediction paths per label

Type:

dict

Notes

This implementation only supports the reversible algorithm described by Karlsson (2020)

Warning

Only shapelet forests fit with the Euclidean distance is supported i.e., metric="euclidean"

References

Karlsson, I., Rebane, J., Papapetrou, P., & Gionis, A. (2020).

Locally and globally explainable time series tweaking. Knowledge and Information Systems, 62(5), 1671-1700.

Karlsson, I., Rebane, J., Papapetrou, P., & Gionis, A. (2018).

Explainable time series tweaking via irreversible and reversible temporal transformations. In 2018 IEEE International Conference on Data Mining (ICDM)

Parameters:

• cost ({"euclidean", "cosine", "manhattan"}, optional) – The cost function to determine the goodness of counterfactual

• aggregation (callable, optional) – The aggregation function for the cost of multivariate counterfactuals.

• epsilon (float, optional) – Control the degree of change from the decision threshold

• batch_size (float, optional) –

  Batch size when evaluating the cost and predictions of counterfactual candidates. The default setting is to evaluate all counterfactual samples.

  Changed in version 1.1: The default value changed to 0.1

• max_paths (float, optional) –

  Sample a fraction of the positive prediction paths.

  New in version 1.1: Add support for subsampling prediction paths.

• verbose (boolean, optional) – Print information to stdout during execution.

• random_state (RandomState or int, optional) – Pseudo-random number for consistency between different runs

explain(x, y)

fit(estimator, x=None, y=None)

wildboar.explain.counterfactual.counterfactuals(estimator, x, y, *, train_x=None, train_y=None, method='best', scoring='deprecated', valid_scoring='deprecated', proximity=None, random_state=None, method_args=None)

Compute a single counterfactual example for each sample

Parameters:

• estimator (object) – The estimator used to compute the counterfactual example

• x (array-like of shape (n_samples, n_timestep)) – The data samples to fit counterfactuals to

• y (array-like broadcast to shape (n_samples,)) – The desired label of the counterfactual

• method (str or BaseCounterfactual, optional) –

  The method to generate counterfactual explanations

  • if ‘best’, infer the most appropriate counterfactual explanation method based on the estimator

    Changed in version 1.1.0.

  • if str, select counterfactual explainer from named collection. See _COUNTERFACTUALS.keys() for a list of valid values.

  • if, BaseCounterfactual use the supplied counterfactual

• scoring (str, callable, list or dict, optional) –

  The scoring function to determine the similarity between the counterfactual sample and the original sample

  Deprecated since version 1.1: scoring was renamed to proximity in 1.1 and will be removed in 1.2.

• proximity (str, callable, list or dict, optional) – The scoring function to determine the similarity between the counterfactual sample and the original sample

• valid_scoring (bool, optional) –

  Only compute score for successful counterfactuals.

  Deprecated since version 1.1: valid_scoring will be removed in 1.2.

• random_state (RandomState or int, optional) – The pseudo random number generator to ensure stable result

• method_args (dict, optional) –

  Optional arguments to the counterfactual explainer.

  New in version 1.1.0.

Returns:

• x_counterfactuals (ndarray of shape (n_samples, n_timestep)) – The counterfactual example.

• valid (ndarray of shape (n_samples,)) – Indicator matrix for valid counterfactuals

• score (ndarray of shape (n_samples,) or dict, optional) – Return score of the counterfactual transform, if scoring is not None

wildboar.explain.counterfactual.proximity(x_true, x_counterfactuals, metric='normalized_euclidean', metric_params=None)

Compute the proximity of the counterfactuals.

Parameters:

• x_true (array-like of shape (n_samples, n_timestep)) – The true samples

• x_counterfactuals (array-like of shape (n_samples, n_timestep)) – The counterfactual samples

• metric (str or callable, optional) –

  The distance metric

  See _DISTANCE_MEASURE.keys() for a list of supported metrics.

• metric_params (dict, optional) –

  Parameters to the metric.

  Read more about the parameters in the User guide.

Returns:

score – The scores

Return type:

ndarray

wildboar.explain.counterfactual.score(x_true, x_counterfactuals, metric='euclidean', success=None)