wildboar.explain.counterfactual._proto

Module Contents

Classes

DynamicTimeWarpTransform	Transform a sample by moving it closer using the dtw alignment matrix
EuclideanTransform	Transform a sample by moving it closer in euclidean space
KNearestPrototypeSampler	Sample a prototype among the samples closest to the current counterfactual
KNearestShapeletPrototypeSampler	Combines the KNearestPrototypeSample and the ShapeletPrototypeSampler
MetricTransform	Move a time series towards a prototype
PredictEvaluator	Evaluate if a counterfactual is predicted as y
ProbabilityEvaluator	Evaluate if the probability of a counterfactual is at least a given constant
PrototypeCounterfactual	Model agnostic approach for constructing counterfactual explanations
PrototypeSampler	Helper class that provides a standard way to create an ABC using
ShapeletPrototypeSampler	Sample shapelet prototypes
TargetEvaluator	Evaluate if a sample is a counterfactual
UniformPrototypeSampler	Sample a prototype uniformly at random from the initial prototype sample
WeightedDynamicTimeWarpTransform	Transform a sample by moving it closer using the dtw alignment matrix

class wildboar.explain.counterfactual._proto.DynamicTimeWarpTransform(gamma, r=1.0)

Bases: MetricTransform

Transform a sample by moving it closer using the dtw alignment matrix

Construct a new transformer

Parameters:

gamma (float) – The strength of the move, where values close to 0 means that the sample is moved less and values closer to 1 mean that the sample is moved more.

move(o, p)

Move the sample o towards p

Parameters:

• o (ndarray of shape (n_timestep,)) – An array, the time series to move

• p (ndarray of shape (n_timestep,)) – An array, the time series to move towards

Returns:

ndarray

Return type:

an array, the result of moving o closer to p

class wildboar.explain.counterfactual._proto.EuclideanTransform(gamma)

Bases: MetricTransform

Transform a sample by moving it closer in euclidean space

Construct a new transformer

Parameters:

gamma (float) – The strength of the move, where values close to 0 means that the sample is moved less and values closer to 1 mean that the sample is moved more.

move(o, p)

Move the sample o towards p

Parameters:

• o (ndarray of shape (n_timestep,)) – An array, the time series to move

• p (ndarray of shape (n_timestep,)) – An array, the time series to move towards

Returns:

ndarray

Return type:

an array, the result of moving o closer to p

class wildboar.explain.counterfactual._proto.KNearestPrototypeSampler(x, y, prototype_indicies, metric_transform)

Bases: PrototypeSampler

Sample a prototype among the samples closest to the current counterfactual

Sample and refine counterfactuals

Parameters:

• x (ndarray of shape (n_samples, n_timestep)) – The data samples labeled as y

• y (object) – The label of the samples in x

• n_prototypes (int) – The number of prototypes in the initial sample

• metric_transform (MetricTransform) – The metric transformer.

• random_state (RandomState) – The random number generator.

nearest_index(o, random_state)

Return the index of the closest sample

Parameters:

o (ndarray of shape (n_timestep,)) – The current counterfactual sample

Returns:

int

Return type:

an index

sample(o, random_state)

Sample an example

Parameters:

o (ndarray of shape (n_timestep,)) – The current counterfactual sample

Returns:

prototype – A prototype of the counterfactual label

Return type:

ndarray of shape (n_timestep,)

class wildboar.explain.counterfactual._proto.KNearestShapeletPrototypeSampler(x, y, prototype_indicies, metric_transform, min_shapelet_size=0, max_shapelet_size=1)

Bases: PrototypeSampler

Combines the KNearestPrototypeSample and the ShapeletPrototypeSampler such that prototype samples are sampled among the nearest neighbors of the counterfactual

Sample and refine counterfactuals

Parameters:

• x (ndarray of shape (n_samples, n_timestep)) – The data samples labeled as y

• y (object) – The label of the samples in x

• n_prototypes (int) – The number of prototypes in the initial sample

• metric_transform (MetricTransform) – The metric transformer.

• random_state (RandomState) – The random number generator.

move(o, p)

Move the current counterfactual toward the prototype

Parameters:

• o (ndarray of shape (n_timestep,)) – The current counterfactual sample

• p (ndarray of shape (n_timestep,)) – The prototype of the counterfactual label

Returns:

new_counterfactual – The new counterfactual moved towards the prototype

Return type:

ndarray of shape (n_timestep,)

sample(o, random_state)

Sample an example

Parameters:

o (ndarray of shape (n_timestep,)) – The current counterfactual sample

Returns:

prototype – A prototype of the counterfactual label

Return type:

ndarray of shape (n_timestep,)

class wildboar.explain.counterfactual._proto.MetricTransform(gamma)

Bases: abc.ABC

Move a time series towards a prototype

Construct a new transformer

Parameters:

gamma (float) – The strength of the move, where values close to 0 means that the sample is moved less and values closer to 1 mean that the sample is moved more.

abstract move(o, p)

Move the sample o towards p

Parameters:

• o (ndarray of shape (n_timestep,)) – An array, the time series to move

• p (ndarray of shape (n_timestep,)) – An array, the time series to move towards

Returns:

ndarray

Return type:

an array, the result of moving o closer to p

class wildboar.explain.counterfactual._proto.PredictEvaluator(estimator)

Bases: TargetEvaluator

Evaluate if a counterfactual is predicted as y

Construct a new evaluator

Parameters:

estimator (object) – The estimator

class wildboar.explain.counterfactual._proto.ProbabilityEvaluator(estimator, probability=0.5)

Bases: TargetEvaluator

Evaluate if the probability of a counterfactual is at least a given constant

Construct a new evaluator

Parameters:

• estimator (object) – The estimator

• probability (float) – The minimum probability of the predicted label

class wildboar.explain.counterfactual._proto.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._proto.PrototypeSampler(x, y, prototype_indices, metric_transform)

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Sample and refine counterfactuals

Parameters:

• x (ndarray of shape (n_samples, n_timestep)) – The data samples labeled as y

• y (object) – The label of the samples in x

• n_prototypes (int) – The number of prototypes in the initial sample

• metric_transform (MetricTransform) – The metric transformer.

• random_state (RandomState) – The random number generator.

move(o, p)

Move the current counterfactual toward the prototype

Parameters:

• o (ndarray of shape (n_timestep,)) – The current counterfactual sample

• p (ndarray of shape (n_timestep,)) – The prototype of the counterfactual label

Returns:

new_counterfactual – The new counterfactual moved towards the prototype

Return type:

ndarray of shape (n_timestep,)

abstract sample(o, random_state)

Sample an example

Parameters:

o (ndarray of shape (n_timestep,)) – The current counterfactual sample

Returns:

prototype – A prototype of the counterfactual label

Return type:

ndarray of shape (n_timestep,)

sample_move(o, random_state)

Sampla a prototype and move the counterfactual towards the prototype

Parameters:

o (ndarray of shape (n_timestep,)) – The current counterfactual sample

Returns:

new_counterfactual – The new counterfactual moved towards the prototype

Return type:

ndarray of shape (n_timestep,)

class wildboar.explain.counterfactual._proto.ShapeletPrototypeSampler(x, y, prototype_indicies, metric_transform, min_shapelet_size=0, max_shapelet_size=1)

Bases: PrototypeSampler

Sample shapelet prototypes

Sample shapelet

Parameters:

• x (ndarray of shape (n_samples, n_timestep)) – The data samples

• y (object) – The label of the samples in x

• metric_transform (MetricTransform) – The metric transformer.

• random_state (RandomState) – The random number generator.

• min_shapelet_size (float) – The minimum shapelet size

• max_shapelet_size (float) – The maximum shapelet size

move(o, p)

Move the best matching shapelet of the counterfactual sample towards the shapelet prototype

Parameters:

• o (ndarray of shape (n_timestep,)) – The counterfactual sample

• p (ndarray) – The prototype shapelet

Returns:

new_counterfactual – The new counterfactual moved towards the prototype

Return type:

ndarray of shape (n_timestep,)

sample(_o, random_state)

Sample an example

Parameters:

o (ndarray of shape (n_timestep,)) – The current counterfactual sample

Returns:

prototype – A prototype of the counterfactual label

Return type:

ndarray of shape (n_timestep,)

sample_shapelet(p, random_state)

Sample a shapelet from x

Parameters:

p (ndarray of shape (n_timestep,)) – The prototype sample

Returns:

shapelet – A shapelet

Return type:

ndarray

class wildboar.explain.counterfactual._proto.TargetEvaluator(estimator)

Bases: abc.ABC

Evaluate if a sample is a counterfactual

Construct a new evaluator

Parameters:

estimator (object) – The estimator

is_counterfactual(x, y)

Return true if x is a counterfactual of label y

Parameters:

• x (ndarray of shape (n_timestep,)) – The counterfactual sample

• y (object) – The counterfactual label

Returns:

bool

Return type:

true if counterfactual

class wildboar.explain.counterfactual._proto.UniformPrototypeSampler(x, y, prototype_indices, metric_transform)

Bases: PrototypeSampler

Sample a prototype uniformly at random from the initial prototype sample

Sample and refine counterfactuals

Parameters:

• x (ndarray of shape (n_samples, n_timestep)) – The data samples labeled as y

• y (object) – The label of the samples in x

• n_prototypes (int) – The number of prototypes in the initial sample

• metric_transform (MetricTransform) – The metric transformer.

• random_state (RandomState) – The random number generator.

sample(_o, random_state)

Sample an example

Parameters:

o (ndarray of shape (n_timestep,)) – The current counterfactual sample

Returns:

prototype – A prototype of the counterfactual label

Return type:

ndarray of shape (n_timestep,)

class wildboar.explain.counterfactual._proto.WeightedDynamicTimeWarpTransform(gamma, r=1, g=0.05)

Bases: DynamicTimeWarpTransform

Transform a sample by moving it closer using the dtw alignment matrix

Construct a new transformer

Parameters:

gamma (float) – The strength of the move, where values close to 0 means that the sample is moved less and values closer to 1 mean that the sample is moved more.