Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/HazyResearch/ukb-cardiac-mri
Weakly Supervised MRI Series Classification for the UK Biobank
https://github.com/HazyResearch/ukb-cardiac-mri
Last synced: 2 days ago
JSON representation
Weakly Supervised MRI Series Classification for the UK Biobank
- Host: GitHub
- URL: https://github.com/HazyResearch/ukb-cardiac-mri
- Owner: HazyResearch
- License: apache-2.0
- Created: 2018-05-24T22:33:54.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2019-09-13T20:34:06.000Z (about 5 years ago)
- Last Synced: 2024-08-02T16:45:57.285Z (3 months ago)
- Language: Python
- Size: 9.79 MB
- Stars: 23
- Watchers: 19
- Forks: 11
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-uk-biobank - ukb-cardiac-mri
README
# Weakly supervised classification of aortic valve malformations using unlabeled cardiac MRI sequences
[](https://zenodo.org/badge/latestdoi/134775347)
This is the code release for our paper in Nature Communications.
https://www.nature.com/articles/s41467-019-11012-3
## Content
* Overview
* Repo Content
* System Requirements
* Installation Guide
* How to Use
## Overview
Bicuspid Aortic Valve (BAV) is the most common congenital malformation of the heart, occurring in 0.5-2% of the general population. We developed a weakly supervised deep learning model for BAV classification using up to 4,000 unlabeled cardiac MRI sequences.
## Repo Content
* *notebooks/* - Weak supervision notebooks.
* *scripts/* - Launch scripts for Supervised model, Weakly-supervised model and Expert-Weakly supervised model
* *ukb/* - the python code and config files needed for training the various models.
* *data.zip* - data provided to run our pipeline (this is all synthetic data, no real patient data was used)
## I. System Requirements
### Hardware Requirements
Weakly supervised MRI classification needs a computer with the following minimum specs:
* CPU : A cores, B Ghz/core
* GPU : CUDA is compatible with almost all NVidia models from 2006, but a minimum of gtx 1050ti, 1060 and above are required.
* RAM : A minimum of 16 GB RAM is required.
All of our runtime estimates are generated from a computer with the following specs:
* CPU : Intel(R) Xeon(R) CPU E5-2690 v4 @ 2.60GHz. 56 CPUs in total.
* GPU : NVidia Tesla P100-PCIE-16GB
* RAM : 503 GB.
### Software Requirements
#### OS Requirements
This package is supported for *Linux* operating systems and has been tested on the following system:
* Linux - GPU/CPU
* Mac OSX - CPU only
Before installing the package, be sure to have the following software installed on your system:
* Python 3.6.4
* Several python packages which can be installed via ```pip``` (see below)
#### Installing Anaconda Distribution of Python
Download the Anaconda installer and install in terminal, detailed instructions can be found in:
```
https://conda.io/docs/user-guide/install/linux.html
```
#### Setting Up a conda Environment
If you plan on creating a standalone environment (conda or virtualenv) please take note of the following. Since matplotlib is imported a lot, we suggest creating a conda environment (as you can install a framework build of python easily and use the package) rather than a virtualenv (which as of this writing installs a non-framework version of python and causes a lot of scripts to crash).
```
conda create -n myEnv python=3.6.4 pip
```
Once you have successfully created your conda environment, be sure to activate it:
```
source activate myEnv
```
Now that your environment is active run the following commands to install all requirements:
* Make Python in the environment a framework build:
```
conda install python.app
```
#### Installing Python package dependencies
To ensure that all python package dependacies are installed, run the following command:
```
pip install -r requirements.txt --find-links=http://download.pytorch.org/whl/torch-0.3.1-cp27-none-macosx_10_6_x86_64.whl --trusted-host download.pytorch.org
```
Package List:
```
backports.functools-lru-cache==1.5
certifi==2018.1.18
cffi==1.11.5
chardet==3.0.4
cycler==0.10.0
decorator==4.2.1
dominate==2.3.1
idna==2.7
imageio==2.3.0
kiwisolver==1.0.1
matplotlib==2.2.0
networkx==2.1
numpy==1.14.2
opencv-contrib-python-headless==3.4.3.18
pandas==0.22.0
Pillow==5.0.0
pycparser==2.18
pyparsing==2.2.0
python-dateutil==2.7.0
pytz==2018.3
PyWavelets==0.5.2
PyYAML==3.12
requests==2.19.1
scikit-image==0.13.1
scikit-learn==0.19.1
scipy==1.0.0
seaborn==0.8.1
six==1.11.0
tabulate==0.8.2
torch==0.4.0
torchvision==0.2.0
urllib3==1.23
```
## II. Installation Guide
To install this package, clone our repo on your system.
Once it has been downloaded, be sure to run the following command:
```
unzip data.zip
```
so that you may utilize our provided data.
## III. How to Use
We have provided various scripts to run our model. These scripts are located in the *scripts/* directory. To execute our example script run the following command:
```
./scripts/Supervised.sh
```
This will launch 5 different jobs taking about 7 GB of GPU memory. In addition, this entire run will take roughly 3.5 hrs. The expected output is (located in Experiments/out/seed_x.out, e.g. Supervised/out/seed_0.out):
```
========================================
Scores
========================================
Pos. class accuracy: 75.0
Neg. class accuracy: 96.2
----------------------------------------
AUC: 96.9
PRC: 48.8
NDCG: 78.4
----------------------------------------
Precision: 42.9
Recall: 75.0
F1: 54.5
----------------------------------------
TP: 6 | FP: 8 | TN: 200 | FN: 2
========================================
```
After all 5 different jobs are finished, another script is provided for generating predictions on the example DEV/TEST set, and collecting the ensemble of TEST results. To execute the script, simply run the following command:
```
./scripts/predict_Supervised.sh
```
The generated predictions will be located in Experiments/predictions, e.g. Supervised/predictions. And the collected results ensemble would be in Experiments/predictions/results_test/ensemble, e.g. Supervised/predictions/results_test/ensemble. The terminal output would look like this:
```
Experiment SEED_0 SEED_14 SEED_57 SEED_123 SEED_1234 AVERAGE STD MEDIAN MV
0 Pos.Acc 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00
1 Neg.Acc 93.10 94.25 89.66 91.95 96.55 93.10 2.30 98.85 94.25
2 Precision 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00
3 Recall 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00
4 F1 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00
5 ROC 80.46 76.25 60.54 65.90 63.98 69.43 7.61 72.80 42.53
6 PRC 7.50 7.30 3.95 4.56 5.22 5.70 1.44 5.42 1.67
7 NDCG 33.73 33.60 27.05 28.06 31.94 30.88 2.80 30.72 26.98
8 TP 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00
9 FP 6.00 5.00 9.00 7.00 3.00 6.00 2.00 1.00 5.00
10 TN 81.00 82.00 78.00 80.00 84.00 81.00 2.00 86.00 82.00
11 FN 3.00 3.00 3.00 3.00 3.00 3.00 0.00 3.00 3.00
```