+ 
- 
+ 
@@ -45,16 +45,16 @@
ยท
Metrics
.
- Example-based
+ Example-based
-> [!IMPORTANT]
-> With the release of Keras 3.X since TensorFlow 2.16, some methods may not function as expected. We are actively working on a fix. In the meantime, we recommend using TensorFlow 2.15 or earlier versions for optimal compatibility.
+> [!NOTE]
+> **What's new in v2.0.0:** Holistic CRAFT can extract and attribute concepts from classification and object detection models through `HolisticCraftTf` and `HolisticCraftTorch`. The release also introduces framework-specific latent extractors, `LayeredModelExtractorBuilder`, `PartialExplainer`, and `EncodedData`. Xplique 2.0.0 supports Python 3.10-3.13, TensorFlow 2.18-2.20, and optional PyTorch 2.5-2.10. Detector-specific adapters are under construction in the DEEL AI organization and will be pip-installable soon.
The library is composed of several modules, the _Attributions Methods_ module implements various methods (e.g Saliency, Grad-CAM, FEM, Integrated-Gradients...), with explanations, examples and links to official papers.
The _Feature Visualization_ module allows to see how neural networks build their understanding of images by finding inputs that maximize neurons, channels, layers or compositions of these elements.
-The _Concepts_ module allows you to extract human concepts from a model and to test their usefulness with respect to a class.
-Finally, the _Metrics_ module covers the current metrics used in explainability. Used in conjunction with the _Attribution Methods_ module, it allows you to test the different methods or evaluate the explanations of a model.
+The _Concepts_ module allows you to extract human concepts from a model and to test their usefulness with respect to a class. Holistic CRAFT extends concept extraction to full activation maps, including object detection models.
+Finally, the _Metrics_ module covers the current metrics used in explainability. Used in conjunction with the _Attribution Methods_ module, it allows you to test the different methods or evaluate the explanations of a model. The _Example-based_ module explains predictions by retrieving relevant examples from a dataset.
@@ -62,9 +62,6 @@ Finally, the _Metrics_ module covers the current metrics used in explainability.
-> [!NOTE]
-> We are proud to announce the release of the _Example-based_ module! This module is dedicated to methods that explain a model by retrieving relevant examples from a dataset. It includes methods that belong to different families: similar examples, contrastive (counter-factuals and semi-factuals) examples, and prototypes (as concepts based methods have a dedicated sections).
-
## ๐ฅ Tutorials
@@ -133,12 +132,18 @@ included. We will try to cover all the possible usage of the library, feel free
## ๐ Quick Start
-Xplique requires a version of python higher than 3.7 and several libraries including Tensorflow and Numpy. Installation can be done using Pypi:
+Xplique supports Python 3.10 through 3.13 and several libraries including TensorFlow and NumPy. Installation can be done using PyPI:
```python
pip install xplique
```
+For PyTorch models and concept methods, install the optional dependencies:
+
+```bash
+pip install "xplique[torch]"
+```
+
Now that Xplique is installed, here are basic examples of what you can do with the available modules.
Table of example-based methods available
diff --git a/TUTORIALS.md b/TUTORIALS.md
index 7839bfb1..82a0daff 100644
--- a/TUTORIALS.md
+++ b/TUTORIALS.md
@@ -58,7 +58,7 @@ Here is the lists of the available tutorial for now:
| Fidelity | Average Drop/Increase/Gain | [](https://colab.research.google.com/drive/1nGP13qiQrsJMBx8TXgA69D-5ALoP3l9p) |
| Complexity | Complexity | [](https://colab.research.google.com/drive/13boAsXGVKS0LaNzslOdjSkYIrpBJdh7K) |
| Randomization | Randomization | [](https://colab.research.google.com/drive/13lNkZqKajRJ63XllkQddgrPOYF1Xv9-Y) |
-| Stability | AverageStability | **(WIP)** |
+| Stability | AverageStability | [Documentation](docs/api/attributions/metrics/avg_stability.md) |
## PyTorch Wrapper
@@ -72,7 +72,13 @@ Here is the lists of the available tutorial for now:
## Concepts extraction
-**WIP**
+| Category | **Tutorial Name** | Documentation / Notebook |
+|:------------- | :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+| Labelled concept methods | CAV + TCAV | [](https://colab.research.google.com/drive/1iuEz46ZjgG97vTBH8p-vod3y14UETvVE) |
+| Automatic concept extraction | CRAFT TensorFlow | [](https://colab.research.google.com/drive/1jmyhb89Bdz7H4G2KfK8uEVbSC-C_aht_) |
+| Automatic concept extraction | CRAFT PyTorch | [](https://colab.research.google.com/drive/16Jn2pQy4gi2qQYZFnuW6ZNtVAYiNyJHO) |
+| Automatic concept extraction | Holistic CRAFT TensorFlow | [Documentation](docs/api/concepts/holistic_craft.md) |
+| Automatic concept extraction | Holistic CRAFT PyTorch | [Documentation](docs/api/concepts/holistic_craft.md) |
## Feature Visualization
diff --git a/docs/api/attributions/object_detection.md b/docs/api/attributions/object_detection.md
index 949be01c..c3604a4c 100644
--- a/docs/api/attributions/object_detection.md
+++ b/docs/api/attributions/object_detection.md
@@ -2,6 +2,9 @@
[Attributions: Object Detection tutorial](https://colab.research.google.com/drive/1X3Yq7BduMKqTA0XEheoVIpOo3IvOrzWL) [](https://colab.research.google.com/drive/1X3Yq7BduMKqTA0XEheoVIpOo3IvOrzWL)
+!!! tip "Concept-based object detection explanations"
+ For concept-level explanations of object detection models, see [Holistic CRAFT](../concepts/holistic_craft.md). Its architecture-specific extractors cover RetinaNet, Faster R-CNN, FCOS, SSD, YOLO, and DETR through the companion `xplique-adapters` package, which is currently under construction and will be pip-installable soon.
+
@@ -241,4 +244,4 @@ explainer = Saliency(model, operator=custom_operator)
... # All following steps are the same as the examples
```
-[^1] [Black-box Explanation of Object Detectors via Saliency Maps (2021)](https://arxiv.org/pdf/2006.03204.pdf)
\ No newline at end of file
+[^1] [Black-box Explanation of Object Detectors via Saliency Maps (2021)](https://arxiv.org/pdf/2006.03204.pdf)
diff --git a/docs/api/attributions/pytorch.md b/docs/api/attributions/pytorch.md
index 87a33e1c..619d309e 100644
--- a/docs/api/attributions/pytorch.md
+++ b/docs/api/attributions/pytorch.md
@@ -6,6 +6,8 @@
- Other tutorials applying Xplique to PyTorch models: [Attributions: Object Detection](https://colab.research.google.com/drive/1X3Yq7BduMKqTA0XEheoVIpOo3IvOrzWL), [Attributions: Semantic Segmentation](https://colab.research.google.com/drive/1AHg7KO1fCOX5nZLGZfxkZ2-DLPPdSfbX)
+- For concept-based explanations of PyTorch models, see [Holistic CRAFT](../concepts/holistic_craft.md), including its object detection support.
+
!!!note
We should point out that what we did with PyTorch should be possible for other frameworks. Do not hesitate to give it a try and to make a PR if you have been successful!
@@ -44,7 +46,7 @@ score_saliency = metric(explanations)
## Does it work for every module?
-It has been tested on both the `attributions` and the `metrics` modules.
+It has been tested on the `attributions`, `metrics`, and `concepts` modules. Holistic CRAFT adds a native PyTorch path for concept extraction, including object detection models.
@@ -82,6 +84,10 @@ Not yet, but it works for most of them (even for gradient-based ones!):
It works for all tasks covered by Xplique, see [the tasks covered and how to specify them](api_attributions.md#the-tasks-covered).
+### Concept-based explanations
+
+PyTorch classification and object detection models can be explained with `HolisticCraftTorch` through the latent extractor builders described in the [Holistic CRAFT documentation](../concepts/holistic_craft.md). Detector-specific builders are provided by the `xplique-adapters` companion package, which is under construction and will be pip-installable soon.
+
diff --git a/docs/api/concepts/cav.md b/docs/api/concepts/cav.md
index 5b1f5799..5a859fb9 100644
--- a/docs/api/concepts/cav.md
+++ b/docs/api/concepts/cav.md
@@ -25,6 +25,10 @@ cav = cav_renderer(positive_examples, random_examples)
```
+## Related concept methods
+
+For automatic concept extraction, see [CRAFT](craft.md) and [Holistic CRAFT](holistic_craft.md).
+
{{xplique.concepts.cav.Cav}}
[^1]: [Interpretability Beyond Feature Attribution: Quantitative Testing with Concept Activation Vectors (TCAV) (2018).](https://arxiv.org/abs/1711.11279)
diff --git a/docs/api/concepts/craft.md b/docs/api/concepts/craft.md
index 0c47d2fb..b75fac55 100644
--- a/docs/api/concepts/craft.md
+++ b/docs/api/concepts/craft.md
@@ -32,6 +32,9 @@ The concepts will be extracted from this latent space.
!!!warning
Please keep in mind that the activations must be positives (after relu or any positive activation function)
+!!! tip "When to use Holistic CRAFT"
+ Regular CRAFT extracts concepts from image crops and is a good fit for classification datasets. For object detection, scenes with multiple objects, or models where global spatial context matters, use [Holistic CRAFT](holistic_craft.md), which factorizes full activation maps instead.
+
## Example
diff --git a/docs/api/concepts/holistic_craft.md b/docs/api/concepts/holistic_craft.md
index 6d5da5f0..95180c65 100644
--- a/docs/api/concepts/holistic_craft.md
+++ b/docs/api/concepts/holistic_craft.md
@@ -14,7 +14,7 @@ The crop-based approach works well for classification because images of classifi
## Supported Object Detection Models
-Holistic CRAFT works with various object detection architectures through specialized latent extractors provided by the `xplique-adapters` package:
+Holistic CRAFT works with various object detection architectures through specialized latent extractors provided by the companion `xplique-adapters` package. This package is under construction in the DEEL AI organization and will be pip-installable soon; the detector examples below use its planned API:
**PyTorch (torchvision & ultralytics):**
- **RetinaNet** - `RetinanetExtractorBuilder`
@@ -340,9 +340,34 @@ craft.display_images_per_concept(input_images[:5])
## API Reference
-{{xplique.concepts.holistic_craft.HolisticCraft}}
+`EncodedData` is the named tuple returned by `HolisticCraft.encode()`. It contains the
+image-specific `latent_data` and its concept coefficients, `coeffs_u`. `LatentData` is
+the framework-independent interface used to read and replace intermediate activations.
-{{xplique.concepts.holistic_craft.PartialExplainer}}
+The public core API consists of `HolisticCraft`, `PartialExplainer`, and `EncodedData`
+from the `xplique.concepts` package. The framework-independent `LatentData`,
+`LatentExtractor`, and `LatentExtractorBuilder` classes are available from
+`xplique.concepts.latent_extractor`. `PartialExplainer` defers attribution-explainer
+construction until a model and batch size are available.
+
+### TensorFlow
+
+`HolisticCraftTf` is the TensorFlow implementation. `TfLatentExtractor` provides the
+TensorFlow latent extraction and decoding interface.
+
+For generic layered TensorFlow models, use `LayeredModelExtractorBuilder` from
+`xplique.concepts.tf.layered_model_latent_extractor`.
+
+### PyTorch
+
+`HolisticCraftTorch` is the PyTorch implementation. `TorchLatentData` stores the
+framework-specific activations, and `TorchLatentExtractor` handles PyTorch latent
+extraction and decoding.
+
+For generic layered PyTorch models, use `LayeredModelExtractorBuilder` from
+`xplique.concepts.torch.layered_model_latent_extractor`. The PyTorch-specific
+`TorchSklearnNMFFactorizer` and optional `OvercompleteFactorizer` are available from
+`xplique.concepts.torch.factorizer`.
## References
diff --git a/docs/api/concepts/tcav.md b/docs/api/concepts/tcav.md
index baf8c781..1823ca57 100644
--- a/docs/api/concepts/tcav.md
+++ b/docs/api/concepts/tcav.md
@@ -28,6 +28,10 @@ tcav_score = tcav_renderer(samples, class_index, cav)
```
+## Related concept methods
+
+For automatic concept extraction, see [CRAFT](craft.md) and [Holistic CRAFT](holistic_craft.md).
+
{{xplique.concepts.tcav.Tcav}}
[^1]: [Interpretability Beyond Feature Attribution: Quantitative Testing with Concept Activation Vectors (TCAV) (2018).](https://arxiv.org/abs/1711.11279)
diff --git a/docs/api/example_based/api_example_based.md b/docs/api/example_based/api_example_based.md
index dce2337f..15aaff67 100644
--- a/docs/api/example_based/api_example_based.md
+++ b/docs/api/example_based/api_example_based.md
@@ -19,7 +19,7 @@ At present, we made the following choices:
- Try to unify the four families of approaches with a common API.
!!! info
- We are in the early stages of development and are looking for feedback on the API design and the methods we have chosen to implement. Also, we are counting on the community to furnish the collection of methods available. If you are willing to contribute reach us on the [GitHub](https://github.com/deel-ai/xplique) repository (with an issue, pull request, ...).
+ Feedback on the API and contributions to the collection of available methods are welcome. Please reach us on the [GitHub](https://github.com/deel-ai/xplique) repository with an issue or pull request.
## Common API ##
@@ -126,4 +126,4 @@ Search methods are used to retrieve examples from the `cases_dataset` that are r
Each example-based method has its own search method. The search method is defined in the `search_method_class` property of the `ExampleMethod` class.
-[^1]: [Natural Example-Based Explainability: a Survey (2023)](https://arxiv.org/abs/2309.03234)
\ No newline at end of file
+[^1]: [Natural Example-Based Explainability: a Survey (2023)](https://arxiv.org/abs/2309.03234)
diff --git a/docs/index.md b/docs/index.md
index 3984dad6..e7d6eb49 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -8,7 +8,7 @@
@@ -48,13 +48,13 @@
Example-based
@@ -62,9 +62,6 @@ Finally, the _Metrics_ module covers the current metrics used in explainability.
@@ -116,7 +115,6 @@ Finally, the _Metrics_ module covers the current metrics used in explainability.
- [**Feature Visualization**: Getting started](https://colab.research.google.com/drive/1st43K9AH-UL4eZM1S4QdyrOi7Epa5K8v) [](https://colab.research.google.com/drive/1st43K9AH-UL4eZM1S4QdyrOi7Epa5K8v)
- - [**Feature Visualization**: Getting started](https://colab.research.google.com/drive/1st43K9AH-UL4eZM1S4QdyrOi7Epa5K8v) [](https://colab.research.google.com/drive/1st43K9AH-UL4eZM1S4QdyrOi7Epa5K8v)
@@ -227,6 +225,41 @@ Now that Xplique is installed, here are some basic examples of what you can do w
More information in the [CRAFT documentation](api/concepts/craft.md).
+ ### Holistic CRAFT
+
+ Holistic CRAFT works directly with full activation maps and can be used with classification models through the built-in layered extractor. Object-detection-specific extractor adapters are under construction and will be pip-installable soon.
+
+ ```python
+ from xplique.concepts import HolisticCraftTf
+ from xplique.concepts.tf.layered_model_latent_extractor import LayeredModelExtractorBuilder
+
+ latent_extractor = LayeredModelExtractorBuilder.build(
+ model,
+ split_layer=-3,
+ batch_size=8,
+ )
+ craft = HolisticCraftTf(latent_extractor, number_of_concepts=10)
+ craft.fit(images)
+ ```
+
+ For object detection, use the architecture-specific extractor builders from the companion `xplique-adapters` package when it becomes available:
+
+ ```python
+ # xplique-adapters is under construction and will be pip-installable soon.
+ from xplique.concepts import HolisticCraftTorch
+ from xplique_adapters.concepts.torch.latent_data_retinanet import RetinanetExtractorBuilder
+
+ latent_extractor = RetinanetExtractorBuilder.build(
+ model,
+ device="cuda",
+ nb_classes=91,
+ extraction_location="resnet",
+ extraction_layer=-1,
+ )
+ craft = HolisticCraftTorch(latent_extractor, number_of_concepts=10, device="cuda")
+ craft.fit(images, class_id=class_id)
+ ```
+
??? example "Feature Visualization"
@@ -275,7 +308,7 @@ Now that Xplique is installed, here are some basic examples of what you can do w
## ๐ฆ What's Included
-There are 4 modules in Xplique, [Attribution methods](api/attributions/api_attributions.md), [Attribution metrics](api/attributions/metrics/api_metrics.md), [Concepts](api/concepts/cav.md), and [Feature visualization](api/feature_viz/feature_viz.md). In particular, the attribution methods module supports a huge diversity of tasks: [Classification](api/attributions/classification.md), [Regression](api/attributions/regression.md), [Object Detection](api/attributions/object_detection.md), and [Semantic Segmentation](api/attributions/semantic_segmentation.md). For diverse data types: [Images, Time Series, and Tabular data](api/attributions/api_attributions.md). The methods compatible with such task and methods compatible with Tensorflow or PyTorch are highlighted in the following table:
+There are 5 modules in Xplique: [Attribution methods](api/attributions/api_attributions.md), [Attribution metrics](api/attributions/metrics/api_metrics.md), [Concepts](api/concepts/cav.md), [Feature visualization](api/feature_viz/feature_viz.md), and [Example-based methods](api/example_based/api_example_based.md). In particular, the attribution methods module supports a huge diversity of tasks: [Classification](api/attributions/classification.md), [Regression](api/attributions/regression.md), [Object Detection](api/attributions/object_detection.md), and [Semantic Segmentation](api/attributions/semantic_segmentation.md). For diverse data types: [Images, Time Series, and Tabular data](api/attributions/api_attributions.md). Holistic CRAFT additionally supports concept-based explanations for object detection models. The methods compatible with such task and methods compatible with TensorFlow or PyTorch are highlighted in the following table:
??? abstract "Table of attributions available"
@@ -325,11 +358,10 @@ There are 4 modules in Xplique, [Attribution methods](api/attributions/api_attri
| Average Stability | TF, PyTorch** | Stability | [Paper](https://arxiv.org/abs/2005.00631) |
| MeGe | TF, PyTorch** | Representativity | [Paper](https://arxiv.org/abs/2009.04521) |
| ReCo | TF, PyTorch** | Consistency | [Paper](https://arxiv.org/abs/2009.04521) |
- | Complexity | TF, PyTorch** | Complexity | [Paper](https://arxiv.org/abs/2005.0031) |
+ | Complexity | TF, PyTorch** | Complexity | [Paper](https://arxiv.org/abs/2005.00631) |
| Sparseness | TF, PyTorch** | Complexity | [Paper](https://proceedings.mlr.press/v119/chalasani20a.html) |
| RandomLogitMetric | TF, PyTorch** | Randomization | [Paper](https://arxiv.org/abs/1810.03292) |
| ModelRandomizationMetric| TF, PyTorch** | Randomization | [Paper](https://arxiv.org/abs/1810.03292) |
- | (WIP) e-robustness |
TF : Tensorflow compatible
@@ -343,11 +375,11 @@ There are 4 modules in Xplique, [Attribution methods](api/attributions/api_attri
| Testing CAV (TCAV) | TF | [Paper](https://arxiv.org/pdf/1711.11279.pdf) | |
| CRAFT Tensorflow | TF | [Paper](https://arxiv.org/pdf/2211.10154.pdf) | [](https://colab.research.google.com/drive/1jmyhb89Bdz7H4G2KfK8uEVbSC-C_aht_) |
| CRAFT PyTorch | PyTorch** | [Paper](https://arxiv.org/pdf/2211.10154.pdf) | [](https://colab.research.google.com/drive/16Jn2pQy4gi2qQYZFnuW6ZNtVAYiNyJHO) |
- | (WIP) Robust TCAV | | | |
- | (WIP) Automatic Concept Extraction (ACE) | | |
+ | Holistic CRAFT TensorFlow | TF | [Holistic paper](https://arxiv.org/pdf/2306.07304.pdf) | [Documentation](api/concepts/holistic_craft.md) |
+ | Holistic CRAFT PyTorch | PyTorch** | [Holistic paper](https://arxiv.org/pdf/2306.07304.pdf) | [Documentation](api/concepts/holistic_craft.md) |
TF : Tensorflow compatible
- ** : See the [Xplique for Pytorch documentation](api/attributions/pytorch.md), and the [**PyTorch's model**: Getting started](https://colab.research.google.com/drive/1bMlO29_0K3YnTQBbbyKQyRfo8YjvDbhe) [](https://colab.research.google.com/drive/1bMlO29_0K3YnTQBbbyKQyRfo8YjvDbhe) notebook
+ ** : See the [Xplique for PyTorch documentation](api/attributions/pytorch.md), and the [**PyTorch's model**: Getting started](https://colab.research.google.com/drive/1bMlO29_0K3YnTQBbbyKQyRfo8YjvDbhe) [](https://colab.research.google.com/drive/1bMlO29_0K3YnTQBbbyKQyRfo8YjvDbhe) notebook
??? abstract "Table of Feature Visualization methods available"
@@ -363,7 +395,7 @@ There are 4 modules in Xplique, [Attribution methods](api/attributions/api_attri
TF : Tensorflow compatible
-Even though we are only at the early stages, we have also recently added an [Example-based methods](api/example_based/api_example_based.md) module. Do not hesitate to give us feedback! Currently, the methods available are summarized in the following table:
+The [Example-based methods](api/example_based/api_example_based.md) module provides several families of example-based explanations. Feedback and contributions are welcome. The currently available methods are summarized in the following table:
??? abstract "Table of example-based methods available"
diff --git a/docs/tutorials.md b/docs/tutorials.md
index 698a8c1d..b256ea90 100644
--- a/docs/tutorials.md
+++ b/docs/tutorials.md
@@ -58,7 +58,7 @@ Here is the lists of the availables tutorial for now:
| Fidelity | Average Drop/Increase/Gain | [](https://colab.research.google.com/drive/1nGP13qiQrsJMBx8TXgA69D-5ALoP3l9p) |
| Complexity | Complexity | [](https://colab.research.google.com/drive/13boAsXGVKS0LaNzslOdjSkYIrpBJdh7K) |
| Randomization | Randomization | [](https://colab.research.google.com/drive/13lNkZqKajRJ63XllkQddgrPOYF1Xv9-Y) |
-| Stability | AverageStability | **(WIP)** |
+| Stability | AverageStability | [Documentation](api/attributions/metrics/avg_stability.md) |
## PyTorch Wrapper
@@ -78,6 +78,8 @@ Here is the lists of the availables tutorial for now:
| | | |
| Automatic concept extraction | CRAFT Tensorflow | [](https://colab.research.google.com/drive/1jmyhb89Bdz7H4G2KfK8uEVbSC-C_aht_) |
| Automatic concept extraction | CRAFT Pytorch | [](https://colab.research.google.com/drive/16Jn2pQy4gi2qQYZFnuW6ZNtVAYiNyJHO) |
+| Automatic concept extraction | Holistic CRAFT TensorFlow | [Documentation](api/concepts/holistic_craft.md) |
+| Automatic concept extraction | Holistic CRAFT PyTorch | [Documentation](api/concepts/holistic_craft.md) |
## Feature Visualization