Skip to content

Commit efac30c

Browse files
mauicvmauicv
authored
Fix broken source links in docs, fix #675 (#698)
* Fix broken source links in docs, fix #675 * Fix links to papers to point to arxiv pages rather than pdf * Fix divide symbol in `similarity.metrics` docstrings * Fix ray link in example notebook
1 parent 28e4f46 commit efac30c

26 files changed

+91
-63
lines changed

‎alibi/explainers/anchors/anchor_base.py

+5-5
Original file line numberDiff line numberDiff line change
@@ -37,9 +37,9 @@ def _init_state(self, batch_size: int, coverage_data: np.ndarray) -> None:
3737
Parameters
3838
----------
3939
batch_size
40-
See :py:meth:`alibi.explainers.anchor_base.AnchorBaseBeam.anchor_beam` method.
40+
See :py:meth:`alibi.explainers.anchors.anchor_base.AnchorBaseBeam.anchor_beam` method.
4141
coverage_data
42-
See :py:meth:`alibi.explainers.anchor_base.AnchorBaseBeam._get_coverage_samples` method.
42+
See :py:meth:`alibi.explainers.anchors.anchor_base.AnchorBaseBeam._get_coverage_samples` method.
4343
"""
4444

4545
prealloc_size = batch_size * self.sample_cache_size
@@ -179,9 +179,9 @@ def _get_coverage_samples(self, coverage_samples: int, samplers: Optional[List[C
179179
Parameters
180180
---------
181181
coverage_samples
182-
See :py:meth:`alibi.explainers.anchor_base.AnchorBaseBeam.anchor_beam` method.
182+
See :py:meth:`alibi.explainers.anchors.anchor_base.AnchorBaseBeam.anchor_beam` method.
183183
samplers
184-
See :py:meth:`alibi.explainers.anchor_base.AnchorBaseBeam.__init__` method.
184+
See :py:meth:`alibi.explainers.anchors.anchor_base.AnchorBaseBeam.__init__` method.
185185
186186
Returns
187187
-------
@@ -419,7 +419,7 @@ def propose_anchors(self, previous_best: list) -> list:
419419
def update_state(self, covered_true: np.ndarray, covered_false: np.ndarray, labels: np.ndarray,
420420
samples: Tuple[np.ndarray, float], anchor: tuple) -> Tuple[int, int]:
421421
"""
422-
Updates the explainer state (see :py:meth:`alibi.explainers.anchor_base.AnchorBaseBeam.__init__`
422+
Updates the explainer state (see :py:meth:`alibi.explainers.anchors.anchor_base.AnchorBaseBeam.__init__`
423423
for full state definition).
424424
425425
Parameters

‎alibi/explainers/anchors/anchor_tabular.py

+4-3
Original file line numberDiff line numberDiff line change
@@ -249,7 +249,8 @@ def compare_labels(self, samples: np.ndarray) -> np.ndarray:
249249

250250
def perturbation(self, anchor: tuple, num_samples: int) -> Tuple[np.ndarray, np.ndarray, float]:
251251
"""
252-
Implements functionality described in :py:meth:`alibi.explainers.anchor_tabular.TabularSampler.__call__`.
252+
Implements functionality described in
253+
:py:meth:`alibi.explainers.anchors.anchor_tabular.TabularSampler.__call__`.
253254
254255
Parameters
255256
----------
@@ -329,7 +330,7 @@ def handle_unk_features(self, allowed_bins: Dict[int, Set[int]], num_samples: in
329330
Parameters
330331
----------
331332
allowed_bins
332-
See :py:meth:`alibi.explainers.anchor_tabular.TabularSampler.get_feature_index` method.
333+
See :py:meth:`alibi.explainers.anchors.anchor_tabular.TabularSampler.get_features_index` method.
333334
num_samples
334335
Number of replacement values.
335336
samples
@@ -819,7 +820,7 @@ def _build_explanation(self, X: np.ndarray, result: dict, predicted_label: int,
819820
predicted_label
820821
Label of the instance to be explained (inferred if not given).
821822
params
822-
Parameters passed to :py:meth:`alibi.explainers.anchor_tabular.AnchorTabular.explain`.
823+
Parameters passed to :py:meth:`alibi.explainers.anchors.anchor_tabular.AnchorTabular.explain`.
823824
824825
Return
825826
------

‎alibi/explainers/anchors/anchor_tabular_distributed.py

+15-15
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,11 @@ def _get_coverage_samples(self, coverage_samples: int, # type: ignore[override]
3333
Parameters
3434
----------
3535
coverage_samples, samplers
36-
See :py:meth:`alibi.explainers.anchor_base.AnchorBaseBeam._get_coverage_samples` implementation.
36+
See :py:meth:`alibi.explainers.anchors.anchor_base.AnchorBaseBeam._get_coverage_samples` implementation.
3737
3838
Returns
3939
-------
40-
See :py:meth:`alibi.explainers.anchor_base.AnchorBaseBeam._get_coverage_samples` implementation.
40+
See :py:meth:`alibi.explainers.anchors.anchor_base.AnchorBaseBeam._get_coverage_samples` implementation.
4141
"""
4242
[coverage_data] = ray.get(
4343
self.sample_fcn(samplers[0], (0, ()), coverage_samples, compute_labels=False)
@@ -52,11 +52,11 @@ def draw_samples(self, anchors: list, batch_size: int) -> Tuple[np.ndarray, np.n
5252
Parameters
5353
----------
5454
anchors, batch_size
55-
See :py:meth:`alibi.explainers.anchor_base.AnchorBaseBeam.draw_samples` implementation.
55+
See :py:meth:`alibi.explainers.anchors.anchor_base.AnchorBaseBeam.draw_samples` implementation.
5656
5757
Returns
5858
-------
59-
See :py:meth:`alibi.explainers.anchor_base.AnchorBaseBeam.draw_samples` implementation.
59+
See :py:meth:`alibi.explainers.anchors.anchor_base.AnchorBaseBeam.draw_samples` implementation.
6060
"""
6161

6262
# partial anchors not generated by propose_anchors are not in the order dictionary
@@ -97,13 +97,13 @@ def __init__(self, *args):
9797
def __call__(self, anchors_batch: Union[Tuple[int, tuple], List[Tuple[int, tuple]]], num_samples: int,
9898
compute_labels: bool = True) -> List:
9999
"""
100-
Wrapper around :py:meth:`alibi.explainers.anchor_tabular.TabularSampler.__call__`. It allows sampling a batch
101-
of anchors in the same process, which can improve performance.
100+
Wrapper around :py:meth:`alibi.explainers.anchors.anchor_tabular.TabularSampler.__call__`. It allows sampling a
101+
batch of anchors in the same process, which can improve performance.
102102
103103
Parameters
104104
----------
105105
anchors_batch, num_samples, compute_labels
106-
A list of result tuples. See :py:meth:`alibi.explainers.anchor_tabular.TabularSampler.__call__`
106+
A list of result tuples. See :py:meth:`alibi.explainers.anchors.anchor_tabular.TabularSampler.__call__`
107107
for details.
108108
"""
109109

@@ -162,16 +162,16 @@ def _get_sampler(self) -> TabularSampler:
162162

163163
def build_lookups(self, X: np.ndarray):
164164
"""
165-
Wrapper around :py:meth:`alibi.explainers.anchor_tabular.TabularSampler.build_lookups`.
165+
Wrapper around :py:meth:`alibi.explainers.anchors.anchor_tabular.TabularSampler.build_lookups`.
166166
167167
Parameters
168168
--------
169169
X
170-
See :py:meth:`alibi.explainers.anchor_tabular.TabularSampler.build_lookups`.
170+
See :py:meth:`alibi.explainers.anchors.anchor_tabular.TabularSampler.build_lookups`.
171171
172172
Returns
173173
-------
174-
See :py:meth:`alibi.explainers.anchor_tabular.TabularSampler.build_lookups`.
174+
See :py:meth:`alibi.explainers.anchors.anchor_tabular.TabularSampler.build_lookups`.
175175
"""
176176

177177
cat_lookup_id, ord_lookup_id, enc2feat_idx_id = self.sampler.build_lookups(X)
@@ -203,7 +203,7 @@ def fit(self, # type: ignore[override]
203203
Parameters
204204
----------
205205
train_data, disc_perc, **kwargs
206-
See :py:meth:`alibi.explainers.anchor_tabular.AnchorTabular.fit` superclass.
206+
See :py:meth:`alibi.explainers.anchors.anchor_tabular.AnchorTabular.fit` superclass.
207207
"""
208208

209209
try:
@@ -248,12 +248,12 @@ def fit(self, # type: ignore[override]
248248

249249
def _build_sampling_lookups(self, X: np.ndarray) -> None:
250250
"""
251-
See :py:meth:`alibi.explainers.anchor_tabular.AnchorTabular._build_sampling_lookups` documentation.
251+
See :py:meth:`alibi.explainers.anchors.anchor_tabular.AnchorTabular._build_sampling_lookups` documentation.
252252
253253
Parameters
254254
----------
255255
X
256-
See :py:meth:`alibi.explainers.anchor_tabular.AnchorTabular._build_sampling_lookups` documentation.
256+
See :py:meth:`alibi.explainers.anchors.anchor_tabular.AnchorTabular._build_sampling_lookups` documentation.
257257
"""
258258

259259
lookups = [sampler.build_lookups.remote(X) for sampler in self.samplers][0]
@@ -284,11 +284,11 @@ def explain(self,
284284
----------
285285
X, threshold, delta, tau, batch_size, coverage_samples, beam_size, stop_on_first, max_anchor_size, \
286286
min_samples_start, n_covered_ex, binary_cache_size, cache_margin, verbose, verbose_every, **kwargs
287-
See :py:meth:`alibi.explainers.anchor_tabular.AnchorTabular.explain`.
287+
See :py:meth:`alibi.explainers.anchors.anchor_tabular.AnchorTabular.explain`.
288288
289289
Returns
290290
-------
291-
See :py:meth:`alibi.explainers.anchor_tabular.AnchorTabular.explain` superclass.
291+
See :py:meth:`alibi.explainers.anchors.anchor_tabular.AnchorTabular.explain` superclass.
292292
"""
293293
# transform one-hot encodings to labels if ohe == True
294294
X = ohe_to_ord(X_ohe=X.reshape(1, -1), cat_vars_ohe=self.cat_vars_ohe)[0].reshape(-1) if self.ohe else X

‎alibi/explainers/anchors/language_model_text_sampler.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,7 @@ def __call__(self, anchor: tuple, num_samples: int) -> Tuple[np.ndarray, np.ndar
151151
152152
Returns
153153
-------
154-
See :py:meth:`alibi.explainers.anchor_text.LanguageModelSampler.perturb_sentence`.
154+
See :py:meth:`alibi.explainers.anchors.language_model_text_sampler.LanguageModelSampler.perturb_sentence`.
155155
"""
156156
assert self.perturb_opts, "Perturbation options are not set."
157157
return self.perturb_sentence(anchor, num_samples, **self.perturb_opts)

‎alibi/explainers/anchors/text_samplers.py

+3-3
Original file line numberDiff line numberDiff line change
@@ -311,8 +311,8 @@ def __call__(self, anchor: tuple, num_samples: int) -> Tuple[np.ndarray, np.ndar
311311
"""
312312
The function returns a `numpy` array of `num_samples` where randomly chosen features,
313313
except those in anchor, are replaced by similar words with the same part of speech of tag.
314-
See :py:meth:`alibi.explainers.anchor_text.SimilaritySampler.perturb_sentence_similarity` for details of how
315-
the replacement works.
314+
See :py:meth:`alibi.explainers.anchors.text_samplers.SimilaritySampler.perturb_sentence_similarity` for details
315+
of how the replacement works.
316316
317317
Parameters
318318
----------
@@ -323,7 +323,7 @@ def __call__(self, anchor: tuple, num_samples: int) -> Tuple[np.ndarray, np.ndar
323323
324324
Returns
325325
-------
326-
See :py:meth:`alibi.explainers.anchor_text.SimilaritySampler.perturb_sentence`.
326+
See :py:meth:`alibi.explainers.anchors.text_samplers.SimilaritySampler.perturb_sentence_similarity`.
327327
"""
328328
assert self.perturb_opts, "Perturbation options are not set."
329329
return self.perturb_sentence_similarity(anchor, num_samples, **self.perturb_opts)

‎alibi/explainers/similarity/metrics.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ def dot(X: np.ndarray, Y: np.ndarray) -> Union[float, np.ndarray]:
2626

2727
def cos(X: np.ndarray, Y: np.ndarray, eps: float = 1e-7) -> Union[float, np.ndarray]:
2828
"""
29-
Computes the cosine between the vector(s) in X and vector Y. (:math:`X^T Y//\\|X\\|\\|Y\\|`). Each of `X` and `Y`
29+
Computes the cosine between the vector(s) in X and vector Y. (:math:`X^T Y/\\|X\\|\\|Y\\|`). Each of `X` and `Y`
3030
should have a leading batch dimension of size at least 1.
3131
3232
Parameters
@@ -51,7 +51,7 @@ def cos(X: np.ndarray, Y: np.ndarray, eps: float = 1e-7) -> Union[float, np.ndar
5151
def asym_dot(X: np.ndarray, Y: np.ndarray, eps: float = 1e-7) -> Union[float, np.ndarray]:
5252
"""
5353
Computes the influence of training instances `Y` to test instances `X`. This is an asymmetric kernel.
54-
(:math:`X^T Y//\\|Y\\|^2`). See the `paper <https://arxiv.org/abs/2102.05262>`_ for more details. Each of `X` and
54+
(:math:`X^T Y/\\|Y\\|^2`). See the `paper <https://arxiv.org/abs/2102.05262>`_ for more details. Each of `X` and
5555
`Y` should have a leading batch dimension of size at least 1.
5656
5757
Parameters

‎doc/source/examples/cem_iris.ipynb

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
"source": [
1414
"The Contrastive Explanation Method (CEM) can generate black box model explanations in terms of pertinent positives (PP) and pertinent negatives (PN). For PP, it finds what should be minimally and sufficiently present (e.g. important pixels in an image) to justify its classification. PN on the other hand identify what should be minimally and necessarily absent from the explained instance in order to maintain the original prediction.\n",
1515
"\n",
16-
"The original paper where the algorithm is based on can be found on [arXiv](https://arxiv.org/pdf/1802.07623.pdf).\n",
16+
"The original paper where the algorithm is based on can be found on [arXiv](https://arxiv.org/abs/1802.07623).\n",
1717
"\n",
1818
"This notebook requires the seaborn package for visualization which can be installed via pip:"
1919
]

‎doc/source/examples/cem_mnist.ipynb

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
"source": [
1414
"The Contrastive Explanation Method (CEM) can generate black box model explanations in terms of pertinent positives (PP) and pertinent negatives (PN). For PP, it finds what should be minimally and sufficiently present (e.g. important pixels in an image) to justify its classification. PN on the other hand identify what should be minimally and necessarily absent from the explained instance in order to maintain the original prediction.\n",
1515
"\n",
16-
"The original paper where the algorithm is based on can be found on [arXiv](https://arxiv.org/pdf/1802.07623.pdf)."
16+
"The original paper where the algorithm is based on can be found on [arXiv](https://arxiv.org/abs/1802.07623)."
1717
]
1818
},
1919
{

‎doc/source/examples/distributed_kernel_shap_adult_lr.ipynb

+1-1
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
"<div class=\"alert alert-warning\">\n",
2424
"Warning\n",
2525
"\n",
26-
"Windows support for the `ray` Python library is [still experimental](https://docs.ray.io/en/stable/installation.html#windows-support). Using `KernelShap` in parallel is not currently supported on Windows platforms.\n",
26+
"Windows support for the `ray` Python library is [in beta](https://docs.ray.io/en/latest/ray-overview/installation.html#windows-support). Using `KernelShap` in parallel is not currently supported on Windows platforms.\n",
2727
"\n",
2828
"\n",
2929
"</div>"

‎doc/source/examples/integrated_gradients_transformers.ipynb

+2-2
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@
6262
"cell_type": "markdown",
6363
"metadata": {},
6464
"source": [
65-
"Here we define some functions needed to process the data and visualize. For consistency with other [text examples](https://github.com/SeldonIO/alibi/blob/master/examples/integrated_gradients_imdb.ipynb) in alibi, we will use the **IMDB reviews** dataset provided by Keras. Since the dataset consists of reviews that are already tokenized, we need to decode each sentence and re-convert them into tokens using the **(distil)BERT** tokenizer."
65+
"Here we define some functions needed to process the data and visualize. For consistency with other [text examples](../examples/integrated_gradients_imdb.ipynb) in alibi, we will use the **IMDB reviews** dataset provided by Keras. Since the dataset consists of reviews that are already tokenized, we need to decode each sentence and re-convert them into tokens using the **(distil)BERT** tokenizer."
6666
]
6767
},
6868
{
@@ -185,7 +185,7 @@
185185
" tokens = [tokenizer.decode([X[i]]) for i in range(len(X))]\n",
186186
" colors = colorize(attrs)\n",
187187
" \n",
188-
" print('Predicted label = {}: {}'.format(pred, pred_dict[pred]))\n",
188+
" print(f'Predicted label = {pred}: {pred_dict[pred]}')\n",
189189
" return HTML(\"\".join(list(map(hlstr, tokens, colors))))"
190190
]
191191
},

‎doc/source/examples/kernel_shap_adult_lr.ipynb

+1-1
Original file line numberDiff line numberDiff line change
@@ -1241,7 +1241,7 @@
12411241
"\n",
12421242
"The following arguments should be passed to the `fit` step in order to perform grouping:\n",
12431243
"\n",
1244-
"- `background_data`: in this case, `X_train_proc`<sup>[**4**](#Footnotes) </sup>\n",
1244+
"- `background_data`: in this case, `X_train_proc`<sup>[(4)](#Footnotes) </sup>\n",
12451245
"- `group_names`: a list containing the feature names\n",
12461246
"- `groups`: for each feature name in `group_name`, `groups` contains a list of column indices in `X_train_proc` which represent that feature."
12471247
]

‎doc/source/examples/overview.ipynb

-8
Original file line numberDiff line numberDiff line change
@@ -1561,14 +1561,6 @@
15611561
"source": [
15621562
"plot_ale(exp, features=['sulphates', 'alcohol', 'residual sugar', 'chlorides', 'free sulfur dioxide', 'total sulfur dioxide'], line_kw={'label': 'Probability of \"good\" class'})"
15631563
]
1564-
},
1565-
{
1566-
"cell_type": "code",
1567-
"execution_count": null,
1568-
"id": "4e929a28-8f20-4d2a-84a8-30ef5bae9e4e",
1569-
"metadata": {},
1570-
"outputs": [],
1571-
"source": []
15721564
}
15731565
],
15741566
"metadata": {

‎doc/source/methods/ALE.ipynb

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"cell_type": "markdown",
55
"metadata": {},
66
"source": [
7-
"[[source]](../api/alibi.explainers.ale.rst)"
7+
"[[source]](../api/alibi.explainers.html#alibi.explainers.ALE)"
88
]
99
},
1010
{

‎doc/source/methods/Anchors.ipynb

+22-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"cell_type": "markdown",
55
"metadata": {},
66
"source": [
7-
"[[source]](../api/alibi.explainers.anchor_tabular.rst)"
7+
"[[source]](../api/alibi.explainers.anchors.rst)"
88
]
99
},
1010
{
@@ -165,6 +165,13 @@
165165
"### Text"
166166
]
167167
},
168+
{
169+
"cell_type": "markdown",
170+
"metadata": {},
171+
"source": [
172+
"[[source]](../api/alibi.explainers.html#alibi.explainers.AnchorText)"
173+
]
174+
},
168175
{
169176
"cell_type": "markdown",
170177
"metadata": {},
@@ -361,6 +368,13 @@
361368
"### Tabular Data"
362369
]
363370
},
371+
{
372+
"cell_type": "markdown",
373+
"metadata": {},
374+
"source": [
375+
"[[source]](../api/alibi.explainers.html#alibi.explainers.AnchorTabular)"
376+
]
377+
},
364378
{
365379
"cell_type": "markdown",
366380
"metadata": {},
@@ -447,6 +461,13 @@
447461
"### Images"
448462
]
449463
},
464+
{
465+
"cell_type": "markdown",
466+
"metadata": {},
467+
"source": [
468+
"[[source]](../api/alibi.explainers.html#alibi.explainers.AnchorImage)"
469+
]
470+
},
450471
{
451472
"cell_type": "markdown",
452473
"metadata": {},

‎doc/source/methods/CEM.ipynb

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"cell_type": "markdown",
55
"metadata": {},
66
"source": [
7-
"[[source]](../api/alibi.explainers.cem.rst)"
7+
"[[source]](../api/alibi.explainers.html#alibi.explainers.CEM)"
88
]
99
},
1010
{

‎doc/source/methods/CF.ipynb

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"cell_type": "markdown",
55
"metadata": {},
66
"source": [
7-
"[[source]](../api/alibi.explainers.counterfactual.rst)"
7+
"[[source]](../api/alibi.explainers.html#alibi.explainers.Counterfactual)"
88
]
99
},
1010
{

0 commit comments

Comments
 (0)