signal-grad-cam 1.0.1__py3-none-any.whl → 2.0.0__py3-none-any.whl

signal_grad_cam/pytorch_cam_builder.py

@@ -119,7 +119,7 @@ class TorchCamBuilder(CamBuilder):
             a layer (i.e., a generic instance attribute, not guaranteed to be a layer).
         """
 
-        if (isinstance(layer, nn.Conv1d) or isinstance(layer, nn.Conv2d) or
+        if (isinstance(layer, nn.Conv1d) or isinstance(layer, nn.Conv2d) or isinstance(layer, nn.Conv3d) or
                 isinstance(layer, nn.Softmax) or isinstance(layer, nn.Sigmoid)):
             super()._show_layer(name, layer, potential=potential)
 
@@ -132,7 +132,8 @@ class TorchCamBuilder(CamBuilder):
         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.
 
-        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal or an image.
+        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal, an image, or
+            a video/volume.
         :param target_class: (mandatory) An integer representing the target class for the explanation.
         :param target_layer: (mandatory) A string representing the target layer for the explanation. This string should
             identify either PyTorch named modules or it should be a class dictionary key, used to retrieve the layer
@@ -176,6 +177,7 @@ class TorchCamBuilder(CamBuilder):
             data_list = padded_data_list
 
         is_2d_layer = self._is_2d_layer(target_layer)
+        is_3d_layer = is_2d_layer is None
         if not self.ignore_channel_dim and (is_2d_layer and len(data_list[0].shape) == 2 or not is_2d_layer
                                             and len(data_list[0].shape) == 1):
             data_list = [x.unsqueeze(0) for x in data_list]
@@ -233,35 +235,41 @@ class TorchCamBuilder(CamBuilder):
             target_score.backward(retain_graph=True)
 
             if explainer_type == "HiResCAM":
-                cam = self._get_hirescam_map(is_2d_layer=is_2d_layer, batch_idx=i)
+                cam = self._get_hirescam_map(is_2d_layer=is_2d_layer, is_3d_layer=is_3d_layer, batch_idx=i)
             else:
-                cam = self._get_gradcam_map(is_2d_layer=is_2d_layer, batch_idx=i)
+                cam = self._get_gradcam_map(is_2d_layer=is_2d_layer, is_3d_layer=is_3d_layer, batch_idx=i)
             cam_list.append(cam.cpu().detach().numpy())
 
         return cam_list, target_probs
 
-    def _get_gradcam_map(self, is_2d_layer: bool, batch_idx: int) -> torch.Tensor:
+    def _get_gradcam_map(self, is_2d_layer: bool, is_3d_layer: bool, batch_idx: int) -> torch.Tensor:
         """
         Compute the CAM using the vanilla Gradient-weighted Class Activation Mapping (Grad-CAM) algorithm.
 
         :param is_2d_layer: (mandatory) A boolean indicating whether the target layers 2D-convolutional layer.
+        :param is_3d_layer: (mandatory) A boolean indicating whether the target layers 3D-convolutional layer.
         :param batch_idx: (mandatory) The index corresponding to the i-th selected item within the original input data
             list.
 
-        :return: cam: A PyTorch tensor representing the Class Activation Map (CAM) for the batch_idx-th input, built
-            with the Grad-CAM algorithm.
+        :return:
+            - cam: A PyTorch tensor representing the Class Activation Map (CAM) for the batch_idx-th input, built with
+                the Grad-CAM algorithm.
         """
 
-        if is_2d_layer:
+        if is_2d_layer is not None and is_2d_layer:
             dim_mean = (1, 2)
+        elif is_3d_layer:
+            dim_mean = (1, 2, 3)
         else:
             dim_mean = 1
         weights = torch.mean(self.gradients[batch_idx], dim=dim_mean)
         activations = self.activations[batch_idx].clone()
 
         for i in range(self.activations.shape[1]):
-            if is_2d_layer:
+            if is_2d_layer is not None and is_2d_layer:
                 activations[i, :, :] *= weights[i]
+            elif is_3d_layer:
+                activations[i, :, :, :] *= weights[i]
             else:
                 activations[i, :] *= weights[i]
 
@@ -270,24 +278,28 @@ class TorchCamBuilder(CamBuilder):
             cam = torch.relu(cam)
         return cam
 
-    def _get_hirescam_map(self, is_2d_layer: bool, batch_idx: int) -> torch.Tensor:
+    def _get_hirescam_map(self, is_2d_layer: bool, is_3d_layer: bool, batch_idx: int) -> torch.Tensor:
         """
         Compute the CAM using the High-Resolution Class Activation Mapping (HiResCAM) algorithm.
 
         :param is_2d_layer: (mandatory) A boolean indicating whether the target layers 2D-convolutional layer.
+        :param is_3d_layer: (mandatory) A boolean indicating whether the target layers 3D-convolutional layer.
         :param batch_idx: (mandatory) The index corresponding to the i-th selected item within the original input data
             list.
 
-        :return: cam: A PyTorch tensor representing the Class Activation Map (CAM) for the batch_idx-th input, built
-            with the HiResCAM algorithm.
+        :return:
+            - cam: A PyTorch tensor representing the Class Activation Map (CAM) for the batch_idx-th input, built with
+                the HiResCAM algorithm.
         """
 
         activations = self.activations[batch_idx].clone()
         gradients = self.gradients[batch_idx]
 
         for i in range(self.activations.shape[1]):
-            if is_2d_layer:
+            if is_2d_layer is not None and is_2d_layer:
                 activations[i, :, :] *= gradients[i, :, :]
+            elif is_3d_layer:
+                activations[i, :, :, :] *= gradients[i, :, :, :]
             else:
                 activations[i, :] *= gradients[i, :]
 
@@ -331,20 +343,23 @@ class TorchCamBuilder(CamBuilder):
         self.gradients = gradients
 
     @staticmethod
-    def _is_2d_layer(target_layer: nn.Module) -> bool:
+    def _is_2d_layer(target_layer: nn.Module) -> bool | None:
         """
-        Evaluates whether the target layer is a 2D-convolutional layer.
+        Evaluates whether the target layer is at least a 2D-convolutional layer.
 
         :param target_layer: (mandatory) A PyTorch module.
 
         :return:
-            - is_2d_layer: A boolean indicating whether the target layers 2D-convolutional layer.
+            - is_2d_layer: A boolean indicating whether the target layers 2D-convolutional layer. If the target layer is
+                a 3D-convolutional layer, the function returns a None.
         """
 
         if isinstance(target_layer, nn.Conv1d):
             is_2d_layer = False
         elif isinstance(target_layer, nn.Conv2d):
             is_2d_layer = True
+        elif isinstance(target_layer, nn.Conv3d):
+            is_2d_layer = None
         else:
             is_2d_layer = CamBuilder._is_2d_layer(target_layer)
         return is_2d_layer

signal_grad_cam/tensorflow_cam_builder.py

@@ -68,13 +68,19 @@ class TfCamBuilder(CamBuilder):
 
         # Check for input/output attributes
         if not hasattr(model, "inputs"):
-            print("Your TensorFlow/Keras model has no attribute 'inputs'. Ensure it is built or loaded correctly, or\n"
-                  "provide a different one. If the model contains a 'Sequential' attribute, that Sequential object may\n"
-                  "be a suitable candidate for an input model.")
+            self._CamBuilder__print_justify("Your TensorFlow/Keras model has no attribute 'inputs'. Ensure it is built "
+                                            "or loaded correctly, or provide a different one. If the model contains a "
+                                            "'Sequential' attribute, that Sequential object may be a suitable candidate"
+                                            " for an input model.")
         elif not hasattr(model, "output"):
-            print("Your TensorFlow/Keras model has no attribute 'output'. Ensure it is built or loaded correctly, or\n"
-                  "provide a different one. If the model contains a 'Sequential' attribute, that Sequential object may\n"
-                  "be a suitable candidate for an input model.")
+            if hasattr(model, "outputs"):
+                self.model.output = model.outputs[self.model_output_index] if self.model_output_index is not None \
+                    else model.outputs[0]
+            else:
+                self._CamBuilder__print_justify("Your TensorFlow/Keras model has no attribute 'output' or 'outputs'. "
+                                                "Ensure it is built or loaded correctly, or provide a different one. If"
+                                                " the model contains a 'Sequential' attribute, that Sequential object "
+                                                "may be a suitable candidate for an input model.")
 
     def _get_layers_pool(self, show: bool = False, extend_search: bool = False) \
             -> Dict[str, tf.keras.layers.Layer | Any]:
@@ -145,7 +151,8 @@ class TfCamBuilder(CamBuilder):
         """
 
         if (isinstance(layer, keras.layers.Conv1D) or isinstance(layer, keras.layers.Conv2D) or
-                isinstance(layer, keras.layers.Softmax) or isinstance(layer, keras.Sequential)):
+            isinstance(layer, keras.layers.Conv3D) or isinstance(layer, keras.layers.Softmax) or
+                isinstance(layer, keras.Sequential)):
             super()._show_layer(name, layer, potential=potential)
 
     def _create_raw_batched_cams(self, data_list: List[np.ndarray | tf.Tensor], target_class: int,
@@ -157,7 +164,8 @@ class TfCamBuilder(CamBuilder):
         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.
 
-        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal or an image.
+        :param data_list: (mandatory) A list of np.ndarrays to be explained, representing either a signal, an image, or
+            a video/volume.
         :param target_class: (mandatory) An integer representing the target class for the explanation.
         :param target_layer: (mandatory) A string representing the target layer for the explanation. This string should
             identify either TensorFlow/Keras layers or it should be a class dictionary key, used to retrieve the layer
@@ -247,64 +255,74 @@ class TfCamBuilder(CamBuilder):
 
         cam_list = []
         is_2d_layer = self._is_2d_layer(target_layer)
+        is_3d_layer = is_2d_layer is None
         for i in range(len(data_list)):
             if explainer_type == "HiResCAM":
-                cam = self._get_hirecam_map(is_2d_layer=is_2d_layer, batch_idx=i)
+                cam = self._get_hirecam_map(is_2d_layer=is_2d_layer, is_3d_layer=is_3d_layer, batch_idx=i)
             else:
-                cam = self._get_gradcam_map(is_2d_layer=is_2d_layer, batch_idx=i)
+                cam = self._get_gradcam_map(is_2d_layer=is_2d_layer, is_3d_layer=is_3d_layer, batch_idx=i)
             cam_list.append(cam.numpy())
 
         return cam_list, target_probs
 
-    def _get_gradcam_map(self, is_2d_layer: bool, batch_idx: int) -> tf.Tensor:
+    def _get_gradcam_map(self, is_2d_layer: bool, is_3d_layer: bool, batch_idx: int) -> tf.Tensor:
         """
         Compute the CAM using the vanilla Gradient-weighted Class Activation Mapping (Grad-CAM) algorithm.
 
         :param is_2d_layer: (mandatory) A boolean indicating whether the target layers 2D-convolutional layer.
+        :param is_3d_layer: (mandatory) A boolean indicating whether the target layers 3D-convolutional layer.
         :param batch_idx: (mandatory) The index corresponding to the i-th selected item within the original input data
             list.
 
-        :return: cam: A TensorFlow/Keras tensor representing the Class Activation Map (CAM) for the batch_idx-th input,
-            built with the Grad-CAM algorithm.
+        :return:
+            - cam: A TensorFlow/Keras tensor representing the Class Activation Map (CAM) for the batch_idx-th input,
+                built with the Grad-CAM algorithm.
         """
 
-        if is_2d_layer:
+        if is_2d_layer is not None and is_2d_layer:
             dim_mean = (0, 1)
+        elif is_3d_layer:
+            dim_mean = (0, 1, 2)
         else:
             dim_mean = 0
         weights = tf.reduce_mean(self.gradients[batch_idx], axis=dim_mean)
         activations = self.activations[batch_idx].numpy()
 
         for i in range(activations.shape[-1]):
-            if is_2d_layer:
+            if is_2d_layer is not None and is_2d_layer:
                 activations[:, :, i] *= weights[i]
+            elif is_3d_layer:
+                activations[:, :, :, i] *= weights[i]
             else:
                 activations[:, i] *= weights[i]
-                activations[:, i] *= weights[i]
 
         cam = tf.reduce_sum(tf.convert_to_tensor(activations), axis=-1)
         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:
+    def _get_hirecam_map(self, is_2d_layer: bool, is_3d_layer: bool, batch_idx: int) -> tf.Tensor:
         """
         Compute the CAM using the High-Resolution Class Activation Mapping (HiResCAM) algorithm.
 
         :param is_2d_layer: (mandatory) A boolean indicating whether the target layers 2D-convolutional layer.
+        :param is_3d_layer: (mandatory) A boolean indicating whether the target layers 3D-convolutional layer.
         :param batch_idx: (mandatory) The index corresponding to the i-th selected item within the original input data
             list.
 
-        :return: cam: A TensorFlow/Keras tensor representing the Class Activation Map (CAM) for the batch_idx-th input,
-            built with the HiResCAM algorithm.
+        :return:
+            - cam: A TensorFlow/Keras tensor representing the Class Activation Map (CAM) for the batch_idx-th input,
+                built with the HiResCAM algorithm.
         """
 
         activations = self.activations[batch_idx].numpy()
         gradients = self.gradients[batch_idx].numpy()
 
         for i in range(activations.shape[-1]):
-            if is_2d_layer:
+            if is_2d_layer is not None and is_2d_layer:
                 activations[:, :, i] *= gradients[:, :, i]
+            elif is_3d_layer:
+                activations[:, :, :, i] *= gradients[:, :, :, i]
             else:
                 activations[:, i] *= gradients[:, i]
 
@@ -314,20 +332,23 @@ class TfCamBuilder(CamBuilder):
         return cam
 
     @staticmethod
-    def _is_2d_layer(target_layer: tf.keras.layers.Layer) -> bool:
+    def _is_2d_layer(target_layer: tf.keras.layers.Layer) -> bool | None:
         """
         Evaluates whether the target layer is a 2D-convolutional layer.
 
         :param target_layer: (mandatory) A TensorFlow/Keras layer.
 
         :return:
-            - is_2d_layer: A boolean indicating whether the target layers 2D-convolutional layer.
+            - is_2d_layer: A boolean indicating whether the target layers 2D-convolutional layer. If the target layer is
+                a 3D-convolutional layer, the function returns a None.
         """
 
         if isinstance(target_layer, keras.layers.Conv1D):
             is_2d_layer = False
         elif isinstance(target_layer, keras.layers.Conv2D):
             is_2d_layer = True
+        elif isinstance(target_layer, keras.layers.Conv3D):
+            is_2d_layer = None
         else:
             is_2d_layer = CamBuilder._is_2d_layer(target_layer)
         return is_2d_layer

{signal_grad_cam-1.0.1.dist-info → signal_grad_cam-2.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
-Name: signal-grad-cam
-Version: 1.0.1
+Name: signal_grad_cam
+Version: 2.0.0
 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
@@ -19,6 +19,7 @@ Requires-Dist: opencv-python
 Requires-Dist: torch
 Requires-Dist: keras
 Requires-Dist: tensorflow
+Requires-Dist: imageio
 
 <div id="top"></div>
 
@@ -31,7 +32,7 @@ Requires-Dist: tensorflow
     SignalGrad-CAM
   </h1>
 
-  <h3 align="center">SignalGrad-CAM aims at generalising Grad-CAM to one-dimensional applications, while enhancing usability and efficiency.</h3>
+  <h3 align="center">SignalGrad-CAM aims at generalising Grad-CAM to time-based applications, while enhancing usability and efficiency.</h3>
 
   <p align="center">
     <a href="https://github.com/bmi-labmedinfo/signal_grad_cam"><strong>Explore the docs</strong></a>
@@ -61,9 +62,9 @@ Requires-Dist: tensorflow
 <!-- ABOUT THE PROJECT -->
 ## About The Project
 
-<p align="justify">Deep learning models have demonstrated remarkable performance across various domains; however, their black-box nature hinders interpretability and trust. As a result, the demand for explanation algorithms has grown, driving advancements in the field of eXplainable AI (XAI). However, relatively few efforts have been dedicated to developing interpretability methods for signal-based models. We introduce SignalGrad-CAM (SGrad-CAM), a versatile and efficient interpretability tool that extends the principles of Grad-CAM to both 1D- and 2D-convolutional neural networks for signal processing. SGrad-CAM is designed to interpret models for either image or signal elaboration, supporting both PyTorch and TensorFlow/Keras frameworks, and provides diagnostic and visualization tools to enhance model transparency. The package is also designed for batch processing, ensuring efficiency even for large-scale applications, while maintaining a simple and user-friendly structure.</p>
+<p align="justify">Deep learning models have achieved remarkable performance across many domains, yet their black-box nature often limits interpretability and trust. This has fueled the development of explanation algorithms within the field of eXplainable AI (XAI). Despite this progress, relatively few methods target time-based convolutional neural networks (CNNs), such as 1D-CNNs for signals and 3D-CNNs for videos. We present SignalGrad-CAM (SGrad-CAM), a versatile and efficient interpretability tool that extends the principles of Grad-CAM to 1D, 2D, and 3D CNNs. SGrad-CAM supports model interpretation for signals, images, and video/volume data in both PyTorch and TensorFlow/Keras frameworks. It includes diagnostic and visualization tools to enhance transparency, and its batch-processing design ensures scalability for large datasets while maintaining a simple, user-friendly structure.</p>
 
-<p align="justify"><i><b>Keywords:</b> eXplainable AI, explanations, local explanation, fidelity, interpretability, transparency, trustworthy AI, feature importance, saliency maps, CAM, Grad-CAM, black-box, deep learning, CNN, signals, time series</i></p>
+<p align="justify"><i><b>Keywords:</b> eXplainable AI, XAI, explanations, local explanation, contrastive explanations, cXAI, fidelity, interpretability, transparency, trustworthy AI, feature importance, saliency maps, CAM, Grad-CAM, HiResCAM, black-box, deep learning, CNN, 1D-CNN, 2D-CNN, 3D-CNN, signals, time series, images, videos, volumes.</i></p>
 
 <p align="right"><a href="#top">Back To Top</a></p>
 
@@ -83,15 +84,13 @@ Requires-Dist: tensorflow
 
 <!-- USAGE EXAMPLES -->
 ## Usage
-<p align="justify">
-Here's a basic example that illustrates SignalGrad-CAM common usage.
+<p align="justify">Here's a basic example that illustrates SignalGrad-CAM common usage.</p>
 
-First, train a classifier on the data or select an already trained model, then instantiate `TorchCamBuilder` (if you are working with a PyTorch model) or `TfCamBuilder` (if the model is built in TensorFlow/Keras).
+<p align="justify">First, train a CNN on the data or load a pre-trained model, then instantiate `TorchCamBuilder` (if you are working with a PyTorch model) or `TfCamBuilder` (if the model is built in TensorFlow/Keras).</p>
 
-Besides the model, `TorchCamBuilder` requires additional information to function effectively. For example, you may provide a list of class labels, a preprocessing function, or an index indicating which dimension corresponds to time. These attributes allow SignalGrad-CAM to be applied to a wide range of models.
+<p align="justify">Besides the model, `TorchCamBuilder` requires additional information to function effectively. For example, you may provide a list of class labels, a pre-processing function, or an index indicating which dimension corresponds to time (for signal elaboration). These attributes allow SignalGrad-CAM to be applied to a wide range of models.</p>
 
-The constructor displays a list of available Grad-CAM algorithms for explanation, as well as a list of layers that can be used as target for the algorithm. It also identifies any Sigmoid/Softmax layer, since its presence or absence will slightly change the algorithm's workflow.
-</p>
+<p align="justify">The constructor displays a list of available Grad-CAM algorithms for explanation (Grad-CAM and HiResCAM at the moment), as well as a list of layers that can be used as target for the algorithm. It also identifies any Sigmoid/Softmax layer, since its presence or absence will slightly change the algorithm's workflow.</p>
 
 ```python
 import numpy as np
@@ -114,14 +113,14 @@ class_labels = ["Class 1", "Class 2", "Class 3"]
 cam_builder = TorchCamBuilder(model=model, transform_fn=preprocess_fn, class_names=class_labels, time_axs=1)
 ```
 
-<p align="justify">Now, you can use the `cam_builder` object to generate class activation maps from a list of input data using the <i>`get_cams`</i> method. You can specify multiple algorithm names, target layers, or target classes as needed.
+<p align="justify">Now, you can use the `cam_builder` object to generate class activation maps from a list of input data using the <i>`get_cams`</i> method. You can specify multiple algorithm names, target layers, or target classes as needed. As described in each function's documentation, every input (such as data and labels) need to be rearranged into lists for versatility.</p>
 
-The function's attributes allow users to customize the visualization (e.g., setting axis ticks or labels). If a result directory path is provided, the output is stored as a '.png' file; otherwise, it is displayed. In all cases, the function returns a dictionary containing the requested CAMs, along with the model's predictions and importance score ranges.
+<p align="justify">The function's attributes allow users to customize the visualization (e.g., setting axes ticks or labels). If a result directory path is provided, the output is stored as a '.png' file; otherwise, it is simply displayed. In all cases, the function returns a dictionary containing the requested CAMs, along with the model's predictions and importance score ranges.</p>
 
-Finally, several visualization tools are available to gain deeper insights into the model's behavior. The display can be customized by adjusting line width, point extension, aspect ratio, and more:
-* <i>`single_channel_output_display`</i> plots the selected channels using a color scheme that reflects the importance of each input feature.
-* <i>`overlapped_output_display`</i> superimposes CAMs onto the corresponding input in an image-like format, allowing users to capture the overall distribution of input importance.
-</p>
+<p align="justify">Finally, several visualization tools are available to gain deeper insights into the model's behavior. Their display can be customized by adjusting features like line width and point extension (for the drawing of signals and their explanation) along with others (e.g., aspect ratio) for a more general task:</p>
+
+* <p align="justify"><i>`single_channel_output_display`</i> plots the selected input channels using a color scheme that reflects the importance of each input feature.</p>
+* <p align="justify"><i>`overlapped_output_display`</i> superimposes CAMs onto the corresponding input in an image-like format, allowing users to capture the overall distribution of input importance.</p>
 
 ```python
 # Prepare data
@@ -132,31 +131,38 @@ target_classes = [0, 1]
 
 # Create CAMs
 cam_dict, predicted_probs_dict, score_ranges_dict = cam_builder.get_cam(data_list=data_list, data_labels=data_labels_list, 
-									target_classes=target_classes, explainer_types="Grad-CAM", 
-									target_layers="conv1d_layer_1", softmax_final=True,
-                                                            		data_sampling_freq=25, dt=1, axes_names=("Time (s)", "Channels"))
+																		target_classes=target_classes, explainer_types="Grad-CAM", 
+																		target_layers="conv1d_layer_1", softmax_final=True,
+																		data_sampling_freq=25, dt=1, axes_names=("Time (s)", "Channels"))
 
 # Visualize single channel importance
 selected_channels_indices = [0, 2, 10]
 cam_builder.single_channel_output_display(data_list=data_list, data_labels=data_labels_list, predicted_probs_dict=predicted_probs_dict,
-					  cams_dict=cam_dict, explainer_types="Grad-CAM", target_classes=target_classes, 
-					  target_layers="target_layer_name", desired_channels=selected_channels_indices, 
-					  grid_instructions=(1, len(selected_channels_indices), bar_ranges_dict=score_ranges_dict, 
-				          results_dir="path_to_your_result_directoory", data_sampling_freq=25, dt=1, line_width=0.5, 
-					  axes_names=("Time (s)", "Amplitude (mV)"))
+										  cams_dict=cam_dict, explainer_types="Grad-CAM", target_classes=target_classes, 
+										  target_layers="target_layer_name", desired_channels=selected_channels_indices, 
+										  grid_instructions=(1, len(selected_channels_indices), bar_ranges_dict=score_ranges_dict, 
+										  results_dir="path_to_your_result_directoory", data_sampling_freq=25, dt=1, line_width=0.5, 
+										  axes_names=("Time (s)", "Amplitude (mV)"))
 
 # Visualize overall importance
 cam_builder.overlapped_output_display(data_list=data_list, data_labels=data_labels_list, predicted_probs_dict=predicted_probs_dict,
                                       cams_dict=cam_dict, explainer_types="Grad-CAM", target_classes=target_classes, 
-				      target_layers="target_layer_name", fig_size=(20 * len(your_data_X), 20), 
-				      grid_instructions=(len(your_data_X), 1), bar_ranges_dict=score_ranges_dict, data_names=item_names 
-				      results_dir_path="path_to_your_result_directoory", data_sampling_freq=25, dt=1)
+									  target_layers="target_layer_name", fig_size=(20 * len(your_data_X), 20), 
+									  grid_instructions=(len(your_data_X), 1), bar_ranges_dict=score_ranges_dict, data_names=item_names 
+									  results_dir_path="path_to_your_result_directoory", data_sampling_freq=25, dt=1)
 ```
 
-You can also explore the Python scripts available in the examples directory of the repository [here](https://github.com/bmi-labmedinfo/signal_grad_cam/examples), which provide complete, ready-to-run demonstrations for both PyTorch and TensorFlow/Keras models. These examples include open-source models for image and signal classification using 1D- and 2D-CNN architectures, and they illustrate how to apply the recently added feature for creating and displaying "contrastive explanations" in each scenario.
+<p align="justify">You can also explore the Python scripts available in the examples directory of the repository [here](https://github.com/bmi-labmedinfo/signal_grad_cam/examples), which provide complete, ready-to-run demonstrations for both PyTorch and TensorFlow/Keras models. These examples include open-source models for signal, image and video/volume classification using 1D, 2D, and 3D CNN architectures. Moreover, these tutorials illustrate how to deploy the recently added feature contrastive explanations in each scenario.</p>
 
 See the [open issues](https://github.com/bmi-labmedinfo/signal_grad_cam/issues) for a full list of proposed features (and known issues).
 
+## <i>NEW!</i> Updates in SignalGrad-CAM
+<p align="justify">Compared to previous versions, SignalGrad-CAM now offers the following enhancements:</p>
+
+* <p align="justify"><i>Support for regression tasks:</i> SGrad-CAM can now handle regression-based models. Previously, substantial adjustments were required for these tasks, similar to those still needed for segmentation or generative models.</p>
+* <p align="justify"><i>Contrastive explanations:</i> Users can generate and visualize contrastive explanations by specifying one or more foil classes via the parameter <i>`contrastive_foil_classes`</i>.</p>
+* <p align="justify"><i>3D-CNN support for videos and volumetric data:</i> After expliciting the time axis in the constructor with the parameter <i>`time_axs`</i>, the same functions used for 1D and 2D data now work seamlessly for 3D-CNNs. Outputs include GIF files for quick visualization of 3D activation maps. For a more detailed analysis, users can also request separate PNG images for each volume slice (across the indicated time axis) or video frame using the parameter <i>`show_single_video_frames`</i>.</p>
+
 <p align="right"><a href="#top">Back To Top</a></p>
 
 
@@ -164,7 +170,7 @@ If you use the SignalGrad-CAM software for your projects, please cite it as:
 
 ```
 @inproceedings{pe_sgradcam_2025_paper,
-  author = {Pe, Samuele and Buonocore, Tommaso Mario and Giovanna, Nicora and Enea, Parimbelli}},
+  author = {Pe, Samuele and Buonocore, Tommaso Mario and Giovanna, Nicora and Enea, Parimbelli},
   title = {SignalGrad-CAM: Beyond Image Explanation},
   booktitle = {Joint Proceedings of the xAI 2025 Late-breaking Work, Demos and Doctoral Consortium co-located with the 3rd World Conference on eXplainable Artificial Intelligence (xAI 2025), Istanbul, Turkey, July 9-11, 2025},
   series = {CEUR Workshop Proceedings},
@@ -179,9 +185,9 @@ If you use the SignalGrad-CAM software for your projects, please cite it as:
 ```   
 @software{pe_sgradcam_2025_repo,
   author = {Pe, Samuele},
-  title = {{SignalGrad-CAM}},
+  title = {SignalGrad-CAM},
   url = {https://github.com/bmi-labmedinfo/signal_grad_cam},
-  version = {1.0.0},
+  version = {1.0.1},
   year = {2025}
 }
 ```

signal_grad_cam-2.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+signal_grad_cam/__init__.py,sha256=JyFFQebs1Rm5r9FCgE68Ii39lLckW8N_gj-nAL5hq2U,137
+signal_grad_cam/cam_builder.py,sha256=k57xMcvHmx1-V08P5rdCDpFaNpO5c-AjX1cIfV3EF9k,92988
+signal_grad_cam/pytorch_cam_builder.py,sha256=0qS0kiNd8uumLI0gt5jK6cxO491YLYoafMnI7Najr-Q,20490
+signal_grad_cam/tensorflow_cam_builder.py,sha256=zG12wFD2T_5_wbh_JCtfcQsuRBZ3nySNZVPlG1uIBDI,20538
+signal_grad_cam-2.0.0.dist-info/LICENSE,sha256=pCSaMipV39klP0dlf75SHw5PTl00_cLlS-EiC-LmOkw,1088
+signal_grad_cam-2.0.0.dist-info/METADATA,sha256=t5Ajz2_Br7lhNoigf1IVMkD3GtVCfyfreb_R5jH-qtc,13594
+signal_grad_cam-2.0.0.dist-info/WHEEL,sha256=R0nc6qTxuoLk7ShA2_Y-UWkN8ZdfDBG2B6Eqpz2WXbs,91
+signal_grad_cam-2.0.0.dist-info/top_level.txt,sha256=S6lf3mfh2uGXJKnUS3qnw6arQu-x3gO8m82WdY7JAIA,16
+signal_grad_cam-2.0.0.dist-info/RECORD,,

{signal_grad_cam-1.0.1.dist-info → signal_grad_cam-2.0.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.41.2)
+Generator: setuptools (72.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

signal_grad_cam-1.0.1.dist-info/RECORD

@@ -1,9 +0,0 @@
-signal_grad_cam/__init__.py,sha256=JyFFQebs1Rm5r9FCgE68Ii39lLckW8N_gj-nAL5hq2U,137
-signal_grad_cam/cam_builder.py,sha256=419Xejd3SaY09Jo6TnDhnSGJTkYxHjuHJZrRkY4yLI0,75092
-signal_grad_cam/pytorch_cam_builder.py,sha256=WAlfyiqHC9i7wQn1Xxpx8xBas_AtWhC7WnbUoKznOxk,19513
-signal_grad_cam/tensorflow_cam_builder.py,sha256=x6QZBdjuS_YwsJ6S3snLSpWray-baueBx0wvpTMcn1k,19087
-signal_grad_cam-1.0.1.dist-info/LICENSE,sha256=pCSaMipV39klP0dlf75SHw5PTl00_cLlS-EiC-LmOkw,1088
-signal_grad_cam-1.0.1.dist-info/METADATA,sha256=nEqgaq_65jYArUt3mLkGxXZMLjkou1hZOf_m1j3ncT0,11956
-signal_grad_cam-1.0.1.dist-info/WHEEL,sha256=yQN5g4mg4AybRjkgi-9yy4iQEFibGQmlz78Pik5Or-A,92
-signal_grad_cam-1.0.1.dist-info/top_level.txt,sha256=S6lf3mfh2uGXJKnUS3qnw6arQu-x3gO8m82WdY7JAIA,16
-signal_grad_cam-1.0.1.dist-info/RECORD,,