explainiverse 0.7.1__py3-none-any.whl → 0.8.1__py3-none-any.whl

{explainiverse-0.7.1.dist-info → explainiverse-0.8.1.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: explainiverse
-Version: 0.7.1
-Summary: Unified, extensible explainability framework supporting LIME, SHAP, Anchors, Counterfactuals, PDP, ALE, SAGE, and more
+Version: 0.8.1
+Summary: Unified, extensible explainability framework supporting 18 XAI methods including LIME, SHAP, LRP, TCAV, GradCAM, and more
 Home-page: https://github.com/jemsbhai/explainiverse
 License: MIT
 Keywords: xai,explainability,interpretability,machine-learning,lime,shap,anchors
@@ -35,7 +35,7 @@ Description-Content-Type: text/markdown
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Explainiverse** is a unified, extensible Python framework for Explainable AI (XAI). It provides a standardized interface for **17 state-of-the-art explanation methods** across local, global, gradient-based, concept-based, and example-based paradigms, along with **comprehensive evaluation metrics** for assessing explanation quality.
+**Explainiverse** is a unified, extensible Python framework for Explainable AI (XAI). It provides a standardized interface for **18 state-of-the-art explanation methods** across local, global, gradient-based, concept-based, and example-based paradigms, along with **comprehensive evaluation metrics** for assessing explanation quality.
 
 ---
 
@@ -43,7 +43,7 @@ Description-Content-Type: text/markdown
 
 | Feature | Description |
 |---------|-------------|
-| **17 Explainers** | LIME, KernelSHAP, TreeSHAP, Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, Saliency Maps, GradCAM/GradCAM++, TCAV, Anchors, Counterfactual, Permutation Importance, PDP, ALE, SAGE, ProtoDash |
+| **18 Explainers** | LIME, KernelSHAP, TreeSHAP, Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, Saliency Maps, GradCAM/GradCAM++, LRP, TCAV, Anchors, Counterfactual, Permutation Importance, PDP, ALE, SAGE, ProtoDash |
 | **8 Evaluation Metrics** | Faithfulness (PGI, PGU, Comprehensiveness, Sufficiency, Correlation) and Stability (RIS, ROS, Lipschitz) |
 | **Unified API** | Consistent `BaseExplainer` interface with standardized `Explanation` output |
 | **Plugin Registry** | Filter explainers by scope, model type, data type; automatic recommendations |
@@ -66,6 +66,7 @@ Description-Content-Type: text/markdown
 | **SmoothGrad** | Gradient | [Smilkov et al., 2017](https://arxiv.org/abs/1706.03825) |
 | **Saliency Maps** | Gradient | [Simonyan et al., 2014](https://arxiv.org/abs/1312.6034) |
 | **GradCAM / GradCAM++** | Gradient (CNN) | [Selvaraju et al., 2017](https://arxiv.org/abs/1610.02391) |
+| **LRP** | Decomposition | [Bach et al., 2015](https://doi.org/10.1371/journal.pone.0130140) |
 | **TCAV** | Concept-Based | [Kim et al., 2018](https://arxiv.org/abs/1711.11279) |
 | **Anchors** | Rule-Based | [Ribeiro et al., 2018](https://ojs.aaai.org/index.php/AAAI/article/view/11491) |
 | **Counterfactual** | Contrastive | [Mothilal et al., 2020](https://arxiv.org/abs/1905.07697) |
@@ -143,7 +144,7 @@ adapter = SklearnAdapter(model, class_names=iris.target_names.tolist())
 # List all available explainers
 print(default_registry.list_explainers())
 # ['lime', 'shap', 'treeshap', 'integrated_gradients', 'deeplift', 'deepshap', 
-#  'smoothgrad', 'saliency', 'gradcam', 'tcav', 'anchors', 'counterfactual', 
+#  'smoothgrad', 'saliency', 'gradcam', 'lrp', 'tcav', 'anchors', 'counterfactual', 
 #  'protodash', 'permutation_importance', 'partial_dependence', 'ale', 'sage']
 
 # Create an explainer via registry
@@ -211,6 +212,70 @@ print(f"Attributions: {explanation.explanation_data['feature_attributions']}")
 print(f"Convergence δ: {explanation.explanation_data['convergence_delta']:.6f}")
 ```
 
+### Layer-wise Relevance Propagation (LRP)
+
+```python
+from explainiverse.explainers.gradient import LRPExplainer
+
+# LRP - Decomposition-based attribution with conservation property
+explainer = LRPExplainer(
+    model=adapter,
+    feature_names=feature_names,
+    class_names=class_names,
+    rule="epsilon",       # Propagation rule: epsilon, gamma, alpha_beta, z_plus, composite
+    epsilon=1e-6          # Stabilization constant
+)
+
+# Basic explanation
+explanation = explainer.explain(X[0], target_class=0)
+print(explanation.explanation_data["feature_attributions"])
+
+# Verify conservation property (sum of attributions ≈ target output)
+explanation = explainer.explain(X[0], return_convergence_delta=True)
+print(f"Conservation delta: {explanation.explanation_data['convergence_delta']:.6f}")
+
+# Compare different LRP rules
+comparison = explainer.compare_rules(X[0], rules=["epsilon", "gamma", "z_plus"])
+for rule, result in comparison.items():
+    print(f"{rule}: top feature = {result['top_feature']}")
+
+# Layer-wise relevance analysis
+layer_result = explainer.explain_with_layer_relevances(X[0])
+for layer, relevances in layer_result["layer_relevances"].items():
+    print(f"{layer}: sum = {sum(relevances):.4f}")
+
+# Composite rules: different rules for different layers
+explainer_composite = LRPExplainer(
+    model=adapter,
+    feature_names=feature_names,
+    class_names=class_names,
+    rule="composite"
+)
+explainer_composite.set_composite_rule({
+    0: "z_plus",    # Input layer: focus on what's present
+    2: "epsilon",   # Middle layers: balanced
+    4: "epsilon"    # Output layer
+})
+explanation = explainer_composite.explain(X[0])
+```
+
+**LRP Propagation Rules:**
+
+| Rule | Description | Use Case |
+|------|-------------|----------|
+| `epsilon` | Adds stabilization constant | General purpose (default) |
+| `gamma` | Enhances positive contributions | Image classification |
+| `alpha_beta` | Separates pos/neg (α-β=1) | Fine-grained control |
+| `z_plus` | Only positive weights | Input layers, what's present |
+| `composite` | Different rules per layer | Best practice for deep nets |
+
+**Supported Layers:**
+- Linear, Conv2d
+- BatchNorm1d, BatchNorm2d
+- ReLU, LeakyReLU, ELU, Tanh, Sigmoid, GELU
+- MaxPool2d, AvgPool2d, AdaptiveAvgPool2d
+- Flatten, Dropout
+
 ### DeepLIFT and DeepSHAP
 
 ```python
@@ -602,7 +667,7 @@ explainiverse/
 │   └── pytorch_adapter.py  # With gradient support
 ├── explainers/
 │   ├── attribution/      # LIME, SHAP, TreeSHAP
-│   ├── gradient/         # IG, DeepLIFT, DeepSHAP, SmoothGrad, Saliency, GradCAM, TCAV
+│   ├── gradient/         # IG, DeepLIFT, DeepSHAP, SmoothGrad, Saliency, GradCAM, LRP, TCAV
 │   ├── rule_based/       # Anchors
 │   ├── counterfactual/   # DiCE-style
 │   ├── global_explainers/  # Permutation, PDP, ALE, SAGE
@@ -626,10 +691,10 @@ poetry run pytest
 poetry run pytest --cov=explainiverse --cov-report=html
 
 # Run specific test file
-poetry run pytest tests/test_smoothgrad.py -v
+poetry run pytest tests/test_lrp.py -v
 
 # Run specific test class
-poetry run pytest tests/test_smoothgrad.py::TestSmoothGradBasic -v
+poetry run pytest tests/test_lrp.py::TestLRPConv2d -v
 ```
 
 ---
@@ -640,6 +705,7 @@ poetry run pytest tests/test_smoothgrad.py::TestSmoothGradBasic -v
 - [x] Core framework (BaseExplainer, Explanation, Registry)
 - [x] Perturbation methods: LIME, KernelSHAP, TreeSHAP
 - [x] Gradient methods: Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, Saliency Maps, GradCAM/GradCAM++
+- [x] Decomposition methods: Layer-wise Relevance Propagation (LRP) with ε, γ, αβ, z⁺, composite rules
 - [x] Concept-based: TCAV (Testing with Concept Activation Vectors)
 - [x] Rule-based: Anchors
 - [x] Counterfactual: DiCE-style
@@ -649,9 +715,6 @@ poetry run pytest tests/test_smoothgrad.py::TestSmoothGradBasic -v
 - [x] Evaluation: Stability metrics (RIS, ROS, Lipschitz)
 - [x] PyTorch adapter with gradient support
 
-### In Progress 🚧
-- [ ] Layer-wise Relevance Propagation (LRP)
-
 ### Planned 📋
 - [ ] Attention-based explanations (for Transformers)
 - [ ] TensorFlow/Keras adapter
@@ -671,7 +734,7 @@ If you use Explainiverse in your research, please cite:
   author = {Syed, Muntaser},
   year = {2025},
   url = {https://github.com/jemsbhai/explainiverse},
-  version = {0.7.1}
+  version = {0.8.0}
 }
 ```
 
@@ -699,5 +762,5 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 ## Acknowledgments
 
-Explainiverse builds upon the foundational work of many researchers in the XAI community. We thank the authors of LIME, SHAP, Integrated Gradients, DeepLIFT, GradCAM, TCAV, Anchors, DiCE, ALE, SAGE, and ProtoDash for their contributions to interpretable machine learning.
+Explainiverse builds upon the foundational work of many researchers in the XAI community. We thank the authors of LIME, SHAP, Integrated Gradients, DeepLIFT, LRP, GradCAM, TCAV, Anchors, DiCE, ALE, SAGE, and ProtoDash for their contributions to interpretable machine learning.
 

{explainiverse-0.7.1.dist-info → explainiverse-0.8.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-explainiverse/__init__.py,sha256=hkP-f-GcO7dKhO6otGj63cuqwFRiXBYAYZr4wrim4fY,1612
+explainiverse/__init__.py,sha256=fnB58cF7z1PvBjNkKvEcmXI0u2l3T3FYLyCx1sLEmXQ,1694
 explainiverse/adapters/__init__.py,sha256=HcQGISyp-YQ4jEj2IYveX_c9X5otLcTNWRnVRRhzRik,781
 explainiverse/adapters/base_adapter.py,sha256=Nqt0GeDn_-PjTyJcZsE8dRTulavqFQsv8sMYWS_ps-M,603
 explainiverse/adapters/pytorch_adapter.py,sha256=DLQKJ7gB0foPwAmcrru7QdZnPRnhqDKpFCT-EaD3420,15612
@@ -6,7 +6,7 @@ explainiverse/adapters/sklearn_adapter.py,sha256=pzIBtMuqrG-6ZbUqUCMt7rSk3Ow0Fgr
 explainiverse/core/__init__.py,sha256=P3jHMnH5coFqTTO1w-gT-rurkCM1-9r3pF-055pbXMg,474
 explainiverse/core/explainer.py,sha256=Z9on-9VblYDlQx9oBm1BHpmAf_NsQajZ3qr-u48Aejo,784
 explainiverse/core/explanation.py,sha256=498BbRYrNR-BOql78sENOsyWxgqLsBVZXn14lh-bhww,6241
-explainiverse/core/registry.py,sha256=BAqk2FKqbrZcoLqlODXRCOolb57DBgS-Kxs_CCtngvw,26376
+explainiverse/core/registry.py,sha256=6HttL27Ty4jYtugRf-EDIKPy80M8BfvUppAKwwGDyQ8,27207
 explainiverse/engine/__init__.py,sha256=1sZO8nH1mmwK2e-KUavBQm7zYDWUe27nyWoFy9tgsiA,197
 explainiverse/engine/suite.py,sha256=G-7OjESisSTaQ1FQrlPl4YydX13uz8Bb70hJZNlcl2M,8918
 explainiverse/evaluation/__init__.py,sha256=ePE97KwSjg_IChZ03DeQax8GruTjx-BVrMSi_nzoyoA,1501
@@ -28,16 +28,17 @@ explainiverse/explainers/global_explainers/ale.py,sha256=tgG3XTppCf8LiD7uKzBt4DI
 explainiverse/explainers/global_explainers/partial_dependence.py,sha256=dH6yMjpwZads3pACR3rSykTbssLGHH7e6HfMlpl-S3I,6745
 explainiverse/explainers/global_explainers/permutation_importance.py,sha256=bcgKz1S_D3lrBMgpqEF_Z6qw8Knxl_cfR50hrSO2tBc,4410
 explainiverse/explainers/global_explainers/sage.py,sha256=57Xw1SK529x5JXWt0TVrcFYUUP3C65LfUwgoM-Z3gaw,5839
-explainiverse/explainers/gradient/__init__.py,sha256=Tkf9jiXVfjVVDAhBocDc2tzFJK8RZv8H1pN8J0Ha53o,1362
+explainiverse/explainers/gradient/__init__.py,sha256=BAMGRO-UsGJx7lD3XG34mJAGHFWPX2AJsIdaf_8gZsg,1498
 explainiverse/explainers/gradient/deeplift.py,sha256=MWOlslizUeoZs31moy2iBgp02N08nBsVU-RoEpODg3M,27775
 explainiverse/explainers/gradient/gradcam.py,sha256=ywW_8PhALwegkpSUDQMFvvVFkA5NnMMW6BB5tb3i8bw,13721
 explainiverse/explainers/gradient/integrated_gradients.py,sha256=EfIX4TMwfSx7Tl_2efy-oLFt9Xx7byJPV8DxbtFIeKw,18098
+explainiverse/explainers/gradient/lrp.py,sha256=ipHC1bgace2KJjlk6UnNWHFsMzNxofVYRjFphc1Ym4g,45469
 explainiverse/explainers/gradient/saliency.py,sha256=pcimyuSqKzsIR1yCMNWfH2M7T_vcDKkwcVv0zQlPL3w,10305
 explainiverse/explainers/gradient/smoothgrad.py,sha256=COIKZSFcApmMkA62M0AForHiYlQ6hSFx5hZIabRXGlM,15727
 explainiverse/explainers/gradient/tcav.py,sha256=zc-8wMsc2ZOhUeSZNBJ6H6BPXlVMJ9DRcAMiL25wU9I,32242
 explainiverse/explainers/rule_based/__init__.py,sha256=gKzlFCAzwurAMLJcuYgal4XhDj1thteBGcaHWmN7iWk,243
 explainiverse/explainers/rule_based/anchors_wrapper.py,sha256=ML7W6aam-eMGZHy5ilol8qupZvNBJpYAFatEEPnuMyo,13254
-explainiverse-0.7.1.dist-info/LICENSE,sha256=28rbHe8rJgmUlRdxJACfq1Sj-MtCEhyHxkJedQd1ZYA,1070
-explainiverse-0.7.1.dist-info/METADATA,sha256=pWUARu9qMLDBnOTcuxumoo9KC0WaCLFh7DdJHdpcDvw,21352
-explainiverse-0.7.1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-explainiverse-0.7.1.dist-info/RECORD,,
+explainiverse-0.8.1.dist-info/LICENSE,sha256=28rbHe8rJgmUlRdxJACfq1Sj-MtCEhyHxkJedQd1ZYA,1070
+explainiverse-0.8.1.dist-info/METADATA,sha256=A5NjgO7v2I-P8sjFW8yaJCd_VcU_Dqumq2iRdl0_Fbc,23770
+explainiverse-0.8.1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+explainiverse-0.8.1.dist-info/RECORD,,