TSInterpret

TSInterpret provides several algorithms for time series interpretability, categorized by their method type (InstanceBased or FeatureAttribution), data compatibility (univariate or multivariate), and backend requirements.

Algorithm Comparison Table

Legend:

• BB: black-box
• TF: TensorFlow
• PYT: PyTorch
• SK: scikit-learn
• uni: univariate time series
• multi: multivariate time series
• y: yes (requires training set)
• n: no (does not require training set)

TSInterpret categorizes explanation methods based on three main criteria to help you choose the right tool for your time series model:

1. Post-Hoc vs. Instinct

• Instinct Interpretability: Models that are interpretable by design (e.g., through constrained complexity or built-in explanation components).
• Post-Hoc Interpretability: Methods applied to a model after it has been trained. These are typically decoupled from the model itself.

2. Model-Specific vs. Model-Agnostic

• Model-Specific: Methods limited to specific model classes. These often require access to model internals, such as Gradients.
• Model-Agnostic: Methods that can be applied to any model by analyzing the relationship between inputs and outputs without accessing internal functions.

3. Results of Explanation Methods

Depending on the insight you need, you can use different types of methods:

• Feature Attribution (FA): Returns a score for each feature indicating its contribution to the model's output.
• Instance-based (IB): Identifies a subset of relevant features that must be present to maintain or change a prediction.
• Surrogate Models: Trains a simpler, inherently interpretable model to approximate the complex model's behavior.

TSInterpret implements the following specific algorithms with these characteristics:

• NUN-CF: Generates counterfactuals using a native guide selected via K-nearest neighbor. It offers three options: the native guide, the native guide with bary centering, and counterfactuals based on the native guide and class activation mapping.
• COMTE: A heuristic perturbation approach for multivariate time series counterfactuals. It aims to change a small number of features to obtain a counterfactual.
• LEFTIST: An agnostic local explanation method adapted from LIME. It uses prefixed shapelets (defined by length and position) as interpretable components to provide feature importance.
• SETS: Generates counterfactuals by perturbing previously extracted shapelets back into the original time series being explained.
• TSEvo: An evolution-based counterfactual generation method for both univariate and multivariate time series. It uses a multi-objective problem and multiple perturbation methods (Gaussian, frequency, and dataset-based) to account for different time series properties.
• TSR (Temporal Saliency Rescaling): Calculates importance for each timestep, followed by feature importance using various Saliency Methods (both Back-propagation and perturbation based). The implementation leverages tf-explain, shap, and captum.

This example demonstrates how to use the TSR (Temporal Saliency Rescaling) interpretability model to explain a TensorFlow-based time series classifier using Integrated Gradients (IG) in time mode.

Note: The example assumes you have a trained model and a dataset (like BasicMotions from tslearn).

from TSInterpret.InterpretabilityModels.Saliency.TSR import TSR
import numpy as np
import tensorflow as tf

# 1. Setup model and data (Conceptual steps)
# model_to_explain = tf.keras.models.load_model(PATH_TO_YOUR_CLASSIFICATION_MODEL)
# train_x, train_y, test_x, test_y = ... (loaded via tslearn)

# 2. Initialize the interpretability model
# Arguments: model, input_dim_1 (time steps), input_dim_2 (features), method, mode
int_mod = TSR(model_to_explain, train_x.shape[-2], train_x.shape[-1], method='IG', mode='time')

# 3. Prepare a single sample and its label for explanation
item = np.array([test_x[0,:,:]])
label = int(np.argmax(test_y[0]))

# 4. Generate explanation
# TSR=True enables Temporal Saliency Rescaling
exp = int_mod.explain(item, labels=label, TSR=True)

# 5. Visualize the results
%matplotlib inline  
int_mod.plot(np.array([test_x[0,:,:]]), exp)

TSInterpret follows a pattern inspired by scikit-learn, consisting of three distinct steps: Initialize, Explain, and Plot.

Note that input and output details vary depending on the specific algorithm used. The following example demonstrates the workflow using the NativeGuideCF method.

1. Import the desired explainer class.
2. Initialize the explainer by passing the model (or a prediction function), data shapes, training data, and method-specific arguments.
3. Explain a specific test instance to retrieve the explanation and labels.
4. Plot the results to visualize the explanation.

from TSInterpret.InterpretabilityModels.counterfactual.NativeGuideCF import NativeGuideCF

# 1. Initialize
exp_model = NativeGuideCF(model, shape, (train_x, train_y), backend='PYT', mode='feat', method='dtw_bary_center')

# 2. Explain
exp, label = exp_model.explain(item, np.argmax(y_target, axis=1))

# 3. Plot
exp_model.plot(item, np.argmax(y_target, axis=1)[0], exp, label)