alibi.explainers.anchor_text module

class alibi.explainers.anchor_text.AnchorText(predictor, sampling_strategy='unknown', nlp=None, language_model=None, seed=0, **kwargs)[source]

Bases: alibi.api.interfaces.Explainer

CLASS_SAMPLER = {'language_model': <class 'alibi.explainers.anchor_text.LanguageModelSampler'>, 'similarity': <class 'alibi.explainers.anchor_text.SimilaritySampler'>, 'unknown': <class 'alibi.explainers.anchor_text.UnknownSampler'>}
DEFAULTS: Dict[str, Dict] = {'language_model': {'batch_size_lm': 32, 'filling': 'parallel', 'frac_mask_templates': 0.1, 'punctuation': '!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~', 'sample_proba': 0.5, 'sample_punctuation': False, 'stopwords': [], 'temperature': 1.0, 'top_n': 100, 'use_proba': False}, 'similarity': {'sample_proba': 0.5, 'temperature': 1.0, 'top_n': 100, 'use_proba': False}, 'unknown': {'sample_proba': 0.5}}
SAMPLING_LANGUAGE_MODEL = 'language_model'
SAMPLING_SIMILARITY = 'similarity'
SAMPLING_UNKNOWN = 'unknown'
__init__(predictor, sampling_strategy='unknown', nlp=None, language_model=None, seed=0, **kwargs)[source]

Initialize anchor text explainer.

Parameters
Raises
build_explanation(text, result, predicted_label, params)[source]

Uses the metadata returned by the anchor search algorithm together with the instance to be explained to build an explanation object.

Parameters
  • text (str) – Instance to be explained.

  • result (dict) – Dictionary containing the search result and metadata.

  • predicted_label (int) – Label of the instance to be explained. Inferred if not received.

  • params (dict) – Parameters passed to explain.

Return type

Explanation

compare_labels(samples)[source]

Compute the agreement between a classifier prediction on an instance to be explained and the prediction on a set of samples which have a subset of features fixed to a given value (aka compute the precision of anchors).

Parameters

samples (ndarray) – Samples whose labels are to be compared with the instance label.

Return type

ndarray

Returns

A boolean array indicating whether the prediction was the same as the instance label.

explain(text, threshold=0.95, delta=0.1, tau=0.15, batch_size=100, coverage_samples=10000, beam_size=1, stop_on_first=True, max_anchor_size=None, min_samples_start=100, n_covered_ex=10, binary_cache_size=10000, cache_margin=1000, verbose=False, verbose_every=1, **kwargs)[source]

Explain instance and return anchor with metadata.

Parameters
  • text (str) – Text instance to be explained.

  • threshold (float) – Minimum precision threshold.

  • delta (float) – Used to compute beta.

  • tau (float) – Margin between lower confidence bound and minimum precision or upper bound.

  • batch_size (int) – Batch size used for sampling.

  • coverage_samples (int) – Number of samples used to estimate coverage from during anchor search.

  • beam_size (int) – Number of options kept after each stage of anchor building.

  • stop_on_first (bool) – If True, the beam search algorithm will return the first anchor that has satisfies the probability constraint.

  • max_anchor_size (Optional[int]) – Maximum number of features to include in an anchor.

  • min_samples_start (int) – Number of samples used for anchor search initialisation.

  • n_covered_ex (int) – How many examples where anchors apply to store for each anchor sampled during search (both examples where prediction on samples agrees/disagrees with predicted label are stored).

  • binary_cache_size (int) – The anchor search pre-allocates binary_cache_size batches for storing the boolean arrays returned during sampling.

  • cache_margin (int) – When only max(cache_margin, batch_size) positions in the binary cache remain empty, a new cache of the same size is pre-allocated to continue buffering samples.

  • kwargs (Any) – Other keyword arguments passed to the anchor beam search and the text sampling and perturbation functions.

  • verbose (bool) – Display updates during the anchor search iterations.

  • verbose_every (int) – Frequency of displayed iterations during anchor search process.

Return type

Explanation

Returns

explanationExplanation object containing the anchor explaining the instance with additional metadata as attributes.

meta: dict
model: Union[spacy.language.Language, alibi.utils.lang_model.LanguageModel]
perturbation: Any
reset_predictor(predictor)[source]
Return type

None

sampler(anchor, num_samples, compute_labels=True)[source]

Generate perturbed samples while maintaining features in positions specified in anchor unchanged.

Parameters
  • anchor (Tuple[int, tuple]) – int: the position of the anchor in the input batch tuple: the anchor itself, a list of words to be kept unchanged

  • num_samples (int) – Number of generated perturbed samples.

  • compute_labels (bool) – If True, an array of comparisons between predictions on perturbed samples and instance to be explained is returned.

Return type

Union[List[Union[ndarray, float, int]], List[ndarray]]

Returns

  • If compute_labels=True, a list containing the following is returned

    • covered_true: perturbed examples where the anchor applies and the model prediction

      on perturbation is the same as the instance prediction

    • covered_false: perturbed examples where the anchor applies and the model prediction

      is NOT the same as the instance prediction

    • labels: num_samples ints indicating whether the prediction on the perturbed sample

      matches (1) the label of the instance to be explained or not (0)

    • data: Matrix with 1s and 0s indicating whether a word in the text has been

      perturbed for each sample

    • 1.0: indicates exact coverage is not computed for this algorithm

    • anchor[0]: position of anchor in the batch request

  • Otherwise, a list containing the data matrix only is returned.

class alibi.explainers.anchor_text.AnchorTextSampler[source]

Bases: object

abstract set_text(text)[source]
Return type

None

alibi.explainers.anchor_text.DEFAULT_SAMPLING_LANGUAGE_MODEL = {'batch_size_lm': 32, 'filling': 'parallel', 'frac_mask_templates': 0.1, 'punctuation': '!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~', 'sample_proba': 0.5, 'sample_punctuation': False, 'stopwords': [], 'temperature': 1.0, 'top_n': 100, 'use_proba': False}

Default perturbation options for similarity sampling

  • 'filling': str, filling method for language models. Allowed values: parallel, autoregressive. parallel method corresponds to a single forward pass through the language model. The masked words are sampled independently, according to the selected probability distribution (see top_n, temperature, use_proba). autoregressive method fills the words one at the time. This corresponds to multiple forward passes through the language model which is computationally expensive.

  • 'sample_proba': float, probability of a word to be masked.

  • 'top_n': int, number of similar words to sample for perturbations.

  • 'temperature': float, sample weight hyper-parameter if use_proba equals True.

  • 'use_proba': bool, whether to sample according to the predicted words distribution. If set to False, the top_n words are sampled uniformly at random.

  • frac_mask_template': float, fraction from the number of samples of mask templates to be generated. In each sampling call, will generate int(frac_mask_templates * num_samples) masking templates. Lower fraction corresponds to lower computation time since the batch fed to the language model is smaller. After the words’ distributions is predicted for each mask, a total of num_samples will be generated by sampling evenly from each template. Note that lower fraction might correspond to less diverse sample. A sample_proba is 1 corresponds to masking each word. For this case only one masking template will be constructed. A filling set to autoregressive will generate num_samples masking templates regardless of the value of frac_mask_templates.

  • batch_size_lm: int, batch size used for the language model forward pass.

  • punctuation: str, string of punctuation not to be masked.

  • stopwords: List[str], list of words not to be masked.

  • sample_punctuation: bool, whether to sample punctuation to fill the masked words. If False, the punctuation defined in punctuation will not be sampled.

alibi.explainers.anchor_text.DEFAULT_SAMPLING_SIMILARITY = {'sample_proba': 0.5, 'temperature': 1.0, 'top_n': 100, 'use_proba': False}

Default perturbation options for similarity sampling

  • 'sample_proba': float, probability of a word to be masked.

  • 'top_n': int, number of similar words to sample for perturbations

  • 'temperature': float, sample weight hyper-parameter if use_proba equals True.

  • 'use_proba': bool, whether to sample according to the words similarity.

alibi.explainers.anchor_text.DEFAULT_SAMPLING_UNKNOWN = {'sample_proba': 0.5}

Default perturbation options for unknown sampling

  • 'sample_proba': float, probability of a word to be masked.

class alibi.explainers.anchor_text.LanguageModelSampler(model, perturb_opts)[source]

Bases: alibi.explainers.anchor_text.AnchorTextSampler

FILLING_AUTOREGRESSIVE = 'autoregressive'
FILLING_PARALLEL = 'parallel'
__call__(anchor, num_samples)[source]

The function returns an np.array of num_samples where randomly chosen features, except those in anchor, are replaced by words sampled according to the language model’s predictions.

Parameters
  • anchor (tuple) – Indices represent the positions of the words to be kept unchanged.

  • num_samples (int) – Number of perturbed sentences to be returned.

Return type

Tuple[ndarray, ndarray]

Returns

See perturb_sentence

__init__(model, perturb_opts)[source]

Initialize language model sampler. This sampler replaces words with the ones sampled according to the output distribution of the language model. There are two modes to use the sampler: parallel and autoregressive. In the parallel mode, all words are replaced simultaneously. In the autoregressive model, the words are replaced one by one, starting from left to right. Thus the following words are conditioned on the previous predicted words.

Parameters
  • model (LanguageModel) – Transformers masked language model.

  • perturb_opts (dict) – Perturbation options.

create_mask(anchor, num_samples, sample_proba=1.0, filling='parallel', frac_mask_templates=0.1, **kwargs)[source]

Create mask for words to be perturbed.

Parameters
  • anchor (tuple) – Indices represent the positions of the words to be kept unchanged.

  • num_samples (int) – Number of perturbed sentences to be returned.

  • sample_proba (float) – Probability of a word being replaced.

  • filling (str) – Method to fill masked words. Either parallel or autoregressive.

  • frac_mask_templates (float) – Fraction of mask templates from the number of requested samples.

Return type

Tuple[ndarray, ndarray]

Returns

  • raw – Array with masked instances.

  • data – A (num_samples, m)-dimensional boolean array, where m is the number of tokens in the instance to be explained.

fill_mask(raw, data, num_samples, top_n=100, batch_size_lm=32, filling='parallel', **kwargs)[source]

Fill in the masked tokens with language model.

Parameters
  • raw (ndarray) – Array of mask templates.

  • data (ndarray) – Binary mask having 0 where the word was masked. Note that the width of the data array is equal to the length of id_samples.

  • num_samples (int) – Number of samples to be drawn.

  • top_n (int) – Use the top n words when sampling.

  • batch_size_lm (int) – Batch size used for language model.

  • filling (str) – Method to fill masked words. Either parallel or autoregressive.

Return type

Tuple[ndarray, ndarray]

Returns

raw – Array containing num_samples elements. Each element is a perturbed sentence.

get_sample_ids(punctuation='!"#$%&\\'()*+, -./:;<=>?@[\\\\]^_`{|}~', stopwords=None, **kwargs)[source]

Find indices in words which can be perturbed.

Parameters
  • punctuation (str) – String of punctuation characters.

  • stopwords (Optional[List[str]]) – List of stopwords.

Return type

None

perturb_sentence(anchor, num_samples, sample_proba=0.5, top_n=100, batch_size_lm=32, filling='parallel', **kwargs)[source]

The function returns an np.array of num_samples where randomly chosen features, except those in anchor, are replaced by words sampled according to the language model’s predictions.

Parameters
  • anchor (tuple) – Indices represent the positions of the words to be kept unchanged.

  • num_samples (int) – Number of perturbed sentences to be returned.

  • sample_proba (float) – Probability of a token being replaced by a similar token.

  • top_n (int) – Used for top n sampling.

  • batch_size_lm (int) – Batch size used for language model.

  • filling (str) – Method to fill masked words. Either parallel or autoregressive.

Return type

Tuple[ndarray, ndarray]

Returns

  • raw – Array containing num_samples elements. Each element is a perturbed sentence.

  • data – A (num_samples, m)-dimensional boolean array, where m is the number of tokens in the instance to be explained.

set_data_type()[source]

Working with numpy arrays of strings requires setting the data type to avoid truncating examples. This function estimates the longest sentence expected during the sampling process, which is used to set the number of characters for the samples and examples arrays. This depends on the perturbation method used for sampling.

Return type

None

set_text(text)[source]

Sets the text to be processed

Parameters

text (str) – Text to be processed.

Return type

None

class alibi.explainers.anchor_text.Neighbors(nlp_obj, n_similar=500, w_prob=- 15.0)[source]

Bases: object

__init__(nlp_obj, n_similar=500, w_prob=- 15.0)[source]

Initialize class identifying neighbouring words from the embedding for a given word.

Parameters
  • nlp_obj (Language) – spaCy model.

  • n_similar (int) – Number of similar words to return.

  • w_prob (float) – Smoothed log probability estimate of token’s type.

neighbors(word, tag, top_n)[source]

Find similar words for a certain word in the vocabulary.

Parameters
  • word (str) – Word for which we need to find similar words.

  • tag (str) – Part of speech tag for the words.

  • top_n (int) – Return only top_n neighbors.

Return type

dict

Returns

  • A dict with two fields. The ‘words’ field contains a numpy array

  • of the top_n most similar words, whereas the fields similarity is

  • a numpy array with corresponding word similarities.

class alibi.explainers.anchor_text.SimilaritySampler(nlp, perturb_opts)[source]

Bases: alibi.explainers.anchor_text.AnchorTextSampler

__call__(anchor, num_samples)[source]

The function returns an np.array of num_samples where randomly chosen features, except those in anchor, are replaced by similar words with the same part of speech of tag. See self.perturb_sentence for details of how the replacement works.

Parameters
  • anchor (tuple) – Indices represent the positions of the words to be kept unchanged.

  • num_samples (int) – Number of perturbed sentences to be returned.

Return type

Tuple[ndarray, ndarray]

Returns

See perturb_sentence_similarity

__init__(nlp, perturb_opts)[source]

Initialize similarity sampler. This sampler replaces words with similar words.

Parameters
  • nlp (Language) – spaCy object.

  • perturb_opts (Dict) – Perturbation options.

find_similar_words()[source]

This function queries a spaCy nlp model to find n similar words with the same part of speech for each word in the instance to be explained. For each word the search procedure returns a dictionary containing an np.array of words (‘words’) and an np.array of word similarities (‘similarities’).

Return type

None

perturb_sentence_similarity(present, n, sample_proba=0.5, forbidden=frozenset({}), forbidden_tags=frozenset({'PRP$'}), forbidden_words=frozenset({'be'}), temperature=1.0, pos=frozenset({'ADJ', 'ADP', 'ADV', 'DET', 'NOUN', 'VERB'}), use_proba=False, **kwargs)[source]

Perturb the text instance to be explained.

Parameters
  • present (tuple) – Word index in the text for the words in the proposed anchor.

  • n (int) – Number of samples used when sampling from the corpus.

  • sample_proba (float) – Sample probability for a word if use_proba is False.

  • forbidden (frozenset) – Forbidden lemmas.

  • forbidden_tags (frozenset) – Forbidden POS tags.

  • forbidden_words (frozenset) – Forbidden words.

  • pos (frozenset) – POS that can be changed during perturbation.

  • use_proba (bool) – Bool whether to sample according to a similarity score with the corpus embeddings.

  • temperature (float) – Sample weight hyperparameter if use_proba equals True.

Return type

Tuple[ndarray, ndarray]

Returns

  • raw – Array of perturbed text instances.

  • data – Matrix with 1s and 0s indicating whether a word in the text has not been perturbed for each sample.

set_data_type()[source]

Working with numpy arrays of strings requires setting the data type to avoid truncating examples. This function estimates the longest sentence expected during the sampling process, which is used to set the number of characters for the samples and examples arrays. This depends on the perturbation method used for sampling.

Return type

None

set_text(text)[source]

Sets the text to be processed

Parameters

text (str) – Text to be processed.

Return type

None

class alibi.explainers.anchor_text.UnknownSampler(nlp, perturb_opts)[source]

Bases: alibi.explainers.anchor_text.AnchorTextSampler

UNK = 'UNK'
__call__(anchor, num_samples)[source]

The function returns an np.array of num_samples where randomly chosen features, except those in anchor, are replaced by self.UNK token.

Parameters
  • anchor (tuple) – Indices represent the positions of the words to be kept unchanged.

  • num_samples (int) – Number of perturbed sentences to be returned.

Return type

Tuple[ndarray, ndarray]

Returns

  • raw – Array containing num_samples elements. Each element is a perturbed sentence.

  • data – A (num_samples, m)-dimensional boolean array, where m is the number of tokens in the instance to be explained.

__init__(nlp, perturb_opts)[source]

Initialize unknown sampler. This sampler replaces word with the UNK token.

Parameters
  • nlp (Language) – spaCy object.

  • perturb_opts (Dict) – Perturbation options.

set_data_type()[source]

Working with numpy arrays of strings requires setting the data type to avoid truncating examples. This function estimates the longest sentence expected during the sampling process, which is used to set the number of characters for the samples and examples arrays. This depends on the perturbation method used for sampling.

Return type

None

set_text(text)[source]

Sets the text to be processed.

Parameters

text (str) – Text to be processed.

Return type

None