signxai2 0.15.2

Extended variant of ZeNNit with SIGNed explanations - Unveiling relevant features by reducing bias

SIGN (Sign-based Improvement of Gradient-based explaNations) 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 (Zennit explains neural networks in torch) package pypi.org/project/zennit/.

If you use this package or parts of it in your own work, please consider citing our paper:

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

Install

To install the package directly from PyPI using pip, use:

$ 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. There is also a version of SIGN available for usage with TensorFlow environments pypi.org/project/signxai/.

The below example code (see 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 and the setup script.

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.

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.

Image Source: Coastal Roamer, CC BY-SA 4.0, via Wikimedia Commons

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 and COPYING.LESSER files for details.