XAI.utils package¶

Submodules¶

XAI.utils.datasets module¶

class XAI.utils.datasets.DatasetFromCSV(path_to_csv, transform=<function data_transforms>)[source]¶

Bases: torch.utils.data.dataset.Dataset

Dataset for Food Scoring images. This class inherits torch.utils.data.Dataset and overrides the __len__ and __getitem__ methods.

class XAI.utils.datasets.FSImageDataset(root_dir, image_ext='.png', transform=None, path_to_labels=None)[source]¶

Bases: torch.utils.data.dataset.Dataset

Dataset for Food Scoring images. This class inherits torch.utils.data.Dataset and overrides the __len__ and __getitem__ methods.

XAI.utils.datasets.data_transforms(image)[source]¶

Applies PyTorch toTensor() and Normalize() transformation to a single image that is a numpy array.

Parameters: image (numpy.ndarray) – The image to apply PyTorch transformations to. It has to be a numpy array of shape (H, W, Channel).
Returns: d_transforms(image) – The transformed image with pixel values ranging from [-1.0, 1.0]
Return type: Torch.Tensor

XAI.utils.inception_resnet_v2 module¶

class XAI.utils.inception_resnet_v2.BasicConv2d(in_planes, out_planes, kernel_size, stride, padding=0)[source]¶

Bases: torch.nn.modules.module.Module

forward(x)[source]¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

training: bool¶

class XAI.utils.inception_resnet_v2.Block17(scale=1.0)[source]¶

Bases: torch.nn.modules.module.Module

forward(x)[source]¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

training: bool¶

class XAI.utils.inception_resnet_v2.Block35(scale=1.0)[source]¶

Bases: torch.nn.modules.module.Module

forward(x)[source]¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

training: bool¶

class XAI.utils.inception_resnet_v2.Block8(scale=1.0, noReLU=False)[source]¶

Bases: torch.nn.modules.module.Module

forward(x)[source]¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

training: bool¶

class XAI.utils.inception_resnet_v2.InceptionResNetV2(num_classes=1001)[source]¶

Bases: torch.nn.modules.module.Module

features(input)[source]¶

forward(input)[source]¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

logits(features)[source]¶

training: bool¶

class XAI.utils.inception_resnet_v2.Mixed_5b[source]¶

Bases: torch.nn.modules.module.Module

forward(x)[source]¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

training: bool¶

class XAI.utils.inception_resnet_v2.Mixed_6a[source]¶

Bases: torch.nn.modules.module.Module

forward(x)[source]¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

training: bool¶

class XAI.utils.inception_resnet_v2.Mixed_7a[source]¶

Bases: torch.nn.modules.module.Module

forward(x)[source]¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

training: bool¶

XAI.utils.load_model_worker module¶

XAI.utils.load_model_worker.load_pretrained_weights(model, pretrained_path=None, as_extractor=False, tuning_layers=None, resume=None)[source]¶

Load pretrained weight.

Source code can be found here: # https://github.com/ChuaHanChong/FoodDX_P2/blob/dev2/src/modules/FoodScoring/__init__.py#L18

Parameters

model (torch.nn.Module) – A torch model.
pretrained_path (str, optional) – Path of an ImageNet pre-trained weight, by default None.
as_extractor (bool, optional) – Fix ConvNets as feature extractor, by default False.
tuning_layers (list, optional) – ConvNet layers to be fine-tuned in training, by default [‘last_linear’].
resume (str, optional) – Path of a training checkpoint, by default None.

Returns

A torch model.

Return type

torch.nn.Module

XAI.utils.plot_helpers module¶

XAI.utils.plot_helpers.find_vmin_vmax(arr)[source]¶

This is a helper function used in plotting Grad-CAM results (plot_gradcam()). It finds the suitable vmin and vmax values to be used in matplotlib’s imshow() for a given Grad-CAM attribution map.

Parameters

arr (numpy.ndarray) – The Grad-CAM attribution map to find the vmin and vmax values for.

Returns

vmin (float) – The vmin value to be used in imshow() plotting.
vmax (float) – The vmax value to be used in imshow() plotting.
(max_val, max_val_abs, min_val, min_val_abs) (tuple of floats) – max_val is the maximum value of the Grad-CAM attribution map. max_val_abs is the absolute of max_val. min_val is the minimum value of the Grad-CAM attribution map. min_val_abs is the absolute of min_val.

These values are intermediate values used to compute vmin and vmax. When not useful to the user, the user can do the following: vmin, vmax, _ = find_vmin_vmax(arr)

XAI.utils.plot_helpers.fnf_plot(do_gradcam_series)[source]¶

This function plots a (nrows=1, ncols=3) image that contains the following:

Original image
Grad-CAM attribution map
Grad-CAM attribution map (overlay)

Parameters: do_gradcam_series (pandas.core.series.Series) – A row from the results_df dataframe that was outputted from the FSGradCam.do_gradcam() function.
Returns
Return type: fig

XAI.utils.plot_helpers.fs_plot(do_gradcam_series)[source]¶

This function plots a (nrows=2, ncols=5) figure for each image in the do_gradcam() output dictionary. Each figure that contains the following:

Row 1 (from left to right)

Original image

Grad-CAM attribution map from model 1

Grad-CAM attribution map from model 2

Grad-CAM attribution map from model 3

Grad-CAM attribution map (average)

Row 2 (from left to right)

Intentional blank

Grad-CAM map from model 1 (overlay with original image)

Grad-CAM map from model 2 (overlay with original image)

Grad-CAM map from model 3 (overlay with original image)

Grad-CAM map (average) (overlay with original image)

Parameters: do_gradcam_series (pandas.core.series.Series) – A row from the results_df dataframe that was outputted from the FSGradCam.do_gradcam() function.
Returns
Return type: fig

XAI.utils.plot_helpers.make_green_transparent_red()[source]¶

Creates the custom colourmap used in plot_gradcam() functions. The colour ranges from red (negative) to tranparent (zero) to green (positive). The transparent colour for zero values is important when plotting Grad-CAM attribution map overlaid onto an image.

Parameters: N/A –
Returns: g_t_r – The custom colourmap.
Return type: matplotlib colormap

XAI.utils.plot_helpers.make_red_transparent_blue()[source]¶

Creates the custom colourmap used in plot_gradcam() functions. The colour ranges from blue (negative) to tranparent (zero) to red (positive). The transparent colour for zero values is important when plotting Grad-CAM attribution map overlaid onto an image.

Parameters: N/A –
Returns: r_t_b – The custom colourmap.
Return type: matplotlib colormap

XAI.utils.report_generation module¶

XAI.utils.report_generation.delete_slide(prs, slide)[source]¶

Custom helper function to delete a single slide from Presentation object WITHOUT deleting the slide layout that is attached to that slide.

To use this function, do the following:

delete_slide(prs=prs, slide=prs.slides[i])
# Where `i` is the index of the slide to delete.

# To loop and delete slides:
for slide in my_prs.slides:
    delete_slide(prs=my_prs, slide=slide)

prs{pptx.presentation.Presentation}: The presentation to delete the slide from.
slide{pptx.slide.Slide}: The slide to delete.

XAI.utils.report_generation.generate_pptx(fnf_or_fs, gradcam_csv_path, pptx_template_path, output_folder)[source]¶

This is the helper function that generates the PowerPoint report for the Grad-CAM results.

Parameters

fnf_of_fs (str) – Either "fnf" or "fs". If the user is trying to generate a report for Food-Non-Food Grad-CAM results, then "fnf". Else if the user is trying to generate a report for Food Scoring Grad-CAM results, then "fs".
gradcam_csv_path (str or Path) – The path to the gradcam_metadata.csv outputed from the FNFGradCam.do_gradcam() and FSGradCam.do_gradcam() functions.
pptx_template_path (str or Path) – The path to the PowerPoint template that is used to generate the report. This is a .pptx file.
output_folder (str or Path) – The path to the folder to save the generated PowerPoint report in. E.g. "./save/to/this/folder/". Refer to the Notes for an elaboration of the output folder structure.
Results –
------- –
None. –

Notes

The PowerPoint XAI report will be saved in the following folder structure.

# For FNF report.
output_folder/
    └── powerpoint_report/
        └── GradCAM_Results_FNF.pptx

# For FS report.
output_folder/
    └── powerpoint_report/
        └── GradCAM_Results_FS.pptx

If the output_folder specified is the same as the output_folder in do_gradcam() and/or plot_gradcam() functions, then the resulting folder structure will be:

output_folder/
    ├── gradcam_metadata.csv
    ├── gradcam_numpy_arrays/
    │   ├── image_id_1.npy
    │   ├── image_id_2.npy
    │   ├── ...
    │   └── image_id_N.npy
    ├── gradcam_plots/
    │   ├── image_id_1.png
    │   ├── image_id_2.png
    │   ├── ...
    │   └── image_id_N.png
    └── powerpoint_report/ <--- Additional folder for PPTX report.
        └── GradCAM_Results_<FNF_or_FS>.pptx

XAI.utils.report_generation.insert_gradcam_explanation(slide, text_placeholder_index)[source]¶: [summary]

XAI.utils.report_generation.insert_resized_picture(slide, picture_placeholder_index, picture_path)[source]¶

This function inserts a picture in a PicturePlaceholder and automatically resizes the picture to fit the PicturePlaceholder (while keeping its aspect ratio). The picture will also be arranged and placed in the horizontal center and vertical center of the PicturePlaceholder.

Parameters

slide (pptx.slide.Slide) – The slide that contains the PicturePlaceholder.
picture_placeholder_index (int) – The index of the PicturePlaceholder. The PicturePlaceholder is a pptx.shapes.placeholder.PicturePlaceholder object. Refer to the Notes section to learn how to find this index.
picture_path (str or Path) – The path to the picture to be inserted into the PicturePlaceholder.

Returns

Return type

None

Notes

To find the index of the PicturePlaceholder object, run the following code:

for shape in slide.placeholders:
    print('%d %s' % (shape.placeholder_format.idx, shape.name))

XAI.utils.report_generation.insert_text_metadata(slide, text_placeholder_index, text_metadata_list)[source]¶: [summary]

Module contents¶

This paragraph describes the contents for the XAI.utils subpackage.

The XAI.utils package has the following structure:

utils (subpackage)
├── datasets.py (module)
├── inception_resnet_v2.py (module)
├── load_model_worker.py (module)
└── plot_helpers.py (module)

The 4 modules in this XAI.utils package (shown above) are utility modules. i.e. Users of the XAI library will not directly interact with these modules, but these modules are called and used within the library .