signal-grad-cam 2.0.19

SignalGrad-CAM aims at generalising Grad-CAM to one-dimensional applications, while enhancing usability and efficiency.

SignalGrad-CAM

SignalGrad-CAM aims at generalising Grad-CAM to time-based applications, while enhancing usability and efficiency.

Explore the docs

Report Bug or Request Feature

Table of Contents

1. About The Project
2. Installation
3. Usage
4. Publications
5. Contacts And Useful Links
6. License

About The Project

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.

Keywords: 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.

Back To Top

Installation

1. Make sure you have the latest version of pip installed

   pip install --upgrade pip
   

2. Install SignalGrad-CAM through pip

    pip install signal-grad-cam
   

Back To Top

Usage

Here's a basic example that illustrates SignalGrad-CAM common usage.

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).

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.

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.

import numpy as np
import torch
from signal_grad_cam import TorchCamBuilder

# Load model
model = YourTorchModelConstructor()
model.load_state_dict(torch.load("path_to_your_stored_model.pt")
model.eval()

# Introduce useful information
def preprocess_fn(signal):
   signal = torch.from_numpy(signal).float()
   # Extra preprocessing: data resizing, reshaping, normalization...
   return signal
class_labels = ["Class 1", "Class 2", "Class 3"]

# Define the CAM builder
cam_builder = TorchCamBuilder(model=model, transform_fn=preprocess_fn, class_names=class_labels, time_axs=1)

Now, you can use the `cam_builder` object to generate class activation maps from a list of input data using the `get_cams` 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.

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.

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:

• `single_channel_output_display` plots the selected input channels using a color scheme that reflects the importance of each input feature.

• `overlapped_output_display` superimposes CAMs onto the corresponding input in an image-like format, allowing users to capture the overall distribution of input importance.

# Prepare data
data_list = [x for x in your_numpy_data_x[:2]]
data_labels_list = [1, 0]
item_names = ["Item 1", "Item 2"]
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"))

# 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)"))

# 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)

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.

See the open issues for a full list of proposed features (and known issues).

NEW! Updates in SignalGrad-CAM

Compared to previous versions, SignalGrad-CAM now offers the following enhancements:

• Support for regression tasks: 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, now it is only required to set as True the parameter `is_regression_network` in the constructor function.

• Contrastive explanations: Users can generate and visualize contrastive explanations by specifying one or more foil classes (for classification tasks) or foil values (for regression tasks) via the parameter `contrastive_foils`.

• 3D-CNN support for videos and volumetric data: After expliciting the time axis in the constructor with the parameter `time_axs`, 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 `show_single_video_frames`.

Back To Top

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},
  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 = {1.0.1},
  year = {2025}
}

Back To Top

Contacts and Useful Links

• Repository maintainer: Samuele Pe

• Project Link: https://github.com/bmi-labmedinfo/signal_grad_cam

• Package Link: https://pypi.org/project/signal-grad-cam/

Back To Top

License

Distributed under MIT License. See LICENSE for more information.

Back To Top