`wildboar.explain.counterfactual`#

Counterfactual explanations.

The wildboar.explain.counterfactual module includes numerous methods for generating counterfactual explanations.

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.

class wildboar.explain.counterfactual.KNeighborsCounterfactual(method='auto', random_state=None)[source]#

Fit a counterfactual explainer to a k-nearest neighbors classifier.

Parameters:

method{“auto”, “mean”, “medoid”}, optional

The method for generating counterfactuals. If ‘auto’, counterfactuals are generated using k-means if possible and k-medoids otherwise. If ‘mean’, counterfactuals are always generated using k-means, which fails if the estimator is fitted with a metric other than ‘euclidean’, ‘dtw’ or ‘wdtw. If ‘medoid’, counterfactuals are generated using k-medoids.

Added in version 1.2.

random_stateint or RandomState, optional

If int, random_state is the seed used by the random number generator.
If RandomState instance, random_state is the random number generator.
If None, the random number generator is the RandomState instance used by np.random.

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.

Attributes:

explainer_dict: The explainer for each label

fit_explain(estimator, x=None, y=None, **kwargs)[source]#

Fit and return the explanation.

Parameters:

estimatorEstimator: The estimator to explain.
xtime-series, optional: The input time series.
yarray-like of shape (n_samples, ), optional: The labels.
**kwargs: Optional extra arguments.

Returns:

ndarray: The explanation.

get_metadata_routing()[source]#

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest: A MetadataRequest encapsulating routing information.

get_params(deep=True)[source]#

Get parameters for this estimator.

Parameters:

deepbool, default=True: If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict: Parameter names mapped to their values.

plot(x=None, y=None, ax=None)[source]#

Plot the explanation.

Returns:

axAxes: The axes object

score(x, y)[source]#

Score the counterfactual explainer in terms of closeness of fit.

Parameters:

xarray-like of shape (n_samples, n_timestep): The samples.
yarray-like of shape (n_samples, ): The desired counterfactal label.

Returns:

scorefloat: The closensess of fit.

set_params(**params)[source]#

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict: Estimator parameters.

Returns:

selfestimator instance: Estimator instance.

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

Model agnostic approach for constructing counterfactual explanations.

References

Samsten, Isak (2020).: Model agnostic time series counterfactuals

Attributes:

estimator_object: The estimator for which counterfactuals are computed
classes_ndarray: The classes
partitions_dict: Dictionary of classes and PrototypeSampler
target_TargetEvaluator: The target evaluator

fit_explain(estimator, x=None, y=None, **kwargs)[source]#

Fit and return the explanation.

Parameters:

estimatorEstimator: The estimator to explain.
xtime-series, optional: The input time series.
yarray-like of shape (n_samples, ), optional: The labels.
**kwargs: Optional extra arguments.

Returns:

ndarray: The explanation.

get_metadata_routing()[source]#

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest: A MetadataRequest encapsulating routing information.

get_params(deep=True)[source]#

Get parameters for this estimator.

Parameters:

deepbool, default=True: If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict: Parameter names mapped to their values.

plot(x=None, y=None, ax=None)[source]#

Plot the explanation.

Returns:

axAxes: The axes object

score(x, y)[source]#

Score the counterfactual explainer in terms of closeness of fit.

Parameters:

xarray-like of shape (n_samples, n_timestep): The samples.
yarray-like of shape (n_samples, ): The desired counterfactal label.

Returns:

scorefloat: The closensess of fit.

set_params(**params)[source]#

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict: Estimator parameters.

Returns:

selfestimator instance: Estimator instance.

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)[source]#

Counterfactual explanations for shapelet forest classifiers.

Parameters:

cost{“euclidean”, “cosine”, “manhattan”} or callable, optional: The cost function to determine the goodness of counterfactual.
aggregationcallable, optional: The aggregation function for the cost of multivariate counterfactuals.
epsilonfloat, optional: Control the degree of change from the decision threshold.
batch_sizefloat, 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_pathsfloat, optional: Sample a fraction of the positive prediction paths.

Added in version 1.1: Add support for subsampling prediction paths.
verbosebool, optional: Print information to stdout during execution.
random_stateRandomState or int, optional: Pseudo-random number for consistency between different runs.

Warning

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

Notes

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

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)

Attributes:

paths_dict: A dictionary of prediction paths per label

fit_explain(estimator, x=None, y=None, **kwargs)[source]#

Fit and return the explanation.

Parameters:

estimatorEstimator: The estimator to explain.
xtime-series, optional: The input time series.
yarray-like of shape (n_samples, ), optional: The labels.
**kwargs: Optional extra arguments.

Returns:

ndarray: The explanation.

get_metadata_routing()[source]#

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest: A MetadataRequest encapsulating routing information.

get_params(deep=True)[source]#

Get parameters for this estimator.

Parameters:

deepbool, default=True: If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict: Parameter names mapped to their values.

plot(x=None, y=None, ax=None)[source]#

Plot the explanation.

Returns:

axAxes: The axes object

score(x, y)[source]#

Score the counterfactual explainer in terms of closeness of fit.

Parameters:

xarray-like of shape (n_samples, n_timestep): The samples.
yarray-like of shape (n_samples, ): The desired counterfactal label.

Returns:

scorefloat: The closensess of fit.

set_params(**params)[source]#

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict: Estimator parameters.

Returns:

selfestimator instance: Estimator instance.

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)[source]#

Compute a single counterfactual example for each sample.

Parameters:

estimatorobject

The estimator used to compute the counterfactual example.

xarray-like of shape (n_samples, n_timestep)

The data samples to fit counterfactuals to.

yarray-like broadcast to shape (n_samples,)

The desired label of the counterfactual.

train_xarray-like of shape (n_samples, n_timestep), optional

Training samples if required by the explainer.

train_yarray-like of shape (n_samples, ), optional

Training labels if required by the explainer.

methodstr 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.

scoringstr, 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.

valid_scoringbool, optional

Only compute score for successful counterfactuals.

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

proximitystr, callable, list or dict, optional

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

random_stateRandomState or int, optional

The pseudo random number generator to ensure stable result.

method_argsdict, optional

Optional arguments to the counterfactual explainer.

Added in version 1.1.0.

Returns:

x_counterfactualsndarray of shape (n_samples, n_timestep): The counterfactual example.
validndarray of shape (n_samples,): Indicator matrix for valid counterfactuals.
scorendarray 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)[source]#

Compute the proximity of the counterfactuals.

Parameters:

x_truearray-like of shape (n_samples, n_timestep)

The true samples.

x_counterfactualsarray-like of shape (n_samples, n_timestep)

The counterfactual samples.

metricstr or callable, optional

The distance metric

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

metric_paramsdict, optional

Parameters to the metric.

Read more about the parameters in the User guide.

Returns:

ndarray: The scores.

wildboar.explain.counterfactual#

Package Contents#

Classes#

Functions#

`wildboar.explain.counterfactual`#