Craft integration

README.md

@@ -90,6 +90,17 @@ Finally, the _Metrics_ module covers the current metrics used in explainability.
     </a>
 </p>
 
+- [**Concepts Methods**: CRAFT: Getting started on Tensorflow](https://colab.research.google.com/drive/1jmyhb89Bdz7H4G2KfK8uEVbSC-C_aht_)
+<sub> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1jmyhb89Bdz7H4G2KfK8uEVbSC-C_aht_) </sub>
+- [**Concepts Methods**: CRAFT: Getting started on Pytorch](https://colab.research.google.com/drive/16Jn2pQy4gi2qQYZFnuW6ZNtVAYiNyJHO)
+<sub> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/16Jn2pQy4gi2qQYZFnuW6ZNtVAYiNyJHO) </sub>
+
+<p align="center" width="100%">
+    <a href="https://colab.research.google.com/drive/1jmyhb89Bdz7H4G2KfK8uEVbSC-C_aht_">
+        <img width="95%" src="./docs/assets/craft.jpeg">
+    </a>
+</p>
+
 - [**Feature Visualization**: Getting started](https://colab.research.google.com/drive/1st43K9AH-UL4eZM1S4QdyrOi7Epa5K8v) <sub> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1st43K9AH-UL4eZM1S4QdyrOi7Epa5K8v) </sub>
 - [**Modern Feature Visualization with MaCo**: Getting started](https://colab.research.google.com/drive/1l0kag1o-qMY4NCbWuAwnuzkzd9sf92ic) <sub> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1l0kag1o-qMY4NCbWuAwnuzkzd9sf92ic) </sub>
 
@@ -159,6 +170,8 @@ All attributions metrics share a common API. You can find out more about it [her
 <details>
 <summary><b>Concepts Extraction</b></summary>
 
+### CAV
+
 Concerning the concept-based methods, we can for example extract a concept vector from a layer of a model. In order to do this, we use two datasets, one containing inputs containing the concept: `positive_samples`, the other containing other entries which do not contain the concept: `negative_samples`.
 
 ```python
@@ -174,6 +187,32 @@ concept_vector = extractor(positive_samples,
 ```
 
 More information on CAV [here](https://deel-ai.github.io/xplique/latest/api/concepts/cav/) and on TCAV [here](https://deel-ai.github.io/xplique/latest/api/concepts/tcav/).
+
+### CRAFT
+
+Use Craft to investigate a single class.
+
+```python
+from xplique.concepts import CraftTf as Craft
+
+# Cut the model in two parts: g and h
+# Create a Craft concept extractor from these 2 models
+craft = Craft(input_to_latent_model = g,
+              latent_to_logit_model = h)
+
+# Use Craft to compute the concepts for a specific class
+craft.fit(images_preprocessed, class_id=rabbit_class_id)
+
+# Compute Sobol indices to understand which concept matters
+importances = craft.estimate_importance()
+
+# Display those concepts by showing the 10 best crops for each concept
+craft.plot_concepts_crops(nb_crops=10)
+
+```
+
+More information in the [CRAFT documentation](https://deel-ai.github.io/xplique/latest/api/concepts/craft/).
+
 </details>
 
 <details>
@@ -289,15 +328,19 @@ TF : Tensorflow compatible
 <details>
 <summary><b>Table of concept methods available</b></summary>
 
-| **Concepts method**             | Type of Model | Source                                        |
-| :------------------------------ | :------------ | :-------------------------------------------- |
-| Concept Activation Vector (CAV) | TF            | [Paper](https://arxiv.org/pdf/1711.11279.pdf) |
-| Testing CAV (TCAV)              | TF            | [Paper](https://arxiv.org/pdf/1711.11279.pdf) |
-| (WIP) Robust TCAV               |               |
-| (WIP) Automatic Concept Extraction (ACE)        |
+| **Concepts method**             | Type of Model | Source                                        | Tutorial       |
+| :------------------------------ | :------------ | :-------------------------------------------- | :------------  |
+| Concept Activation Vector (CAV) | TF            | [Paper](https://arxiv.org/pdf/1711.11279.pdf) | |
+| Testing CAV (TCAV)              | TF            | [Paper](https://arxiv.org/pdf/1711.11279.pdf) | |
+| CRAFT Tensorflow | TF | [Paper](https://arxiv.org/pdf/2211.10154.pdf) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1jmyhb89Bdz7H4G2KfK8uEVbSC-C_aht_) |
+| CRAFT PyTorch  | PyTorch** | [Paper](https://arxiv.org/pdf/2211.10154.pdf) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/16Jn2pQy4gi2qQYZFnuW6ZNtVAYiNyJHO) |
+| (WIP) Robust TCAV               |               | | |
+| (WIP) Automatic Concept Extraction (ACE)        | | |
 
 TF : Tensorflow compatible
 
+** : See the [Xplique for Pytorch documentation](https://deel-ai.github.io/xplique/latest/pytorch/), and the [**PyTorch's model**: Getting started](https://colab.research.google.com/drive/1bMlO29_0K3YnTQBbbyKQyRfo8YjvDbhe)<sub> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1bMlO29_0K3YnTQBbbyKQyRfo8YjvDbhe) </sub> notebook
+
 </details>
 
 <details>

docs/api/concepts/craft.md

@@ -0,0 +1,111 @@
+# CRAFT
+
+<sub>
+    <img src="https://upload.wikimedia.org/wikipedia/commons/d/d0/Google_Colaboratory_SVG_Logo.svg" width="20">
+</sub>
+[View colab Tensorflow tutorial](https://colab.research.google.com/drive/1jmyhb89Bdz7H4G2KfK8uEVbSC-C_aht_) |
+<sub>
+    <img src="https://upload.wikimedia.org/wikipedia/commons/d/d0/Google_Colaboratory_SVG_Logo.svg" width="20">
+</sub>
+[View colab Pytorch tutorial](https://colab.research.google.com/drive/16Jn2pQy4gi2qQYZFnuW6ZNtVAYiNyJHO) |
+<sub>
+    <img src="https://upload.wikimedia.org/wikipedia/commons/9/91/Octicons-mark-github.svg" width="20">
+</sub>[View source](https://github.com/deel-ai/xplique/blob/master/xplique/concepts/craft.py) |
+📰 [Paper](https://arxiv.org/pdf/2211.10154)
+
+CRAFT or Concept Recursive Activation FacTorization for Explainability is a method for automatically extracting human-interpretable concepts from deep networks.
+
+This concept activations factorization method aims to explain a trained model's decisions on a per-class and per-image basis by highlighting both "what" the model saw and “where” it saw it. Thus CRAFT generates post-hoc local and global explanations.
+
+It is made up from 3 ingredients:
+
+1. a method to recursively decompose concepts into sub-concepts
+2. a method to better estimate the importance of extracted concepts
+3. a method to use any attribution method to create concept attribution maps, using implicit differentiation
+
+CRAFT requires splitting the model in two parts: $(g, h)$ such that $f(x) = (g \cdot h)(x)$. To put it simply, $g$ is the function that maps our input to the latent space (an inner layer of our model), and $h$ is the function that maps the latent space to the output.
+The concepts will be extracted from this latent space.
+
+!!!info
+    It is important to note that if the model contains a global average pooling layer, it is strongly recommended to provide CRAFT with the layer before the global average pooling.
+
+!!!warning
+    Please keep in mind that the activations must be positives (after relu or any positive activation function)
+
+
+## Example
+
+Use Craft to investigate a single class.
+
+```python
+from xplique.concepts import CraftTf as Craft
+
+# Cut the model in two parts (as explained in the paper)
+# first part is g(.) our 'input_to_latent' model returning positive activations,
+# second part is h(.) our 'latent_to_logit' model
+
+g = tf.keras.Model(model.input, model.layers[-3].output)
+h = tf.keras.Model(model.layers[-2].input, model.layers[-1].output)
+
+# Create a Craft concept extractor from these 2 models
+craft = Craft(input_to_latent_model = g,
+              latent_to_logit_model = h,
+              number_of_concepts = 10,
+              patch_size = 80,
+              batch_size = 64)
+
+# Use Craft to get the crops (crops), the embedding of the crops (crops_u),
+# and the concept bank (w)
+crops, crops_u, w = craft.fit(images_preprocessed, class_id=rabbit_class_id)
+
+# Compute Sobol indices to understand which concept matters
+importances = craft.estimate_importance()
+
+# Display those concepts by showing the 10 best crops for each concept
+craft.plot_concepts_crops(nb_crops=10)
+
+```
+
+Use CraftManager to investigate multiple classes.
+
+```python
+from xplique.concepts import CraftManagerTf as CraftManager
+
+
+# Cut the model in two parts (as explained in the paper)
+# first part is g(.) our 'input_to_latent' model returning positive activations,
+# second part is h(.) our 'latent_to_logit' model
+
+g = tf.keras.Model(model.input, model.layers[-3].output)
+h = tf.keras.Model(model.layers[-2].input, model.layers[-1].output)
+
+# CraftManager will create one instance of Craft per class of interest
+# to investigate
+list_of_class_of_interest = [0, 491, 497, 569, 574] # list of class_ids
+cm = CraftManager(input_to_latent_model = g,
+                 latent_to_logit_model = h,
+                 inputs = inputs_preprocessed,
+                 labels = y,
+                 list_of_class_of_interest = list_of_class_of_interest,
+                 number_of_concepts = 10,
+                 patch_size = 80,
+                 batch_size = 64)
+
+cm.fit(nb_samples_per_class=50)
+
+# Compute Sobol indices to understand which concept matters
+cm.estimate_importance()
+
+# Display those concepts by showing the 10 best crops for each concept,
+# for the 1st class
+cm.plot_concepts_crops(class_id=0, nb_crops=10)
+
+```
+
+
+{{xplique.concepts.craft_tf.CraftTf}}
+
+{{xplique.concepts.craft_tf.CraftManagerTf}}
+
+
+[^1]: [CRAFT: Concept Recursive Activation FacTorization for Explainability (2023).](https://arxiv.org/pdf/2211.10154.pdf)

docs/index.md

@@ -89,6 +89,17 @@ Finally, the _Metrics_ module covers the current metrics used in explainability.
         </a>
     </p>
 
+    - [**Concepts Methods**: CRAFT: Getting started on Tensorflow](https://colab.research.google.com/drive/1jmyhb89Bdz7H4G2KfK8uEVbSC-C_aht_)
+    <sub> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1jmyhb89Bdz7H4G2KfK8uEVbSC-C_aht_) </sub>
+    - [**Concepts Methods**: CRAFT: Getting started on Pytorch](https://colab.research.google.com/drive/16Jn2pQy4gi2qQYZFnuW6ZNtVAYiNyJHO)
+    <sub> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/16Jn2pQy4gi2qQYZFnuW6ZNtVAYiNyJHO) </sub>
+
+    <p align="center" width="100%">
+        <a href="https://colab.research.google.com/drive/1jmyhb89Bdz7H4G2KfK8uEVbSC-C_aht_">
+            <img width="95%" src="./assets/craft.jpeg">
+        </a>
+    </p>
+
     - [**Feature Visualization**: Getting started](https://colab.research.google.com/drive/1st43K9AH-UL4eZM1S4QdyrOi7Epa5K8v) <sub> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1st43K9AH-UL4eZM1S4QdyrOi7Epa5K8v) </sub>
 
     - [**Feature Visualization**: Getting started](https://colab.research.google.com/drive/1st43K9AH-UL4eZM1S4QdyrOi7Epa5K8v) <sub> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1st43K9AH-UL4eZM1S4QdyrOi7Epa5K8v) </sub>
@@ -151,6 +162,8 @@ Now that Xplique is installed, here are some basic examples of what you can do w
 
 ??? example "Concepts Extraction"
 
+    ### CAV
+
     Concerning the concept-based methods, we can for example extract a concept vector from a layer of a model. In order to do this, we use two datasets, one containing inputs containing the concept: `positive_samples`, the other containing other entries which do not contain the concept: `negative_samples`.
 
     ```python
@@ -167,6 +180,32 @@ Now that Xplique is installed, here are some basic examples of what you can do w
 
     More information on CAV [here](api/concepts/cav/) and on TCAV [here](api/concepts/tcav/).
 
+    ### CRAFT
+
+    Use Craft to investigate a single class.
+
+    ```python
+    from xplique.concepts import CraftTf as Craft
+
+    # Cut the model in two parts: g and h
+    # Create a Craft concept extractor from these 2 models
+    craft = Craft(input_to_latent_model = g,
+                latent_to_logit_model = h)
+
+    # Use Craft to compute the concepts for a specific class
+    craft.fit(images_preprocessed, class_id=rabbit_class_id)
+
+    # Compute Sobol indices to understand which concept matters
+    importances = craft.estimate_importance()
+
+    # Display those concepts by showing the 10 best crops for each concept
+    craft.plot_concepts_crops(nb_crops=10)
+
+    ```
+
+    More information in the [CRAFT documentation](api/concepts/craft/).
+
+
 ??? example "Feature Visualization"
 
     Finally, in order to find an image that maximizes a neuron and at the same time a layer, we build two objectives that we combine together. We then call the optimizer which returns our images
@@ -268,15 +307,18 @@ There are 4 modules in Xplique, [Attribution methods](api/attributions/api_attri
 
 ??? abstract "Table of concept methods available"
 
-    | **Concepts method**             | Type of Model | Source                                        |
-    | :------------------------------ | :------------ | :-------------------------------------------- |
-    | Concept Activation Vector (CAV) | TF            | [Paper](https://arxiv.org/pdf/1711.11279.pdf) |
-    | Testing CAV (TCAV)              | TF            | [Paper](https://arxiv.org/pdf/1711.11279.pdf) |
-    | (WIP) Robust TCAV               |               |
-    | (WIP) Automatic Concept Extraction (ACE)        |
-
+    | **Concepts method**             | Type of Model | Source                                        | Tutorial       |
+    | :------------------------------ | :------------ | :-------------------------------------------- | :------------  |
+    | Concept Activation Vector (CAV) | TF            | [Paper](https://arxiv.org/pdf/1711.11279.pdf) | |
+    | Testing CAV (TCAV)              | TF            | [Paper](https://arxiv.org/pdf/1711.11279.pdf) | |
+    | CRAFT Tensorflow | TF | [Paper](https://arxiv.org/pdf/2211.10154.pdf) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1jmyhb89Bdz7H4G2KfK8uEVbSC-C_aht_) |
+    | CRAFT PyTorch  | PyTorch** | [Paper](https://arxiv.org/pdf/2211.10154.pdf) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/16Jn2pQy4gi2qQYZFnuW6ZNtVAYiNyJHO) |
+    | (WIP) Robust TCAV               |               | | |
+    | (WIP) Automatic Concept Extraction (ACE)        | | |
     TF : Tensorflow compatible
 
+    ** : See the [Xplique for Pytorch documentation](pytorch/), and the [**PyTorch's model**: Getting started](https://colab.research.google.com/drive/1bMlO29_0K3YnTQBbbyKQyRfo8YjvDbhe)<sub> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1bMlO29_0K3YnTQBbbyKQyRfo8YjvDbhe) </sub> notebook
+
 ??? abstract "Table of Feature Visualization methods available"
 
     | **Feature Visualization** [(Paper)](https://distill.pub/2017/feature-visualization/) | Type of Model | Details                                                                                                            |

docs/tutorials.md

@@ -64,7 +64,12 @@ Here is the lists of the availables tutorial for now:
 
 ## Concepts extraction
 
-**WIP**
+| Category      | **Tutorial Name**      | Notebook                                                                                                                                                           |
+|:------------- | :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+| Labelled concept methods | CAV + TCAV           | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1iuEz46ZjgG97vTBH8p-vod3y14UETvVE) |
+|  |  |  |
+| Automatic concept extraction      | CRAFT Tensorflow          | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1jmyhb89Bdz7H4G2KfK8uEVbSC-C_aht_) |
+| Automatic concept extraction      | CRAFT Pytorch             | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/16Jn2pQy4gi2qQYZFnuW6ZNtVAYiNyJHO) |
 
 ## Feature Visualization
 

mkdocs.yml

@@ -41,6 +41,7 @@ nav:
   - Concept based:
       - Cav: api/concepts/cav.md
       - Tcav: api/concepts/tcav.md
+      - Craft: api/concepts/craft.md
   - Feature visualization:
       - Modern Feature Visualization (MaCo): api/feature_viz/maco.md
       - Feature visualization: api/feature_viz/feature_viz.md

setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.2.1
+current_version = 1.3.0
 commit = True
 tag = False
 
@@ -46,7 +46,7 @@ deps =
 	tf211: tensorflow ~= 2.11.0
 	-rrequirements.txt
 commands = 
-	pytest --cov=xplique --ignore=xplique/wrappers/pytorch.py --ignore=tests/wrappers/test_pytorch_wrapper.py {posargs}
+	pytest --cov=xplique --ignore=xplique/wrappers/pytorch.py --ignore=tests/wrappers/test_pytorch_wrapper.py --ignore=tests/concepts/test_craft_torch.py {posargs}
 
 [testenv:py{38,39,310}-tf{25,28,211}-torch{111,113,200}]
 deps = 
@@ -60,7 +60,7 @@ deps =
 	torch200: torch
 	-rrequirements.txt
 commands = 
-	pytest --cov=xplique/wrappers/pytorch tests/wrappers/test_pytorch_wrapper.py
+	pytest --cov=xplique/wrappers/pytorch tests/wrappers/test_pytorch_wrapper.py tests/concepts/test_craft_torch.py
 
 [mypy]
 check_untyped_defs = True

setup.py

@@ -5,7 +5,7 @@
 
 setup(
     name="Xplique",
-    version="1.2.1",
+    version="1.3.0",
     description="Explanations toolbox for Tensorflow 2",
     long_description=README,
     long_description_content_type="text/markdown",