fatf.transparency.predictions.surrogate_image_explainers.ImageBlimeyLime

class fatf.transparency.predictions.surrogate_image_explainers.ImageBlimeyLime(image: numpy.ndarray, predictive_model: object, as_probabilistic: bool = True, class_names: Union[List[str], List[int], None] = None, segmentation_mask: Optional[numpy.ndarray] = None, segments_merge_list: Union[None, List[int], List[List[int]]] = None, ratio: float = 0.2, kernel_size: float = 4, max_dist: float = 200, colour: Union[str, int, Tuple[int, int, int], None] = None)

Implements a surrogate image explainer equivalent to LIME.

New in version 0.1.1.

By default this explainer uses quickshift segmentation (the fatf.utils.data.segmentation.QuickShift class) and mean-colour occlusion (the fatf.utils.data.occlusion.Occlusion class). It uses the cosine distance transformed thorough the exponential kernel to generate similarity scores between the binary representation of the explained instance and the data sample. It works with both crisp and probabilistic classifiers; it assumes the latter by default (as_probabilistic=True).

Parameters

imagenumpy.ndarray

A numpy array representing an image to be explained.

predictive_modelobject

A pre-trained (black-box) predictive model to be explained. If as_probabilistic (see below) is set to True, it must have a predict_proba method that takes a data set as the only required input parameter and returns a 2-dimensional numpy array with probabilities of belonging to each class. Otherwise, if as_probabilistic is set to False, the predictive_model must have a predict method that outputs a 1-dimensional array with (class) predictions.

as_probabilisticboolean, optional (default=True)

A boolean indicating whether the global model is probabilistic. If True, the predictive_model must have a predict_proba method. If False, the predictive_model must have a predict method.

class_namesList[string, integer], optional (default=None)

A list of strings or integer corresponding to the names of classes. If the predictive model is probabilistic, the order of the class names should correspond to the order of columns output by the model. For crisp models the order is irrelevant.

segmentation_masknumpy.ndarray, optional (default=None)

A numpy array representing an image to be used for generating the segmentation. If this parameter is not provided, the image will be used to generate the segmentation.

segments_merge_listlist(integer) or list(list(integer)), optional (default=None)

A collection or a set of collections of segment ids to be merged. See the documentation of the fatf.utils.data.segmentation.Segmentation.merge_segments method for more details.

rationumber, optional (default=0.2)

Balances color-space proximity and image-space proximity for the quickshift segmenter. Higher values give more weight to color-space. Between 0 and 1.

kernel_sizenumber, optional (default=4)

Width of Gaussian kernel used in smoothing the sample density for the quickshift segmenter. Higher means fewer clusters.

max_distnumber, optional (default=200)

Cut-off point for data distances for the quickshift segmenter. Higher means fewer clusters.

colourstring, integer, tuple(integer, integer, integer), optional (default=None)

An occlusion colour specifier. By default (colour=None) the mean colouring strategy is used. See the documentation of the fatf.utils.data.occlusion.Occlusion.set_colouring_strategy method for more details.

Attributes

imagenumpy.ndarray

A numpy array representing an image to be explained.

segmentation_masknumpy.ndarray

A numpy array representing an image used to perform segmentation.

segmenterfatf.utils.data.segmentation.Segmentation

A quickshift image segmenter (fatf.utils.data.segmentation.QuickShift).

occluderfatf.utils.data.occlusion.Occlusion

An image occluder (fatf.utils.data.occlusion.Occlusion).

as_probabilisticboolean

True if the predictive_model should be treated as probabilistic and False if it should be treated as a classifier.

predictive_modelobject

A pre-trained (black-box) predictive model to be explained.

predictive_functionCallable[[numpy.ndarray], numpy.ndarray]

A function that will be used to get predictions from the explained predictive model. It references the predictive_model.predict_proba method for for probabilistic models (as_probabilistic=True) and the predictive_model.predict method for crisp classifiers.

image_predictionUnion[string, integer]

The prediction of the explained image. For probabilistic models it is the index of the class assigned to this instance by the explained model; for crisp classifier it is the predicted class.

classes_numberinteger or None

The number of modelled classes for probabilistic models; None for crisp classifiers unless class_names was provided.

class_namesList[string] or None

A list of class names that can be predicted by the explained model. For probabilistic models these are in order they appear in the probability vector output by the model. There is no particular order for crisp predictors.

surrogate_data_samplenumpy.ndarray or None

A binary data sample generated during the last call of the explain_instance method.

surrogate_data_predictionsnumpy.ndarray or None

Predictions of the explained model for the binary data sample (reversed to the image representation) generated during the last call of the explain_instance method.

similaritiesnumpy.ndarray or None

Similarities between the explained instance and the sampled data computed in the binary domain using the cosine distance transformed thorough the exponential kernel and generated during the last call of the explain_instance method.

Raises

IncompatibleModelError

The predictive_model does not have the required functionality: predict_proba method for probabilistic models and predict method crisp classifiers.

RuntimeError

The number of class names provided via the class_names parameter does not agree with the number of classes output by the probabilistic model.

TypeError

The as_probabilistic parameter is not a boolean. The class_names parameter is neither a list nor None. Some of the elements in the class_names list are neither a string nor an integer.

ValueError

The class_names list is empty or it contains duplicates.

Methods

explain_instance(explained_class, str, …)	Explains the image used to initialise this class.
set_occlusion_colour(colour)	Sets the occlusion colour.

explain_instance(explained_class: Union[int, str, None] = None, samples_number: int = 50, batch_size: int = 50, kernel_width: float = 0.25, colour: Union[str, int, Tuple[int, int, int], None] = None, reuse_sample: bool = False, return_model: bool = False) → Union[Dict[str, numbers.Number], Tuple[Dict[str, numbers.Number], fatf.utils.models.models.Model]]

Explains the image used to initialise this class.

Parameters

explained_classUnion[integer, string], optional (default=None)

The class to be explained. By default (explained_class=None) the class predicted by the explained model for the explained image will be used. For probabilistic models this can be the index of the class in the probability vector output by the explained model or the name of the class if class_names parameter was provided while initialising this class. For crisp classifiers this has to be one of the values predicted by the explained model.

samples_numberinteger, optional (default=50)

The number of data points sampled from the random binary generator to be used for fitting the local surrogate model.

batch_sizeinteger, optional (default=50)

The number of images to be processed in one iteration. Since this step is computationally expensive – images need to be generated and occluded according to the binary data sample, and then predicted by the explained model – the data points can be processed in fixed-size batches.

kernel_widthfloat, optional (default=0.25)

The width of the exponential kernel used when computing weights of the binary sampled data based on the cosine distances between them and the explained image.

colourstring, integer, tuple(integer, integer, integer), optional (default=None)

An occlusion colour specifier. By default (colour=None) the colour specified when initialising this class is used. See the documentation of the fatf.utils.data.occlusion.Occlusion.set_colouring_strategy method for more details.

reuse_sampleboolean, optional (default=False)

Whether to generate a new binary data sample or reuse the one generated with the last call of this method.

return_modelsboolean, optional (default=False)

If True, this method will return both the feature importance explanation and the local surrogate model. Otherwise, only the explanation is returned.

Returns

explanationsDictionary[string, float]

A dictionary containing image segment importance (extracted from the local linear surrogate).

modelssklearn.linear_model.base.LinearModel, optional

A locally fitted surrogate linear model. This model is only returned when return_model=True.

Raises

IndexError

The name of the class chosen to be explained could not be located among the class names provided upon initialising this object. The index of the explained class – when explaining a probabilistic model – is invalid.

RuntimeError

Some of the cosine distances could not be computed due to a numerical error. The data sample cannot be reused without calling this method at least once beforehand. A class name cannot be used when explaining a probabilistic model without initialising this object with class names.

TypeError

The return_model or reuse_sample parameter is not a boolean. The explained_class parameter is neither of None, a string or an integer.

Warns

UserWarning

Informs the user if none of the sampled data were predicted with the explained class when explaining a crisp model – such a situation will most probably result in unreliable explanations.

set_occlusion_colour(colour)

Sets the occlusion colour.

See the documentation of the fatf.utils.data.occlusion.Occlusion.set_colouring_strategy method for more details.

Examples using fatf.transparency.predictions.surrogate_image_explainers.ImageBlimeyLime

Using LIME Image Explainer