scope-rx 2.0.0__tar.gz

scope_rx-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 ScopeRX Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scope_rx-2.0.0/PKG-INFO

@@ -0,0 +1,361 @@
+Metadata-Version: 2.4
+Name: scope-rx
+Version: 2.0.0
+Summary: A comprehensive neural network explainability and interpretability library
+Author-email: XCALEN <desenyon@gmail.com>
+Maintainer-email: XCALEN <desenyon@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/xcalen/scope-rx
+Project-URL: Documentation, https://scope-rx.readthedocs.io
+Project-URL: Repository, https://github.com/xcalen/scope-rx
+Project-URL: Issues, https://github.com/xcalen/scope-rx/issues
+Project-URL: Changelog, https://github.com/xcalen/scope-rx/blob/main/CHANGELOG.md
+Keywords: deep-learning,explainability,interpretability,neural-networks,pytorch,gradcam,integrated-gradients,shap,lime,attention,xai,machine-learning,computer-vision,transformers
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=1.10.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: opencv-python>=4.5.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: pillow>=8.0.0
+Requires-Dist: tqdm>=4.60.0
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: scikit-image>=0.19.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: interactive
+Requires-Dist: plotly>=5.10.0; extra == "interactive"
+Requires-Dist: ipywidgets>=8.0.0; extra == "interactive"
+Requires-Dist: jupyter>=1.0.0; extra == "interactive"
+Provides-Extra: full
+Requires-Dist: shap>=0.42.0; extra == "full"
+Requires-Dist: lime>=0.2.0; extra == "full"
+Requires-Dist: captum>=0.6.0; extra == "full"
+Requires-Dist: torchvision>=0.12.0; extra == "full"
+Requires-Dist: transformers>=4.20.0; extra == "full"
+Provides-Extra: docs
+Requires-Dist: sphinx>=6.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.22.0; extra == "docs"
+Requires-Dist: myst-parser>=1.0.0; extra == "docs"
+Dynamic: license-file
+
+# ScopeRX
+
+**Neural Network Explainability and Interpretability Library**
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![CI](https://github.com/xcalen/scope-rx/actions/workflows/ci.yml/badge.svg)](https://github.com/xcalen/scope-rx/actions/workflows/ci.yml) [![Codecov](https://codecov.io/gh/xcalen/scope-rx/branch/main/graph/badge.svg)](https://codecov.io/gh/xcalen/scope-rx)
+
+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.
+
+## Version 2.0.0 Updates
+- **Type Safety**: Fully typed codebase with `mypy` compliance.
+- **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.
+
+## Features
+
+- **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
+
+## Installation
+
+```bash
+pip install scope-rx
+```
+
+**With optional dependencies:**
+
+```bash
+# For interactive Plotly visualizations
+pip install scope-rx[interactive]
+
+# For development
+pip install scope-rx[dev]
+
+# Full installation with all extras
+pip install scope-rx[full]
+```
+
+## Quick Start
+
+```python
+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")
+```
+
+## Available Methods
+
+### Gradient-Based Methods
+
+| 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       |
+
+### Perturbation-Based Methods
+
+| 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     |
+
+### Model-Agnostic Methods
+
+| Method          | Description                      | Use Case                       |
+| --------------- | -------------------------------- | ------------------------------ |
+| `kernel_shap` | Kernel SHAP approximation        | Shapley value estimation       |
+| `lime`        | Local Interpretable Explanations | Interpretable local surrogates |
+
+### Attention-Based Methods (for Transformers)
+
+| 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    |
+
+## Compare Methods
+
+```python
+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()})
+```
+
+## Evaluate Explanations
+
+```python
+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)
+```
+
+## Visualization
+
+```python
+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
+```
+
+## Command Line Interface
+
+```bash
+# 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 resnet50
+```
+
+## Advanced Usage
+
+### Custom Target Layers
+
+```python
+from scope_rx import GradCAM
+
+# Specify exact layer
+explainer = GradCAM(model, target_layer="layer4.1.conv2")
+```
+
+### Custom Baselines for Integrated Gradients
+
+```python
+from scope_rx import IntegratedGradients
+
+# Use different baselines
+explainer = IntegratedGradients(
+    model,
+    n_steps=50,
+    baseline="blur"  # Options: "zero", "random", "blur"
+)
+```
+
+### Batch Processing
+
+```python
+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")
+```
+
+### Using Individual Explainers
+
+```python
+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)
+```
+
+## Testing
+
+```bash
+# Run all tests
+pytest tests/
+
+# Run with coverage
+pytest tests/ --cov=scope_rx --cov-report=html
+
+# Run specific test module
+pytest tests/test_gradient_methods.py -v
+```
+
+## Documentation
+
+For full documentation, visit our [documentation site](https://github.com/xcalen/scope-rx/docs).
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Citation
+
+If you use ScopeRX in your research, please cite:
+
+```bibtex
+@software{scoperx2024,
+  title = {ScopeRX: Neural Network Explainability Library},
+  author = {XCALEN},
+  year = {2024},
+  url = {https://github.com/xcalen/scope-rx}
+}
+```
+
+## Acknowledgments
+
+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**

scope_rx-2.0.0/README.md

@@ -0,0 +1,297 @@
+# ScopeRX
+
+**Neural Network Explainability and Interpretability Library**
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![CI](https://github.com/xcalen/scope-rx/actions/workflows/ci.yml/badge.svg)](https://github.com/xcalen/scope-rx/actions/workflows/ci.yml) [![Codecov](https://codecov.io/gh/xcalen/scope-rx/branch/main/graph/badge.svg)](https://codecov.io/gh/xcalen/scope-rx)
+
+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.
+
+## Version 2.0.0 Updates
+- **Type Safety**: Fully typed codebase with `mypy` compliance.
+- **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.
+
+## Features
+
+- **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
+
+## Installation
+
+```bash
+pip install scope-rx
+```
+
+**With optional dependencies:**
+
+```bash
+# For interactive Plotly visualizations
+pip install scope-rx[interactive]
+
+# For development
+pip install scope-rx[dev]
+
+# Full installation with all extras
+pip install scope-rx[full]
+```
+
+## Quick Start
+
+```python
+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")
+```
+
+## Available Methods
+
+### Gradient-Based Methods
+
+| 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       |
+
+### Perturbation-Based Methods
+
+| 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     |
+
+### Model-Agnostic Methods
+
+| Method          | Description                      | Use Case                       |
+| --------------- | -------------------------------- | ------------------------------ |
+| `kernel_shap` | Kernel SHAP approximation        | Shapley value estimation       |
+| `lime`        | Local Interpretable Explanations | Interpretable local surrogates |
+
+### Attention-Based Methods (for Transformers)
+
+| 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    |
+
+## Compare Methods
+
+```python
+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()})
+```
+
+## Evaluate Explanations
+
+```python
+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)
+```
+
+## Visualization
+
+```python
+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
+```
+
+## Command Line Interface
+
+```bash
+# 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 resnet50
+```
+
+## Advanced Usage
+
+### Custom Target Layers
+
+```python
+from scope_rx import GradCAM
+
+# Specify exact layer
+explainer = GradCAM(model, target_layer="layer4.1.conv2")
+```
+
+### Custom Baselines for Integrated Gradients
+
+```python
+from scope_rx import IntegratedGradients
+
+# Use different baselines
+explainer = IntegratedGradients(
+    model,
+    n_steps=50,
+    baseline="blur"  # Options: "zero", "random", "blur"
+)
+```
+
+### Batch Processing
+
+```python
+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")
+```
+
+### Using Individual Explainers
+
+```python
+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)
+```
+
+## Testing
+
+```bash
+# Run all tests
+pytest tests/
+
+# Run with coverage
+pytest tests/ --cov=scope_rx --cov-report=html
+
+# Run specific test module
+pytest tests/test_gradient_methods.py -v
+```
+
+## Documentation
+
+For full documentation, visit our [documentation site](https://github.com/xcalen/scope-rx/docs).
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Citation
+
+If you use ScopeRX in your research, please cite:
+
+```bibtex
+@software{scoperx2024,
+  title = {ScopeRX: Neural Network Explainability Library},
+  author = {XCALEN},
+  year = {2024},
+  url = {https://github.com/xcalen/scope-rx}
+}
+```
+
+## Acknowledgments
+
+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**