wildboar.explain

Explanation methods for classifiers and regressors.

Classes

AmplitudeImportance	Compute the importance of equi-probable amplitude intervals.
FrequencyImportance	Explainer to evaluate feature importance based on frequency bands.
IntervalImportance	Interval importance for time series.
ShapeletImportance	Compute the importance of shapelets.

Functions

plot_importances(importances[, ax, labels])

Plot the importances as a boxplot.

class wildboar.explain.AmplitudeImportance(scoring=None, n_intervals='sqrt', window=None, binning='normal', n_bins=4, n_repeat=1, random_state=None)

Compute the importance of equi-probable amplitude intervals.

The implementation uses transform.SAX to discretize the time series and then for each bin permute the samples along that bin.

fit_explain(estimator, x=None, y=None, **kwargs)

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.

**kwargsdict, optional

Optional extra arguments.

Returns:

ndarray

The explanation.

get_metadata_routing()

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)

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, n_samples=100, scoring=None, preprocess=True, k=None, show_bins=False, show_grid=True)

Plot the importances.

If x is given, the importances are plotted over the samples optionally labeling each sample using the supplied labels. If x is not give, the importances are plotted as one or more boxplots.

Parameters:

xarray-like of shape (n_samples, n_timesteps), optional

The samples.

yarray-like of shape (n_samples, ), optional

The labels.

axAxes, optional

Axes to plot. If ax is set, x is None and scoring is None, the number of axes must be the same as the number of scorers.

n_samplesint or float, optional

The number of samples to plot, set to None to plot all.

scoringstr, optional

The scoring to plot if multiple scorers were used when fitting.

preprocessbool, optional

Preprocess the time series to align with the bins, ignored if x is not None.

kint or float, optional

The number of top bins to plot, ignored if x is not None.

• if int, the specified number of bins are shown

• if float, a fraction of the number of bins are shown.

show_binsbool, optional

Annotate the plot with the index of the bin, ignored if x is not None.

show_gridbool, optional

Annotate the plot with the bin thresholds, ignored if x is not None.

Returns:

axAxis

The axis.

mappableScalarMappable, optional

Return the mappable used to plot the colorbar. Only returned if ax is not None and x is not None.

set_params(**params)

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.FrequencyImportance(scoring=None, n_repeat=5, random_state=None, n_bands=10, spectrum='amplitude', growth_factor=np.e)

Explainer to evaluate feature importance based on frequency bands.

This class implements a frequency-based importance measure by permuting values within frequency bands obtained from the Fourier transform of time series data. It extends PermuteImportance to analyze the impact of different frequency components on model predictions.

Parameters:

scoringstr, callable, or None, optional

Scoring metric to evaluate importance. If None, uses estimator’s score method.

n_repeatint, optional

Number of times to permute each frequency band.

random_stateint, RandomState instance or None, optional

Controls randomization for permutations.

n_bandsint, optional

Number of frequency bands to analyze.

spectrum{“amplitude”, “phase”}, optional

Whether to permute amplitude components or to permute phase components.

growth_factorfloat, optional

Controls growth of frequency band sizes: - growth_factor > 1: exponential growth (more detail at lower frequencies) - growth_factor = 1: linear growth (equal-sized bands) - growth_factor < 1: logarithmic decay (more detail at higher frequencies)

Defaults to np.e.

Attributes:

components_list of tuples

The frequency bands used for permutation, as (start, end) indices.

importances_ImportanceContainer

Contains the calculated feature importance scores.

n_timesteps_in_int

Number of timesteps in the input data.

See also

PermuteImportance

Base class for permutation-based importance.

Notes

The frequency bands are constructed by dividing the frequency domain into windows, with the size of each window controlled by the growth_factor parameter. This allows for analyzing different scales of temporal patterns in the data.

fit_explain(estimator, x=None, y=None, **kwargs)

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.

**kwargsdict, optional

Optional extra arguments.

Returns:

ndarray

The explanation.

get_metadata_routing()

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)

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, k=None, sample_spacing=1, jitter=False)

Plot the explanation.

Parameters:

xarray-like, optional

Optional imput samples.

yarray-like, optional

Optional target labels.

axAxes, optional

Optional axes to plot to.

Returns:

Axes

The axes object.

set_params(**params)

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.IntervalImportance(*, scoring=None, n_repeat=5, n_intervals='sqrt', window=None, random_state=None)

Interval importance for time series.

Parameters:

scoringstr, list, dict or callable, optional

The scoring function. By default the estimators score function is used.

n_repeatint, optional

The number of repeated permutations.

n_intervalsstr, optional

The number of intervals.

• if “sqrt”, the number of intervals is the square root of n_timestep.

• if “log2”, the number of intervals is the log2 of n_timestep.

• if int, exact number of intervals.

windowint, optional

The window size. If specicied, n_intervals is ignored and the number of intervals is computed such that each interval is (at least) of size window.

random_stateint or RandomState

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

Attributes:

importances_dict or Importance

The importance scores for each interval. If dict, one value per scoring function.

components_ndarray of shape (n_intervals, 2)

The interval start and end positions.

fit_explain(estimator, x=None, y=None, **kwargs)

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.

**kwargsdict, optional

Optional extra arguments.

Returns:

ndarray

The explanation.

get_metadata_routing()

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)

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, scoring=None, k=None, n_samples=100, show_grid=True)

Plot the explanation.

Parameters:

xarray-like, optional

Optional imput samples.

yarray-like, optional

Optional target labels.

axAxes, optional

Optional axes to plot to.

Returns:

Axes

The axes object.

set_params(**params)

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.ShapeletImportance(scoring=None, n_repeat=1, n_shapelets=10, min_shapelet_size=0.0, max_shapelet_size=1.0, coverage_probability=None, variability=1, metric='euclidean', metric_params=None, random_state=None)

Compute the importance of shapelets.

The importance is given by permuting time series sections with the minimum distance to shapelets.

Parameters:

scoringstr, list, dict or callable, optional

The scoring function. By default the estimators score function is used.

n_repeatint, optional

The number of repeated permutations.

n_shapeletsint, optional

The number of shapelets to sample for the explanation.

min_shapelet_sizefloat, optional

The minimum size of shapelets used for explanation.

max_shapelet_sizefloat, optional

The maximum size of shapelets used for explanation.

coverage_probabilityfloat, optional

The probability that a time step is covered by a shapelet, in the range 0 < coverage_probability <= 1.

• For larger coverage_probability, we get larger shapelets.

• For smaller coverage_probability, we get shorter shapelets.

variabilityfloat, optional

Controls the shape of the Beta distribution used to sample shapelets. Defaults to 1.

• Higher variability creates more uniform intervals.

• Lower variability creates more variable intervals sizes.

metricstr, optional

The metric.

metric_paramsstr, optional

The metric parameters.

random_stateint or RandomState, optional

Controls the random resampling of the original dataset.

• If int, random_state is the seed used by the random number generator.

• If numpy.random.RandomState instance, random_state is the random number generator.

• If None, the random number generator is the numpy.random.RandomState instance used by numpy.random.

Attributes:

componentsndarray

The shapelets

fit_explain(estimator, x=None, y=None, **kwargs)

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.

**kwargsdict, optional

Optional extra arguments.

Returns:

ndarray

The explanation.

get_metadata_routing()

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)

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, k=None, scoring=None, kernel_scale=0.25, ax=None)

Plot the explanation.

Parameters:

xarray-like, optional

Optional imput samples.

yarray-like, optional

Optional target labels.

axAxes, optional

Optional axes to plot to.

Returns:

Axes

The axes object.

set_params(**params)

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.plot_importances(importances, ax=None, labels=None)

Plot the importances as a boxplot.

Parameters:

importancesImportance or dict

The importances.

axAxes, optional

The axes to plot. If importances is dict, ax must contain at least len(importances) Axes objects.

labelsarray-like, optional

The labels for the importances.

Returns:

Axes

The plotted Axes.