MiMICRI: Towards Domain-centered Counterfactual Explanations of Cardiovascular Image Classification Models
This repository is a demonstration of the MiMICRI approach proposed in the ACM FAccT 2024 paper titled:
MiMICRI: Towards Domain-centered Counterfactual Explanations of Cardiovascular Image Classification Models
mimicri is a python library of interactive visualizations for segmentation-based counterfactual generation, designed to work with the JupyterLab computational environment.
@inproceedings{guo2024towards,
title={MiMICRI: Towards Domain-centered Counterfactual Explanations of Cardiovascular Image Classification Models},
author={Guo, Grace and Deng, Lifu and Tandon, Animesh and Endert, Alex and Kwon, Bum Chul},
booktitle={Proceedings of the 2024 FAccT Conference on Fairness, Accountability, and Transparency},
pages={1--14},
year={2024}
}
The MiMICRI system requires images to first be pre-processed using semantic segmentation.
The demo uses the ukbb_cardiac toolbox to segment cardiac MRI images from the UK Biobank.
We have pre-downloaded and segmented two cardiac MRIs from the ukbb_cardiac toolbox.
They are included in the notebooks/demo_image folder.
We also include a notebook (notebooks/plot_segmentation.ipynb) to view the segmentations.
The demo only includes a small subset of images. If you would like to use the full UK Biobank dataset, you must register for an account and obtain the necessary approvals.
Note that other types of medical images and segmentation methods, including manual segmentation, may be used.
Create a clean conda environment with the exact versions of the following packages:
conda create -n mimicri python=3.8 jupyterlab=3.4 ipywidgets=7.6 ipykernel=5.3
conda activate mimicri
Clone the repo locally:
git clone https://{YOUR_GITHUB_TOKEN}@github.com/IBM/mimicri.git
Navigate to your local cloned mimicri folder and install dependencies.
A recent circular dependency error in the torch module requires a new installation of the libraries needed to run MiMICRI. If this is your first time installing MiMICRI use:
conda install pytorch torchvision -c pytorch
pip install -r requirements.txt
pip install mimicri
If you have installed MiMICRI before, please first uninstall all existing installations of torch and torchvision:
pip uninstall torch
pip uninstall torchvision
conda uninstall torch
conda uninstall torchvision
Then run:
conda install pytorch torchvision -c pytorch
pip install -r requirements.txt
pip install mimicri
Once the dependencies have been installed correctly, the MiMICRI package should show up with:
jupyter labextension list
Use this installation only if you are making changes to the MiMICRI widget. If you are using MiMICRI as-is, the regular install (above) will be sufficient.
Create a clean conda environment with the exact versions of the following packages:
conda create -n mimicri python=3.8 jupyterlab=3.4 ipywidgets=7.6 ipykernel=5.3
conda activate mimicri
Clone the repo locally:
git clone https://{YOUR_GITHUB_TOKEN}@github.com/IBM/mimicri.git
Navigate to your local cloned mimicri folder and install other dependencies: pip install -r requirements.txt.
Ensure that the yarn package manager has been installed.
If you have npm, you can do this using: npm install --global yarn
Finally, install the local mimicri package with sh ./setup.sh
The package should show up when you run:
jupyter labextension list
After making updates to the widget, your changes will be reflected by running sh ./update.sh
We provide the notebook (notebooks/mimicri_demo.ipynb) to demonstrate usage of the MiMICRI modules end-to-end.
To protect the privacy of patients' healthcare data, we are unable to provide any UK BioBank patient demographic data. We also exclude any original UK BioBank files in this code repository. We have included two cardiac MRIs and segmentation files from the ukbb_cardiac toolbox. You may also provide your own cardiac MRIs and segmentation files if you would like to use a larger data set.