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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: explainiverse
-Version: 0.6.0
+Version: 0.7.1
 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 **16 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 |
 |---------|-------------|
-| **16 Explainers** | LIME, KernelSHAP, TreeSHAP, Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, Saliency Maps, 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 |
@@ -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) |
+| **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) |
@@ -142,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(
@@ -317,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
@@ -551,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
@@ -589,6 +640,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] Concept-based: TCAV (Testing with Concept Activation Vectors)
 - [x] Rule-based: Anchors
 - [x] Counterfactual: DiCE-style
 - [x] Global: Permutation Importance, PDP, ALE, SAGE
@@ -598,7 +650,6 @@ poetry run pytest tests/test_smoothgrad.py::TestSmoothGradBasic -v
 - [x] PyTorch adapter with gradient support
 
 ### In Progress 🚧
-- [ ] TCAV (Testing with Concept Activation Vectors)
 - [ ] Layer-wise Relevance Propagation (LRP)
 
 ### Planned 📋
@@ -620,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.6.0}
+  version = {0.7.1}
 }
 ```
 
@@ -648,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.6.0.dist-info → explainiverse-0.7.1.dist-info}/RECORD

@@ -1,23 +1,23 @@
-explainiverse/__init__.py,sha256=oVivthTc0ts34DyEPWhilq7YOGYDjLLRvWxoKYHsIlo,1612
+explainiverse/__init__.py,sha256=hkP-f-GcO7dKhO6otGj63cuqwFRiXBYAYZr4wrim4fY,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
+explainiverse/adapters/pytorch_adapter.py,sha256=DLQKJ7gB0foPwAmcrru7QdZnPRnhqDKpFCT-EaD3420,15612
 explainiverse/adapters/sklearn_adapter.py,sha256=pzIBtMuqrG-6ZbUqUCMt7rSk3Ow0FgrY268FSweFvw4,958
 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=ZIq9Jzrr_oXi5tvGmY0k9gVNA34EtGIeTpWO5hQ3iVg,25527
+explainiverse/core/explanation.py,sha256=498BbRYrNR-BOql78sENOsyWxgqLsBVZXn14lh-bhww,6241
+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/engine/suite.py,sha256=G-7OjESisSTaQ1FQrlPl4YydX13uz8Bb70hJZNlcl2M,8918
 explainiverse/evaluation/__init__.py,sha256=ePE97KwSjg_IChZ03DeQax8GruTjx-BVrMSi_nzoyoA,1501
 explainiverse/evaluation/_utils.py,sha256=ej7YOPZ90gVHuuIMj45EXHq9Jx3QG7lhaj5sk26hRpg,10519
 explainiverse/evaluation/faithfulness.py,sha256=_40afOW6vJ3dQguHlJySlgWqiJF_xIvN-uVA3nPKRvI,14841
-explainiverse/evaluation/metrics.py,sha256=tSBXtyA_-0zOGCGjlPZU6LdGKRH_QpWfgKa78sdlovs,7453
+explainiverse/evaluation/metrics.py,sha256=snNK9Ua1VzHDT6DlrhYL4m2MmRF3X15vuuVXiHbeicU,9944
 explainiverse/evaluation/stability.py,sha256=q2d3rpxpp0X1s6ADST1iZA4tzksLJpR0mYBnA_U5FIs,12090
 explainiverse/explainers/__init__.py,sha256=-ncRXbFKahH3bR0oXM2UQM4LtTdTlvdeprL6cHeqNBs,2549
 explainiverse/explainers/attribution/__init__.py,sha256=YeVs9bS_IWDtqGbp6T37V6Zp5ZDWzLdAXHxxyFGpiQM,431
-explainiverse/explainers/attribution/lime_wrapper.py,sha256=OnXIV7t6yd-vt38sIi7XmHFbgzlZfCEbRlFyGGd5XiE,3245
-explainiverse/explainers/attribution/shap_wrapper.py,sha256=tKie5AvN7mb55PWOYdMvW0lUAYjfHPzYosEloEY2ZzI,3210
+explainiverse/explainers/attribution/lime_wrapper.py,sha256=yexy8m4VoVbsIGaMIcwU41ChWZvd-Y_vadtfyarwE4k,5518
+explainiverse/explainers/attribution/shap_wrapper.py,sha256=M6t-W9S0czZsOFXDsCn9uMW1wMoVO97ISDpiNjN0TsU,5902
 explainiverse/explainers/attribution/treeshap_wrapper.py,sha256=LcBjHzQjmeyWCwLXALJ0WFQ9ol-N_8dod577EDxFDKY,16758
 explainiverse/explainers/counterfactual/__init__.py,sha256=gEV6P8h2fZ3-pv5rqp5sNDqrLErh5ntqpxIIBVCMFv4,247
 explainiverse/explainers/counterfactual/dice_wrapper.py,sha256=PyJYF-z1nyyy0mFROnkJqPtcuT2PwEBARwfh37mZ5ew,11373
@@ -28,15 +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=-A6hk5k9kbSOf8iTkzWvpnQ6SRVc72KvpVUH_1fuFNI,805
+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/integrated_gradients.py,sha256=EfIX4TMwfSx7Tl_2efy-oLFt9Xx7byJPV8DxbtFIeKw,18098
 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.6.0.dist-info/LICENSE,sha256=28rbHe8rJgmUlRdxJACfq1Sj-MtCEhyHxkJedQd1ZYA,1070
-explainiverse-0.6.0.dist-info/METADATA,sha256=KLQeJ57yUbYptTo5uS7IaVA3i6I60n3qXS7vfbW8vaU,19569
-explainiverse-0.6.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-explainiverse-0.6.0.dist-info/RECORD,,
+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,,