signal-grad-cam 0.1.1__tar.gz → 0.1.3__tar.gz

{signal_grad_cam-0.1.1 → signal_grad_cam-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: signal_grad_cam
-Version: 0.1.1
+Version: 0.1.3
 Summary: SignalGrad-CAM aims at generalising Grad-CAM to one-dimensional applications, while enhancing usability and efficiency.
 Home-page: https://github.com/samuelepe11/signal_grad_cam
 Author: Samuele Pe

{signal_grad_cam-0.1.1 → signal_grad_cam-0.1.3}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r") as f:
 
 setup(
     name="signal_grad_cam",
-    version="0.1.1",
+    version="0.1.3",
     description="SignalGrad-CAM aims at generalising Grad-CAM to one-dimensional applications, while enhancing usability"
                 " and efficiency.",
     keywords="XAI, class activation maps, CNN, time series",

{signal_grad_cam-0.1.1 → signal_grad_cam-0.1.3}/signal_grad_cam/cam_builder.py

@@ -23,8 +23,8 @@ class CamBuilder:
     def __init__(self, model: torch.nn.Module | tf.keras.Model | Any,
                  transform_fn: Callable[[np.ndarray, *tuple[Any, ...]], torch.Tensor | tf.Tensor] = None,
                  class_names: List[str] = None, time_axs: int = 1, input_transposed: bool = False,
-                 ignore_channel_dim: bool = False, model_output_index: int = None, extend_search: bool = False,
-                 padding_dim: int = None, seed: int = 11):
+                 ignore_channel_dim: bool = False, is_regression_network: bool = False, model_output_index: int = None,
+                 extend_search: bool = False, padding_dim: int = None, seed: int = 11):
         """
         Initializes the CamBuilder class. The constructor also displays, if present and retrievable, the 1D- and
         2D-convolutional layers in the network, as well as the final Sigmoid/Softmax activation. Additionally, the CAM
@@ -44,6 +44,10 @@ class CamBuilder:
             during model inference, either by the model itself or by the preprocessing function.
         :param ignore_channel_dim: (optional, default is False) A boolean indicating whether to ignore the channel
             dimension. This is useful when the model expects inputs without a singleton channel dimension.
+        :param is_regression_network: (optional, default is False) A boolean indicating whether the network is designed
+            for a regression task. If set to True, the CAM will highlight both positive and negative contributions.
+            While negative contributions are typically irrelevant for classification-based saliency maps, they can be
+            meaningful in regression settings, as they may represent features that decrease the predicted value.
         :param model_output_index: (optional, default is None) An integer index specifying which of the model's outputs
             represents output scores (or probabilities). If there is only one output, this argument can be ignored.
         :param extend_search: (optional, default is False) A boolean flag indicating whether to deepend the search for
@@ -67,6 +71,7 @@ class CamBuilder:
         self.time_axs = time_axs
         self.input_transposed = input_transposed
         self.ignore_channel_dim = ignore_channel_dim
+        self.is_regression_network = is_regression_network
         self.model_output_index = model_output_index
         self.padding_dim = padding_dim
         self.original_dims = []
@@ -136,7 +141,8 @@ class CamBuilder:
         :param results_dir_path: (optional, default is None) A string representing the relative path to the directory
             for storing results. If None, the output will be displayed in a figure.
         :param aspect_factor: (optional, default is 100) A numerical value to set the aspect ratio of the output signal
-            one-dimensional CAM.
+            one-dimensional CAM. Note that this value should be grater than the length of the input signal considered,
+            otherwise it is set to the length of the considered signal.
         :param data_shape_list: (optional, default is None) A list of integer tuples storing the original input sizes,
             used to set the CAM shape after resizing during preprocessing. The expected format is number of rows x
             number of columns.
@@ -648,7 +654,8 @@ class CamBuilder:
         :param dt: (optional, default is 10) A numerical value representing the granularity of the time axis in seconds
             in the output display.
         :param aspect_factor: (optional, default is 100) A numerical value to set the aspect ratio of the output signal
-            one-dimensional CAM.
+            one-dimensional CAM. Note that this value should be grater than the length of the input signal considered,
+            otherwise it is set to the length of the considered signal.
         :param bar_ranges: A tuple containing two np.ndarrays, corresponding to the minimum and maximum importance scores
             per CAM for each item in the input data list, based on a given setting (defined by algorithm, target
             layer, and target class).
@@ -674,7 +681,7 @@ class CamBuilder:
             norm = self.__get_norm(map)
 
             if map.shape[1] == 1:
-                aspect = int(map.shape[0] / aspect_factor)
+                aspect = int(map.shape[0] / aspect_factor) if map.shape[0] <= aspect_factor else 1
                 map = np.transpose(map)
             else:
                 if is_2d_layer:

{signal_grad_cam-0.1.1 → signal_grad_cam-0.1.3}/signal_grad_cam/pytorch_cam_builder.py

@@ -15,8 +15,8 @@ class TorchCamBuilder(CamBuilder):
 
     def __init__(self, model: nn.Module | Any, transform_fn: Callable[[np.ndarray, *tuple[Any, ...]], torch.Tensor]
                  = None, class_names: List[str] = None, time_axs: int = 1, input_transposed: bool = False,
-                 ignore_channel_dim: bool = False, model_output_index: int = None, extend_search: bool = False,
-                 use_gpu: bool = False, padding_dim: int = None, seed: int = 11):
+                 ignore_channel_dim: bool = False, is_regression_network: bool = False, model_output_index: int = None,
+                 extend_search: bool = False, use_gpu: bool = False, padding_dim: int = None, seed: int = 11):
         """
         Initializes the TorchCamBuilder class. The constructor also displays, if present and retrievable, the 1D- and
         2D-convolutional layers in the network, as well as the final Sigmoid/Softmax activation. Additionally, the CAM
@@ -36,6 +36,10 @@ class TorchCamBuilder(CamBuilder):
             during model inference, either by the model itself or by the preprocessing function.
         :param ignore_channel_dim: (optional, default is False) A boolean indicating whether to ignore the channel
             dimension. This is useful when the model expects inputs without a singleton channel dimension.
+        :param is_regression_network: (optional, default is False) A boolean indicating whether the network is designed
+            for a regression task. If set to True, the CAM will highlight both positive and negative contributions.
+            While negative contributions are typically irrelevant for classification-based saliency maps, they can be
+            meaningful in regression settings, as they may represent features that decrease the predicted value.
         :param model_output_index: (optional, default is None) An integer index specifying which of the model's outputs
             represents output scores (or probabilities). If there is only one output, this argument can be ignored.
         :param extend_search: (optional, default is False) A boolean flag indicating whether to deepend the search for
@@ -52,6 +56,7 @@ class TorchCamBuilder(CamBuilder):
         super(TorchCamBuilder, self).__init__(model=model, transform_fn=transform_fn, class_names=class_names,
                                               time_axs=time_axs, input_transposed=input_transposed,
                                               ignore_channel_dim=ignore_channel_dim,
+                                              is_regression_network=is_regression_network,
                                               model_output_index=model_output_index, extend_search=extend_search,
                                               padding_dim=padding_dim, seed=seed)
 
@@ -180,12 +185,29 @@ class TorchCamBuilder(CamBuilder):
 
         if softmax_final:
             # Approximate Softmax inversion formula logit = log(prob) + constant, as the constant is negligible
-            # during derivation
-            target_scores = torch.log(outputs)
+            # during derivation. Clamp probabilities before log application to avoid null maps for maximum confidence.
+            target_scores = torch.log(torch.clamp(outputs, min=0, max=1 - 1e-6))
             target_probs = outputs
+
+            # Adjust results for binary network
+            if len(outputs.shape) == 1:
+                target_scores = torch.stack([-target_scores, target_scores], dim=1)
+                target_probs = torch.stack([1 - target_probs, target_probs], dim=1)
+            elif len(outputs.shape) == 2 and outputs.shape[1] == 1:
+                target_scores = torch.cat([-target_scores, target_scores], dim=1)
+                target_probs = torch.cat([1 - target_probs, target_probs], dim=1)
         else:
+            if len(outputs.shape) == 1:
+                outputs = torch.stack([-outputs, outputs], dim=1)
+            elif len(outputs.shape) == 2 and outputs.shape[1] == 1:
+                outputs = torch.cat([-outputs, outputs], dim=1)
             target_scores = outputs
-            target_probs = torch.softmax(target_scores, dim=1)
+
+            if len(outputs.shape) == 2 and outputs.shape[1] > 1:
+                target_probs = torch.softmax(target_scores, dim=1)
+            else:
+                tmp = torch.sigmoid(target_scores[:, 1])
+                target_probs = torch.stack([1 - tmp, tmp], dim=1)
 
         target_probs = target_probs[:, target_class].cpu().detach().numpy()
 
@@ -229,7 +251,8 @@ class TorchCamBuilder(CamBuilder):
                 activations[i, :] *= weights[i]
 
         cam = torch.sum(activations, dim=0)
-        cam = torch.relu(cam)
+        if not self.is_regression_network:
+            cam = torch.relu(cam)
         return cam
 
     def _get_hirescam_map(self, is_2d_layer: bool, batch_idx: int) -> torch.Tensor:
@@ -254,7 +277,8 @@ class TorchCamBuilder(CamBuilder):
                 activations[i, :] *= gradients[i, :]
 
         cam = torch.sum(activations, dim=0)
-        cam = torch.relu(cam)
+        if not self.is_regression_network:
+            cam = torch.relu(cam)
         return cam
 
     def __get_activation_forward_hook(self, layer: nn.Module, inputs: Tuple[torch.Tensor, ...], outputs: torch.Tensor) \

{signal_grad_cam-0.1.1 → signal_grad_cam-0.1.3}/signal_grad_cam/tensorflow_cam_builder.py

@@ -20,8 +20,8 @@ class TfCamBuilder(CamBuilder):
 
     def __init__(self, model: tf.keras.Model | Any, transform_fn: Callable[[np.ndarray, *tuple[Any, ...]], tf.Tensor]
                  = None, class_names: List[str] = None, time_axs: int = 1, input_transposed: bool = False,
-                 ignore_channel_dim: bool = False, model_output_index: int = None, extend_search: bool = False,
-                 padding_dim: int = None, seed: int = 11):
+                 ignore_channel_dim: bool = False, is_regression_network: bool = False, model_output_index: int = None,
+                 extend_search: bool = False, padding_dim: int = None, seed: int = 11):
         """
         Initializes the TfCamBuilder class. The constructor also displays, if present and retrievable, the 1D- and
         2D-convolutional layers in the network, as well as the final Sigmoid/Softmax activation. Additionally, the CAM
@@ -41,6 +41,10 @@ class TfCamBuilder(CamBuilder):
             during model inference, either by the model itself or by the preprocessing function.
         :param ignore_channel_dim: (optional, default is False) A boolean indicating whether to ignore the channel
             dimension. This is useful when the model expects inputs without a singleton channel dimension.
+        :param is_regression_network: (optional, default is False) A boolean indicating whether the network is designed
+            for a regression task. If set to True, the CAM will highlight both positive and negative contributions.
+            While negative contributions are typically irrelevant for classification-based saliency maps, they can be
+            meaningful in regression settings, as they may represent features that decrease the predicted value.
         :param model_output_index: (optional, default is None) An integer index specifying which of the model's outputs
             represents output scores (or probabilities). If there is only one output, this argument can be ignored.
         :param extend_search: (optional, default is False) A boolean flag indicating whether to deepend the search for
@@ -54,7 +58,9 @@ class TfCamBuilder(CamBuilder):
         # Initialize attributes
         super(TfCamBuilder, self).__init__(model=model, transform_fn=transform_fn, class_names=class_names,
                                            time_axs=time_axs, input_transposed=input_transposed,
-                                           ignore_channel_dim=ignore_channel_dim, model_output_index=model_output_index,
+                                           ignore_channel_dim=ignore_channel_dim,
+                                           is_regression_network=is_regression_network,
+                                           model_output_index=model_output_index,
                                            extend_search=extend_search, padding_dim=padding_dim, seed=seed)
 
         # Set seeds
@@ -189,17 +195,35 @@ class TfCamBuilder(CamBuilder):
 
         grad_model = keras.models.Model(self.model.inputs, [target_layer.output, self.model.output])
         extra_inputs_list = extra_inputs_list or []
-        with tf.GradientTape() as tape:
+        with (tf.GradientTape() as tape):
             self.activations, outputs = grad_model([data_batch] + extra_inputs_list)
 
             if softmax_final:
                 # Approximate Softmax inversion formula logit = log(prob) + constant, as the constant is negligible
-                # during derivation
-                target_scores = tf.math.log(outputs)
+                # during derivation. Clamp probabilities before log application to avoid null maps for maximum
+                # confidence.
+                target_scores = tf.math.log(tf.clip_by_value(outputs, 0, 1.0 - 1e-6))
                 target_probs = outputs
+
+                # Adjust results for binary network
+                if len(outputs.shape) == 1:
+                    target_scores = tf.stack([-target_scores, target_scores], axis=1)
+                    target_probs = tf.stack([1 - target_probs, target_probs], axis=1)
+                elif len(outputs.shape) == 2 and outputs.shape[1] == 1:
+                    target_scores = tf.concat([-target_scores, target_scores], axis=1)
+                    target_probs = tf.concat([1 - target_probs, target_probs], axis=1)
             else:
+                if len(outputs.shape) == 1:
+                    outputs = tf.stack([-outputs, outputs], axis=1)
+                elif len(outputs.shape) == 2 and outputs.shape[1] == 1:
+                    outputs = tf.concat([-outputs, outputs], axis=1)
                 target_scores = outputs
-                target_probs = tf.nn.softmax(target_scores, axis=1)
+
+                if len(outputs.shape) == 2 and outputs.shape[1] > 1:
+                    target_probs = tf.nn.softmax(target_scores, axis=1)
+                else:
+                    tmp = tf.math.sigmoid(target_scores[:, 1])
+                    target_probs = tf.stack([1 - tmp, tmp], axis=1)
 
             target_scores = target_scores[:, target_class]
             target_probs = target_probs[:, target_class]
@@ -243,7 +267,8 @@ class TfCamBuilder(CamBuilder):
                 activations[:, i] *= weights[i]
 
         cam = tf.reduce_sum(tf.convert_to_tensor(activations), axis=-1)
-        cam = tf.nn.relu(cam)
+        if not self.is_regression_network:
+            cam = tf.nn.relu(cam)
         return cam
 
     def _get_hirecam_map(self, is_2d_layer: bool, batch_idx: int) -> tf.Tensor:
@@ -268,7 +293,8 @@ class TfCamBuilder(CamBuilder):
                 activations[:, i] *= gradients[:, i]
 
         cam = tf.reduce_sum(tf.convert_to_tensor(activations), axis=-1)
-        cam = tf.nn.relu(cam)
+        if not self.is_regression_network:
+            cam = tf.nn.relu(cam)
         return cam
 
     @staticmethod

{signal_grad_cam-0.1.1 → signal_grad_cam-0.1.3}/signal_grad_cam.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: signal-grad-cam
-Version: 0.1.1
+Version: 0.1.3
 Summary: SignalGrad-CAM aims at generalising Grad-CAM to one-dimensional applications, while enhancing usability and efficiency.
 Home-page: https://github.com/samuelepe11/signal_grad_cam
 Author: Samuele Pe