cross-domain-saliency-maps 0.0.4__py3-none-any.whl

cross_domain_saliency_maps/torch_ig/domain_transforms.py

@@ -0,0 +1,208 @@
+import abc
+import torch
+import numpy as np
+
+class DomainBase:
+    """ Defines the base class for a domain transformation.
+
+    Attributes:
+        device (torch.device): The device used to run the model.
+        coefficients (tf.Tensor): The input samples expressed
+            in the target domain. 
+        baseline_coefficients (tf.Tensor): The baseline samples expressed
+            in the target domain. 
+        dtype: The dtype of the coefficients when they are 
+            converted to tf.Tensor.
+    """
+    def __init__(self, device: torch.device, dtype = torch.float32):
+        """ Initialize the Domain.
+        """
+        self.device = device
+        self.dtype = dtype
+        self.coefficients = None
+        self.baseline_coefficients = None
+            
+    def get_coefficients(self):
+        """ Return the coeffcients.
+        """
+        return self.coefficients
+    
+    def get_coefficient_baseline(self):
+        """ Return the baseline coefficients.
+        """
+        return self.baseline_coefficients
+
+    @abc.abstractmethod
+    def set_coefficients(self, x, x_baseline):
+        """ Sets the coefficients depending on the transform
+        used. Should be implemented by class inheriting DomainBase.
+
+        Args:
+            x (np.array): The input sample.
+            x_baseline (np.array): The baseline sample.
+        """
+        return
+    
+    @abc.abstractmethod
+    def forward_transform(self, x):
+        """ Performs the forward transform, transforming the input
+        sample x into the corresponding target domain.
+
+        Args:
+            x : The input sample
+        """
+        return
+    
+    @abc.abstractmethod
+    def inverse_transform(self, x_input):
+        """ Performs the inverse transform, transforming the
+        sample x from the target domain back to the original one.
+
+        Args:
+            x_input : The input sample
+        """
+        return
+
+class FourierDomain(DomainBase):
+    """ Domain implementation for the Fourier transform, mapping 
+    time-domain samples into the frequency domain.
+    """
+    def __init__(self, device, dtype = torch.float32, time_dimension = -1):
+        """ Initialize the Fourier Domain.
+
+        Args:
+            dtype: The type of the input features. 
+            time_dimension: The dimension in the input which 
+                corresponds to the time-points.
+        """
+        super().__init__(device = device, dtype = dtype)
+        self.time_dimension = time_dimension
+    
+    def forward_transform(self, x: torch.Tensor):
+        """ Implementation of the forward transform, transforming the input
+        time sample to the corresponding frequency domain sample. 
+
+        Args:
+            x (tf.Tensor): Input time-domain sample.
+        """
+        return torch.fft.fft(x.type(torch.complex64), dim = self.time_dimension)
+      
+    def set_coefficients(self, x: np.array, x_baseline: np.array):
+        """ Sets the frequency coefficients transforming the input and
+        baseline samples into the frequency domain.
+
+        Args:
+            x (np.array): The input sample in time-domain.
+            x_baseline (np.array): The baseline sample in time-domain.
+        """
+        x_tf = torch.from_numpy(x).type(self.dtype).to(self.device)
+        x_baseline_tf = torch.from_numpy(x_baseline).type(self.dtype).to(self.device)
+
+        self.coefficients = self.forward_transform(x_tf)
+        self.baseline_coefficients = self.forward_transform(x_baseline_tf)
+    
+    def inverse_transform(self, x_input: torch.Tensor):
+        """ Inverse transform, transforming the frequency domain input
+        x_input points back into the time domain.
+
+        Args:
+            x_input (tf.Tensor): The frequency domain input.
+        """
+        return torch.fft.ifft(x_input, dim = self.time_dimension).to(torch.float32)
+
+class ICADomain(DomainBase):
+    """ Implements the Domain for the Independent Component Analysis 
+    (ICA) decomposition.
+
+    We consider the independent channels to form the basis of 
+    the input. The mixing matrix forms the actual input coefficients. 
+    This way, ICA IG expresses significance of each independent component.
+
+    """
+    def __init__(self, device, ica, dtype = torch.float32, channel_permutation = (0, 2, 1)):
+        super().__init__(device = device, dtype = dtype)
+        self.channel_permutation = channel_permutation
+        self.ica = ica
+    
+    def forward_transform(self, x: np.array):
+        """ Forward transform, transforms the input channels into 
+        independent channels.
+
+        Args:
+            x (np.array): Input sample
+        """
+        X = self.ica.transform(x)
+        return X
+    
+    def set_coefficients(self, x:np.array, x_baseline: np.array):
+        """ Sets the coefficients in the ICA space. We consider the 
+        independent channels to form the basis of the input. The 
+        mixing matrix forms the actual input coefficients. This way
+        ICA IG expresses significance of each independent component.
+
+        Since the basis of the transform are the independent components,
+        we only consider zero baseline.
+
+        Args:
+            x (np.array): Input sample of size [1, n_time_points, n_channels]
+        """
+
+        self.basis = torch.from_numpy(self.forward_transform(x[0, ...].T)).type(self.dtype).to(self.device)
+
+        self.coefficients = torch.from_numpy(self.ica.mixing_.T).type(self.dtype).to(self.device)[None, ...]
+        self.baseline_coefficients = torch.zeros_like(self.coefficients)
+        self.mean = torch.from_numpy(self.ica.mean_).type(self.dtype).to(self.device)
+    
+    def inverse_transform(self, x_input: torch.Tensor):
+        """ Inverses the ICA transform given an input matrix 
+        x_input and the basis stored in the domain. 
+
+        Args:
+            x_input (torch.Tensor): Input unmixing matrix of size [n_channels, n_channels].
+        """
+        return torch.transpose(torch.matmul(self.basis, x_input) + self.mean, 1, 2)
+
+class TimeDomain(DomainBase):
+    """ Domain implementation for the Time transform. This is the original input domain,
+        no transform takes place.
+    """
+    def __init__(self, device, dtype = torch.float32, time_dimension = -1):
+        """ Initialize the Fourier Domain.
+
+        Args:
+            dtype: The type of the input features. 
+            time_dimension: The dimension in the input which 
+                corresponds to the time-points.
+        """
+        super().__init__(device = device, dtype = dtype)
+        self.time_dimension = time_dimension
+    
+    def forward_transform(self, x: torch.Tensor):
+        """ Implementation of the forward transform. No transform takes place. 
+
+        Args:
+            x (tf.Tensor): Input time-domain sample.
+        """
+        return x
+      
+    def set_coefficients(self, x: np.array, x_baseline: np.array):
+        """ Sets the frequency coefficients transforming the input and
+        baseline samples into the frequency domain.
+
+        Args:
+            x (np.array): The input sample in time-domain.
+            x_baseline (np.array): The baseline sample in time-domain.
+        """
+        x_tf = torch.from_numpy(x).type(self.dtype).to(self.device)
+        x_baseline_tf = torch.from_numpy(x_baseline).type(self.dtype).to(self.device)
+
+        self.coefficients = self.forward_transform(x_tf)
+        self.baseline_coefficients = self.forward_transform(x_baseline_tf)
+    
+    def inverse_transform(self, x_input: torch.Tensor):
+        """ Inverse transform.
+
+        Args:
+            x_input (tf.Tensor): The frequency domain input.
+        """
+        return x_input

cross_domain_saliency_maps-0.0.4.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: cross_domain_saliency_maps
+Version: 0.0.4
+Summary: A pytorch/tensorflow library for generating Cross-Domain saliency maps.
+Project-URL: Homepage, https://github.com/esl-epfl/cross-domain-saliency-maps
+Author-email: Christodoulos Kechris <christodoulos.kechris@epfl.ch>
+License-File: LICENSE
+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: tensorflow<=2.19,>=2.13.0
+Requires-Dist: torch<=2.7,>=2.6.0
+Requires-Dist: tqdm==4.67.1
+Description-Content-Type: text/markdown
+
+# 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.
+
+[![arXiv](https://img.shields.io/badge/arXiv-2505.13100-b31b1b.svg)](https://arxiv.org/abs/2505.13100)
+
+<img src="./figures/cross_domain_saliency_maps_banner.svg" width="755">
+
+# Installation
+Download this repository:
+```
+git clone https://github.com/esl-epfl/cross-domain-saliency-maps
+```
+
+Install using ```pip```:
+```
+pip install ./cross_domain_saliency_maps
+```
+
+# 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) [![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)
+
+# 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).
+
+## 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```](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)``` 
+
+## 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}
+}

cross_domain_saliency_maps-0.0.4.dist-info/RECORD

@@ -0,0 +1,11 @@
+cross_domain_saliency_maps/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cross_domain_saliency_maps/tensorflow_ig/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cross_domain_saliency_maps/tensorflow_ig/cross_domain_integrated_gradients.py,sha256=og7t6XrLfzu3s2sbpeqi5REG4hkXdcIIvwumShT5q7Q,5991
+cross_domain_saliency_maps/tensorflow_ig/domain_transforms.py,sha256=LeayOMh2EWmGU_GQ2Wa50Z5A_YH5gnEErFpi2FEz4Sw,7531
+cross_domain_saliency_maps/torch_ig/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cross_domain_saliency_maps/torch_ig/cross_domain_integrated_gradients.py,sha256=xWSA88HkUFw-FoUW9cfEmMCNIzpj4KYB5wabmx9PeBI,6128
+cross_domain_saliency_maps/torch_ig/domain_transforms.py,sha256=wpAljfS9oo5fn68FHH6rPz1y64UykINmk7hRJVSHv0E,7642
+cross_domain_saliency_maps-0.0.4.dist-info/METADATA,sha256=-WT7nRI7LV2jSzZKLlZT7SY3m8pbjjL9WIRn5-xYQGE,5581
+cross_domain_saliency_maps-0.0.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cross_domain_saliency_maps-0.0.4.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+cross_domain_saliency_maps-0.0.4.dist-info/RECORD,,

cross_domain_saliency_maps-0.0.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any