Metadata-Version: 2.4
Name: cross_domain_saliency_maps
Version: 0.0.8
Summary: Pytorch/Tensorflow package for generating saliency maps for time-series models using Cross-Domain Integrated Gradients.
Project-URL: Homepage, https://github.com/esl-epfl/cross-domain-saliency-maps
Author-email: Christodoulos Kechris <christodoulos.kechris@epfl.ch>
License-File: LICENSE
Keywords: explainable-ai,interpretability,pytorch,saliency-maps,tensorflow,time-series,xai
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10.16
Requires-Dist: tqdm==4.67.1
Provides-Extra: all
Requires-Dist: captum<1.0,>=0.9.0; extra == 'all'
Requires-Dist: pytest; extra == 'all'
Requires-Dist: tensorflow<=2.19,>=2.13.0; extra == 'all'
Requires-Dist: torch<=2.7,>=2.6.0; extra == 'all'
Provides-Extra: captum
Requires-Dist: captum<1.0,>=0.9.0; extra == 'captum'
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Provides-Extra: tensorflow
Requires-Dist: tensorflow<=2.19,>=2.13.0; extra == 'tensorflow'
Provides-Extra: torch
Requires-Dist: torch<=2.7,>=2.6.0; extra == 'torch'
Description-Content-Type: text/markdown

# Timeseries Saliency Maps: Explaining models across multiple domains

Official Pytorch/Captum/Tensorflow implementation of Cross-Domain Saliency Maps.
The method does not require any model model retraining or modications.

[![arXiv](https://img.shields.io/badge/arXiv-2505.13100-b31b1b.svg)](https://arxiv.org/abs/2505.13100)

<img src="https://raw.githubusercontent.com/esl-epfl/cross-domain-saliency-maps/main/figures/cross_domain_saliency_maps_banner.svg" width="755">

# Installation

## Captum
Install using ```pip```:
```
pip install cross-domain-saliency-maps[captum]
```

## Torch
Install using ```pip```:
```
pip install cross-domain-saliency-maps[torch]
```

## Tensorflow
Install using ```pip```:
```
pip install cross-domain-saliency-maps[tensorflow]
```

## All
Install using ```pip```:
```
pip install cross-domain-saliency-maps[all]
```

# Examples
Get started with our PyTorch/TensorFlow examples (one-click run)
1. [Pytorch getting started](./examples/torch_demo.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/esl-epfl/cross-domain-saliency-maps/blob/main/examples/torch_demo.ipynb)
2. [Tensorflow getting started](./examples/tensorflow_demo.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/esl-epfl/cross-domain-saliency-maps/blob/main/examples/tensorflow_demo.ipynb)
3. [What does your model see in your EEG?](./examples/seizure_detection.ipynb) ([with MNE](https://mne.tools/stable/index.html)) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/esl-epfl/cross-domain-saliency-maps/blob/main/examples/seizure_detection.ipynb)
4. [Explaining time-series forecasts](./examples/forecast_saliency_maps_skforecast.ipynb) ([with skforecast](https://skforecast.org/0.17.0/index.html)) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/esl-epfl/cross-domain-saliency-maps/blob/main/examples/forecast_saliency_maps_skforecast.ipynb)

# Usage
The library supports generating saliency maps for any domain which
can be formulated as an invertible transformation with a differentiable
inverse transformation. 

To generate maps expressed in a domain, a corresponding ```Domain```
object needs to be defined. This describes the operations performed
during the forward and inverse transformations. 

Implementations for the [Frequency and Independent Component Analysis (ICA)](#saliency-maps-in-the-frequency-and-ica-domains)
transformations are already implemented and can be directly deployed. 
Additionally, the libraryprovides the flexibility of 
[defining new transformations](#saliency-maps-in-any-domain).

## Plug-and-play implemented domains
The following domains are already implemented and can be
directly used to generate saliency maps:

1. **Time Domain.** This is the original Integrated Gradients,
expressing saliency maps in the raw input domain (time). The
corresponding ```Domain``` object is ```TimeDomain```. The map
can be directly generated:
```timeIG = TimeIG(model, n_iterations, output_channel = 0)``` 

2. **Frequency Domain.** Each point in the map corresponds to
the importance of the corresponding frquency component. The 
Fourier transform is used to transform the time-domain to 
the frequency domain. The corresponding ```Domain``` object
is ```FourierDomain```. The map can be directly generated:
```fourierIG = FourierIG(model, n_iterations, output_channel = 0)``` 

3. **Independent Component Domain.** Each point in the 
map corresponds to an independent component (IC) of the ICA
decomposition. Any ICA implementation can be used as long as it
complies with [```sklearn.decomposition.FastICA```](https://scikit-learn.org/stable/modules/generated/sklearn.decomposition.FastICA.html). The domain is defined 
by ```ICADomain```. Before generating the map a ```FastICA```
needs to be fitted to the input sample (see [example](./examples/tensorflow_demo.ipynb)). The map can be directly generated:
``` icaIG = ICAIG(model, fastICA, n_iterations, output_channel = 0)``` 

4. **Short-Time Fouerier Transform (STFT) Domain**. Each point in 
the saliency map corresponds to the importance of the corresponding
time-frequency bin. The short-time fourier transform is used to 
transform the time-domain the time-frequency domain. The corresponding
```Domain``` is ```STFTDomain```. The map can be directly generated:
```stftIG = STFTIG(model, n_iterations, n_fft, hop_length, win_length,output_channel = 0)```

5. **Complex-Cepstrum Domain**. Each point in the map corresponds to
the importance of the corresponding Cepstrum bin. The Complex Cepstrum 
transform is formulated as ```C = ifft(log(fft(X)))```. The corresponding 
```Domain``` is ```ComplexCepstrumDomain```. The map can be directly
generated: 
```ccIG = ComplexCepstrumIG(model, n_iterations, output_channel = 0)```

6. **Haar-DWT Domain**. Each point in the map corresponds to the 
importance of a DWT decomposition level. We use the Haar decomposition.
The ```Domain``` is ```HaarDWTLevelsDomain```. The map can be directly 
generated:
```dwtIG = DWTIG(model, n_iterations, output_channel = 0, levels = 6)```

## Saliency Maps in any domain
The library supports extending the Cross-domain Integrated Gradients
for any invertible domain with a differentiable inverse transform. This
requires:
1. Creating the propert ```Domain``` object describing the corresponding
transform. ```Domain``` objects need to inherit from ```DomainBase``` and
implement the required functions. More details can be found in the 
implementation of the ```FourierDomain``` and ```ICADomain``` (
[tensorflow](/src/cross_domain_saliency_maps/tensorflow_ig/domain_transforms.py), [pytorch](/src/cross_domain_saliency_maps/torch_ig/domain_transforms.py)).

2. Calling ```CrossDomainIG``` with the new domain as the input. This
can be done either by creating a ```CrossDomainIG```, initializing it
with the new domain, or by implementing a new dedicated class inheriting
```CrossDomainIG```. For more details check the implementations of 
```FourierIG``` and ```ICAIG```(
[tensorflow](/src/cross_domain_saliency_maps/tensorflow_ig/cross_domain_integrated_gradients.py), [pytorch](/src/cross_domain_saliency_maps/torch_ig/cross_domain_integrated_gradients.py)).

# Reference
**BibTeX**
```bibtex
@article{kechris2025time,
  title={Time series saliency maps: Explaining models across multiple domains},
  author={Kechris, Christodoulos and Dan, Jonathan and Atienza, David},
  journal={arXiv preprint arXiv:2505.13100},
  year={2025}
}