API Reference

This page provides detailed technical documentation for the EXPLICAD modules, automatically generated from the source code docstrings.

Evaluator Core

class evaluator.evaluate.Evaluate(model, processor, target_layers, targets, explainability_method='cam', cam_method='gradcamelementwise', discard_ratio=0.9, head_fusion='min')

Bases: object

assert_heatmap_range(heatmap1, heatmap2)

calculate_metrics(heatmap1: numpy.ndarray, heatmap2: numpy.ndarray)

draw_boxes(image, boxes, classes=['heatmap', 'ground_truth'], colors=[(255, 0, 0), (0, 0, 0)])

Draws bounding boxes on an image.

Parameters:

• image (numpy.ndarray) – The image on which to draw the bounding boxes. It’s expected to be a NumPy array representing an image (e.g., with shape (height, width, 3) for BGR).

• boxes (list) – A list of bounding box coordinates. Each bounding box should be a list or tuple of four integers: (x1, y1, x2, y2), where (x1, y1) is the top-left corner and (x2, y2) is the bottom-right corner.

• classes (list, optional) – A list of strings representing the class labels for each bounding box. Defaults to [“heatmap”, “ground_truth”]. The length of this list should match the number of bounding boxes.

• colors (list, optional) – A list of BGR color tuples (e.g., (255, 0, 0) for blue) for drawing each bounding box. Defaults to [(255, 0, 0), (0, 255, 0)] (blue and green). The length of this list should match the number of bounding boxes.

Returns:

The image with the bounding boxes drawn on it.

Return type:

numpy.ndarray

get_cam_on_image(heatmap, image)

Plausibility

class evaluator.plausibility.plausibility.Plausibility(model, processor, target_layers, targets, bbox_func, explainability_method='cam', cam_method='gradcamelementwise', discard_ratio=0.9, head_fusion='max')

Bases: Evaluate

calculate_average_batch_plausibility(image_list, ground_truth_list, threshold=0.9)

calculate_iou(box1, box2)

Calculates the Intersection over Union (IoU) of two bounding boxes.

Parameters:

• box1 (tuple or list) – A tuple/list of four integers (x1, y1, x2, y2) representing the coordinates of the first bounding box. (x1, y1) is the top-left corner, and (x2, y2) is the bottom-right corner.

• box2 (tuple or list) – A tuple/list of four integers (x1_p, y1_p, x2_p, y2_p) representing the coordinates of the second bounding box. (x1_p, y1_p) is the top-left corner, and (x2_p, y2_p) is the bottom-right corner.

Returns:

A tuple containing:

• iou (float): The Intersection over Union (IoU) value, a float between 0 and 1.

• box1_area (int): The area of the first bounding box.

• box2_area (int): The area of the second bounding box.

Return type:

tuple

calculate_plausibility_overlap(heatmap, ground_truth, cam_image)

calculate_plausibility_remove_iou(image, ground_truth)

plausibility(image, ground_truth, threshold=0.9)

positive_attribution_sum(heatmap, ground_truth=None)

Sums the number of non-zero heatmap values within a ground truth bounding box or for the entire heatmap.

Parameters:

• heatmap (np.ndarray) – A 2D numpy array representing the heatmap.

• ground_truth (tuple or list) – A tuple or list of four integers (x_min, y_min, x_max, y_max) defining the coordinates of the ground truth bounding box.

Returns:

The number of heatmap values within the ground truth bounding box

that are strictly greater than 0.

Return type:

int

relevance_mass_accuracy(heatmap, ground_truth)

relevance_rank_accuracy(heatmap, ground_truth, threshold=0.9)

threshold_heatmap(heatmap, threshold)

Normalizes a numpy array heatmap and retains values above a specified threshold.

Parameters:

• heatmap (np.ndarray) – A 2D numpy array representing the heatmap.

• threshold (float) – A value between 0 and 1. Only normalized values greater than this threshold will be retained.

Returns:

A numpy array of the same shape as the input heatmap,

where values below or equal to the threshold are set to 0, and the remaining values are the normalized original values.

Return type:

np.ndarray

Fidelity Metrics

class evaluator.fidelity.insertion.Insertion(model, processor, target_layers, targets, cam_method='gradcamelementwise', explainability_method='cam')

Bases: Evaluate

A class to evaluate the faithfulness of an explainability method by performing a insertion-based experiment. It adds the most important pixels (based on the heatmap scores) from the input image to a base image and measures the corresponding gain in model’s confidence.

The final metric is the Area Under the Insertion Curve (AUC). A lower AUC indicates that the model’s confidence drops more quickly, suggesting a more faithful explanation.

get_idx_list(image)

insertion(image, interval=0.1, base_value=None)

modify_input(image, idx_list, insertion_ratio, base_value=None)

plot_insertion_curve(image, interval=0.1, base_value=None, title='Insertion Curve', save_path=None)

Plots the deletion curve.

Parameters:

• fractions_removed (list) – List of fractions of the image removed.

• logit_values (list) – List of corresponding logit values.

• save_path (str, optional) – Path to save the plot. If None, the plot is displayed.

class evaluator.fidelity.deletion.Deletion(model, processor, target_layers, targets, cam_method='gradcamelementwise', explainability_method='cam')

Bases: Evaluate

A class to evaluate the faithfulness of an explainability method by performing a deletion-based experiment. It removes the most important pixels (based on the heatmap scores) from the input image and measures the corresponding drop in model’s confidence.

The final metric is the Area Under the Deletion Curve (AUC). A lower AUC indicates that the model’s confidence drops more quickly, suggesting a more faithful explanation.

deletion(image, interval=0.1, base_value=None)

get_idx_list(image)

modify_input(image, idx_list, mask_ratio, base_value=None)

plot_deletion_curve(image, interval=0.2, base_value=None, title=None, save_path=None)

Plots the deletion curve.

Parameters:

• fractions_removed (list) – List of fractions of the image removed.

• logit_values (list) – List of corresponding logit values.

• save_path (str, optional) – Path to save the plot. If None, the plot is displayed.

class evaluator.fidelity.faithfulness_corr.FaithfulnessCorrelation(model, processor, target_layers, targets, cam_method='gradcamelementwise', explainability_method='cam')

Bases: Evaluate

A class to evaluate the faithfulness of an explainability method by calculating the Pearson correlation coefficient between the change in model logits and the heatmap scores of perturbed regions. This assumes the heatmap and input image have the same spatial dimensions (height, width).

average_subset_explanation_score(heatmap, idx_list)

Averages the heatmap values corresponding to a list of flattened indices.

Parameters:

• heatmap (np.ndarray) – The heatmap generated by the explainer.

• idx_list (np.ndarray) – A list of random flattened indices.

Returns:

The average heatmap score for the selected subset of pixels.

Return type:

float

calculate_pearsons(logit_list, exp_scores)

Takes two lists and calculates the Pearson’s correlation coefficient between them.

Parameters:

• logit_list (list) – A list of logit differences.

• exp_scores (list) – A list of average explanation scores.

Returns:

The Pearson correlation coefficient.

Return type:

float

idx_sample(image, size=10)

Creates a list of size ‘size’ containing a random sample of indices from the flattened image indices.

Parameters:

• image (np.ndarray) – The input image.

• size (int) – The number of indices to sample.

Returns:

An array of randomly sampled flattened indices.

Return type:

np.ndarray

modify_input(image, idx_list, base_value=None)

Sets a subset of pixels in the input image to a base value.

Parameters:

• image (np.ndarray) – The input image as a NumPy array.

• idx_list (np.ndarray) – A list of random flattened indices corresponding to the image.

• base_value (int or tuple, optional) – The value to set the pixels to. If None, the mean of the image is used. Defaults to None.

Returns:

The modified image.

Return type:

np.ndarray

Consistency Metrics

class evaluator.consistency.consistency.Stability(model, processor, target_layers, targets, cam_method='gradcamelementwise', explainability_method='cam')

Bases: Evaluate

A class to evaluate the stability of an explainability method by calculating the relative change in explanations for similar inputs w.r.t the change in the input itself.

Lower is better

evaluation_metric(image: Image, transformed_images: List[Image] = [], transform_type: str = 'rotation', p_val=2, min_eps=1e-05, **kwargs)

Calculates the metric for a batch of transformed images.

Parameters:

• image (np.ndarray) – The original input image.

• transformed_images (List[np.ndarray]) – A list of transformed versions of the original image.

• p_val (int) – The p-value for the L_p norm calculation.

• min_eps (float) – A small epsilon value to prevent division by zero.

Returns:

The metric value for a given image.

Return type:

float

generate_transformed_images(image: Image, transform_type: str, **kwargs) → List[Image]

Generates a list of transformed images based on the specified transformation type.

Parameters:

• image (PIL.Image.Image) – The original input image.

• transform_type (str) – The type of transformation to apply (‘rotation’ or ‘noise’).

Kwargs:

max_angle (int):

[For ‘rotation’] The maximum rotation angle in degrees from the original image. Default is 5.

step (float):

[For ‘rotation’ and ‘noise’] The increment between each transformation level. Default is 0.1.

max_std (float):

[For ‘noise’] The maximum standard deviation of the Gaussian noise to be added. Default is 5.

Returns:

A list of transformed images.

Return type:

List[PIL.Image.Image]

Raises:

ValueError – If an unknown transform type is specified.

class evaluator.consistency.RIS.RIS(model, processor, target_layers, targets, cam_method='gradcamelementwise', explainability_method='cam')

Bases: Stability

A class to evaluate the stability of an explainability method by calculating the relative change in explanations for similar inputs w.r.t the change in the input itself.

Lower is better

evaluation_metric(image: Image, transformed_images=None, transform_type: str = 'rotation', p_val=2, min_eps=1e-05, **kwargs)

Calculates the Relative Input Stability (RIS) metric for a batch of transformed images.

Parameters:

• image (np.ndarray) – The original input image.

• transformed_images (List[np.ndarray]) – A list of transformed versions of the original image.

• p_val (int) – The p-value for the L_p norm calculation.

• min_eps (float) – A small epsilon value to prevent division by zero.

Returns:

The maximum RIS value found among the valid transformed images.

Return type:

float

class evaluator.consistency.ROS.ROS(model, processor, target_layers, targets, cam_method='gradcamelementwise', explainability_method='cam')

Bases: Stability

A class to evaluate the stability of an explainability method by calculating the relative change in explanations for similar inputs w.r.t the change in the input itself.

Lower is better

evaluation_metric(image: Image, transformed_images=None, transform_type: str = 'rotation', p_val=2, min_eps=1e-05, **kwargs)

Calculates the Relative Input Stability (RIS) metric for a batch of transformed images.

Parameters:

• image (np.ndarray) – The original input image.

• transformed_images (List[np.ndarray]) – A list of transformed versions of the original image.

• p_val (int) – The p-value for the L_p norm calculation.

• min_eps (float) – A small epsilon value to prevent division by zero.

Returns:

The maximum RIS value found among the valid transformed images.

Return type:

float

class evaluator.consistency.SSIM.SSIM(model, processor, target_layers, targets, cam_method='gradcamelementwise', explainability_method='cam')

Bases: Stability

A class to evaluate the stability of an explainability method by calculating the SSIM in explanations for similar inputs.

Higher is better

evaluation_metric(image: Image, transformed_images=None, transform_type: str = 'rotation', p_val=2, min_eps=1e-05, **kwargs)

Calculates the Relative Input Stability (RIS) metric for a batch of transformed images.

Parameters:

• image (np.ndarray) – The original input image.

• transformed_images (List[np.ndarray]) – A list of transformed versions of the original image.

• p_val (int) – The p-value for the L_p norm calculation.

• min_eps (float) – A small epsilon value to prevent division by zero.

Returns:

The maximum RIS value found among the valid transformed images.

Return type:

float

XAI Methods

class xai_methods.gradcam_vit.HuggingfaceToTensorModelWrapper(*args: Any, **kwargs: Any)

Bases: Module

Model wrapper to return a tensor

forward(x)

class xai_methods.gradcam_vit.ViTCAM(model, processor, target_layers, targets, cam_method='gradcamelementwise', use_attentions=False, patch_size=16, image_size=224)

Bases: object

A class for generating and visualizing Class Activation Maps (CAMs) for Vision Transformer (ViT) models. It supports various CAM methods implemented in the pytorch gradcam library.

cleanup(clear_cache=False)

Cleans up the stored activations and gradients in the CAM object to free memory.

generate(input_image)

Generates a heatmap for a given input image using the selected CAM method.

Parameters:

input_image (PIL.Image.Image) – The input image (assumed to be resized to 224x224) (H, W, C)

Returns:

A tuple containing:

• input_tensor (torch.Tensor): The processed input tensor.

• image (np.ndarray): The input image as a NumPy array (range 0-1).

• grayscale_cam (np.ndarray): The generated grayscale CAM heatmap (H, W).

• cam_image (np.ndarray): The CAM overlaid on the original image (uint8).

• label (str): The predicted class label for the input image.

Return type:

tuple

get_rot_bbox_true(bbox, rot)

Gets the bounding box coordinates after rotating an image.

Parameters:

• bbox (tuple or list) – A tuple/list of four integers (x_min, y_min, x_max, y_max) representing the original bounding box.

• rot (int) – The rotation angle in degrees (0, 90, 180, or 270).

Returns:

A list of four integers [x_min_rot, y_min_rot, x_max_rot, y_max_rot]

representing the bounding box coordinates after rotation.

Return type:

list

plot_heatmaps(input_image, rotations=[0])

Generates and plots heatmaps for an input image at different rotation angles.

Parameters:

• input_image (PIL.Image.Image) – The input image to generate heatmaps for.

• rotations (list, optional) – A list of rotation angles (in degrees) to apply to the image before generating heatmaps. Defaults to [0] (no rotation).

xai_methods.gradcam_vit.vit_reshape_attention_transform(tensor, height=14, width=14)

class xai_methods.chefer_vit.CheferRelevance(model, processor, attention_layer_name='attention.dropout')

Bases: object

apply_self_attention_rules(R_ss, cam_ss)

avg_heads(cam, grad)

cleanup(clear_cache=False)

generate(images, class_index=None)

get_attention(module, input, output)

get_attention_gradient(module, grad_input, grad_output)

remove_hooks()

xai_methods.chefer_vit.apply_self_attention_rules(R_ss, cam_ss)

xai_methods.chefer_vit.avg_heads(cam, grad)

xai_methods.chefer_vit.generate_relevance(model, input, index=None)

xai_methods.chefer_vit.generate_visualization(original_image, model=None, class_index=None)

xai_methods.chefer_vit.show_cam_on_image(img, mask)

class xai_methods.rollout_vit.VITAttentionGradRollout(model, processor, attention_layer_name='attention.dropout', discard_ratio=0.9)

Bases: object

cleanup(clear_cache=False)

generate(image)

get_attention(module, input, output)

get_attention_gradient(module, grad_input, grad_output)

grad_rollout()

remove_hooks()

class xai_methods.rollout_vit.VITAttentionRollout(model, processor, attention_layer_name='attention.dropout', head_fusion='mean', discard_ratio=0.9)

Bases: object

cleanup(clear_cache=False)

generate(images)

get_attention(module, input, output)

remove_hooks()

rollout()

xai_methods.rollout_vit.show_mask_on_image(img, mask)