Time Interpret (tint)

This package expands the Captum library with a specific focus on time-series. As such, it includes various interpretability methods specifically designed to handle time series data.

Installation

Quick-start

First, let’s load an Arma dataset:

from tint.datasets import Arma

arma = Arma()
arma.download()  # This method generates the dataset

We then load some test data from the dataset and the corresponding true saliency:

inputs = arma.preprocess()["x"][0]
true_saliency = arma.true_saliency(dim=1)[0]

We can now load an attribution method and use it to compute the saliency:

from tint.attr import TemporalIntegratedGradients

explainer = TemporalIntegratedGradients(arma.get_white_box)

baselines = inputs * 0
attr = explainer.attribute(
    inputs,
    baselines=baselines,
    additional_forward_args=(true_saliency,),
    temporal_additional_forward_args=(True,),
).abs()

Finally, we evaluate our method using the true saliency and a white box metric:

from tint.metrics.white_box import aup

print(f"{aup(attr, true_saliency):.4}")

API

Each of the implemented interpretability methods can be found here:

tint.attr.AugmentedOcclusion(forward_func, data)

Augmented Occlusion by sampling the baseline from a bootstrapped distribution.

tint.attr.BayesKernelShap(forward_func[, ...])

Bayesian version of KernelShap.

tint.attr.BayesLime(forward_func[, ...])

Bayesian version of Lime.

tint.attr.DiscretetizedIntegratedGradients(...)

Discretetized Integrated Gradients.

tint.attr.DynaMask(forward_func)

Dynamic masks.

tint.attr.ExtremalMask(forward_func)

Extremal masks.

tint.attr.FeatureAblation(forward_func)

Feature ablation.

tint.attr.Fit(forward_func[, generator, ...])

Feature Importance in Time.

tint.attr.GeodesicIntegratedGradients(...[, ...])

Geodesic Integrated Gradients.

tint.attr.LofKernelShap(forward_func, embeddings)

Local Outlier Factor Kernel Shap.

tint.attr.LofLime(forward_func, embeddings)

Local Outlier Factor Lime.

tint.attr.NonLinearitiesTunnel(...)

Replace non linearities (or any module) with others before running an attribution method.

tint.attr.Occlusion(forward_func)

A perturbation based approach to compute attribution, involving replacing each contiguous rectangular region with a given baseline / reference, and computing the difference in output.

tint.attr.Retain([forward_func, retain, ...])

Retain explainer method.

tint.attr.SequentialIntegratedGradients(...)

Sequential Integrated Gradients.

tint.attr.TemporalAugmentedOcclusion(...[, ...])

Temporal Augmented Occlusion.

tint.attr.TemporalIntegratedGradients(...[, ...])

Temporal Integrated Gradients.

tint.attr.TemporalOcclusion(forward_func)

Temporal Occlusion.

tint.attr.TimeForwardTunnel(attribution_method)

Time Forward Tunnel.

Some of these attributions use specific models which are listed here:

tint.attr.models.BLRRegression(**kwargs)

tint.attr.models.BLRRidge(**kwargs)

tint.attr.models.ExtremalMaskNet(forward_func)

Extremal mask model as a Pytorch Lightning model.

tint.attr.models.JointFeatureGeneratorNet([...])

Conditional generator model to predict future observations as a Pytorch Lightning module.

tint.attr.models.MaskNet(forward_func[, ...])

Mask network as a Pytorch Lightning module.

tint.attr.models.RetainNet([dim_emb, ...])

Retain Network as a Pytorch Lightning module.

tint.attr.models.scale_inputs(input_ids, ...)

Creates a monotonic path between input_ids and ref_input_ids (the baseline).

In addition, tint also provides some time series datasets which have been used as benchmark in recent publications. These datasets are listed here:

tint.datasets.Arma([times, features, ...])

Arma dataset.

tint.datasets.BioBank([label, discretised, ...])

BioBank dataset.

tint.datasets.Hawkes([mu, alpha, decay, ...])

Hawkes dataset.

tint.datasets.HMM([n_signal, n_state, ...])

2-state Hidden Markov Model as described in the DynaMask paper.

tint.datasets.Mimic3([task, data_dir, ...])

MIMIC-III dataset.

We also provide some metrics to evaluate different attribution methods. These metrics differ depending on if the true saliency is known:

tint.metrics.accuracy(forward_func, inputs, ...)

Accuracy metric.

tint.metrics.comprehensiveness(forward_func, ...)

Comprehensiveness metric.

tint.metrics.cross_entropy(forward_func, ...)

Cross-entropy metric.

tint.metrics.lipschitz_max(explanation_func, ...)

Lipschitz Max as a stability metric.

tint.metrics.log_odds(forward_func, inputs, ...)

Log-odds metric.

tint.metrics.mae(forward_func, inputs, ...)

Mean absolute error.

tint.metrics.mse(forward_func, inputs, ...)

Mean square error.

tint.metrics.sufficiency(forward_func, ...)

Sufficiency metric.

tint.metrics.white_box.aup(attributions, ...)

Area under precision.

tint.metrics.white_box.auprc(attributions, ...)

Area under precision-recall.

tint.metrics.white_box.aur(attributions, ...)

Area under recall.

tint.metrics.white_box.entropy(attributions, ...)

Entropy measure of the attributions over the true_attributions.

tint.metrics.white_box.information(...[, ...])

Information measure of the attributions over the true_attributions.

tint.metrics.white_box.mae(attributions, ...)

Mean absolute error.

tint.metrics.white_box.mse(attributions, ...)

Mean squared error.

tint.metrics.white_box.rmse(attributions, ...)

Root mean squared error.

tint.metrics.white_box.roc_auc(attributions, ...)

Roc auc score.

Finally, a few general deep learning models, as well as a network to be used along with the Pytorch Lightning framework. These models can easily be used and trained with this framework.

tint.models.Bert([...])

Get Bert model for sentence classification, either as a pre-trained model or from scratch.

tint.models.DistilBert([...])

Get DistilBert model for sentence classification, either as a pre-trained model or from scratch.

tint.models.CNN(units, kernel_size[, ...])

Base CNN class.

tint.models.MLP(units[, bias, dropout, ...])

Base MLP class.

tint.models.Net(layers[, loss, optim, lr, ...])

Base Net class.

tint.models.RNN(input_size[, rnn, ...])

A base recurrent model class.

tint.models.Roberta([...])

Get Roberta model for sentence classification, either as a pre-trained model or from scratch.

tint.models.TransformerEncoder(d_model[, ...])

A base transformer encoder model class.

More details about each of these categories can be found here: