This paper documents how to install/run CLEAR Image in order to reproduce1 the results in the paper `Contrastive Counterfactual Visual Explanations With Overdetermination’. Please note that CLEAR Image requires the user to have previously trained a GAN to generate contrast images. A new version of CLEAR Image has subsequently been developed specifically for Brain MRI scans. The new version uses a brain atlas (e.g. Brainnetome) to segment MRI’s into regions of interest. It also chooses a contrast image from ‘nearby’ MRIs rather than requiring a GAN generated image. Please contact Dr Adam White at adam.white.3@city.ac.uk for further details.
CLEAR Image is written in Python 3.7.9 and runs on Windows 10. The paper has two case studies, the first using a synthetic dataset, the second using CheXpert. The classifiers for the synthetic dataset were trained using PyTorch 1.8.1, whereas PyTorch 1.51 was used for the CheXpert dataset. The corresponding yml files are: synthetic.yml and medical_images.yml.
The file CLEAR_settings.py contains the parameter variables for CLEAR Image. Open CLEAR_settings.py and change the value of parameter CLEAR_path to the name of the directory you have created for CLEAR e.g., CLEAR_path='D:/CLEAR/'. CLEAR Image requires the user to have created both a directory containing the original image files and another directory containing the corresponding GAN images. The addresses of these two directories should be assigned in CLEAR_settings to the parameters: ‘input_images_path’ and ‘GAN_images_path’ e.g., ‘input_images_path’ = ‘D:/Diseased_Xrays/’. In order to get the original images for CheXpert, the CheXpert dataset will need to be downloaded: https://stanfordmlgroup.github.io/competitions/chexpert/ . The GAN generated images generated from CheXpert are in folder ‘CheXpert GAN’. The file ‘Medical.csv' lists the images that were used in our paper. ‘Synthetic Images .csv’ lists the synthetic images used, these are included in the folder ‘Synthetic test images’, the corresponding GAN images are in the folder ‘GAN Synthetic data’.
Running CLEAR.py will process all the images listed in ‘Medical.csv' for CheXpert or ‘Synthetic Images.csv’ for the synthetic dataset. CLEAR will generate a HTML report explaining a single prediction if only one image is listed in the csv file. The report is entitled ‘CLEAR_Image_report_full.html'. It is expected that CLEAR Image will normally be run for single images (rather than batches of images). For each image listed in the csv file, a png file and a csv file of CLEAR’s corresponding saliency map is generated; they are saved to the directory specified by CLEAR_path, and should be transferred to a results folder that the user has created. Two detailed Excel spreadsheets are also created each time that CLEAR Image is run. ‘Fidelity.xlsx’ contains data for each counterfactual that CLEAR Image identifies. ‘Results_Xrays.xlsx’ contains regression data for each image, column L can be used to calculate the number of images that were classified as ‘causally overdetermined’. It is not expected that a user would normally access either of these spreadsheets.
Generating Pointing Game Scores The pointing game scripts score the saliency maps created by CLEAR Image, Captum library’s version of Grad-CAM https://captum.ai/api/layer.html#gradcam, TorchRay’s Extremal https://facebookresearch.github.io/TorchRay/ and LIME https://github.com/marcotcr/lime. Each of these packages needs to be installed. The saliency maps for LIME can be generated by running ‘Lime saliency maps for pointing game.py’. As this is not part of CLEAR Image, the following parameters need to be entered in lines 9 to 12 of the script: model_path, results_path and original_images_path, model_type. The first 3 specify file directories, model_type should be ‘VGG’ or ‘Densenet’. The kernel_size that LIME uses in its segmentation algorithm also needs to be set to 4 for the CheXpert dataset and 20 for the synthetic dataset, and this is set in line 180 of the LIME script on GitHub ‘lime_image.py’ (correct as at 9/9/21). The saliency maps for Grad-CAM, Extremal are generated when running the pointing game scripts: CLEAR_Synthetic_Pointing_Scores.py and CLEAR_Medical_Pointing_Scores.py which calculate the average pointing game scores for each XAI method and also provide a pdf file of all the saliency maps with their individual scores. These scripts require the following parameters which specify the paths for the classifiers and their saliency maps: model_path, original_images_path, GAN_images_path, GradCAM_Densenet_path, GradCAM_VGG_path, Extremal_Densenet_path, Extremal_VGG_path, CLEAR_Densenet_path, CLEAR_VGG_path, LIME_Densenet_path, LIME_VGG_path, model_type. .
The Synthetic Dataset is generated by running ‘Synthetic Data.py’. This requires the following parameters which specify the paths for the synthetic data and for a pickle file (synthetic_pointing_df.pkl) which stores the locations of the ‘pathological’ shapes that are detected by the pointing game: model_path, heathy_images_path, IoU_images_path, diseased_images_path.
The Intersection over Union (IOU) score is based on the calculation of the proportion of intersection between the annotated ground truth against the saliency maps for each XAI models over the union of the area covered by the two segmental regions. Two scripts are provided (i.e. iou_syndata.py and iou_chexpert.py) for each dataset respectively. These scripts require the following parameters which specify the paths for the classifiers and their saliency maps: model_path, original_images_path, GAN_images_path, GradCAM_Densenet_path, GradCAM_VGG_path, Extremal_Densenet_path, Extremal_VGG_path, CLEAR_Densenet_path, CLEAR_VGG_path, LIME_Densenet_path, LIME_VGG_path, mdl, mtd. mdl is classifier model type ('Densenet' or 'VGG') and mtd is the explainable method with: 0 - CLEAR Image, 1- Grad-CAM, 2- Extremal and 3-LIME. The scripts output the average IOU score for the evaluated set of test images and the option to save a csv file of the per-image IOU score. *Note: Original diseased images are omitted in this distribution. Please seek approval from the original authors for CheXpert: (https://stanfordmlgroup.github.io/competitions/chexpert/).
The model weights for the trained models (Densenet, VGG16 and GANs) all exceed the file size limit for the code/data appendix (100MB). Please contact the original authors if required.