wildboar.explain.counterfactual#

Submodules#

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#

score(x_true, x_counterfactuals[, metric, success])

Compute the score for the counterfactuals

counterfactuals(estimator, x, y, *[, method, scoring, ...])

Compute a single counterfactual example for each sample
class wildboar.explain.counterfactual.KNeighborsCounterfactual(random_state=None)#

Bases: wildboar.explain.counterfactual.base.BaseCounterfactual

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.

fit(estimator)#

Fit the counterfactual to a given estimator

Parameters:

estimator (object) – An estimator for which counterfactual explanations are produced

Return type:

self

transform(x, y)#

Transform the i:th sample in x to a sample that would be labeled as the i:th label in y

Parameters:

  • x (array-like of shape (n_samples, n_timestep) or (n_samples, n_dimension, n_timestep)) – The samples to generate counterfactual explanations for

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

Returns:

  • counterfactuals (ndarray of same shape as x) – The counterfactual for each sample. If success[i] == False, then the value of counterfactuals[i] is undefined.

  • success (ndarray of shape (n_samples,)) – Boolean vector indicating successful transformations.

class wildboar.explain.counterfactual.PrototypeCounterfactual(background_x, background_y, *, metric='euclidean', metric_params=None, max_iter=100, step_size=0.1, n_prototypes='auto', target='auto', method='sample', method_params=None, random_state=None)#

Bases: wildboar.explain.counterfactual.base.BaseCounterfactual

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

fit(estimator)#

Fit the counterfactual to a given estimator

Parameters:

estimator (object) – An estimator for which counterfactual explanations are produced

Return type:

self

transform(x, y)#

Transform the i:th sample in x to a sample that would be labeled as the i:th label in y

Parameters:

  • x (array-like of shape (n_samples, n_timestep) or (n_samples, n_dimension, n_timestep)) – The samples to generate counterfactual explanations for

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

Returns:

  • counterfactuals (ndarray of same shape as x) – The counterfactual for each sample. If success[i] == False, then the value of counterfactuals[i] is undefined.

  • success (ndarray of shape (n_samples,)) – Boolean vector indicating successful transformations.

class wildboar.explain.counterfactual.ShapeletForestCounterfactual(*, epsilon=1.0, batch_size=1, random_state=10)#

Bases: wildboar.explain.counterfactual.base.BaseCounterfactual

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)

fit(estimator)#

Fit the counterfactual to a given estimator

Parameters:

estimator (object) – An estimator for which counterfactual explanations are produced

Return type:

self

transform(x, y)#

Transform the i:th sample in x to a sample that would be labeled as the i:th label in y

Parameters:

  • x (array-like of shape (n_samples, n_timestep) or (n_samples, n_dimension, n_timestep)) – The samples to generate counterfactual explanations for

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

Returns:

  • counterfactuals (ndarray of same shape as x) – The counterfactual for each sample. If success[i] == False, then the value of counterfactuals[i] is undefined.

  • success (ndarray of shape (n_samples,)) – Boolean vector indicating successful transformations.

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

Compute the score for 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, callable, list or dict, optional) –

    The scoring metric

    • if str use metrics from scikit-learn

    • if list compute all metrics and return a dict where the key is the name of the metric and the value an ndarray of scores

    • if dict compute all metrics and return a dict where the key is the key and the value an ndarry of scores

    • if callable

  • success (ndarray of shape (n_samples)) – Indicator matrix of successful counterfactual transformations

Returns:

score – The scores

Return type:

ndarray or dict

wildboar.explain.counterfactual.counterfactuals(estimator, x, y, *, method='infer', scoring=None, valid_scoring=False, random_state=None, **kwargs)#

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) or (n_samples, n_dimension, 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, optional) –

    The method to generate counterfactual explanations

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

    • if ‘prototype’, compute model agnostic counterfactual explanations using the PrototypeCounterfactual method

  • scoring (str, callable, list or dict, optional) – The scoring function to determine the goodness of

  • valid_scoring (bool, optional) – Only compute score for successful counterfactuals

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

  • **kwargs (dict, optional) – Optional arguments to the counterfactual explainer

Returns:

  • x_counterfactuals (ndarray of shape (n_samples, n_timestep) or (n_samples, n_dimension, 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) – Score of the counterfactual transform. Only returned if scoring is not None