signal-grad-cam 0.1.7__tar.gz → 1.0.0__tar.gz

{signal_grad_cam-0.1.7 → signal_grad_cam-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: signal_grad_cam
-Version: 0.1.7
+Version: 1.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
@@ -111,7 +111,7 @@ def preprocess_fn(signal):
 class_labels = ["Class 1", "Class 2", "Class 3"]
 
 # Define the CAM builder
-cam_builder = TorchCamBuilder(model=model, transform_fc=preprocess_fc, class_names=class_labels, time_axs=1)
+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.
@@ -133,7 +133,7 @@ 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_layer="conv1d_layer_1", softmax_final=True,
+									target_layers="conv1d_layer_1", softmax_final=True,
                                                             		data_sampling_freq=25, dt=1, axes_names=("Time (s)", "Channels"))
 
 # Visualize single channel importance
@@ -141,7 +141,7 @@ 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=score_ranges_dict, 
+					  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)"))
 
@@ -149,11 +149,11 @@ cam_builder.single_channel_output_display(data_list=data_list, data_labels=data_
 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=score_ranges_dict, data_names=item_names 
-				      results_dir="path_to_your_result_directoory", data_sampling_freq=25, dt=1)
+				      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 check the python scripts [here](https://github.com/bmi-labmedinfo/signal_grad_cam/examples).
+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.
 
 See the [open issues](https://github.com/bmi-labmedinfo/signal_grad_cam/issues) for a full list of proposed features (and known issues).
 
@@ -163,11 +163,25 @@ See the [open issues](https://github.com/bmi-labmedinfo/signal_grad_cam/issues)
 If you use the SignalGrad-CAM software for your projects, please cite it as:
 
 ```
-@software{Pe_SignalGrad_CAM_2025,
-  author = {Pe, Samuele and Buonocore, Tommaso Mario and Giovanna, Nicora and Enea, Parimbelli},
+@inproceedings{pe_sgradcam_2025_paper,
+  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},
+  volume = {4017},
+  pages = {209--216},
+  url = {https://ceur-ws.org/Vol-4017/paper_27.pdf},
+  publisher = {CEUR-WS.org},
+  year = {2025}
+}
+```
+
+```   
+@software{pe_sgradcam_2025_repo,
+  author = {Pe, Samuele},
   title = {{SignalGrad-CAM}},
   url = {https://github.com/bmi-labmedinfo/signal_grad_cam},
-  version = {0.0.1},
+  version = {1.0.0},
   year = {2025}
 }
 ```

{signal_grad_cam-0.1.7 → signal_grad_cam-1.0.0}/README.md

@@ -89,7 +89,7 @@ def preprocess_fn(signal):
 class_labels = ["Class 1", "Class 2", "Class 3"]
 
 # Define the CAM builder
-cam_builder = TorchCamBuilder(model=model, transform_fc=preprocess_fc, class_names=class_labels, time_axs=1)
+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.
@@ -111,7 +111,7 @@ 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_layer="conv1d_layer_1", softmax_final=True,
+									target_layers="conv1d_layer_1", softmax_final=True,
                                                             		data_sampling_freq=25, dt=1, axes_names=("Time (s)", "Channels"))
 
 # Visualize single channel importance
@@ -119,7 +119,7 @@ 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=score_ranges_dict, 
+					  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)"))
 
@@ -127,11 +127,11 @@ cam_builder.single_channel_output_display(data_list=data_list, data_labels=data_
 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=score_ranges_dict, data_names=item_names 
-				      results_dir="path_to_your_result_directoory", data_sampling_freq=25, dt=1)
+				      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 check the python scripts [here](https://github.com/bmi-labmedinfo/signal_grad_cam/examples).
+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.
 
 See the [open issues](https://github.com/bmi-labmedinfo/signal_grad_cam/issues) for a full list of proposed features (and known issues).
 
@@ -141,11 +141,25 @@ See the [open issues](https://github.com/bmi-labmedinfo/signal_grad_cam/issues)
 If you use the SignalGrad-CAM software for your projects, please cite it as:
 
 ```
-@software{Pe_SignalGrad_CAM_2025,
-  author = {Pe, Samuele and Buonocore, Tommaso Mario and Giovanna, Nicora and Enea, Parimbelli},
+@inproceedings{pe_sgradcam_2025_paper,
+  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},
+  volume = {4017},
+  pages = {209--216},
+  url = {https://ceur-ws.org/Vol-4017/paper_27.pdf},
+  publisher = {CEUR-WS.org},
+  year = {2025}
+}
+```
+
+```   
+@software{pe_sgradcam_2025_repo,
+  author = {Pe, Samuele},
   title = {{SignalGrad-CAM}},
   url = {https://github.com/bmi-labmedinfo/signal_grad_cam},
-  version = {0.0.1},
+  version = {1.0.0},
   year = {2025}
 }
 ```

{signal_grad_cam-0.1.7 → signal_grad_cam-1.0.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r") as f:
 
 setup(
     name="signal_grad_cam",
-    version="0.1.7",
+    version="1.0.0",
     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.7 → signal_grad_cam-1.0.0}/signal_grad_cam/cam_builder.py

@@ -111,10 +111,11 @@ class CamBuilder:
 
     def get_cam(self, data_list: List[np.ndarray], data_labels: List[int], target_classes: int | List[int],
                 explainer_types: str | List[str], target_layers: str | List[str], softmax_final: bool,
-                data_names: List[str] = None, data_sampling_freq: float = None, dt: float = 10,
-                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,
+                data_names: List[str] = None, contrastive_foil_classes: int | List[int] = None,
+                data_sampling_freq: float = None, dt: float = 10, 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, eps: float = 1e-6) \
             -> Tuple[Dict[str, List[np.ndarray]], Dict[str, np.ndarray],  Dict[str, Tuple[np.ndarray, np.ndarray]]]:
         """
@@ -137,6 +138,9 @@ class CamBuilder:
             activation function.
         :param data_names: (optional, default is None) A list of strings where each string represents the name of an
             input item.
+        :param contrastive_foil_classes: (optional, default is None) An integer or list of integers representing the
+            comparative classes (foils) for the explanation in the context of Contrastive Explanations. If None, the
+            explanation would follow the classical paradigm.
         :param data_sampling_freq: (optional, default is None) A numerical value representing the sampling frequency of
             signal inputs in samples per second.
         :param dt: (optional, default is 10) A numerical value representing the granularity of the time axis in seconds
@@ -176,8 +180,8 @@ class CamBuilder:
             data_names = ["item" + str(i) for i in range(len(data_list))]
 
         # Check input types
-        target_classes, explainer_types, target_layers = self.__check_input_types(target_classes, explainer_types,
-                                                                                  target_layers)
+        target_classes, explainer_types, target_layers, contrastive_foil_classes = self.__check_input_types(
+            target_classes, explainer_types, target_layers, contrastive_foil_classes)
         for explainer_type in explainer_types:
             if explainer_type not in self.explainer_types:
                 raise ValueError("'explainer_types' should be an explainer identifier or a list of explainer "
@@ -190,21 +194,28 @@ class CamBuilder:
         for explainer_type in explainer_types:
             for target_class in target_classes:
                 for target_layer in target_layers:
-                    cam_list, output_probs, bar_ranges = self.__create_batched_cams(data_list, target_class,
-                                                                                    target_layer, explainer_type,
-                                                                                    softmax_final,
-                                                                                    data_shape_list=data_shape_list,
-                                                                                    extra_preprocess_inputs_list=
-                                                                                    extra_preprocess_inputs_list,
-                                                                                    extra_inputs_list=extra_inputs_list,
-                                                                                    eps=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})
-                    bar_ranges_dict.update({item_key: bar_ranges})
-                    self.__display_output(data_labels, target_class, explainer_type, target_layer, cam_list, output_probs,
-                                          results_dir_path, data_names, data_sampling_freq, dt, aspect_factor,
-                                          bar_ranges, channel_names, time_names=time_names, axes_names=axes_names)
+                    for contrastive_foil_class in contrastive_foil_classes:
+                        cam_list, output_probs, bar_ranges = self.__create_batched_cams(data_list, target_class,
+                                                                                        target_layer, explainer_type,
+                                                                                        softmax_final,
+                                                                                        data_shape_list=data_shape_list,
+                                                                                        extra_preprocess_inputs_list=
+                                                                                        extra_preprocess_inputs_list,
+                                                                                        extra_inputs_list=
+                                                                                        extra_inputs_list,
+                                                                                        contrastive_foil_class=
+                                                                                        contrastive_foil_class,
+                                                                                        eps=eps)
+                        item_key = explainer_type + "_" + target_layer + "_class" + str(target_class)
+                        if contrastive_foil_class is not None:
+                            item_key += "_foil" + str(contrastive_foil_class)
+                        cams_dict.update({item_key: cam_list})
+                        predicted_probs_dict.update({item_key: output_probs})
+                        bar_ranges_dict.update({item_key: bar_ranges})
+                        self.__display_output(data_labels, target_class, explainer_type, target_layer, cam_list, output_probs,
+                                              results_dir_path, data_names, data_sampling_freq, dt, aspect_factor,
+                                              bar_ranges, channel_names, time_names=time_names, axes_names=axes_names,
+                                              contrastive_foil_class=contrastive_foil_class)
 
         return cams_dict, predicted_probs_dict, bar_ranges_dict
 
@@ -213,7 +224,8 @@ class CamBuilder:
                                   predicted_probs_dict: Dict[str, np.ndarray], cams_dict: Dict[str, List[np.ndarray]],
                                   explainer_types: str | List[str], target_classes: int | List[int],
                                   target_layers: str | List[str], target_item_ids: List[int] = None,
-                                  data_names: List[str] = None, grid_instructions: Tuple[int, int] = None,
+                                  data_names: List[str] = None, contrastive_foil_classes: int | List[int] = None,
+                                  grid_instructions: Tuple[int, int] = None,
                                   bar_ranges_dict: Dict[str, Tuple[np.ndarray, np.ndarray]] = None,
                                   results_dir_path: str = None, data_sampling_freq: float = None, dt: float = 10,
                                   channel_names: List[str | float] = None, time_names: List[str | float] = None,
@@ -242,11 +254,14 @@ class CamBuilder:
             among the items in the input data list.
         :param data_names: (optional, default is None) A list of strings where each string represents the name of an
             input item.
+        :param contrastive_foil_classes: (optional, default is None) An integer or list of integers representing the
+            comparative classes (foils) for the explanation in the context of Contrastive Explanations. If None, the
+            explanation would follow the classical paradigm.
         :param grid_instructions: (optional, default is None) A tuple of integers defining the desired tabular layout
             for figure subplots. The expected format is number of columns (width) x number of rows (height).
         :param bar_ranges_dict: A dictionary storing a tuple of np.ndarrays. Each tuple contains 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).
+            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).
         :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 data_sampling_freq: (optional, default is None) A numerical value representing the sampling frequency of
@@ -263,8 +278,8 @@ class CamBuilder:
         """
 
         # Check input types
-        target_classes, explainer_types, target_layers = self.__check_input_types(target_classes, explainer_types,
-                                                                                  target_layers)
+        target_classes, explainer_types, target_layers, contrastive_foil_classes = self.__check_input_types(
+            target_classes, explainer_types, target_layers, contrastive_foil_classes)
         if target_item_ids is None:
             target_item_ids = list(range(len(data_list)))
 
@@ -279,36 +294,40 @@ class CamBuilder:
         for explainer_type in explainer_types:
             for target_layer in target_layers:
                 for target_class in target_classes:
-                    plt.figure(figsize=fig_size)
-                    for i in range(n_items):
-                        cam, item, batch_idx, item_key = self.__get_data_for_plots(data_list, i, target_item_ids,
-                                                                                   cams_dict, explainer_type,
-                                                                                   target_layer, target_class)
-
-                        plt.subplot(w, h, i + 1)
-                        plt.imshow(item)
-                        aspect = "auto" if cam.shape[0] / cam.shape[1] < 0.1 else None
-
-                        norm = self.__get_norm(cam)
-                        map = plt.imshow(cam, cmap="jet", aspect=aspect, norm=norm)
-                        self.__set_colorbar(bar_ranges_dict[item_key], i)
-                        map.set_alpha(0.3)
-
-                        self.__set_axes(cam, data_sampling_freq, dt, channel_names, time_names=time_names,
-                                        axes_names=axes_names)
-                        data_name = data_names[batch_idx] if data_names is not None else "item" + str(batch_idx)
-                        plt.title(self.__get_cam_title(data_name, target_class, data_labels, batch_idx, item_key,
-                                                       predicted_probs_dict))
-
-                    # Store or show CAM
-                    self.__display_plot(results_dir_path, explainer_type, target_layer, target_class)
+                    for contrastive_foil_class in contrastive_foil_classes:
+                        plt.figure(figsize=fig_size)
+                        for i in range(n_items):
+                            cam, item, batch_idx, item_key = self.__get_data_for_plots(data_list, i, target_item_ids,
+                                                                                       cams_dict, explainer_type,
+                                                                                       target_layer, target_class,
+                                                                                       contrastive_foil_class)
+
+                            plt.subplot(w, h, i + 1)
+                            plt.imshow(item)
+                            aspect = "auto" if cam.shape[0] / cam.shape[1] < 0.1 else None
+
+                            norm = self.__get_norm(cam)
+                            map = plt.imshow(cam, cmap="jet", aspect=aspect, norm=norm)
+                            self.__set_colorbar(bar_ranges_dict[item_key], i)
+                            map.set_alpha(0.3)
+
+                            self.__set_axes(cam, data_sampling_freq, dt, channel_names, time_names=time_names,
+                                            axes_names=axes_names)
+                            data_name = data_names[batch_idx] if data_names is not None else "item" + str(batch_idx)
+                            plt.title(self.__get_cam_title(data_name, target_class, data_labels, batch_idx, item_key,
+                                                           predicted_probs_dict, contrastive_foil_class))
+
+                        # Store or show CAM
+                        self.__display_plot(results_dir_path, explainer_type, target_layer, target_class,
+                                            contrastive_foil_class)
 
     def single_channel_output_display(self, data_list: List[np.ndarray], data_labels: List[int],
                                       predicted_probs_dict: Dict[str, np.ndarray],
                                       cams_dict: Dict[str, List[np.ndarray]], explainer_types: str | List[str],
                                       target_classes: int | List[int], target_layers: str | List[str],
                                       target_item_ids: List[int] = None, desired_channels: List[int] = None,
-                                      data_names: List[str] = None, grid_instructions: Tuple[int, int] = None,
+                                      data_names: List[str] = None, contrastive_foil_classes: int | List[int] = None,
+                                      grid_instructions: Tuple[int, int] = None,
                                       bar_ranges_dict: Dict[str, Tuple[np.ndarray, np.ndarray]] = None,
                                       results_dir_path: str = None, data_sampling_freq: float = None, dt: float = 10,
                                       channel_names: List[str | float] = None, time_names: List[str | float] = None,
@@ -340,6 +359,9 @@ class CamBuilder:
             to be displayed.
         :param data_names: (optional, default is None) A list of strings where each string represents the name of an
             input item.
+        :param contrastive_foil_classes: (optional, default is None) An integer or list of integers representing the
+            comparative classes (foils) for the explanation in the context of Contrastive Explanations. If None, the
+            explanation would follow the classical paradigm.
         :param grid_instructions: (optional, default is None) A tuple of integers defining the desired tabular layout
             for figure subplots. The expected format is number of columns (width) x number of rows (height).
         :param bar_ranges_dict: A dictionary storing a tuple of np.ndarrays. Each tuple contains two np.ndarrays
@@ -365,8 +387,8 @@ class CamBuilder:
         """
 
         # Check input types
-        target_classes, explainer_types, target_layers = self.__check_input_types(target_classes, explainer_types,
-                                                                                  target_layers)
+        target_classes, explainer_types, target_layers, contrastive_foil_classes = self.__check_input_types(
+            target_classes, explainer_types, target_layers, contrastive_foil_classes)
         if desired_channels is None:
             try:
                 desired_channels = list(range(data_list[0].shape[1]))
@@ -387,42 +409,44 @@ class CamBuilder:
         for explainer_type in explainer_types:
             for target_layer in target_layers:
                 for target_class in target_classes:
-                    for i in range(n_items):
-                        plt.figure(figsize=fig_size)
-                        cam, item, batch_idx, item_key = self.__get_data_for_plots(data_list, i, target_item_ids,
-                                                                                   cams_dict, explainer_type,
-                                                                                   target_layer, target_class)
-
-                        # Cross-CAM normalization
-                        minimum = np.min(cam)
-                        maximum = np.max(cam)
-
-                        data_name = data_names[batch_idx] if data_names is not None else "item" + str(batch_idx)
-                        desired_channels = desired_channels if desired_channels is not None else range(cam.shape[1])
-                        for j in range(len(desired_channels)):
-                            channel = desired_channels[j]
-                            plt.subplot(w, h, j + 1)
-                            try:
-                                cam_j = cam[channel, :]
-                            except IndexError:
-                                cam_j = cam[0, :]
-                            item_j = item[:, channel] if item.shape[0] == len(cam_j) else item[channel, :]
-                            plt.plot(item_j, color="black", linewidth=line_width)
-                            plt.scatter(np.arange(len(item_j)), item_j, c=cam_j, cmap="jet", marker=".",
-                                        s=marker_width, norm=None, vmin=minimum, vmax=maximum)
-                            self.__set_colorbar(bar_ranges_dict[item_key], i)
-
-                            if channel_names is None:
-                                channel_names = ["Channel " + str(c) for c in desired_channels]
-                            self.__set_axes(cam, data_sampling_freq, dt, channel_names, time_names,
-                                            axes_names=axes_names, only_x=True)
-                            plt.title(channel_names[j])
-                        plt.suptitle(self.__get_cam_title(data_name, target_class, data_labels, batch_idx, item_key,
-                                                          predicted_probs_dict))
-
-                        # Store or show CAM
-                        self.__display_plot(results_dir_path, explainer_type, target_layer, target_class, data_name,
-                                            is_channel=True)
+                    for contrastive_foil_class in contrastive_foil_classes:
+                        for i in range(n_items):
+                            plt.figure(figsize=fig_size)
+                            cam, item, batch_idx, item_key = self.__get_data_for_plots(data_list, i, target_item_ids,
+                                                                                       cams_dict, explainer_type,
+                                                                                       target_layer, target_class,
+                                                                                       contrastive_foil_class)
+
+                            # Cross-CAM normalization
+                            minimum = np.min(cam)
+                            maximum = np.max(cam)
+
+                            data_name = data_names[batch_idx] if data_names is not None else "item" + str(batch_idx)
+                            desired_channels = desired_channels if desired_channels is not None else range(cam.shape[1])
+                            for j in range(len(desired_channels)):
+                                channel = desired_channels[j]
+                                plt.subplot(w, h, j + 1)
+                                try:
+                                    cam_j = cam[channel, :]
+                                except IndexError:
+                                    cam_j = cam[0, :]
+                                item_j = item[:, channel] if item.shape[0] == len(cam_j) else item[channel, :]
+                                plt.plot(item_j, color="black", linewidth=line_width)
+                                plt.scatter(np.arange(len(item_j)), item_j, c=cam_j, cmap="jet", marker=".",
+                                            s=marker_width, norm=None, vmin=minimum, vmax=maximum)
+                                self.__set_colorbar(bar_ranges_dict[item_key], i)
+
+                                if channel_names is None:
+                                    channel_names = ["Channel " + str(c) for c in desired_channels]
+                                self.__set_axes(cam, data_sampling_freq, dt, channel_names, time_names,
+                                                axes_names=axes_names, only_x=True)
+                                plt.title(channel_names[j])
+                            plt.suptitle(self.__get_cam_title(data_name, target_class, data_labels, batch_idx, item_key,
+                                                              predicted_probs_dict, contrastive_foil_class))
+
+                            # Store or show CAM
+                            self.__display_plot(results_dir_path, explainer_type, target_layer, target_class,
+                                                contrastive_foil_class, data_name, is_channel=True)
 
     def _get_layers_pool(self, show: bool = False, extend_search: bool = False) \
             -> Dict[str, torch.nn.Module | tf.keras.layers.Layer | Any]:
@@ -464,7 +488,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, eps: float = 1e-6) \
+                                 extra_inputs_list: List[Any] = None, contrastive_foil_class: int = 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,
@@ -481,6 +506,9 @@ 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 contrastive_foil_class: (optional, default is None) An integer representing the comparative class (foil)
+            for the explanation in the context of Contrastive Explanations. If None, the explanation would follow the
+            classical paradigm.
         :param eps: (optional, default is 1e-6) A float number used in probability clamping before logarithm application
             to avoid null or None results.
 
@@ -529,7 +557,7 @@ 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,
-                              eps: float = 1e-6) \
+                              contrastive_foil_class: int = 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
@@ -552,6 +580,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.
+        :param contrastive_foil_class: (optional, default is None) An integer representing the comparative class (foil)
+            for the explanation in the context of Contrastive Explanations. If None, the explanation would follow the
+            classical paradigm.
         :param eps: (optional, default is 1e-6) A float number used in probability clamping before logarithm application
             to avoid null or None results.
 
@@ -589,7 +620,7 @@ class CamBuilder:
 
         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,
-                                                               eps=eps)
+                                                               contrastive_foil_class=contrastive_foil_class, eps=eps)
         self.activations = None
         self.gradients = None
         cams = np.stack(cam_list)
@@ -645,7 +676,7 @@ class CamBuilder:
                          data_names: List[str], data_sampling_freq: float = None, dt: float = 10,
                          aspect_factor: float = 100, bar_ranges: Tuple[np.ndarray, np.ndarray] = None,
                          channel_names: List[str | float] = None, time_names: List[str | float] = None,
-                         axes_names: Tuple[str | None, str | None] = None) -> None:
+                         axes_names: Tuple[str | None, str | None] = None, contrastive_foil_class: int = None) -> None:
         """
         Create plots displaying the obtained CAMs, set their axes, and show them as multiple figures or as ".png" files.
 
@@ -679,6 +710,9 @@ 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 contrastive_foil_class: (optional, default is None) An integer representing the comparative class (foil)
+            for the explanation in the context of Contrastive Explanations. If None, the explanation would follow the
+            classical paradigm.
         """
 
         if not os.path.exists(results_dir_path):
@@ -711,19 +745,26 @@ class CamBuilder:
             self.__set_colorbar(bar_ranges, i)
 
             # Set title
-            plt.title("CAM for class '" + str(self.class_names[target_class]) + "' (confidence = " +
-                      str(np.round(predicted_probs[i] * 100, 2)) + "%) - true label " +
-                      str(self.class_names[data_labels[i]]))
+            if contrastive_foil_class is None:
+                plt.title("CAM for class '" + self.class_names[target_class] + "' (confidence = " +
+                          str(np.round(predicted_probs[i] * 100, 2)) + "%) - true label " +
+                          self.class_names[data_labels[i]])
+            else:
+                plt.title("Why '" + self.class_names[target_class] + "' (confidence = " +
+                          str(np.round(predicted_probs[i][0] * 100, 2)) + "%), rather than '" +
+                          self.class_names[contrastive_foil_class] + "'(confidence = " +
+                          str(np.round(predicted_probs[i][1] * 100, 2)) + "%)?")
 
             # Set axis
             self.__set_axes(map, data_sampling_freq, dt, channel_names, time_names=time_names, axes_names=axes_names)
 
             # Store or show CAM
-            self.__display_plot(results_dir_path, explainer_type, target_layer, target_class, data_name)
+            self.__display_plot(results_dir_path, explainer_type, target_layer, target_class, contrastive_foil_class,
+                                data_name)
 
     def __get_data_for_plots(self, data_list: List[np.ndarray], i: int, target_item_ids: List[int],
                              cams_dict: Dict[str, List[np.ndarray]], explainer_type: str, target_layer: str,
-                             target_class: int) -> Tuple[np.ndarray, np.ndarray, int, str]:
+                             target_class: int, contrastive_foil_class: int) -> Tuple[np.ndarray, np.ndarray, int, str]:
         """
         Prepares input data and CAMs to be plotted, identifying the string key to retrieve CAMs, probabilities and
         ranges from the corresponding dictionaries.
@@ -740,6 +781,9 @@ class CamBuilder:
             identify either PyTorch named modules, TensorFlow/Keras layers, or it should be a class dictionary key,
             used to retrieve the layer from the class attributes.
         :param target_class: (mandatory) An integer representing the target class for the explanation.
+        :param contrastive_foil_class: (mandatory) An integer representing the comparative classes (foils) for the
+            explanation in the context of Contrastive Explanations. If None, the explanation would follow the classical
+            paradigm.
 
         :return:
             - cam: The CAM for the given setting (defined by algorithm, target layer, and target class), corresponding
@@ -752,6 +796,8 @@ class CamBuilder:
         batch_idx = target_item_ids[i]
         item = data_list[batch_idx]
         item_key = explainer_type + "_" + target_layer + "_class" + str(target_class)
+        if contrastive_foil_class is not None:
+            item_key += "_foil" + str(contrastive_foil_class)
         cam = cams_dict[item_key][batch_idx]
 
         item_dims = item.shape
@@ -823,7 +869,7 @@ class CamBuilder:
                 plt.ylabel(axes_names[1])
 
     def __get_cam_title(self, item_name: str, target_class: int, data_labels: List[int], batch_idx: int, item_key: str,
-                        predicted_probs: Dict[str, np.ndarray]) -> str:
+                        predicted_probs: Dict[str, np.ndarray], contrastive_foil_class: int) -> str:
         """
         Builds the CAM title for a given item and target class.
 
@@ -836,18 +882,28 @@ class CamBuilder:
             and target class).
         :param predicted_probs: (mandatory) A np.ndarray, representing the inferred class probabilities for each item in
             the input list.
+        :param contrastive_foil_class: (mandatory) An integer representing the comparative class (foil) for the
+            explanation in the context of Contrastive Explanations. If None, the explanation would follow the classical
+            paradigm.
 
         :return:
             - title: A string representing the title of the CAM for a given item and target class.
         """
+        if contrastive_foil_class is None:
+            title = ("'" + item_name + "': CAM for class '" + self.class_names[target_class] + "' (confidence = " +
+                     str(np.round(predicted_probs[item_key][batch_idx] * 100, 2)) + "%) - true class " +
+                     self.class_names[data_labels[batch_idx]])
+        else:
+            title = ("'" + item_name + "' (true class '" + self.class_names[data_labels[batch_idx]] + "'): Why '" +
+                     self.class_names[target_class] + "' (confidence = " +
+                     str(np.round(predicted_probs[item_key][batch_idx][0] * 100, 2)) + "%), rather than '" +
+                     self.class_names[contrastive_foil_class] + "' (confidence = " +
+                     str(np.round(predicted_probs[item_key][batch_idx][1] * 100, 2)) + "%)?")
 
-        title = ("'" + item_name + "': CAM for class '" + self.class_names[target_class] + "' (confidence = " +
-                 str(np.round(predicted_probs[item_key][batch_idx] * 100, 2)) + "%) - true class " +
-                 self.class_names[data_labels[batch_idx]])
         return title
 
     def __display_plot(self, results_dir_path: str, explainer_type: str, target_layer: str, target_class: int,
-                       item_name: str = None, is_channel: bool = False) -> None:
+                       contrastive_foil_class: int, item_name: str = None, is_channel: bool = False) -> None:
         """
         Show one CAM plot as a figure or as a ".png" file.
 
@@ -859,6 +915,9 @@ class CamBuilder:
             identify either PyTorch named modules, TensorFlow/Keras layers, or it should be a class dictionary key,
             used to retrieve the layer from the class attributes.
         :param target_class: (mandatory) An integer representing the target class for the explanation.
+        :param contrastive_foil_class: (mandatory) An integer representing the comparative class (foil) for the
+            explanation in the context of Contrastive Explanations. If None, the explanation would follow the classical
+            paradigm.
         :param item_name: (optional, default is False) A string representing the name of an input item.
         :param is_channel: (optional, default is False) A boolean flag indicating whether the figure represents graphs
             of multiple input channels, to discriminate it from other display modalities.
@@ -882,13 +941,18 @@ class CamBuilder:
                 if data_name not in os.listdir(results_dir_path):
                     os.mkdir(filepath)
             filename = (name_addon + explainer_type + "_" + re.sub(r"\W", "_", target_layer) + "_class" +
-                        str(target_class) + ".png")
+                        str(target_class))
+            if contrastive_foil_class is not None:
+                filename += "_foil" + str(contrastive_foil_class)
+            filename += ".png"
 
             # Communicate outcome
             descr_addon1 = "for item '" + item_name + "' " if item_name is not None else ""
-            self.__print_justify("Storing " + descr_addon + "output display " + descr_addon1 + "(class " +
-                                 self.class_names[target_class] + ", layer " + target_layer + ", algorithm " + explainer_type +
-                                 ") as '" + filename + "'...")
+            tmp_txt = ("Storing " + descr_addon + "output display " + descr_addon1 + "(class " +
+                       self.class_names[target_class] + ", layer " + target_layer + ", algorithm " + explainer_type)
+            if contrastive_foil_class is not None:
+                tmp_txt += ", foil class " + self.class_names[contrastive_foil_class]
+            self.__print_justify(tmp_txt + ") as '" + filename + "'...")
 
             plt.savefig(os.path.join(filepath, filename), format="png", bbox_inches="tight", pad_inches=0,
                         dpi=500)
@@ -986,7 +1050,8 @@ class CamBuilder:
 
     @staticmethod
     def __check_input_types(target_classes: int | List[int], explainer_types: str | List[str],
-                            target_layers: str | List[str]) -> Tuple[List[int], List[str], List[str]]:
+                            target_layers: str | List[str], contrastive_foil_classes: int | List[int]) \
+            -> Tuple[List[int], List[str], List[str], List[int]]:
         """
         Checks whether the setting specifics (target classes, explainer algorithms, and target layers) are provided
         as lists of values. If not, they are transformed into a list.
@@ -999,6 +1064,9 @@ class CamBuilder:
         :param target_layers: (mandatory) A string or a list of strings representing the target layers for the
             explanations. These strings should identify either PyTorch named modules, TensorFlow/Keras layers, or they
             should be class dictionary keys, used to retrieve each layer from the class attributes.
+        :param contrastive_foil_classes: (mandatory) An integer or list of integers representing the comparative classes
+            (foils) for the explanation in the context of Contrastive Explanations. If None, the explanation would
+            follow the classical paradigm.
 
         :return:
             - target_classes: A list of integers representing the target classes for the explanation.
@@ -1007,6 +1075,9 @@ class CamBuilder:
             - target_layers: A list of strings representing the target layers for the explanations. These strings should
             identify either PyTorch named modules, TensorFlow/Keras layers, or they should be class dictionary keys,
             used to retrieve each layer from the class attributes.
+            - contrastive_foil_classes: A list of intergers representing the comparative classes (foils) for the
+            explanation in the context of Contrastive Explanations. If None, the explanation would follow the classical
+            paradigm.
         """
 
         if not isinstance(target_classes, list):
@@ -1015,8 +1086,10 @@ class CamBuilder:
             explainer_types = [explainer_types]
         if not isinstance(target_layers, list):
             target_layers = [target_layers]
+        if not isinstance(contrastive_foil_classes, list):
+            contrastive_foil_classes = [contrastive_foil_classes]
 
-        return target_classes, explainer_types, target_layers
+        return target_classes, explainer_types, target_layers, contrastive_foil_classes
 
     @staticmethod
     def __set_grid(n_items: int, grid_instructions: Tuple[int, int]) -> Tuple[int, int]:

{signal_grad_cam-0.1.7 → signal_grad_cam-1.0.0}/signal_grad_cam/pytorch_cam_builder.py

@@ -125,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, eps: float = 1e-6) \
+                                 extra_inputs_list: List[Any] = None, contrastive_foil_class: int = 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,
@@ -142,6 +143,9 @@ 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 contrastive_foil_class: (optional, default is None) An integer representing the comparative class (foil)
+            for the explanation in the context of Contrastive Explanations. If None, the explanation would follow the
+            classical paradigm.
         :param eps: (optional, default is 1e-6) A float number used in probability clamping before logarithm application
             to avoid null or None results.
 
@@ -215,12 +219,18 @@ class TorchCamBuilder(CamBuilder):
                     target_scores = torch.cat([-outputs, outputs], dim=1)
                     target_probs = torch.cat([1 - p, p], dim=1)
 
-        target_probs = target_probs[:, target_class].cpu().detach().numpy()
+        class_idx = target_class if contrastive_foil_class is None else [target_class, contrastive_foil_class]
+        target_probs = target_probs[:, class_idx].cpu().detach().numpy()
 
         cam_list = []
         for i in range(len(data_list)):
             self.model.zero_grad()
-            target_score = target_scores[i, target_class]
+            if contrastive_foil_class is None:
+                target_score = target_scores[i, target_class]
+            else:
+                contrastive_foil = torch.autograd.Variable(torch.from_numpy(np.asarray([contrastive_foil_class]
+                                                                                       * target_scores.shape[0])))
+                target_score = nn.CrossEntropyLoss()(target_scores[i].unsqueeze(0), contrastive_foil)
             target_score.backward(retain_graph=True)
 
             if explainer_type == "HiResCAM":

{signal_grad_cam-0.1.7 → signal_grad_cam-1.0.0}/signal_grad_cam/tensorflow_cam_builder.py

@@ -150,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, eps: float = 1e-6) \
+                                 extra_inputs_list: List[Any] = None, contrastive_foil_class: int = 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,
@@ -167,6 +168,9 @@ 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 contrastive_foil_class: (optional, default is None) An integer representing the comparative class (foil)
+            for the explanation in the context of Contrastive Explanations. If None, the explanation would follow the
+            classical paradigm.
         :param eps: (optional, default is 1e-6) A float number used in probability clamping before logarithm application
             to avoid null or None results.
 
@@ -230,8 +234,15 @@ class TfCamBuilder(CamBuilder):
                         target_scores = tf.concat([-outputs, outputs], axis=1)
                         target_probs = tf.concat([1 - p, p], axis=1)
 
-            target_scores = target_scores[:, target_class]
-            target_probs = target_probs[:, target_class]
+            if contrastive_foil_class is not None:
+                contrastive_foil = tf.constant([contrastive_foil_class] * target_scores.shape[0], dtype=tf.int32)
+                target_scores = tf.keras.losses.SparseCategoricalCrossentropy(from_logits=True)(contrastive_foil,
+                                                                                                target_scores)
+                target_probs = tf.gather(target_probs, [target_class, contrastive_foil_class], axis=1)
+            else:
+                target_scores = target_scores[:, target_class]
+                target_probs = target_probs[:, target_class]
+
             self.gradients = tape.gradient(target_scores, self.activations)
 
         cam_list = []

{signal_grad_cam-0.1.7 → signal_grad_cam-1.0.0}/signal_grad_cam.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: signal-grad-cam
-Version: 0.1.7
+Version: 1.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
@@ -111,7 +111,7 @@ def preprocess_fn(signal):
 class_labels = ["Class 1", "Class 2", "Class 3"]
 
 # Define the CAM builder
-cam_builder = TorchCamBuilder(model=model, transform_fc=preprocess_fc, class_names=class_labels, time_axs=1)
+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.
@@ -133,7 +133,7 @@ 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_layer="conv1d_layer_1", softmax_final=True,
+									target_layers="conv1d_layer_1", softmax_final=True,
                                                             		data_sampling_freq=25, dt=1, axes_names=("Time (s)", "Channels"))
 
 # Visualize single channel importance
@@ -141,7 +141,7 @@ 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=score_ranges_dict, 
+					  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)"))
 
@@ -149,11 +149,11 @@ cam_builder.single_channel_output_display(data_list=data_list, data_labels=data_
 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=score_ranges_dict, data_names=item_names 
-				      results_dir="path_to_your_result_directoory", data_sampling_freq=25, dt=1)
+				      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 check the python scripts [here](https://github.com/bmi-labmedinfo/signal_grad_cam/examples).
+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.
 
 See the [open issues](https://github.com/bmi-labmedinfo/signal_grad_cam/issues) for a full list of proposed features (and known issues).
 
@@ -163,11 +163,25 @@ See the [open issues](https://github.com/bmi-labmedinfo/signal_grad_cam/issues)
 If you use the SignalGrad-CAM software for your projects, please cite it as:
 
 ```
-@software{Pe_SignalGrad_CAM_2025,
-  author = {Pe, Samuele and Buonocore, Tommaso Mario and Giovanna, Nicora and Enea, Parimbelli},
+@inproceedings{pe_sgradcam_2025_paper,
+  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},
+  volume = {4017},
+  pages = {209--216},
+  url = {https://ceur-ws.org/Vol-4017/paper_27.pdf},
+  publisher = {CEUR-WS.org},
+  year = {2025}
+}
+```
+
+```   
+@software{pe_sgradcam_2025_repo,
+  author = {Pe, Samuele},
   title = {{SignalGrad-CAM}},
   url = {https://github.com/bmi-labmedinfo/signal_grad_cam},
-  version = {0.0.1},
+  version = {1.0.0},
   year = {2025}
 }
 ```