MRNet XAI

Explainable deep learning for knee MRI classification on the MRNet dataset (CAM + SHAP) with an interactive viewer.
Train → generate explanations → inspect axial/coronal/sagittal slices side-by-side.

MRNet Dataset » · Report Bug · Request Feature

About The Project

This repository contains scripts to train MRNet-style models and generate explainability artifacts (CAM/SHAP) for knee MRI exams. MRNet is a knee MRI dataset/competition with 1,370 exams from Stanford University Medical Center.

Key Features

• Training scripts for MRNet-style classification workflows (train_mrnet.py, train_classifier.py).
• Generate CAM visualizations (create_cams.py).
• Generate SHAP visualizations (create_shaps.py).
• Interactive OpenCV-based viewer that shows CAM / raw slice / SHAP for axial, coronal, sagittal planes (vis_predictions.py).
• Notebook included for experimentation (MRNet_v1_0.ipynb).

Built With

• PyTorch + TorchVision.
• OpenCV, NumPy, Pandas, Matplotlib.
• SHAP.

Getting Started

Prerequisites

• Python environment (venv/conda recommended).
• MRNet dataset access (see Dataset section).

Installation

1. Clone:

   git clone https://github.com/KaMeLoTmArMoT/mrnet_xai.git
   cd mrnet_xai

2. Install dependencies:

   pip install -r requirements.txt

   Note: requirements include a Git dependency (torchsample).

Dataset

• MRNet is distributed under a research-use agreement; the download link and dataset must not be redistributed.
• Official info + registration: https://stanfordmlgroup.github.io/competitions/mrnet/

Usage

1) Train a model

Start with the training scripts:

• train_mrnet.py
• train_classifier.py

2) Generate explanations

Use:

• create_cams.py for CAM outputs.
• create_shaps.py for SHAP outputs.

3) View predictions + explanations

Run the viewer:

• vis_predictions.py

Viewer key bindings (current)

• Quit: q or Esc.
• Change slice index (per plane):
  • Decrease: 1 (axial), 2 (coronal), 3 (sagittal).
  • Increase: 7 (axial), 8 (coronal), 9 (sagittal).
• Change case:
  • Prev/next: 4 / 6.
  • Jump to case: Enter then type case id (in console).
• Switch SHAP source: v (if multiple sources exist).
• Zoom: + / -, reset with 0.

Examples

Contributing

Contributions are welcome:

1. Fork the repo
2. Create a feature branch
3. Open a PR

License