alibi.explainers.anchor_image module

class alibi.explainers.anchor_image.AnchorImage(predictor, image_shape, segmentation_fn='slic', segmentation_kwargs=None, images_background=None, seed=None)[source]

Bases: alibi.api.interfaces.Explainer

__init__(predictor, image_shape, segmentation_fn='slic', segmentation_kwargs=None, images_background=None, seed=None)[source]

Initialize anchor image explainer.

Parameters
  • predictor (Callable) – A callable that takes a tensor of N data points as inputs and returns N outputs.

  • image_shape (tuple) – Shape of the image to be explained.

  • segmentation_fn (Any) – Any of the built in segmentation function strings: ‘felzenszwalb’, ‘slic’ or ‘quickshift’ or a custom segmentation function (callable) which returns an image mask with labels for each superpixel. See http://scikit-image.org/docs/dev/api/skimage.segmentation.html for more info.

  • segmentation_kwargs (Optional[dict]) – Keyword arguments for the built in segmentation functions.

  • images_background (Optional[ndarray]) – Images to overlay superpixels on.

  • seed (Optional[int]) – If set, ensures different runs with the same input will yield same explanation.

Return type

None

build_explanation(image, 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
  • image (ndarray) – Instance to be explained.

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

  • predicted_label (int) – Label of the instance to be explained.

  • 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 perturbed superpixels.

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(image, p_sample=0.5, threshold=0.95, delta=0.1, tau=0.15, batch_size=100, coverage_samples=10000, beam_size=1, stop_on_first=False, 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
  • image (ndarray) – Image to be explained.

  • p_sample (float) – Probability for a pixel to be represented by the average value of its superpixel.

  • threshold (float) – Minimum precision threshold.

  • delta (float) – Used to compute beta.

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

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

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

  • beam_size (int) – The number of anchors extended at each step of new anchors construction.

  • 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 in result.

  • min_samples_start (int) – Min number of initial samples.

  • 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 desired_label are stored).

  • binary_cache_size (int) – The result search pre-allocates binary_cache_size batches for storing the binary 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.

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

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

Return type

Explanation

Returns

explanation – Dictionary containing the anchor explaining the instance with additional metadata.

generate_superpixels(image)[source]

Generates superpixels from (i.e., segments) an image.

Parameters

image (ndarray) – A grayscale or RGB image.

Return type

ndarray

Returns

A [H, W] array of integers. Each integer is a segment (superpixel) label.

overlay_mask(image, segments, mask_features, scale=(0, 255))[source]

Overlay image with mask described by the mask features.

Parameters
  • image (ndarray) – Image to be explained.

  • segments (ndarray) – Superpixels

  • mask_features (list) – List with superpixels present in mask.

  • scale (tuple) – Pixel scale for masked image.

Return type

ndarray

Returns

masked_image – Image overlaid with mask.

perturbation(anchor, num_samples)[source]

Perturbs an image by altering the values of selected superpixels. If a dataset of image backgrounds is provided to the explainer, then the superpixels are replaced with the equivalent superpixels from the background image. Otherwise, the superpixels are replaced by their average value.

Parameters
  • anchor (tuple) – Contains the superpixels whose values are not going to be perturbed.

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

Return type

Tuple[ndarray, ndarray]

Returns

  • imgs – A [num_samples, H, W, C] array of perturbed images.

  • segments_mask – A [num_samples, M] binary mask, where M is the number of image superpixels segments. 1 indicates the values in that particular superpixels are not perturbed.

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

Sample images from a perturbation distribution by masking randomly chosen superpixels from the original image and replacing them with pixel values from superimposed images if background images are provided to the explainer. Otherwise, the superpixels from the original image are replaced with their average values.

Parameters
  • anchor (Tuple[int, tuple]) – int: order of anchor in the batch tuple: features (= superpixels) present in the proposed anchor

  • num_samples (int) – Number of samples used

  • 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 perturbed is the same as the instance prediction

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

      on pertrurbed sample 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 the values in a superpixel will

      remain unchanged (1) or will be perturbed (0), 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.