signal-grad-cam 0.1.2__tar.gz → 0.1.4__tar.gz

{signal_grad_cam-0.1.2 → signal_grad_cam-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: signal_grad_cam
-Version: 0.1.2
+Version: 0.1.4
 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.2 → signal_grad_cam-0.1.4}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r") as f:
 
 setup(
     name="signal_grad_cam",
-    version="0.1.2",
+    version="0.1.4",
     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.2 → signal_grad_cam-0.1.4}/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 = []
@@ -105,7 +110,7 @@ class CamBuilder:
                 channel_names: List[str | float] = None, results_dir_path: str = None, aspect_factor: float = 100,
                 data_shape_list: List[Tuple[int, int]] = None, extra_preprocess_inputs_list: List[List[Any]] = None,
                 extra_inputs_list: List[Any] = None, time_names: List[str | float] = None,
-                axes_names: Tuple[str | None, str | None] | List[str | None] = None) \
+                axes_names: Tuple[str | None, str | None] | List[str | None] = None, eps: float = 1e-6) \
             -> Tuple[Dict[str, List[np.ndarray]], Dict[str, np.ndarray],  Dict[str, Tuple[np.ndarray, np.ndarray]]]:
         """
         Allows the user to request Class Activation Maps (CAMs) for a given list of inputs, a set of algorithms,
@@ -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.
@@ -147,6 +153,8 @@ class CamBuilder:
         :param time_names: (optional, default is None) A list of strings representing tick names for the time axis.
         :param axes_names: (optional, default is None) A tuple of strings representing names for X and Y axes,
             respectively.
+        :param eps: (optional, default is 1e-6) A float number used in probability clamping before logarithm application
+            to avoid null or None results.
 
         :return:
             - cams_dict: A dictionary storing a list of CAMs. Each list contains CAMs for each item in the input data
@@ -183,7 +191,8 @@ class CamBuilder:
                                                                                     data_shape_list=data_shape_list,
                                                                                     extra_preprocess_inputs_list=
                                                                                     extra_preprocess_inputs_list,
-                                                                                    extra_inputs_list=extra_inputs_list)
+                                                                                    extra_inputs_list=extra_inputs_list,
+                                                                                    esp=eps)
                     item_key = explainer_type + "_" + target_layer + "_class" + str(target_class)
                     cams_dict.update({item_key: cam_list})
                     predicted_probs_dict.update({item_key: output_probs})
@@ -450,7 +459,8 @@ class CamBuilder:
 
     def _create_raw_batched_cams(self, data_list: List[np.ndarray | torch.Tensor | tf.Tensor], target_class: int,
                                  target_layer: str, explainer_type: str, softmax_final: bool,
-                                 extra_inputs_list: List[Any] = None) -> Tuple[List[np.ndarray], np.ndarray]:
+                                 extra_inputs_list: List[Any] = None, eps: float = 1e-6) \
+            -> Tuple[List[np.ndarray], np.ndarray]:
         """
         Retrieves raw CAMs from an input data list based on the specified settings (defined by algorithm, target layer,
         and target class). Additionally, it returns the class probabilities predicted by the model.
@@ -466,6 +476,8 @@ class CamBuilder:
             activation function.
         :param extra_inputs_list: (optional, defaults is None) A list of additional input objects required by the
             model's forward method.
+        :param eps: (optional, default is 1e-6) A float number used in probability clamping before logarithm application
+            to avoid null or None results.
 
         :return:
             - cam_list: A list of np.ndarray containing CAMs for each item in the input data list, corresponding to the
@@ -511,7 +523,8 @@ class CamBuilder:
 
     def __create_batched_cams(self, data_list: List[np.ndarray], target_class: int, target_layer: str,
                               explainer_type: str, softmax_final: bool, data_shape_list: List[Tuple[int, int]] = None,
-                              extra_preprocess_inputs_list: List[List[Any]] = None, extra_inputs_list: List[Any] = None) \
+                              extra_preprocess_inputs_list: List[List[Any]] = None, extra_inputs_list: List[Any] = None,
+                              eps: float = 1e-6) \
             -> Tuple[List[np.ndarray], np.ndarray, Tuple[np.ndarray, np.ndarray]]:
         """
         Prepares the input data list and retrieves CAMs based on the specified settings (defined by algorithm, target
@@ -534,7 +547,9 @@ class CamBuilder:
             represents the additional input objects required by the preprocessing method for the i-th input.
         :param extra_inputs_list: (optional, default is None) A list of additional input objects required by the model's
             forward method.
-0
+        :param eps: (optional, default is 1e-6) A float number used in probability clamping before logarithm application
+            to avoid null or None results.
+
         :return:
             - cam_list: A list of np.ndarray containing CAMs for each item in the input data list, corresponding to the
                 given setting (defined by algorithm, target layer, and target class).
@@ -568,7 +583,8 @@ class CamBuilder:
                                      "time.")
 
         cam_list, target_probs = self._create_raw_batched_cams(data_list, target_class, target_layer, explainer_type,
-                                                               softmax_final, extra_inputs_list=extra_inputs_list)
+                                                               softmax_final, extra_inputs_list=extra_inputs_list,
+                                                               eps=eps)
         self.activations = None
         self.gradients = None
         cams = np.stack(cam_list)
@@ -648,7 +664,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 +691,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:
@@ -890,7 +907,7 @@ class CamBuilder:
             - is_2d_layer: A boolean indicating whether the target layers 2D-convolutional layer.
         """
 
-        raise ValueError(target_layer + " must be a 1D or 2D convolutional layer.")
+        raise ValueError(str(target_layer) + " must be a 1D or 2D convolutional layer.")
 
     @staticmethod
     def __normalize_cams(cams: np.ndarray, is_2d_layer: bool) -> Tuple[np.ndarray, Tuple[np.ndarray, np.ndarray]]:

{signal_grad_cam-0.1.2 → signal_grad_cam-0.1.4}/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)
 
@@ -120,7 +125,8 @@ class TorchCamBuilder(CamBuilder):
 
     def _create_raw_batched_cams(self, data_list: List[np.ndarray | torch.Tensor], target_class: int,
                                  target_layer: nn.Module, explainer_type: str, softmax_final: bool,
-                                 extra_inputs_list: List[Any] = None)  -> Tuple[List[np.ndarray], np.ndarray]:
+                                 extra_inputs_list: List[Any] = None, eps: float = 1e-6) \
+            -> Tuple[List[np.ndarray], np.ndarray]:
         """
         Retrieves raw CAMs from an input data list based on the specified settings (defined by algorithm, target layer,
         and target class). Additionally, it returns the class probabilities predicted by the model.
@@ -136,6 +142,8 @@ class TorchCamBuilder(CamBuilder):
             activation function.
         :param extra_inputs_list: (optional, defaults is None) A list of additional input objects required by the
             model's forward method.
+        :param eps: (optional, default is 1e-6) A float number used in probability clamping before logarithm application
+            to avoid null or None results.
 
         :return:
             - cam_list: A list of np.ndarray containing CAMs for each item in the input data list, corresponding to the
@@ -179,30 +187,32 @@ class TorchCamBuilder(CamBuilder):
             outputs = outputs[self.model_output_index]
 
         if softmax_final:
-            # Approximate Softmax inversion formula logit = log(prob) + constant, as the constant is negligible
-            # during derivation
-            target_scores = torch.log(outputs)
             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)
+            if len(outputs.shape) == 2 and outputs.shape[1] > 1:
+                # Approximate Softmax inversion formula logit = log(prob) + constant, as the constant is negligible
+                # during derivation. Clamp probabilities before log application to avoid null maps for maximum
+                # confidence.
+                target_scores = torch.log(torch.clamp(outputs, min=eps, max=1 - eps))
+            else:
+                # Adjust results for binary networks
+                target_scores = torch.logit(outputs, eps=eps)
+                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)
+                else:
+                    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
-
             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)
+                if len(outputs.shape) == 1:
+                    target_scores = torch.stack([-outputs, outputs], dim=1)
+                elif len(outputs.shape) == 2 and outputs.shape[1] == 1:
+                    target_scores = torch.cat([-outputs, outputs], dim=1)
+                p = torch.sigmoid(outputs)
+                target_probs = torch.stack([1 - p, p], dim=1)
 
         target_probs = target_probs[:, target_class].cpu().detach().numpy()
 
@@ -246,7 +256,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:
@@ -271,7 +282,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.2 → signal_grad_cam-0.1.4}/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
@@ -144,7 +150,8 @@ class TfCamBuilder(CamBuilder):
 
     def _create_raw_batched_cams(self, data_list: List[np.ndarray | tf.Tensor], target_class: int,
                                  target_layer: tf.keras.layers.Layer, explainer_type: str, softmax_final: bool,
-                                 extra_inputs_list: List[Any] = None) -> Tuple[List[np.ndarray], np.ndarray]:
+                                 extra_inputs_list: List[Any] = None, eps: float = 1e-6) \
+            -> Tuple[List[np.ndarray], np.ndarray]:
         """
         Retrieves raw CAMs from an input data list based on the specified settings (defined by algorithm, target layer,
         and target class). Additionally, it returns the class probabilities predicted by the model.
@@ -160,6 +167,8 @@ class TfCamBuilder(CamBuilder):
             activation function.
         :param extra_inputs_list: (optional, defaults is None) A list of additional input objects required by the
             model's forward method.
+        :param eps: (optional, default is 1e-6) A float number used in probability clamping before logarithm application
+            to avoid null or None results.
 
         :return:
             - cam_list: A list of np.ndarray containing CAMs for each item in the input data list, corresponding to the
@@ -193,30 +202,32 @@ class TfCamBuilder(CamBuilder):
             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)
                 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)
+                if len(outputs.shape) == 2 and outputs.shape[1] > 1:
+                    # Approximate Softmax inversion formula logit = log(prob) + constant, as the constant is negligible
+                    # during derivation. Clamp probabilities before log application to avoid null maps for maximum
+                    # confidence.
+                    target_scores = tf.math.log(tf.clip_by_value(outputs, eps, 1.0 - eps))
+                else:
+                    # Adjust results for binary network
+                    target_scores = tf.math.logit(outputs, eps=eps)
+                    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)
+                    else:
+                        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
-
                 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)
+                    if len(outputs.shape) == 1:
+                        target_scores = tf.stack([-outputs, outputs], axis=1)
+                    elif len(outputs.shape) == 2 and outputs.shape[1] == 1:
+                        target_scores = tf.concat([-outputs, outputs], axis=1)
+                    p = tf.math.sigmoid(outputs)
+                    target_probs = tf.stack([1 - p, p], axis=1)
 
             target_scores = target_scores[:, target_class]
             target_probs = target_probs[:, target_class]
@@ -260,7 +271,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:
@@ -285,7 +297,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.2 → signal_grad_cam-0.1.4}/signal_grad_cam.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: signal-grad-cam
-Version: 0.1.2
+Version: 0.1.4
 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