XAI.gradcam package

Submodules

XAI.gradcam.gradcam module

class XAI.gradcam.gradcam.FNFGradCam(model, target_layer_name)[source]

Bases: object

This class contains a function that performs Grad-CAM for the Food-Non-Food (FNF) model and a function that plots and saves the Grad-CAM results. The Grad-CAM is computed using the captum library.

Parameters

  • model (torch model object) – The black-box model to be explained. The weights have to already be loaded into the model.

  • target_layer (torch model layer object) – The convolutional layer that is to be used for Grad-CAM computation. For example, model.conv2d_7b.

  • target_layer_name (str) – The name of the target_layer. For example, if the target layer is model.conv2d_7b, then the name should be "conv2d_7b". This name is used solely for metadata purposes and plotting purposes in the plot_gradcam() function. While the user can set the name to whatever s/he likes, it is recommended that the user sets this to the actual name of the layer for consistency, as shown in the example.

do_gradcam(image_dataset, output_folder, batch_size=10, relu_attributions=False, return_metadata=True, plot_gradcam=True)[source]

Each call to this function performs Grad-CAM on a dataset of images for the given black-box model.

Parameters

  • image_dataset (FSImageDataset object) – The FSImageDataset object containing the images in a given directory.

  • output_folder (str or Path) – The path to the directory to save the Grad-CAM outputs to. A folder structure will be created in this output_folder, which is elaborated in the Notes section.

  • batch_size (int, default=10) – The batch size to split the image_dataset into.

  • relu_attributions (boolean, default=False) – Indicates whether to apply a ReLU operation on the final attribution, returning only non-negative attributions. Setting this flag to True matches the original GradCAM algorithm, otherwise, by default, both positive and negative attributions are returned.

  • return_metadata (boolean, default=True) – If True, this function will return the metadata (listed in the Returns section of this docstring) corresponding to the input image along with the Grad-CAM attribution maps. If False, this function will only return the Grad-CAM attribution maps and a np.nan inplace of each metadata.

  • plot_gradcam (boolean, default=True) – If True, the plot_gradcam() function will be called and a “gradcam_plots” folder will be created in output_dir where all the plots are saved. Refer to Notes section for more details.

Returns

results_df – A dataframe containing the metadata about the Grad-CAM results for all the images that Grad-CAM was performed on. The structure of this dataframe can be found in the Notes section.

Return type

pd.DataFrame

Notes

Here is the breakdown of results_df. pred_proba_0 and pred_proba_1 are metadata. i.e. if return_metadata=False, these columns would be np.nan values.

Columns in results_df:
----------------------
[0] id: Image id or filename
[1] target_layer: Name of target layer that was used to perform the Grad-CAM
[2] label_fnf: The ground truth label of the image
[3] path_fns: The path to the original image
[4] path_gradcam: The path to the .npy file that contains the Grad-CAM arrays
[5] path_gradcam_plot: The path to the .png plot of the Grad-CAM arrays
--- metadata columns below ---
[5] pred_proba_0: The model's predicted probability for class 0 (non-food)
[6] pred_proba_1: The model's predicted probability for class 1 (food)

Note: If ``return_metadata=False``, all metadata columns will be ``np.nan``.

The output_folder will have the following structure.

output_folder/
├── gradcam_numpy_arrays/
│   ├── image_id_1.npy
│   ├── image_id_2.npy
│   ├── ...
│   └── image_id_N.npy
└── gradcam_metadata.csv

If plot_gradcam=True, the output_folder will have the following structure:

output_folder/
├── gradcam_metadata.csv
├── gradcam_numpy_arrays/
│   ├── image_id_1.npy
│   ├── image_id_2.npy
│   ├── ...
│   └── image_id_N.npy
└── gradcam_plots/ <----- Additional folder with plots.
    ├── image_id_1.png
    ├── image_id_2.png
    ├── ...
    └── image_id_N.png
plot_gradcam(do_gradcam_df, savefig_dir=None, savefig=False, plt_show=True, save_csv=True)[source]

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

  1. Original image

  2. Grad-CAM attribution map

  3. Grad-CAM attribution map (overlay onto original image)

Parameters

  • do_gradcam_df (pandas.DataFrame) – The dataframe returned from the FNFGradCam.do_gradcam() function.

  • savefig_dir (str or Path, default=None) – The path to the folder that the plotted figures should be saved to. This should be the same as the output_folder specified in the do_gradcam() function. Refer to the Notes section for details on the folder structure that will be created.

  • savefig (boolean, default=False) – If True, saves the plotted image to the path specified in savefig_dir. If False, the plotted image will not be saved, even if savefig_dir is specified.

  • plt_show (boolean, default=True) – If True, the plotted image will be displayed using plt.show(). If False, the plotted image will not be displayed.

  • save_csv (boolean, default=True) – If True, saves the do_gradcam_df dataframe as “gradcam_metadata.csv” in savefig_dir.

Returns

do_gradcam_df – The dataframe with the path_gradcam_plot column populated.

Return type

pandas.DataFrame

Notes

The folder structure that will be created in savefig_dir is as follows:

savefig_dir/
└── gradcam_plots/
    ├── image_id_1.png
    ├── image_id_2.png
    ├── ...
    └── image_id_N.png

If savefig_dir is the same directory as output_folder in the do_gradcam() function, then the folder structure will be as follows:

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
class XAI.gradcam.gradcam.FSGradCam(model_1, model_2, model_3, target_layer_name)[source]

Bases: object

This class contains a function that performs Grad-CAM for the Food Scoring (FS) model and a function that plots and saves the Grad-CAM results. The Grad-CAM is computed using the captum library.

Specifically, the FS model is an ensemble (average, in this case) of 3 models. In this class, we call these models model_1, model_2 and model_3.

Parameters

  • model_1 (torch model object) – The black-box model to be explained. The weights have to already be loaded into the model. The same goes for model_2 and model_3.

  • target_layer_1 (torch model layer object) – The convolutional layer that is to be used for Grad-CAM computation. For example, model.conv2d_7b.

  • target_layer_name (str) – The name of the target_layer_X. For example, if the target layer is model.conv2d_7b, then the name should be "conv2d_7b". This name is used solely for metadata purposes and plotting purposes in the plot_gradcam() function. While the user can set the name to whatever s/he likes, it is recommended that the user sets this to the actual name of the layer for consistency, as shown in the example.

device

An object representing the device on which a torch.Tensor / model is or will be allocated.

Type

torch.device

target_layer_name

The name of the layer to be used when computing Grad-CAM.

Type

str

models_list

A list containing the 3 Food Scoring models. Each model is set to .eval() mode and the device is set to the device attribute of this class.

Type

list of torch models

do_gradcam(image_dataset, output_folder, batch_size=10, relu_attributions=False, return_metadata=True, plot_gradcam=True)[source]

Each call to this function performs Grad-CAM on a dataset of images for the given black-box model.

Parameters

  • image_dataset (FSImageDataset object) – The FSImageDataset object containing the images in a given directory.

  • output_folder (str or Path) – The path to the directory to save the Grad-CAM outputs to. A folder structure will be created in this output_folder, which is elaborated in the Notes section.

  • batch_size (int, default=10) – The batch size to split the image_dataset into.

  • relu_attributions (boolean, default=False) – Indicates whether to apply a ReLU operation on the final attribution, returning only non-negative attributions. Setting this flag to True matches the original GradCAM algorithm, otherwise, by default, both positive and negative attributions are returned.

  • return_metadata (boolean, default=True) – If True, this function will return the metadata (listed in the Returns section of this docstring) corresponding to the input image along with the Grad-CAM attribution maps. If False, this function will only return the 4 Grad-CAM attribution maps and a np.nan inplace of each metadata.

  • plot_gradcam (boolean, default=True) – If True, the plot_gradcam() function will be called and a “gradcam_plots” folder will be created in output_dir where all the plots are saved. Refer to Notes section for more details.

Returns

results_df – A dataframe containing the metadata about the Grad-CAM results for all the images that Grad-CAM was performed on. The structure of this dataframe can be found in the Notes section.

Return type

pd.DataFrame

Notes

Here is the breakdown of the list of columns of results_df.

Columns in results_df:
----------------------

[0] id: Image id or filename
[1] target_layer: Name of target layer that was used to perform the Grad-CAM
[2] food_score: The ground truth label of the image
[3] path_fns: The path to the original image
[4] path_gradcam: The path to the .npy file that contains the Grad-CAM arrays
[5] path_gradcam_plot: The path to the .png plot of the Grad-CAM arrays
--- metadata columns below ---
[6] m1_pred_raw: Model_1's predicted food score (RAW)
[7] m1_pred_clip: Model_1's predicted food score (CLIPPED)
[8] m1_diff_raw: Model_1's predicted food score (RAW) - ground truth label
[9] m1_diff_clip: Model_1's predicted food score (CLIPPED) - ground truth label
[10] m2_pred_raw: Model_2's predicted food score (RAW)
[11] m2_pred_clip: Model_2's predicted food score (CLIPPED)
[12] m2_diff_raw: Model_2's predicted food score (RAW) - ground truth label
[13] m2_diff_clip: Model_2's predicted food score (CLIPPED) - ground truth label
[14] m3_pred_raw: Model_3's predicted food score (RAW)
[15] m3_pred_clip: Model_3's predicted food score (CLIPPED)
[16] m3_diff_raw: Model_3's predicted food score (RAW) - ground truth label
[17] m3_diff_clip:Model_3's predicted food score (CLIPPED) - ground truth label
[18] avg_pred_raw: Average predicted food score (RAW)
[19] avg_pred_clip: Average predicted food score (CLIPPED)
[20] avg_diff_raw: Average predicted food score (RAW) - ground truth label
[21] avg_diff_clip: Average predicted food score (CLIPPED) - ground truth label

Note: If ``return_metadata=False``, all metadata columns will be ``np.nan``.

The output_folder will have the following structure.

output_folder/
├── gradcam_numpy_arrays/
│   ├── image_id_1.npy
│   ├── image_id_2.npy
│   ├── ...
│   └── image_id_N.npy
└── gradcam_metadata.csv

The numpy arrays saved in the .npy files will have the shape [4, 299, 299, 1], where each [299, 299, 1] array are the following:

  • [0, 299, 299, 1] Grad-CAM array from Model 1

  • [1, 299, 299, 1] Grad-CAM array from Model 2

  • [2, 299, 299, 1] Grad-CAM array from Model 3

  • [3, 299, 299, 1] Average of the 3 Grad-CAM arrays

If plot_gradcam=True, the output_folder will have the following structure:

output_folder/
├── gradcam_metadata.csv
├── gradcam_numpy_arrays/
│   ├── image_id_1.npy
│   ├── image_id_2.npy
│   ├── ...
│   └── image_id_N.npy
└── gradcam_plots/ <----- Additional folder with plots.
    ├── image_id_1.png
    ├── image_id_2.png
    ├── ...
    └── image_id_N.png
plot_gradcam(do_gradcam_df, savefig_dir=None, savefig=False, plt_show=True, save_csv=True)[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:

  1. Row 1 (from left to right)

    1. Original image

    2. Grad-CAM attribution map from model 1

    3. Grad-CAM attribution map from model 2

    4. Grad-CAM attribution map from model 3

    5. Grad-CAM attribution map (average)

  2. Row 2 (from left to right)

    1. Intentional blank

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

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

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

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

Parameters

  • do_gradcam_df (pandas.DataFrame) – The dataframe returned from the FNFGradCam.do_gradcam() function.

  • savefig_dir (str or Path, default=None) – The path to the folder that the plotted figures should be saved to. This should be the same as the output_folder specified in the do_gradcam() function. Refer to the notes section for details on the folder structure that will be created.

  • savefig (boolean, default=False) – If True, saves the plotted image to the path specified in savefig_dir. If False, the plotted image will not be saved, even if savefig_dir is specified.

  • plt_show (boolean, default=True) – If True, the plotted image will be displayed using plt.show(). If False, the plotted image will not be displayed.

  • save_csv (boolean, default=True) – If True, saves the do_gradcam_df dataframe as “gradcam_metadata.csv” in savefig_dir.

Returns

do_gradcam_df – The dataframe with the path_gradcam_plot column populated.

Return type

pandas.DataFrame

Notes

The folder structure that will be created in savefig_dir is as follows:

savefig_dir/
└── gradcam_plots/
    ├── image_id_1.png
    ├── image_id_2.png
    ├── ...
    └── image_id_N.png

If savefig_dir is the same directory as output_folder in the do_gradcam() function, then the folder structure will be as follows:

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

Module contents

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

The XAI.gradcam package has the following structure:

gradcam (subpackage)
└── gradcam.py (module)

The XAI.gradcam.gradcam module is the main driver of the Grad-CAM capabilities of the XAI library. There are two main classes in the XAI.gradcam.gradcam module, namely FSGradCAM and FNFGradCAM. They are used to perform Grad-CAM on the Food Scoring (FS) and Food-Non-Food (FNF) models respectively.