Timeseries Saliency Maps: Explaining models across multiple domains

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

Installation

Install using pip:

pip install cross-domain-saliency-maps

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.

Saliency Maps in the Frequency and ICA 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)

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