Neural Network Explainability and Interpretability Library
ScopeRX is a comprehensive, production-grade Python library for explaining and interpreting neural network predictions. It provides state-of-the-art attribution methods, evaluation metrics, and visualization tools - all unified under a simple, intuitive API.
torchvisionpromoted to core dependency — no longer requirespip install scope-rx[full].KernelSHAP/LIME: Fixed all-zero attributions on low-complexity images (SLIC grid fallback + Ridge label scaling).GuidedBackprop: Input tensor is cloned beforerequires_grad, preventing mutation of caller's tensor.MeaningfulPerturbation: Validated input detached before optimisation to avoid gradient graph conflicts.- Metrics:
aopc_scorereturns a writeable array;max_sensitivityalways returns a plainfloat. - Tests: New end-to-end integration suite (
test/test_everything.py) with correctness assertions for all 15 methods.
- Type Safety: Fully typed codebase with
mypycompliance. - Production Grade: Enhanced stability, error handling, and performance optimizations.
- CI/CD: Automated testing and linting pipelines.
- Improved Methods: Refactored
KernelSHAP,RISE, and Attention methods for better accuracy and speed.
- 15+ Explanation Methods: From classic GradCAM to cutting-edge RISE and attention methods
- Unified API: One interface to rule them all - switch between methods with a single parameter
- Evaluation Metrics: Faithfulness, sensitivity, and stability metrics to quantify explanation quality
- Beautiful Visualizations: Publication-ready plots with minimal code
- Model Agnostic: Works with any PyTorch model architecture
- Transformer Support: Dedicated attention visualization for Vision Transformers
- CLI Tool: Generate explanations from the command line
pip install scope-rxWith optional dependencies:
# For interactive Plotly visualizations
pip install scope-rx[interactive]
# For development
pip install scope-rx[dev]
# Full installation with all extras (transformers, SHAP, captum)
pip install scope-rx[full]Note:
torchvisionis a core dependency and is installed automatically withpip install scope-rx.
from scope_rx import ScopeRX
import torch
import torchvision.models as models
# Load your model
model = models.resnet50(pretrained=True)
model.eval()
# Create explainer
explainer = ScopeRX(model)
# Generate explanation
result = explainer.explain(
input_tensor,
method='gradcam',
target_class=predicted_class
)
# Visualize
result.visualize()
# Or save to file
result.save("explanation.png")| Method | Description | Use Case |
|---|---|---|
gradcam |
Gradient-weighted Class Activation Mapping | General CNN visualization |
gradcam++ |
Improved GradCAM with better localization | Multiple object instances |
scorecam |
Score-based CAM (gradient-free) | When gradients are unstable |
layercam |
Layer-wise CAM | Fine-grained attribution |
smoothgrad |
Noise-smoothed gradients | Reducing gradient noise |
integrated_gradients |
Axiomatic attribution method | Theoretically grounded explanations |
vanilla |
Simple input gradients | Quick baseline |
guided_backprop |
Guided backpropagation | High-resolution visualization |
| Method | Description | Use Case |
|---|---|---|
occlusion |
Sliding window occlusion | Understanding spatial importance |
rise |
Randomized Input Sampling | Black-box models |
meaningful_perturbation |
Optimized minimal perturbation | Finding minimal explanations |
| Method | Description | Use Case |
|---|---|---|
kernel_shap |
Kernel SHAP approximation | Shapley value estimation |
lime |
Local Interpretable Explanations | Interpretable local surrogates |
| Method | Description | Use Case |
|---|---|---|
attention_rollout |
Attention weight aggregation | Vision Transformers |
attention_flow |
Attention flow propagation | Understanding attention paths |
raw_attention |
Raw attention weights | Quick attention inspection |
from scope_rx import ScopeRX
explainer = ScopeRX(model)
# Compare multiple methods at once
results = explainer.compare_methods(
input_tensor,
methods=['gradcam', 'smoothgrad', 'integrated_gradients', 'rise'],
target_class=predicted_class
)
# Visualize comparison
from scope_rx.visualization import plot_comparison
plot_comparison({name: r.attribution for name, r in results.items()})from scope_rx.metrics import (
faithfulness_score,
insertion_deletion_auc,
sensitivity_score,
stability_score
)
# Faithfulness: Does the explanation reflect model behavior?
faith = faithfulness_score(model, input_tensor, attribution, target_class=0)
# Insertion/Deletion: How does model output change as we add/remove important features?
scores = insertion_deletion_auc(model, input_tensor, attribution, target_class=0)
print(f"Insertion AUC: {scores['insertion_auc']:.3f}")
print(f"Deletion AUC: {scores['deletion_auc']:.3f}")
# Sensitivity: Are explanations sensitive to meaningful changes?
sens = sensitivity_score(explainer, input_tensor, target_class=0)
# Stability: Are explanations stable across similar inputs?
stab = stability_score(explainer, input_tensor, target_class=0)from scope_rx.visualization import (
plot_attribution,
plot_comparison,
overlay_attribution,
create_interactive_plot,
export_visualization
)
# Simple plot
plot_attribution(attribution, image=original_image)
# Interactive Plotly plot
fig = create_interactive_plot(attribution, image=original_image)
fig.show()
# Export to various formats
export_visualization(attribution, "output.png", colormap="jet")
export_visualization(attribution, "output.npy") # Raw numpy array# Generate explanation
scope-rx explain image.jpg --model resnet50 --method gradcam --output heatmap.png
# Compare methods
scope-rx compare image.jpg --model resnet50 --methods gradcam,smoothgrad,rise
# List available methods
scope-rx list-methods
# Show model layers (for layer selection)
scope-rx show-layers --model resnet50from scope_rx import GradCAM
# Specify exact layer
explainer = GradCAM(model, target_layer="layer4.1.conv2")from scope_rx import IntegratedGradients
# Use different baselines
explainer = IntegratedGradients(
model,
n_steps=50,
baseline="blur" # Options: "zero", "random", "blur"
)from scope_rx import ScopeRX
from scope_rx.utils import preprocess_image
from pathlib import Path
explainer = ScopeRX(model)
# Process multiple images
for image_path in image_paths:
input_tensor = preprocess_image(image_path)
result = explainer.explain(input_tensor, method='gradcam')
result.save(f"explanations/{Path(image_path).stem}.png")from scope_rx import GradCAM, SmoothGrad, RISE
# Use specific explainer directly
gradcam = GradCAM(model, target_layer="layer4")
result = gradcam.explain(input_tensor, target_class=0)
# SmoothGrad with custom parameters
smoothgrad = SmoothGrad(model, n_samples=50, noise_level=0.2)
result = smoothgrad.explain(input_tensor, target_class=0)# Run the comprehensive end-to-end test suite (CLI + Python API + metrics + visualization)
python test/test_everything.py
# Run unit tests with pytest
pytest tests/
# Run with coverage
pytest tests/ --cov=scope_rx --cov-report=html
# Run specific test module
pytest tests/test_gradient_methods.py -vFor full documentation, visit our documentation site.
We welcome contributions! Please see our Contributing Guide for details.
This project is licensed under the MIT License - see the LICENSE file for details.
If you use ScopeRX in your research, please cite:
@software{scoperx2024,
title = {ScopeRX: Neural Network Explainability Library},
author = {XCALEN},
year = {2024},
url = {https://github.com/xcalen/scope-rx}
}ScopeRX builds upon the excellent work of the interpretability research community. Special thanks to the authors of:
- GradCAM, GradCAM++, ScoreCAM, LayerCAM
- SHAP and LIME
- Integrated Gradients
- RISE
- And many others who have contributed to the field of explainable AI
Made with love by Desenyon