Metadata-Version: 2.4
Name: signxai2
Version: 0.15.3
Summary: Extended variant of ZeNNit with SIGNed explanations - Unveiling relevant features by reducing bias
Project-URL: Documentation, https://TimeXAIgroup.github.io/signxai2/index.html
Project-URL: Repository, https://github.com/TimeXAIgroup/signxai2.git
Project-URL: Bug Reports, https://github.com/TimeXAIgroup/signxai2/issues
Project-URL: Publication, https://www.sciencedirect.com/science/article/pii/S1566253523001999?via%3Dihub
Author-email: TimeXAIgroup <jennifer.hannig@kite.thm.de>, Nils Gumpfer <nils.gumpfer@kite.thm.de>
Maintainer-email: Nils Gumpfer <nils.gumpfer@kite.thm.de>
License-Expression: GPL-3.0
License-File: COPYING.LESSER
License-File: COPYING.txt
Keywords: Artificial Intelligence,Deep Learning,Explainable AI,Feature Attribution,Interpretability,Machine Learning,SIGN,XAI
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11.11
Requires-Dist: zennit==1.0.0
Description-Content-Type: text/markdown

# SIGNed XAI for Image and Time Series Models

<img alt="SIGNXAI-Example" src="https://raw.githubusercontent.com/TimeXAIgroup/signxai2/main/img/sign_mnist.png" width=750>

[![PyPI Version](https://img.shields.io/pypi/v/signxai2)](https://pypi.org/project/signxai2/)
[![License](https://img.shields.io/pypi/l/signxai2)](https://github.com/TimeXAIgroup/signxai2/blob/master/COPYING.LESSER)


SIGN (**S**ign-based **I**mprovement of **G**radient-based expla**N**ations) is a novel XAI method intended to reduce bias in explanations that are intrinsically induced by several state-of-the-art XAI methods. The SIGN-XAI-2 package enables simple application of this method in your projects using the established Zennit (**Z**ennit **e**xplains **n**eural **n**etworks **i**n **t**orch) package [pypi.org/project/zennit/](https://pypi.org/project/zennit/). 

SIGN-based explanations are particularly well suited for generating bias-reduced heatmaps for both image and time series data, enhancing interpretability by more reliably uncovering relevant features.

If you use this package or parts of it in your own work, please consider citing our [paper](https://doi.org/10.1016/j.inffus.2023.101883):
```bibtex
 @article{Gumpfer2023SIGN,
    title = {SIGNed explanations: Unveiling relevant features by reducing bias},
    author = {Nils Gumpfer and Joshua Prim and Till Keller and Bernhard Seeger and Michael Guckert and Jennifer Hannig},
    journal = {Information Fusion},
    pages = {101883},
    year = {2023},
    issn = {1566-2535},
    doi = {https://doi.org/10.1016/j.inffus.2023.101883}
}
```

## Documentation
The latest documentation is available from [timexaigroup.github.io/signxai2](https://timexaigroup.github.io/signxai2/).

## Install
To install the package directly from PyPI using pip, use:
```shell
$ pip install signxai2
```

## Usage
SIGN-XAI-2 is based on Zennit and works with PyTorch. If you want to know more about Zennit and its usage, visit [github.com/chr5tphr/zennit](https://github.com/chr5tphr/zennit). There is also a version of SIGN available for usage with TensorFlow environments [pypi.org/project/signxai/](https://pypi.org/project/signxai/).

The below example code (see [vgg16_simple.py](https://github.com/TimeXAIgroup/signxai2/blob/main/examples/vgg16_simple.py)) demonstrates the basic usage of a SIGN-based composite as an extension to LRP-Epsilon in Zennit. To run this code, have a look at the [requirements](https://github.com/TimeXAIgroup/signxai2/blob/main/examples/requirements.txt) and the [setup script](https://github.com/TimeXAIgroup/signxai2/blob/main/examples/setup.sh).

```python
import matplotlib.pyplot as plt
import numpy as np
import torch

from torchvision.models import vgg16, VGG16_Weights
from torchvision.transforms import Compose, Resize, ToTensor, Normalize
from zennit.attribution import Gradient

from signxai2.misc import get_example_image
from signxai2.sign import EpsilonStdXSIGN

# Define the preprocessing pipeline
transform = Compose([
    Resize(224),
    ToTensor(),
    Normalize((0.485, 0.456, 0.406), (0.229, 0.224, 0.225)),
])

# Load and preprocess image
image = get_example_image(1)
data = transform(image)[None]  # Add batch dimension

# Load pretrained VGG16 model
weights=VGG16_Weights.IMAGENET1K_V1
model = vgg16(weights=weights).eval()

# Get model prediction
output = model(data)
pred = output.argmax(1)[0].item()
target = torch.eye(1000)[[pred]]

# Get the class label
label = weights.meta['categories'][pred]
print('Predicted class: {}'.format(label))

# Visualize the original image and relevance map
fig, axs = plt.subplots(1, 2, figsize=(12, 5))
axs[0].imshow(image)
axs[0].set_title('Image')

# Compute attribution
composite = EpsilonStdXSIGN(mu=0, stdfactor=0.3, signstdfactor=0.3)
with Gradient(model=model, composite=composite) as attributor:
    _, attribution = attributor(data, target)

# Prepare relevance map
attribution = np.nan_to_num(attribution)
relevance = attribution.sum(1)
R = relevance[0] / np.abs(relevance).max()

# Plot relevance map
axs[1].matshow(R, cmap='seismic', clim=(-1, 1))
axs[1].set_title('LRP-Epsilon-SIGN')

# Switch off axes and labels
for ax in axs:
    ax.axis('off')

# Plot to screen
plt.tight_layout()
plt.show()
```

For more details and examples, have a look at our
[**documentation**](https://timexaigroup.github.io/signxai2/).

## Examples

The above code can be used to generate heatmaps as shown for the example images below. Comparing the baseline LRP-Epsilon method with its SIGN-augmented counterpart highlights notable differences in pixel-level attributions and image-induced contrast, with SIGN mitigating this explanatory bias and distortion inherent to the standard variant.

<img alt="Example 1" src="https://raw.githubusercontent.com/TimeXAIgroup/signxai2/main/img/heatmaps_example_1.png" width=750>

***Image Source:*** Coastal Roamer, [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0), via Wikimedia Commons

<img alt="Example 2" src="https://raw.githubusercontent.com/TimeXAIgroup/signxai2/main/img/heatmaps_example_2.png" width=750>

***Image Source:*** randomwild, CC0, via Wikimedia Commons

## License
SIGN-XAI-2 and Zennit are licensed under the GNU LESSER GENERAL PUBLIC LICENSE VERSION 3 OR LATER -- see the [COPYING](https://github.com/TimeXAIgroup/signxai2/blob/main/COPYING) and [COPYING.LESSER](https://github.com/TimeXAIgroup/signxai2/blob/main/COPYING.LESSER) files for details.
