Metadata-Version: 2.1
Name: time_interpret
Version: 0.3.0
Summary: Model interpretability library for PyTorch with a focus on time series.
Keywords: deep-learning,pytorch,captum,explainable-ai,time-series
Author-email: Joseph Enguehard <joseph@skippr.com>
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Dist: captum
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pytorch-lightning
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: torch
Requires-Dist: captum ; extra == "full"
Requires-Dist: numpy ; extra == "full"
Requires-Dist: pandas ; extra == "full"
Requires-Dist: pytorch-lightning ; extra == "full"
Requires-Dist: scikit-learn ; extra == "full"
Requires-Dist: scipy ; extra == "full"
Requires-Dist: torch ; extra == "full"
Requires-Dist: fasttext ; extra == "full"
Requires-Dist: google ; extra == "full"
Requires-Dist: jupyter ; extra == "full"
Requires-Dist: optuna ; extra == "full"
Requires-Dist: pandarallel ; extra == "full"
Requires-Dist: psycopg2 ; extra == "full"
Requires-Dist: scikit-image ; extra == "full"
Requires-Dist: statsmodels ; extra == "full"
Requires-Dist: tick ; extra == "full"
Requires-Dist: torchmetrics ; extra == "full"
Requires-Dist: torchvision ; extra == "full"
Requires-Dist: tqdm ; extra == "full"
Requires-Dist: transformers ; extra == "full"
Requires-Dist: huggingface_hub ; extra == "full"
Requires-Dist: pytest ; extra == "full"
Requires-Dist: pytest-cov ; extra == "full"
Requires-Dist: pytest-mock ; extra == "full"
Requires-Dist: fasttext ; extra == "graphgym"
Requires-Dist: google ; extra == "graphgym"
Requires-Dist: jupyter ; extra == "graphgym"
Requires-Dist: optuna ; extra == "graphgym"
Requires-Dist: pandarallel ; extra == "graphgym"
Requires-Dist: psycopg2 ; extra == "graphgym"
Requires-Dist: scikit-image ; extra == "graphgym"
Requires-Dist: statsmodels ; extra == "graphgym"
Requires-Dist: tick ; extra == "graphgym"
Requires-Dist: torchmetrics ; extra == "graphgym"
Requires-Dist: torchvision ; extra == "graphgym"
Requires-Dist: tqdm ; extra == "graphgym"
Requires-Dist: transformers ; extra == "graphgym"
Requires-Dist: huggingface_hub ; extra == "modelhub"
Requires-Dist: pytest ; extra == "test"
Requires-Dist: pytest-cov ; extra == "test"
Requires-Dist: pytest-mock ; extra == "test"
Project-URL: documentation, https://josephenguehard.github.io/time_interpret
Project-URL: homepage, https://github.com/josephenguehard/time_interpret
Provides-Extra: full
Provides-Extra: graphgym
Provides-Extra: modelhub
Provides-Extra: test

# Time Interpret (tint)

This library expands the [captum library](https://captum.ai) with a specific 
focus on time series. For more details, please see the documentation and our [paper](https://arxiv.org/abs/2306.02968).


## Install

Time Interpret can be installed with pip:

```shell script
pip install time_interpret
```

Please see the documentation for alternative installation modes.


## Quick-start

First, let's load an Arma dataset:

```python
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:

```python
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:

```python
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:

```python
from tint.metrics.white_box import aup

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

## Methods

- [AugmentedOcclusion](https://arxiv.org/abs/2003.02821)
- [BayesKernelShap](https://arxiv.org/abs/2008.05030)
- [BayesLime](https://arxiv.org/abs/2008.05030)
- [Discretized Integrated Gradients](https://arxiv.org/abs/2108.13654)
- [DynaMask](https://arxiv.org/abs/2106.05303)
- [ExtremalMask](https://arxiv.org/abs/2305.18840)
- [Fit](https://arxiv.org/abs/2003.02821)
- [LofKernelShap](https://arxiv.org/abs/2306.02968)
- [LofLime](https://arxiv.org/abs/2306.02968)
- [Non-linearities Tunnel](https://arxiv.org/abs/1906.07983)
- [Occlusion](https://arxiv.org/abs/1311.2901)
- [Retain](https://arxiv.org/abs/1608.05745)
- [SequentialIntegratedGradients](https://arxiv.org/abs/2305.15853)
- [TemporalAugmentedOcclusion](https://arxiv.org/abs/2003.02821)
- [TemporalOcclusion](https://arxiv.org/abs/2003.02821)
- [TemporalIntegratedGradients](https://arxiv.org/abs/2306.02968)
- [TimeForwardTunnel](https://arxiv.org/abs/2306.02968)

This package also provides several datasets, models and metrics. Please refer to the documentation for more details.


## Paper: Learning Perturbations to Explain Time Series Predictions

The experiments for the paper: [Learning Perturbations to Explain Time Series Predictions](https://arxiv.org/abs/2305.18840) 
can be found on these folders:
- [HMM](experiments/hmm)
- [Mimic3](experiments/mimic3/mortality)


## Paper: Sequential Integrated Gradients: a simple but effective method for explaining language models

The experiments for the paper: 
[Sequential Integrated Gradients: a simple but effective method for explaining language models](https://arxiv.org/abs/2305.15853) 
can be found on the [NLP](experiments/nlp) section of the experiments.


## TSInterpret

More methods to interpret predictions of time series classifiers have been grouped 
into [TSInterpret](https://github.com/fzi-forschungszentrum-informatik/TSInterpret), another library with a specific 
focus on time series.
We developed Time Interpret concurrently, not being aware of this library at the time.


## Acknowledgment
- [Jonathan Crabbe](https://github.com/JonathanCrabbe/Dynamask) for the DynaMask implementation.
- [Sana Tonekaboni](https://github.com/sanatonek/time_series_explainability/tree/master/TSX) for the fit implementation.
- [INK Lab](https://github.com/INK-USC/DIG) for the discretized integrated gradients' implementation.
- [Dylan Slack](https://github.com/dylan-slack/Modeling-Uncertainty-Local-Explainability) for the BayesLime and BayesShap implementations.
