signal-grad-cam 0.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of signal-grad-cam might be problematic. Click here for more details.
- signal_grad_cam-0.0.1/LICENSE +21 -0
- signal_grad_cam-0.0.1/PKG-INFO +228 -0
- signal_grad_cam-0.0.1/README.md +206 -0
- signal_grad_cam-0.0.1/pyproject.toml +3 -0
- signal_grad_cam-0.0.1/setup.cfg +4 -0
- signal_grad_cam-0.0.1/setup.py +35 -0
- signal_grad_cam-0.0.1/signal_grad_cam/__init__.py +3 -0
- signal_grad_cam-0.0.1/signal_grad_cam/cam_builder.py +1032 -0
- signal_grad_cam-0.0.1/signal_grad_cam/pytorch_cam_builder.py +314 -0
- signal_grad_cam-0.0.1/signal_grad_cam/tensorflow_cam_builder.py +286 -0
- signal_grad_cam-0.0.1/signal_grad_cam.egg-info/PKG-INFO +228 -0
- signal_grad_cam-0.0.1/signal_grad_cam.egg-info/SOURCES.txt +14 -0
- signal_grad_cam-0.0.1/signal_grad_cam.egg-info/dependency_links.txt +1 -0
- signal_grad_cam-0.0.1/signal_grad_cam.egg-info/not-zip-safe +1 -0
- signal_grad_cam-0.0.1/signal_grad_cam.egg-info/requires.txt +6 -0
- signal_grad_cam-0.0.1/signal_grad_cam.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Samuele Pe
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: signal_grad_cam
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: SignalGrad-CAM aims at generalising Grad-CAM to one-dimensional applications, while enhancing usability and efficiency.
|
|
5
|
+
Home-page: https://github.com/samuelepe11/signal_grad_cam
|
|
6
|
+
Author: Samuele Pe
|
|
7
|
+
Author-email: samuele.pe01@universitadipavia.it
|
|
8
|
+
License: MIT
|
|
9
|
+
Keywords: XAI,class activation maps,CNN,time series
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
13
|
+
Requires-Python: >=3.11
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
License-File: LICENSE
|
|
16
|
+
Requires-Dist: numpy
|
|
17
|
+
Requires-Dist: matplotlib
|
|
18
|
+
Requires-Dist: opencv-python
|
|
19
|
+
Requires-Dist: torch
|
|
20
|
+
Requires-Dist: keras
|
|
21
|
+
Requires-Dist: tensorflow
|
|
22
|
+
|
|
23
|
+
<div id="top"></div>
|
|
24
|
+
|
|
25
|
+
[![Contributors][contributors-shield]][contributors-url] [![Forks][forks-shield]][forks-url] [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] [![MIT License][license-shield]][license-url]
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
<br />
|
|
29
|
+
<div align="center">
|
|
30
|
+
<h1>
|
|
31
|
+
SignalGrad-CAM
|
|
32
|
+
</h1>
|
|
33
|
+
|
|
34
|
+
<h3 align="center">SignalGrad-CAM aims at generalising Grad-CAM to one-dimensional applications, while enhancing usability and efficiency.</h3>
|
|
35
|
+
|
|
36
|
+
<p align="center">
|
|
37
|
+
<a href="https://github.com/samuelepe11/signal-grad-cam"><strong>Explore the docs</strong></a>
|
|
38
|
+
<br />
|
|
39
|
+
<br />
|
|
40
|
+
<a href="https://github.com/samuelepe11/signal-grad-cam/issues">Report Bug or Request Feature</a>
|
|
41
|
+
</p>
|
|
42
|
+
</div>
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
<!-- TABLE OF CONTENTS -->
|
|
47
|
+
<details>
|
|
48
|
+
<summary>Table of Contents</summary>
|
|
49
|
+
<ol>
|
|
50
|
+
<li><a href="#about-the-project">About The Project</a></li>
|
|
51
|
+
<li><a href="#installation">Installation</a></li>
|
|
52
|
+
<li><a href="#usage">Usage</a></li>
|
|
53
|
+
<li><a href="#publications">Publications</a></li>
|
|
54
|
+
<li><a href="#contacts-and-useful-links">Contacts And Useful Links</a></li>
|
|
55
|
+
<li><a href="#license">License</a></li>
|
|
56
|
+
</ol>
|
|
57
|
+
</details>
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
<!-- ABOUT THE PROJECT -->
|
|
62
|
+
## About The Project
|
|
63
|
+
|
|
64
|
+
<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>
|
|
65
|
+
|
|
66
|
+
<p align="justify">**Keywords:** *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*</p>
|
|
67
|
+
|
|
68
|
+
<p align="right"><a href="#top">Back To Top</a></p>
|
|
69
|
+
|
|
70
|
+
<!-- INSTALLATION -->
|
|
71
|
+
## Installation
|
|
72
|
+
|
|
73
|
+
1. Make sure you have the latest version of pip installed
|
|
74
|
+
```sh
|
|
75
|
+
pip install --upgrade pip
|
|
76
|
+
```
|
|
77
|
+
2. Install SignalGrad-CAM through pip
|
|
78
|
+
```sh
|
|
79
|
+
pip install -i https://test.pypi.org/simple/ signal-grad-cam
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
<p align="right"><a href="#top">Back To Top</a></p>
|
|
83
|
+
|
|
84
|
+
<!-- USAGE EXAMPLES -->
|
|
85
|
+
## Usage
|
|
86
|
+
<p align="justify">
|
|
87
|
+
Here's a basic example that illustrates SignalGrad-CAM common usage.
|
|
88
|
+
|
|
89
|
+
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).
|
|
90
|
+
|
|
91
|
+
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.
|
|
92
|
+
|
|
93
|
+
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.
|
|
94
|
+
</p>
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
import numpy as np
|
|
98
|
+
import torch
|
|
99
|
+
from signal_grad_cam import TorchCamBuilder
|
|
100
|
+
|
|
101
|
+
# Load model
|
|
102
|
+
model = YourTorchModelConstructor()
|
|
103
|
+
model.load_state_dict(torch.load("path_to_your_stored_model.pt")
|
|
104
|
+
model.eval()
|
|
105
|
+
|
|
106
|
+
# Introduce useful information
|
|
107
|
+
def preprocess_fn(signal):
|
|
108
|
+
signal = torch.from_numpy(signal).float()
|
|
109
|
+
# Extra preprocessing: data resizing, reshaping, normalization...
|
|
110
|
+
return signal
|
|
111
|
+
class_labels = ["Class 1", "Class 2", "Class 3"]
|
|
112
|
+
|
|
113
|
+
# Define the CAM builder
|
|
114
|
+
cam_builder = TorchCamBuilder(model=model, transform_fc=preprocess_fc, class_names=class_labels, time_axs=1)
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
<p align="justify">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.
|
|
118
|
+
|
|
119
|
+
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.
|
|
120
|
+
|
|
121
|
+
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:
|
|
122
|
+
* *`single_channel_output_display`* plots the selected channels using a color scheme that reflects the importance of each input feature.
|
|
123
|
+
* *`overlapped_output_display`* superimposes CAMs onto the corresponding input in an image-like format, allowing users to capture the overall distribution of input importance.
|
|
124
|
+
</p>
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
# Prepare data
|
|
128
|
+
data_list = [x for x in your_numpy_data_x[:2]]
|
|
129
|
+
data_labels_list = [1, 0]
|
|
130
|
+
item_names = ["Item 1", "Item 2"]
|
|
131
|
+
target_classes = [0, 1]
|
|
132
|
+
|
|
133
|
+
# Create CAMs
|
|
134
|
+
cam_dict, predicted_probs_dict, score_ranges_dict = cam_builder.get_cam(data_list=data_list, data_labels=data_labels_list,
|
|
135
|
+
target_classes=target_classes, explainer_types="Grad-CAM",
|
|
136
|
+
target_layer="conv1d_layer_1", softmax_final=True,
|
|
137
|
+
data_sampling_freq=25, dt=1, axes_names=("Time (s)", "Channels"))
|
|
138
|
+
|
|
139
|
+
# Visualize single channel importance
|
|
140
|
+
selected_channels_indices = [0, 2, 10]
|
|
141
|
+
cam_builder.single_channel_output_display(data_list=data_list, data_labels=data_labels_list, predicted_probs=predicted_probs_dict,
|
|
142
|
+
cams_dict=cam_dict, explainer_types="Grad-CAM", target_classes=target_classes,
|
|
143
|
+
target_layers="target_layer_name", desired_channels=selected_channels_indices,
|
|
144
|
+
grid_instructions=(1, len(selected_channels_indices), bar_ranges=score_ranges_dict,
|
|
145
|
+
results_dir="path_to_your_result_directoory", data_sampling_freq=25, dt=1, line_width=0.5,
|
|
146
|
+
axes_names=("Time (s)", "Amplitude (mV)"))
|
|
147
|
+
|
|
148
|
+
# Visualize overall importance
|
|
149
|
+
cam_builder.overlapped_output_display(data_list=data_list, data_labels=data_labels_list, predicted_probs=predicted_probs_dict,
|
|
150
|
+
cams_dict=cam_dict, explainer_types="Grad-CAM", target_classes=target_classes,
|
|
151
|
+
target_layers="target_layer_name", fig_size=(20 * len(your_data_X), 20),
|
|
152
|
+
grid_instructions=(len(your_data_X), 1), bar_ranges=score_ranges_dict, data_names=item_names
|
|
153
|
+
results_dir="path_to_your_result_directoory", data_sampling_freq=25, dt=1)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
You can also check the python scripts [here](https://github.com/samuelepe11/signal-grad-cam/examples).
|
|
157
|
+
|
|
158
|
+
See the [open issues](https://github.com/samuelepe11/signal-grad-cam/issues) for a full list of proposed features (and known issues).
|
|
159
|
+
|
|
160
|
+
<p align="right"><a href="#top">Back To Top</a></p>
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
If you use the SignalGrad-CAM software for your projects, please cite it as:
|
|
164
|
+
|
|
165
|
+
```
|
|
166
|
+
@software{Pe_SignalGrad_CAM_2025,
|
|
167
|
+
author = {Pe, Samuele and Buonocore, Tommaso Mario and Giovanna, Nicora and Enea, Parimbelli},
|
|
168
|
+
title = {{SignalGrad-CAM}},
|
|
169
|
+
url = {https://github.com/samuelepe11/signal-grad-cam},
|
|
170
|
+
version = {0.0.1},
|
|
171
|
+
year = {2025}
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
<p align="right"><a href="#top">Back To Top</a></p>
|
|
176
|
+
|
|
177
|
+
<!-- CONTACTS AND USEFUL LINKS -->
|
|
178
|
+
## Contacts and Useful Links
|
|
179
|
+
|
|
180
|
+
* **Repository maintainer**: Samuele Pe [![Gmail][gmail-shield]][gmail-url] [![LinkedIn][linkedin-shield]][linkedin-url]
|
|
181
|
+
|
|
182
|
+
* **Project Link**: [https://github.com/samuelepe11/signal-grad-cam](https://github.com/samuelepe11/signal-grad-cam)
|
|
183
|
+
|
|
184
|
+
* **Package Link**: [https://test.pypi.org/project/signal-grad-cam/](https://test.pypi.org/project/signal-grad-cam/)
|
|
185
|
+
|
|
186
|
+
<p align="right"><a href="#top">Back To Top</a></p>
|
|
187
|
+
|
|
188
|
+
<!-- LICENSE -->
|
|
189
|
+
## License
|
|
190
|
+
|
|
191
|
+
Distributed under MIT License. See `LICENSE` for more information.
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
<p align="right"><a href="#top">Back To Top</a></p>
|
|
195
|
+
|
|
196
|
+
<!-- MARKDOWN LINKS -->
|
|
197
|
+
|
|
198
|
+
[contributors-shield]: https://img.shields.io/github/contributors/samuelepe11/signal-grad-cam.svg?style=for-the-badge
|
|
199
|
+
|
|
200
|
+
[contributors-url]: https://github.com/samuelepe11/signal-grad-cam/graphs/contributors
|
|
201
|
+
|
|
202
|
+
[status-shield]: https://img.shields.io/badge/Status-pre--release-blue
|
|
203
|
+
|
|
204
|
+
[status-url]: https://github.com/samuelepe11/signal-grad-cam/releases
|
|
205
|
+
|
|
206
|
+
[forks-shield]: https://img.shields.io/github/forks/samuelepe11/signal-grad-cam.svg?style=for-the-badge
|
|
207
|
+
|
|
208
|
+
[forks-url]: https://github.com/samuelepe11/signal-grad-cam/network/members
|
|
209
|
+
|
|
210
|
+
[stars-shield]: https://img.shields.io/github/stars/samuelepe11/signal-grad-cam.svg?style=for-the-badge
|
|
211
|
+
|
|
212
|
+
[stars-url]: https://github.com/samuelepe11/signal-grad-cam/stargazers
|
|
213
|
+
|
|
214
|
+
[issues-shield]: https://img.shields.io/github/issues/samuelepe11/signal-grad-cam.svg?style=for-the-badge
|
|
215
|
+
|
|
216
|
+
[issues-url]: https://github.com/samuelepe11/signal-grad-cam/issues
|
|
217
|
+
|
|
218
|
+
[license-shield]: https://img.shields.io/github/license/samuelepe11/signal-grad-cam.svg?style=for-the-badge
|
|
219
|
+
|
|
220
|
+
[license-url]: https://github.com/samuelepe11/signal-grad-cam/LICENSE
|
|
221
|
+
|
|
222
|
+
[linkedin-shield]: https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white
|
|
223
|
+
|
|
224
|
+
[linkedin-url]: https://linkedin.com/in/samuele-pe-818bbb307
|
|
225
|
+
|
|
226
|
+
[gmail-shield]: https://img.shields.io/badge/Email-D14836?style=for-the-badge&logo=gmail&logoColor=white
|
|
227
|
+
|
|
228
|
+
[gmail-url]: mailto:samuele.pe01@universitadipavia.it
|
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
<div id="top"></div>
|
|
2
|
+
|
|
3
|
+
[![Contributors][contributors-shield]][contributors-url] [![Forks][forks-shield]][forks-url] [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] [![MIT License][license-shield]][license-url]
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
<br />
|
|
7
|
+
<div align="center">
|
|
8
|
+
<h1>
|
|
9
|
+
SignalGrad-CAM
|
|
10
|
+
</h1>
|
|
11
|
+
|
|
12
|
+
<h3 align="center">SignalGrad-CAM aims at generalising Grad-CAM to one-dimensional applications, while enhancing usability and efficiency.</h3>
|
|
13
|
+
|
|
14
|
+
<p align="center">
|
|
15
|
+
<a href="https://github.com/samuelepe11/signal-grad-cam"><strong>Explore the docs</strong></a>
|
|
16
|
+
<br />
|
|
17
|
+
<br />
|
|
18
|
+
<a href="https://github.com/samuelepe11/signal-grad-cam/issues">Report Bug or Request Feature</a>
|
|
19
|
+
</p>
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
<!-- TABLE OF CONTENTS -->
|
|
25
|
+
<details>
|
|
26
|
+
<summary>Table of Contents</summary>
|
|
27
|
+
<ol>
|
|
28
|
+
<li><a href="#about-the-project">About The Project</a></li>
|
|
29
|
+
<li><a href="#installation">Installation</a></li>
|
|
30
|
+
<li><a href="#usage">Usage</a></li>
|
|
31
|
+
<li><a href="#publications">Publications</a></li>
|
|
32
|
+
<li><a href="#contacts-and-useful-links">Contacts And Useful Links</a></li>
|
|
33
|
+
<li><a href="#license">License</a></li>
|
|
34
|
+
</ol>
|
|
35
|
+
</details>
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
<!-- ABOUT THE PROJECT -->
|
|
40
|
+
## About The Project
|
|
41
|
+
|
|
42
|
+
<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>
|
|
43
|
+
|
|
44
|
+
<p align="justify">**Keywords:** *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*</p>
|
|
45
|
+
|
|
46
|
+
<p align="right"><a href="#top">Back To Top</a></p>
|
|
47
|
+
|
|
48
|
+
<!-- INSTALLATION -->
|
|
49
|
+
## Installation
|
|
50
|
+
|
|
51
|
+
1. Make sure you have the latest version of pip installed
|
|
52
|
+
```sh
|
|
53
|
+
pip install --upgrade pip
|
|
54
|
+
```
|
|
55
|
+
2. Install SignalGrad-CAM through pip
|
|
56
|
+
```sh
|
|
57
|
+
pip install -i https://test.pypi.org/simple/ signal-grad-cam
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
<p align="right"><a href="#top">Back To Top</a></p>
|
|
61
|
+
|
|
62
|
+
<!-- USAGE EXAMPLES -->
|
|
63
|
+
## Usage
|
|
64
|
+
<p align="justify">
|
|
65
|
+
Here's a basic example that illustrates SignalGrad-CAM common usage.
|
|
66
|
+
|
|
67
|
+
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).
|
|
68
|
+
|
|
69
|
+
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.
|
|
70
|
+
|
|
71
|
+
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.
|
|
72
|
+
</p>
|
|
73
|
+
|
|
74
|
+
```python
|
|
75
|
+
import numpy as np
|
|
76
|
+
import torch
|
|
77
|
+
from signal_grad_cam import TorchCamBuilder
|
|
78
|
+
|
|
79
|
+
# Load model
|
|
80
|
+
model = YourTorchModelConstructor()
|
|
81
|
+
model.load_state_dict(torch.load("path_to_your_stored_model.pt")
|
|
82
|
+
model.eval()
|
|
83
|
+
|
|
84
|
+
# Introduce useful information
|
|
85
|
+
def preprocess_fn(signal):
|
|
86
|
+
signal = torch.from_numpy(signal).float()
|
|
87
|
+
# Extra preprocessing: data resizing, reshaping, normalization...
|
|
88
|
+
return signal
|
|
89
|
+
class_labels = ["Class 1", "Class 2", "Class 3"]
|
|
90
|
+
|
|
91
|
+
# Define the CAM builder
|
|
92
|
+
cam_builder = TorchCamBuilder(model=model, transform_fc=preprocess_fc, class_names=class_labels, time_axs=1)
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
<p align="justify">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.
|
|
96
|
+
|
|
97
|
+
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.
|
|
98
|
+
|
|
99
|
+
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:
|
|
100
|
+
* *`single_channel_output_display`* plots the selected channels using a color scheme that reflects the importance of each input feature.
|
|
101
|
+
* *`overlapped_output_display`* superimposes CAMs onto the corresponding input in an image-like format, allowing users to capture the overall distribution of input importance.
|
|
102
|
+
</p>
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
# Prepare data
|
|
106
|
+
data_list = [x for x in your_numpy_data_x[:2]]
|
|
107
|
+
data_labels_list = [1, 0]
|
|
108
|
+
item_names = ["Item 1", "Item 2"]
|
|
109
|
+
target_classes = [0, 1]
|
|
110
|
+
|
|
111
|
+
# Create CAMs
|
|
112
|
+
cam_dict, predicted_probs_dict, score_ranges_dict = cam_builder.get_cam(data_list=data_list, data_labels=data_labels_list,
|
|
113
|
+
target_classes=target_classes, explainer_types="Grad-CAM",
|
|
114
|
+
target_layer="conv1d_layer_1", softmax_final=True,
|
|
115
|
+
data_sampling_freq=25, dt=1, axes_names=("Time (s)", "Channels"))
|
|
116
|
+
|
|
117
|
+
# Visualize single channel importance
|
|
118
|
+
selected_channels_indices = [0, 2, 10]
|
|
119
|
+
cam_builder.single_channel_output_display(data_list=data_list, data_labels=data_labels_list, predicted_probs=predicted_probs_dict,
|
|
120
|
+
cams_dict=cam_dict, explainer_types="Grad-CAM", target_classes=target_classes,
|
|
121
|
+
target_layers="target_layer_name", desired_channels=selected_channels_indices,
|
|
122
|
+
grid_instructions=(1, len(selected_channels_indices), bar_ranges=score_ranges_dict,
|
|
123
|
+
results_dir="path_to_your_result_directoory", data_sampling_freq=25, dt=1, line_width=0.5,
|
|
124
|
+
axes_names=("Time (s)", "Amplitude (mV)"))
|
|
125
|
+
|
|
126
|
+
# Visualize overall importance
|
|
127
|
+
cam_builder.overlapped_output_display(data_list=data_list, data_labels=data_labels_list, predicted_probs=predicted_probs_dict,
|
|
128
|
+
cams_dict=cam_dict, explainer_types="Grad-CAM", target_classes=target_classes,
|
|
129
|
+
target_layers="target_layer_name", fig_size=(20 * len(your_data_X), 20),
|
|
130
|
+
grid_instructions=(len(your_data_X), 1), bar_ranges=score_ranges_dict, data_names=item_names
|
|
131
|
+
results_dir="path_to_your_result_directoory", data_sampling_freq=25, dt=1)
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
You can also check the python scripts [here](https://github.com/samuelepe11/signal-grad-cam/examples).
|
|
135
|
+
|
|
136
|
+
See the [open issues](https://github.com/samuelepe11/signal-grad-cam/issues) for a full list of proposed features (and known issues).
|
|
137
|
+
|
|
138
|
+
<p align="right"><a href="#top">Back To Top</a></p>
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
If you use the SignalGrad-CAM software for your projects, please cite it as:
|
|
142
|
+
|
|
143
|
+
```
|
|
144
|
+
@software{Pe_SignalGrad_CAM_2025,
|
|
145
|
+
author = {Pe, Samuele and Buonocore, Tommaso Mario and Giovanna, Nicora and Enea, Parimbelli},
|
|
146
|
+
title = {{SignalGrad-CAM}},
|
|
147
|
+
url = {https://github.com/samuelepe11/signal-grad-cam},
|
|
148
|
+
version = {0.0.1},
|
|
149
|
+
year = {2025}
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
<p align="right"><a href="#top">Back To Top</a></p>
|
|
154
|
+
|
|
155
|
+
<!-- CONTACTS AND USEFUL LINKS -->
|
|
156
|
+
## Contacts and Useful Links
|
|
157
|
+
|
|
158
|
+
* **Repository maintainer**: Samuele Pe [![Gmail][gmail-shield]][gmail-url] [![LinkedIn][linkedin-shield]][linkedin-url]
|
|
159
|
+
|
|
160
|
+
* **Project Link**: [https://github.com/samuelepe11/signal-grad-cam](https://github.com/samuelepe11/signal-grad-cam)
|
|
161
|
+
|
|
162
|
+
* **Package Link**: [https://test.pypi.org/project/signal-grad-cam/](https://test.pypi.org/project/signal-grad-cam/)
|
|
163
|
+
|
|
164
|
+
<p align="right"><a href="#top">Back To Top</a></p>
|
|
165
|
+
|
|
166
|
+
<!-- LICENSE -->
|
|
167
|
+
## License
|
|
168
|
+
|
|
169
|
+
Distributed under MIT License. See `LICENSE` for more information.
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
<p align="right"><a href="#top">Back To Top</a></p>
|
|
173
|
+
|
|
174
|
+
<!-- MARKDOWN LINKS -->
|
|
175
|
+
|
|
176
|
+
[contributors-shield]: https://img.shields.io/github/contributors/samuelepe11/signal-grad-cam.svg?style=for-the-badge
|
|
177
|
+
|
|
178
|
+
[contributors-url]: https://github.com/samuelepe11/signal-grad-cam/graphs/contributors
|
|
179
|
+
|
|
180
|
+
[status-shield]: https://img.shields.io/badge/Status-pre--release-blue
|
|
181
|
+
|
|
182
|
+
[status-url]: https://github.com/samuelepe11/signal-grad-cam/releases
|
|
183
|
+
|
|
184
|
+
[forks-shield]: https://img.shields.io/github/forks/samuelepe11/signal-grad-cam.svg?style=for-the-badge
|
|
185
|
+
|
|
186
|
+
[forks-url]: https://github.com/samuelepe11/signal-grad-cam/network/members
|
|
187
|
+
|
|
188
|
+
[stars-shield]: https://img.shields.io/github/stars/samuelepe11/signal-grad-cam.svg?style=for-the-badge
|
|
189
|
+
|
|
190
|
+
[stars-url]: https://github.com/samuelepe11/signal-grad-cam/stargazers
|
|
191
|
+
|
|
192
|
+
[issues-shield]: https://img.shields.io/github/issues/samuelepe11/signal-grad-cam.svg?style=for-the-badge
|
|
193
|
+
|
|
194
|
+
[issues-url]: https://github.com/samuelepe11/signal-grad-cam/issues
|
|
195
|
+
|
|
196
|
+
[license-shield]: https://img.shields.io/github/license/samuelepe11/signal-grad-cam.svg?style=for-the-badge
|
|
197
|
+
|
|
198
|
+
[license-url]: https://github.com/samuelepe11/signal-grad-cam/LICENSE
|
|
199
|
+
|
|
200
|
+
[linkedin-shield]: https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white
|
|
201
|
+
|
|
202
|
+
[linkedin-url]: https://linkedin.com/in/samuele-pe-818bbb307
|
|
203
|
+
|
|
204
|
+
[gmail-shield]: https://img.shields.io/badge/Email-D14836?style=for-the-badge&logo=gmail&logoColor=white
|
|
205
|
+
|
|
206
|
+
[gmail-url]: mailto:samuele.pe01@universitadipavia.it
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
from setuptools import setup, find_packages
|
|
2
|
+
|
|
3
|
+
with open("README.md", "r") as f:
|
|
4
|
+
description = f.read()
|
|
5
|
+
|
|
6
|
+
setup(
|
|
7
|
+
name="signal_grad_cam",
|
|
8
|
+
version="0.0.1",
|
|
9
|
+
description="SignalGrad-CAM aims at generalising Grad-CAM to one-dimensional applications, while enhancing usability"
|
|
10
|
+
" and efficiency.",
|
|
11
|
+
keywords="XAI, class activation maps, CNN, time series",
|
|
12
|
+
author="Samuele Pe",
|
|
13
|
+
author_email="samuele.pe01@universitadipavia.it",
|
|
14
|
+
long_description=description,
|
|
15
|
+
long_description_content_type="text/markdown",
|
|
16
|
+
url="https://github.com/samuelepe11/signal_grad_cam",
|
|
17
|
+
license="MIT",
|
|
18
|
+
classifiers=[
|
|
19
|
+
"License :: OSI Approved :: MIT License",
|
|
20
|
+
"Operating System :: OS Independent",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
],
|
|
23
|
+
packages=find_packages(),
|
|
24
|
+
python_requires=">=3.11",
|
|
25
|
+
install_requires=[
|
|
26
|
+
"numpy",
|
|
27
|
+
"matplotlib",
|
|
28
|
+
"opencv-python",
|
|
29
|
+
"torch",
|
|
30
|
+
"keras",
|
|
31
|
+
"tensorflow"
|
|
32
|
+
],
|
|
33
|
+
include_package_data=True,
|
|
34
|
+
zip_safe=False
|
|
35
|
+
)
|