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)[source]¶ 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 meancolour occlusion (thefatf.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 pretrained (blackbox) predictive model to be explained. If
as_probabilistic
(see below) is set toTrue
, it must have apredict_proba
method that takes a data set as the only required input parameter and returns a 2dimensional numpy array with probabilities of belonging to each class. Otherwise, ifas_probabilistic
is set toFalse
, thepredictive_model
must have apredict
method that outputs a 1dimensional array with (class) predictions. as_probabilisticboolean, optional (default=True)
A boolean indicating whether the global model is probabilistic. If
True
, thepredictive_model
must have apredict_proba
method. IfFalse
, thepredictive_model
must have apredict
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 colorspace proximity and imagespace proximity for the quickshift segmenter. Higher values give more weight to colorspace. 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)
Cutoff 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 thefatf.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 thepredictive_model
should be treated as probabilistic andFalse
if it should be treated as a classifier. predictive_modelobject
A pretrained (blackbox) 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 thepredictive_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 unlessclass_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 andpredict
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. Theclass_names
parameter is neither a list norNone
. Some of the elements in theclass_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]][source]¶ 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 ifclass_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 fixedsize 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 thefatf.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
orreuse_sample
parameter is not a boolean. Theexplained_class
parameter is neither ofNone
, 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)[source]¶ Sets the occlusion colour.
See the documentation of the
fatf.utils.data.occlusion.Occlusion.set_colouring_strategy
method for more details.