explainiverse 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

{explainiverse-0.5.0.dist-info → explainiverse-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: explainiverse
-Version: 0.5.0
+Version: 0.7.0
 Summary: Unified, extensible explainability framework supporting LIME, SHAP, Anchors, Counterfactuals, PDP, ALE, SAGE, and more
 Home-page: https://github.com/jemsbhai/explainiverse
 License: MIT
@@ -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 **15 state-of-the-art explanation methods** across local, global, gradient-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 **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.
 
 ---
 
@@ -43,7 +43,7 @@ Description-Content-Type: text/markdown
 
 | Feature | Description |
 |---------|-------------|
-| **15 Explainers** | LIME, KernelSHAP, TreeSHAP, Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, GradCAM/GradCAM++, Anchors, Counterfactual, Permutation Importance, PDP, ALE, SAGE, ProtoDash |
+| **17 Explainers** | LIME, KernelSHAP, TreeSHAP, Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, Saliency Maps, GradCAM/GradCAM++, 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 |
@@ -64,7 +64,9 @@ Description-Content-Type: text/markdown
 | **DeepLIFT** | Gradient | [Shrikumar et al., 2017](https://arxiv.org/abs/1704.02685) |
 | **DeepSHAP** | Gradient + Shapley | [Lundberg & Lee, 2017](https://arxiv.org/abs/1705.07874) |
 | **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) |
+| **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) |
 | **ProtoDash** | Example-Based | [Gurumoorthy et al., 2019](https://arxiv.org/abs/1707.01212) |
@@ -141,8 +143,8 @@ 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', 'gradcam', 'anchors', 'counterfactual', 'protodash',
-#  'permutation_importance', 'partial_dependence', 'ale', 'sage']
+#  'smoothgrad', 'saliency', 'gradcam', 'tcav', 'anchors', 'counterfactual', 
+#  'protodash', 'permutation_importance', 'partial_dependence', 'ale', 'sage']
 
 # Create an explainer via registry
 explainer = default_registry.create(
@@ -233,6 +235,41 @@ deepshap = DeepLIFTShapExplainer(
 explanation = deepshap.explain(X[0])
 ```
 
+### Saliency Maps
+
+```python
+from explainiverse.explainers.gradient import SaliencyExplainer
+
+# Saliency Maps - simplest and fastest gradient method
+explainer = SaliencyExplainer(
+    model=adapter,
+    feature_names=feature_names,
+    class_names=class_names,
+    absolute_value=True  # Default: absolute gradient magnitudes
+)
+
+# Standard saliency (absolute gradients)
+explanation = explainer.explain(X[0], method="saliency")
+
+# Input × Gradient (gradient scaled by input values)
+explanation = explainer.explain(X[0], method="input_times_gradient")
+
+# Signed saliency (keep gradient direction)
+explainer_signed = SaliencyExplainer(
+    model=adapter,
+    feature_names=feature_names,
+    class_names=class_names,
+    absolute_value=False
+)
+explanation = explainer_signed.explain(X[0])
+
+# Compare all variants
+variants = explainer.compute_all_variants(X[0])
+print(variants["saliency_absolute"])
+print(variants["saliency_signed"])
+print(variants["input_times_gradient"])
+```
+
 ### SmoothGrad
 
 ```python
@@ -281,6 +318,56 @@ heatmap = explanation.explanation_data["heatmap"]
 overlay = explainer.get_overlay(original_image, heatmap, alpha=0.5)
 ```
 
+### TCAV (Concept-Based Explanations)
+
+```python
+from explainiverse.explainers.gradient import TCAVExplainer
+
+# For neural network models with concept examples
+adapter = PyTorchAdapter(model, task="classification", class_names=class_names)
+
+# Create TCAV explainer targeting a specific layer
+explainer = TCAVExplainer(
+    model=adapter,
+    layer_name="layer3",  # Target layer for concept analysis
+    class_names=class_names
+)
+
+# Learn a concept from examples (e.g., "striped" pattern)
+explainer.learn_concept(
+    concept_name="striped",
+    concept_examples=striped_images,      # Images with stripes
+    negative_examples=random_images,      # Random images without stripes
+    min_accuracy=0.6                      # Minimum CAV classifier accuracy
+)
+
+# Compute TCAV score: fraction of inputs where concept positively influences prediction
+tcav_score = explainer.compute_tcav_score(
+    test_inputs=test_images,
+    target_class=0,           # e.g., "zebra"
+    concept_name="striped"
+)
+print(f"TCAV score: {tcav_score:.3f}")  # >0.5 means concept positively influences class
+
+# Statistical significance testing against random concepts
+result = explainer.statistical_significance_test(
+    test_inputs=test_images,
+    target_class=0,
+    concept_name="striped",
+    n_random=10,
+    negative_examples=random_images
+)
+print(f"p-value: {result['p_value']:.4f}, significant: {result['significant']}")
+
+# Full explanation with multiple concepts
+explanation = explainer.explain(
+    test_inputs=test_images,
+    target_class=0,
+    run_significance_test=True
+)
+print(explanation.explanation_data["tcav_scores"])
+```
+
 ---
 
 ## Example-Based Explanations
@@ -515,7 +602,7 @@ explainiverse/
 │   └── pytorch_adapter.py  # With gradient support
 ├── explainers/
 │   ├── attribution/      # LIME, SHAP, TreeSHAP
-│   ├── gradient/         # IG, DeepLIFT, DeepSHAP, SmoothGrad, GradCAM
+│   ├── gradient/         # IG, DeepLIFT, DeepSHAP, SmoothGrad, Saliency, GradCAM, TCAV
 │   ├── rule_based/       # Anchors
 │   ├── counterfactual/   # DiCE-style
 │   ├── global_explainers/  # Permutation, PDP, ALE, SAGE
@@ -552,7 +639,8 @@ poetry run pytest tests/test_smoothgrad.py::TestSmoothGradBasic -v
 ### Completed ✅
 - [x] Core framework (BaseExplainer, Explanation, Registry)
 - [x] Perturbation methods: LIME, KernelSHAP, TreeSHAP
-- [x] Gradient methods: Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, GradCAM/GradCAM++
+- [x] Gradient methods: Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, Saliency Maps, GradCAM/GradCAM++
+- [x] Concept-based: TCAV (Testing with Concept Activation Vectors)
 - [x] Rule-based: Anchors
 - [x] Counterfactual: DiCE-style
 - [x] Global: Permutation Importance, PDP, ALE, SAGE
@@ -562,8 +650,6 @@ poetry run pytest tests/test_smoothgrad.py::TestSmoothGradBasic -v
 - [x] PyTorch adapter with gradient support
 
 ### In Progress 🚧
-- [ ] Saliency Maps (vanilla gradients)
-- [ ] TCAV (Testing with Concept Activation Vectors)
 - [ ] Layer-wise Relevance Propagation (LRP)
 
 ### Planned 📋
@@ -585,7 +671,7 @@ If you use Explainiverse in your research, please cite:
   author = {Syed, Muntaser},
   year = {2025},
   url = {https://github.com/jemsbhai/explainiverse},
-  version = {0.5.0}
+  version = {0.7.0}
 }
 ```
 
@@ -613,5 +699,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, 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, GradCAM, TCAV, Anchors, DiCE, ALE, SAGE, and ProtoDash for their contributions to interpretable machine learning.
 

{explainiverse-0.5.0.dist-info → explainiverse-0.7.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-explainiverse/__init__.py,sha256=LB5iTelrUHMZa5ctl2MMei54U6Ir_CBqlxi8yY5kHJY,1612
+explainiverse/__init__.py,sha256=u67gp9ZbzMDs2ECjXvs4aZUbjELRPfx32jGszJhhZ7U,1612
 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=GTilJAR1VF_OgWG88qZoqlqefHaSXB3i9iOwCJkyHTg,13318
@@ -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=6zxFh_TH8tFHc-r_H5-WHQ05Sp1Kp2TxLz3gyFek5jo,881
-explainiverse/core/registry.py,sha256=VK_a2C_ff7HspyR0MhprQPPHYLaN9H7q2F3gofXe0bo,24754
+explainiverse/core/registry.py,sha256=BAqk2FKqbrZcoLqlODXRCOolb57DBgS-Kxs_CCtngvw,26376
 explainiverse/engine/__init__.py,sha256=1sZO8nH1mmwK2e-KUavBQm7zYDWUe27nyWoFy9tgsiA,197
 explainiverse/engine/suite.py,sha256=sq8SK_6Pf0qRckTmVJ7Mdosu9bhkjAGPGN8ymLGFP9E,4914
 explainiverse/evaluation/__init__.py,sha256=ePE97KwSjg_IChZ03DeQax8GruTjx-BVrMSi_nzoyoA,1501
@@ -28,14 +28,16 @@ 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=HEVotHgwUi731Y_jzSz4_URAGFtjebyU1uk1RHunF4c,707
+explainiverse/explainers/gradient/__init__.py,sha256=Tkf9jiXVfjVVDAhBocDc2tzFJK8RZv8H1pN8J0Ha53o,1362
 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=feBgY3Vw2rDti7fxRZtLkxse75m2dbP_R05ARqo2BRM,13367
+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.5.0.dist-info/LICENSE,sha256=28rbHe8rJgmUlRdxJACfq1Sj-MtCEhyHxkJedQd1ZYA,1070
-explainiverse-0.5.0.dist-info/METADATA,sha256=ZYzZiwm33v08PA3Ihl5rwhuWieLzRrFgoR6WmPFABsc,18511
-explainiverse-0.5.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-explainiverse-0.5.0.dist-info/RECORD,,
+explainiverse-0.7.0.dist-info/LICENSE,sha256=28rbHe8rJgmUlRdxJACfq1Sj-MtCEhyHxkJedQd1ZYA,1070
+explainiverse-0.7.0.dist-info/METADATA,sha256=DoZnwq5ew4n_xKcuoWu7Xi6uPb386yUTeDMPHWsWg1s,21352
+explainiverse-0.7.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+explainiverse-0.7.0.dist-info/RECORD,,