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

cross_domain_saliency_maps/tensorflow_ig/cross_domain_integrated_gradients.py

@@ -0,0 +1,152 @@
+import tensorflow as tf
+import numpy as np
+
+from cross_domain_saliency_maps.tensorflow_ig.domain_transforms import DomainBase
+from cross_domain_saliency_maps.tensorflow_ig.domain_transforms import FourierDomain
+from cross_domain_saliency_maps.tensorflow_ig.domain_transforms import TimeDomain
+from cross_domain_saliency_maps.tensorflow_ig.domain_transforms import ICADomain
+
+class CrossDomainIG:
+    """ Cross Domain IG base class. Defines the basic functionality 
+        for cross-domain ig. 
+
+        Attributes:
+        model (tf.keras.models.Model): A tensorflow model.
+        n_iterations (int): Number of iterations for approximating IG.
+        output_channel(int): The output channel of the model for which 
+                             we generate the saliency map.
+        dtype (dtype): The type of the target domain.
+    """
+    def __init__(self, model: tf.keras.models.Model, 
+                 n_iterations: int, 
+                 output_channel: int, 
+                 dtype = tf.float32):
+        """ Initializes CrossDomainIG.
+
+        Args:
+            model (tf.keras.models.Model): A tensorflow model for which 
+                saliency maps will be generated.
+            n_iterations (int): Number of steps used in approximating
+                the integral in the Integrated Gradients computation.
+            output_channel (int): The channle of the model's output used
+                for the saliency map (e.g. the class channel).
+        """
+        self.model = model
+        self.n_iterations = n_iterations
+        self.output_channel = output_channel
+
+    def initialize_domain(self, Domain: DomainBase, **kwargs):
+        """ Initializes the target domain in which the IG is 
+            expressed.
+
+            Args:
+                Domain (DomainBase): The target domain.
+                **kwargs: Parameters needed to initialize the Domain.
+        """
+        self.domain = Domain(**kwargs)
+    
+    def run(self, x: np.array, x_baseline: np.array):
+        """ Runs the saliency map generation for input sample x
+            using the x_baseline for baseline.
+
+            Args:
+                x (np.array): a single sample with shape [1, n_timesteps, n_channels]
+                x_baseline (np.array): the baseline sample with shape [1, n_timesteps, n_channels]
+        """
+        self.domain.set_coefficients(x, x_baseline)
+        
+        with tf.GradientTape() as tape:
+            X_in = self.domain.get_coefficients()
+            X_baseline = self.domain.get_coefficient_baseline()
+
+            a = tf.constant(np.linspace(0, 1, self.n_iterations), dtype = X_in.dtype)
+
+            X_samples = X_baseline + (X_in - X_baseline) * a[:, tf.newaxis, tf.newaxis]
+            tape.watch(X_samples)
+            x_ = self.domain.inverse_transform(X_samples)
+            y_ = self.model(x_)
+            grads = tape.gradient(y_[:, self.output_channel], X_samples)
+            
+        S = tf.math.reduce_mean(tf.math.conj(grads), axis = 0)
+        self.multiIG = tf.math.real((X_in[0, :] - X_baseline[0, :]) * S)
+        return self.multiIG
+
+    def getMultiIG(self):
+        """ Get the generated saliency map.
+        """
+        return self.multiIG
+
+class TimeIG(CrossDomainIG):
+    """ Implementation of the CrossDomainIG specifically for the
+    time target domain (Original IG). 
+    """
+    def __init__(self, 
+                 model: tf.keras.models.Model, 
+                 n_iterations: int, 
+                 output_channel: int, 
+                 dtype = tf.float32):
+        super().__init__(model, n_iterations,
+                         output_channel, dtype)
+        
+        self.initialize_domain(TimeDomain, dtype = dtype)
+
+class FourierIG(CrossDomainIG):
+    """ Implementation of the CrossDomainIG specifically for the
+    frequency target domain. 
+    """
+    def __init__(self, 
+                 model: tf.keras.models.Model, 
+                 n_iterations: int, 
+                 output_channel: int, 
+                 dtype = tf.float32):
+        super().__init__(model, n_iterations,
+                         output_channel, dtype)
+        
+        self.initialize_domain(FourierDomain, dtype = dtype)
+
+class ICAIG(CrossDomainIG):
+    """ Implementation of the CrossDomainIG specifically for the
+    target domain defined by the Independent Component Analysis
+    (ICA) decomposition.
+
+    Here the decomposed signal channels act as the signal basis,
+    while the mixing matrix is the features on which the saliency
+    is expressed.
+
+    Args:
+        model (tf.keras.models.Model): The tensorflow model.
+        ica: A ICA object compatible with sklearn's FastICA object.
+        n_iterations (int): Number of steps to approximate the integral
+            in the IG.
+        output_channel (int): The model's output channel for which the
+            saliency map will be generated.
+        dtype: The type of the features. 
+    """
+    def __init__(self, 
+                 model: tf.keras.models.Model, 
+                 ica, 
+                 n_iterations: int, 
+                 output_channel: int, 
+                 dtype = tf.float32):
+        super().__init__(model, n_iterations,
+                         output_channel, dtype)
+        
+        self.initialize_domain(ICADomain, ica = ica, dtype = dtype)
+    
+    def run(self, x: np.array, x_baseline: np.array):
+        """ Runs the IG generation. 
+
+        The IG components are expressed over the elements of 
+        the entire unmixing matrix, since this is considered
+        as the input features (projected over the basis defined
+        by the independent channels). We sume along the first
+        dimension of the matrix to express the IG in terms of 
+        independent channels.
+
+        Args:
+            x (np.array): Input sample for which to generate saliency.
+            x_basleine (np.array): Baseline sample.
+        """
+        super().run(x, x_baseline)
+        self.multiIG = tf.reduce_sum(self.multiIG, axis = 1)
+        return self.multiIG

cross_domain_saliency_maps/tensorflow_ig/domain_transforms.py

@@ -0,0 +1,207 @@
+import abc
+import tensorflow as tf
+import numpy as np
+
+class DomainBase:
+    """ Defines the base class for a domain transformation.
+
+    Attributes:
+        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, dtype = tf.float32):
+        """ Initialize the Domain.
+        """
+        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, dtype = tf.float32, channel_permutation = (0, 2, 1)):
+        """ Initialize the Fourier Domain.
+
+        Args:
+            dtype: The type of the input features. 
+            channel_permutation: Permutation of the input samples such that 
+                the time-samples are placed in the last channel. This is used
+                because tensorflow's fft transformation requires the last dimension
+                to correspond to the time domain.
+        """
+        super().__init__(dtype)
+        self.channel_permutation = channel_permutation
+    
+    def forward_transform(self, x: tf.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 tf.signal.fft(tf.cast(tf.transpose(x, perm = self.channel_permutation), 
+                                        dtype = tf.complex64))
+      
+    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 = tf.constant(x, dtype = self.dtype)
+        x_baseline_tf = tf.constant(x_baseline, dtype = self.dtype)
+
+        self.coefficients = self.forward_transform(x_tf)
+        self.baseline_coefficients = self.forward_transform(x_baseline_tf)
+    
+    def inverse_transform(self, x_input: tf.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 tf.transpose(tf.cast(tf.signal.ifft(x_input), 
+                                    dtype = tf.float32), 
+                            perm = self.channel_permutation)
+
+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, ica, dtype = tf.float32, channel_permutation = (0, 2, 1)):
+        super().__init__(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 = tf.constant(self.forward_transform(x[0, ...]), dtype = self.dtype)
+
+        self.coefficients = tf.constant(self.ica.mixing_.T, dtype = self.dtype)[tf.newaxis, ...]
+        self.baseline_coefficients = tf.zeros_like(self.coefficients)
+        self.mean = tf.constant(self.ica.mean_, dtype = self.dtype)
+    
+    def inverse_transform(self, x_input: tf.Tensor):
+        """ Inverses the ICA transform given an input matrix 
+        x_input and the basis stored in the domain. 
+
+        Args:
+            x_input (tf.Tensor): Input unmixing matrix of size [n_channels, n_channels].
+        """
+        return tf.matmul(self.basis, x_input) + self.mean
+
+class TimeDomain(DomainBase):
+    """ Time domain implementation (Original input domain).
+    """
+    def __init__(self, dtype = tf.float32, channel_permutation = (0, 2, 1)):
+        """ Initialize the Time Domain.
+        """
+        super().__init__(dtype)
+
+        self.channel_permutation = channel_permutation
+    
+    def forward_transform(self, x: tf.Tensor):
+        """ Implementation of the forward transform. No transformation
+        take place. 
+
+        Args:
+            x (tf.Tensor): Input time-domain sample.
+        """
+        return tf.transpose(x, perm = self.channel_permutation)
+      
+    def set_coefficients(self, x: np.array, x_baseline: np.array):
+        """ Sets the time coefficients transforming.
+
+        Args:
+            x (np.array): The input sample in time-domain.
+            x_baseline (np.array): The baseline sample in time-domain.
+        """
+        x_tf = tf.constant(x, dtype = self.dtype)
+        x_baseline_tf = tf.constant(x_baseline, dtype = self.dtype)
+
+        self.coefficients = self.forward_transform(x_tf)
+        self.baseline_coefficients = self.forward_transform(x_baseline_tf)
+    
+    def inverse_transform(self, x_input: tf.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 tf.transpose(x_input, perm = self.channel_permutation)

cross_domain_saliency_maps/torch_ig/cross_domain_integrated_gradients.py

@@ -0,0 +1,162 @@
+import torch
+import numpy as np
+
+from cross_domain_saliency_maps.torch_ig.domain_transforms import DomainBase
+from cross_domain_saliency_maps.torch_ig.domain_transforms import FourierDomain
+from cross_domain_saliency_maps.torch_ig.domain_transforms import ICADomain
+from cross_domain_saliency_maps.torch_ig.domain_transforms import TimeDomain
+
+from tqdm import tqdm
+
+class CrossDomainIG:
+    """ Cross Domain IG base class. Defines the basic functionality 
+        for cross-domain ig. 
+
+        Attributes:
+        model (torch.nn.Module): A pytorch model.
+        n_iterations (int): Number of iterations for approximating IG.
+        output_channel(int): The output channel of the model for which 
+                             we generate the saliency map.
+        dtype (dtype): The type of the target domain.
+    """
+    def __init__(self, model: torch.nn.Module, 
+                 n_iterations: int, 
+                 output_channel: int, 
+                 dtype = torch.float32):
+        """ Initializes CrossDomainIG.
+
+        Args:
+            model (torch.nn.Module): A pytorch model for which 
+                saliency maps will be generated.
+            n_iterations (int): Number of steps used in approximating
+                the integral in the Integrated Gradients computation.
+            output_channel (int): The channle of the model's output used
+                for the saliency map (e.g. the class channel).
+        """
+        self.model = model
+        self.n_iterations = n_iterations
+        self.output_channel = output_channel
+
+    def initialize_domain(self, Domain: DomainBase, **kwargs):
+        """ Initializes the target domain in which the IG is 
+            expressed.
+
+            Args:
+                Domain (DomainBase): The target domain.
+                **kwargs: Parameters needed to initialize the Domain.
+        """
+        self.domain = Domain(**kwargs)
+    
+    def run(self, x: np.array, x_baseline: np.array):
+        """ Runs the saliency map generation for input sample x
+            using the x_baseline for baseline.
+
+            Args:
+                x (np.array): a single sample with shape [1, n_timesteps, n_channels]
+                x_baseline (np.array): the baseline sample with shape [1, n_timesteps, n_channels]
+        """
+        self.domain.set_coefficients(x, x_baseline)
+
+        grad_sum = 0
+
+        X_in = self.domain.get_coefficients()
+        X_baseline = self.domain.get_coefficient_baseline()
+
+        X_samples = [ X_baseline + (float(i) / self.n_iterations) * (X_in - X_baseline) for i in range(1, self.n_iterations + 1)]
+
+        for X_sample in tqdm(X_samples):
+            X_sample.requires_grad = True
+            x_ = self.domain.inverse_transform(X_sample)
+            prediction = self.model(x_)
+            prediction[0, self.output_channel].backward()
+            grad_sum += torch.conj(X_sample.grad)
+
+        grad_sum /= self.n_iterations
+        self.multiIG = torch.real((X_in - X_baseline) * grad_sum)
+        
+        return self.multiIG
+
+    def getMultiIG(self):
+        """ Get the generated saliency map.
+        """
+        return self.multiIG
+
+
+class TimeIG(CrossDomainIG):
+    """ Implementation of the CrossDomainIG specifically for the
+    time target domain. This is the original Integrated Gradients
+    method.
+    """
+    def __init__(self, 
+                 model: torch.nn.Module, 
+                 n_iterations: int, 
+                 output_channel: int, 
+                 device: torch.device,
+                 dtype = torch.float32):
+        super().__init__(model, n_iterations,
+                         output_channel, dtype)
+        
+        self.initialize_domain(TimeDomain, device = device, dtype = dtype)
+
+class FourierIG(CrossDomainIG):
+    """ Implementation of the CrossDomainIG specifically for the
+    frequency target domain. 
+    """
+    def __init__(self, 
+                 model: torch.nn.Module, 
+                 n_iterations: int, 
+                 output_channel: int, 
+                 device: torch.device,
+                 dtype = torch.float32):
+        super().__init__(model, n_iterations,
+                         output_channel, dtype)
+        
+        self.initialize_domain(FourierDomain, device = device, dtype = dtype)
+
+class ICAIG(CrossDomainIG):
+    """ Implementation of the CrossDomainIG specifically for the
+    target domain defined by the Independent Component Analysis
+    (ICA) decomposition.
+
+    Here the decomposed signal channels act as the signal basis,
+    while the mixing matrix is the features on which the saliency
+    is expressed.
+
+    Args:
+        model (torch.nn.Module): The pytorch model.
+        ica: A ICA object compatible with sklearn's FastICA object.
+        n_iterations (int): Number of steps to approximate the integral
+            in the IG.
+        output_channel (int): The model's output channel for which the
+            saliency map will be generated.
+        dtype: The type of the features. 
+    """
+    def __init__(self, 
+                 model: torch.nn.Module, 
+                 ica, 
+                 n_iterations: int, 
+                 output_channel: int, 
+                 device: torch.device,
+                 dtype = torch.float32):
+        super().__init__(model, n_iterations,
+                         output_channel, dtype)
+        
+        self.initialize_domain(ICADomain, ica = ica, dtype = dtype, device = device)
+    
+    def run(self, x: np.array, x_baseline: np.array):
+        """ Runs the IG generation. 
+
+        The IG components are expressed over the elements of 
+        the entire unmixing matrix, since this is considered
+        as the input features (projected over the basis defined
+        by the independent channels). We sume along the first
+        dimension of the matrix to express the IG in terms of 
+        independent channels.
+
+        Args:
+            x (np.array): Input sample for which to generate saliency.
+            x_basleine (np.array): Baseline sample.
+        """
+        super().run(x, x_baseline)
+        self.multiIG = torch.sum(self.multiIG[0], dim = 1)
+        return self.multiIG