Anchor documentation improvements #711

RobertSamoilescu · 2022-06-30T13:50:07Z

This PR addresses the following updates:

addresses the issue Update AnchorTabular precision warning #699, by providing additional justification on why the anchor precision constraint cannot be satisfied.
includes the method description and additional section Use-case insights as suggested by the product team.
a more suggestive description of the parameters passed to the explain method including a formal description for clarity.

review-notebook-app · 2022-06-30T13:50:12Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

codecov · 2022-06-30T15:00:07Z

Codecov Report

Merging #711 (715d247) into master (efac30c) will increase coverage by 0.51%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master     #711      +/-   ##
==========================================
+ Coverage   80.55%   81.06%   +0.51%     
==========================================
  Files         105      105              
  Lines       11790    11794       +4     
==========================================
+ Hits         9497     9561      +64     
+ Misses       2293     2233      -60

Impacted Files	Coverage Δ
alibi/explainers/anchors/anchor_image.py	`93.12% <ø> (ø)`
alibi/explainers/anchors/anchor_tabular.py	`90.17% <ø> (ø)`
alibi/explainers/anchors/anchor_text.py	`94.44% <ø> (ø)`
alibi/explainers/anchors/anchor_base.py	`92.70% <100.00%> (ø)`
alibi/utils/missing_optional_dependency.py	`94.28% <0.00%> (+0.16%)`	⬆️
alibi/explainers/shap_wrappers.py	`91.89% <0.00%> (+2.65%)`	⬆️
alibi/explainers/tests/test_shap_wrappers.py	`95.72% <0.00%> (+5.28%)`	⬆️

mauicv · 2022-07-04T08:52:21Z

alibi/explainers/anchors/anchor_image.py

-            Probability for a pixel to be represented by the average value of its superpixel.
+            Probability for a pixel to be represented by the average value of its superpixel. The missingness of a
+            superpixel (i.e. querying the model on a reduced input) is simulated by randomly turning it on and off
+            with a probability `p_sample`.


I think if images_background we replace with the other image, not the average.

mauicv · 2022-07-04T12:36:41Z

alibi/explainers/anchors/anchor_base.py

+                           f'Now returning the best non-eligible result. The desired precision threshold might not be '
+                           f'achieved due to the quantile-based discretisation of the numerical features since the '
+                           f'synthetic instances satisfying the anchor are constructed by sampling the numerical '
+                           f'features from their corresponding, potentially large, quantile intervals.')


I'm sort of tempted to suggest just saying something like: "The resolution of bins may be too large to ensure we find an anchor of required precision. Note that higher resolution may not be possible due to sparsity of samples.". But I'm not sure... I think the above is fine as well.

mauicv · 2022-07-04T12:56:39Z

alibi/explainers/anchors/anchor_image.py

-            Margin between lower confidence bound and minimum precision of upper bound.
+            Multi-armed bandit parameter used to select candidate anchors in each iteration. The multi-armed bandit
+            algorithm tries to find the potentially best (i.e. highest precision) `beam_size` candidate anchors from a
+            list of anchors created by including a new predicate in the candidate anchors form the previous iteration.


form -> from

mauicv · 2022-07-04T13:16:07Z

alibi/explainers/anchors/anchor_image.py

+            the algorithm returns with a probability of at least `1 - delta` an anchor :math:`A` with a precision lower
+            than the precision of the highest precision anchor in the current iteration, :math:`A^\\star`,
+            with a maximum error tolerance of `tau`. A bigger value for `tau` means faster convergence but also looser
+            anchor conditions.


Perhaps mention that the aim of the algorithm is to return an anchor you're confident is good rather than the best anchor you're less confident in. Hence it doesn't necessarily return the best anchor instead it's managing a trade-off between confidence and precision.

Ignore, I misuderstood

mauicv · 2022-07-04T13:19:52Z

alibi/explainers/anchors/anchor_image.py

        coverage_samples
            Number of samples used to estimate coverage from during result search.
        beam_size
-            The number of anchors extended at each step of new anchors construction.
+            The number of anchors extended (i.e. candidate anchors returned by the multi-armed bandit)


Note sure what you mean by extended? Perhaps: "Number of anchors selected by the MAB algorithm in each generation of building the anchors..."

mauicv · 2022-07-04T13:37:52Z

alibi/explainers/anchors/anchor_image.py

-            The number of anchors extended at each step of new anchors construction.
+            The number of anchors extended (i.e. candidate anchors returned by the multi-armed bandit)
+            at each step of new anchors construction. A bigger beam width can lead to a better overall anchor at the
+            expense of more computation time.


Perhaps mention that the beam size aims to prevent the anchor being in a local maximum...

mauicv · 2022-07-04T13:42:16Z

doc/source/methods/Anchors.ipynb

+    "There are some edge cases that a practitioner should be aware:\n",
+    "\n",
+    "- An anchor with many predicates and a small coverage might indicate that the explained input lies near the decision boundary. Many more predicates are needed to ensure that an instance keeps the predicted label since minor perturbations may push the prediction to another class.\n",
+    "- An empty anchor with a coverage of 1 indicates that there is no salient subset of features that is necessary for the prediction to hold. In other words, with high probability (as measured by the precision), the predicted class of the data point does not change regardless of the perturbations applied to it."


Perhaps add that this is likely to occur if the data set is very unbalanced

Also maybe link to the FAQs on this

jklaise · 2022-07-20T13:09:38Z

alibi/explainers/anchors/anchor_base.py

+                           f'Now returning the best non-eligible result. The desired precision threshold might not be '
+                           f'achieved due to the quantile-based discretisation of the numerical features. The '
+                           f'resolution of the bins may be too large to find an anchor of required precision. '
+                           f'Note that higher resolution may or may not be easily achieved depending on the underling '


underling -> underlying

With respect to the message itself, should we replace the last sentence with something actionable? E.g. mention increasing the number of bins in disc_perc (whilst keeping the caveat that it may not help if the numerical feature distributions are skewed).

jklaise · 2022-07-20T13:11:59Z

alibi/explainers/anchors/anchor_image.py

        delta
-            Used to compute `beta`.
+            Significant threshold. `1 - delta` represents the confidence threshold for the anchor precision


Significant -> Significance?

jklaise · 2022-07-20T13:19:42Z

doc/source/methods/Anchors.ipynb

@@ -49,6 +49,40 @@
    "As highlighted by the above example, an anchor explanation consists of *if-then rules*, called the anchors, which sufficiently guarantee the explanation locally and try to maximize the area for which the explanation holds. This means that as long as the anchor holds, the prediction should remain the same regardless of the values of the features not present in the anchor. Going back to the sentiment example: as long as *not good* is present, the sentiment is negative, regardless of the other words in the movie review."


Should we have a "loose" definition of a "predicate" as well before using it in the definitions of precision/coverage?
With respect to the FAQ link, I think we discussed that the 2nd reason for the empty anchor is actually not possible ("The predicted class of the data point always changes regardless of the perturbations applied to it."). Would you be able to edit the FAQ entry to reflect that?

Reply via ReviewNB

jklaise · 2022-07-20T13:19:42Z

doc/source/methods/Anchors.ipynb

@@ -49,6 +49,40 @@
    "As highlighted by the above example, an anchor explanation consists of *if-then rules*, called the anchors, which sufficiently guarantee the explanation locally and try to maximize the area for which the explanation holds. This means that as long as the anchor holds, the prediction should remain the same regardless of the values of the features not present in the anchor. Going back to the sentiment example: as long as *not good* is present, the sentiment is negative, regardless of the other words in the movie review."


Significant -> Significance?

Reply via ReviewNB

jklaise

Thanks Robert, left a few comments.

…e concepts. Changed link to FAQ.

jklaise · 2022-07-26T16:14:59Z

doc/source/methods/Anchors.ipynb

+    "For a more intuitive understanding of what the method tries to achieve, we will loosely define a few concepts and explain some insights we get from an anchor explanation.\n",
+    "\n",
+    "A **predicate** represents an expression involving a single feature. Some examples of predicates for a tabular dataset having features such as *Age*, *Relationship*, and *Occupation* are: \n",
+    "\n",
+    " - `28 < Age < 50`\n",
+    " - `Relationship = Husband`\n",
+    " - `Occupation = Blue-Collar`\n",
+    "\n",
+    "A **rule** represents a set of predicates connected by the `AND` operator. Considering all the predicate examples above, we can construct the following rule: `28 < Age < 50 AND Relationship = Husband AND Occupation = Blue-Collar`. Note that a rule selects/refers to a particular subpopulation from the given dataset.\n",
+    "\n",
+    "We can now define the notion of an **anchor**. Following the definition from [Ribeiro et al. (2018)](https://homes.cs.washington.edu/~marcotcr/aaai18.pdf), \"an **anchor** explanation is a **rule** that sufficiently 'anchors' the prediction locally – such that changes to the rest of the feature values of the instance do not matter\".\n",
+    "\n",
+    "As previously mentioned, the power of the Anchors over other local explanations methods comes from the objective formulation which is to maximize the **coverage** under the **precision** constraints. \n",


Nice explanation!

jklaise · 2022-07-26T16:15:14Z

doc/source/methods/Anchors.ipynb

    "\n",
    "- An anchor with many predicates and a small coverage might indicate that the explained input lies near the decision boundary. Many more predicates are needed to ensure that an instance keeps the predicted label since minor perturbations may push the prediction to another class.\n",
    "- An empty anchor with a coverage of 1 indicates that there is no salient subset of features that is necessary for the prediction to hold. In other words, with high probability (as measured by the precision), the predicted class of the data point does not change regardless of the perturbations applied to it. This behaviour can be typical for very imbalanced datasets.\n",
    "\n",
-    "Check [FAQ](https://docs.seldon.io/projects/alibi/en/stable/overview/faq.html#anchor-explanations) for further details."
+    "Check [FAQ](https://docs.seldon.io/projects/alibi/en/latest/overview/faq.html#anchor-explanations) for further details."


Not sure how this sneaked in but should be stable.

jklaise

Looks good, I think I got confused myself that the FAQ had already deleted the wrong justification for an empty anchor but the rendered docs show stable so the change won't be visible until next release. Just to clarify, all docs links should point to stable as that's the version the vast majority of people will be using.

RobertSamoilescu added 3 commits June 30, 2022 10:34

Updated Anchor warning when precision constraint is not satisfied.

3a6d9c4

Added general Use-case insight in the method description

e7c00a6

Updated explain method docs for tabular, text, image

8c42cc7

RobertSamoilescu requested a review from mauicv June 30, 2022 13:50

RobertSamoilescu requested a review from jklaise June 30, 2022 13:50

RobertSamoilescu marked this pull request as draft June 30, 2022 13:50

Updated method params docs and sync with docs

4e73c6f

RobertSamoilescu marked this pull request as ready for review June 30, 2022 14:22

Rephrasing of docs for threshold and tau

bb98ef0

mauicv reviewed Jul 4, 2022

View reviewed changes

Improved p_sample description and some minor corrections.

23a2e66

mauicv reviewed Jul 4, 2022

View reviewed changes

RobertSamoilescu added 2 commits July 4, 2022 16:32

Parameters description update.

8b9bb7d

Updated tau param description

1274485

jklaise reviewed Jul 20, 2022

View reviewed changes

jklaise suggested changes Jul 20, 2022

View reviewed changes

RobertSamoilescu added 2 commits July 21, 2022 15:48

Fixed minor grammatical errors. Included additional definition of bas…

734ede8

…e concepts. Changed link to FAQ.

Merge remote-tracking branch 'origin/anchor-docs' into anchor-docs

006c34e

jklaise reviewed Jul 26, 2022

View reviewed changes

jklaise suggested changes Jul 26, 2022

View reviewed changes

Addressed faq link

715d247

jklaise approved these changes Jul 27, 2022

View reviewed changes

jklaise changed the title ~~Anchor docs~~ Anchor documentation improvements Jul 27, 2022

jklaise merged commit 69713b5 into SeldonIO:master Jul 27, 2022

jklaise mentioned this pull request Jul 27, 2022

Update AnchorTabular precision warning #699

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Anchor documentation improvements #711

Anchor documentation improvements #711

RobertSamoilescu commented Jun 30, 2022

review-notebook-app bot commented Jun 30, 2022

codecov bot commented Jun 30, 2022 •

edited

Loading

mauicv Jul 4, 2022

mauicv Jul 4, 2022

mauicv Jul 4, 2022

mauicv Jul 4, 2022 •

edited

Loading

mauicv Jul 4, 2022 •

edited

Loading

mauicv Jul 4, 2022

mauicv Jul 4, 2022 •

edited

Loading

jklaise Jul 20, 2022

jklaise Jul 20, 2022

jklaise Jul 20, 2022

jklaise Jul 20, 2022

jklaise left a comment

jklaise Jul 26, 2022

jklaise Jul 26, 2022

jklaise left a comment

		@@ -49,6 +49,40 @@
		"As highlighted by the above example, an anchor explanation consists of if-then rules, called the anchors, which sufficiently guarantee the explanation locally and try to maximize the area for which the explanation holds. This means that as long as the anchor holds, the prediction should remain the same regardless of the values of the features not present in the anchor. Going back to the sentiment example: as long as not good is present, the sentiment is negative, regardless of the other words in the movie review."

Anchor documentation improvements #711

Anchor documentation improvements #711

Conversation

RobertSamoilescu commented Jun 30, 2022

review-notebook-app bot commented Jun 30, 2022

codecov bot commented Jun 30, 2022 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mauicv Jul 4, 2022 • edited Loading

Choose a reason for hiding this comment

mauicv Jul 4, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mauicv Jul 4, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jklaise left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jklaise left a comment

Choose a reason for hiding this comment

codecov bot commented Jun 30, 2022 •

edited

Loading

mauicv Jul 4, 2022 •

edited

Loading

mauicv Jul 4, 2022 •

edited

Loading

mauicv Jul 4, 2022 •

edited

Loading