cross-domain-saliency-maps 0.0.8

Pytorch/Tensorflow package for generating saliency maps for time-series models using Cross-Domain Integrated Gradients.

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.

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
2. Tensorflow getting started
3. What does your model see in your EEG? (with MNE)
4. Explaining time-series forecasts (with skforecast)

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) transformations are already implemented and can be directly deployed. Additionally, the libraryprovides the flexibility of defining new transformations.

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. The domain is defined by ICADomain. Before generating the map a FastICA needs to be fitted to the input sample (see example). 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, pytorch).

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, pytorch).

Reference

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}
}