ct-net-models / Git / Diff of /README.md

Models:

SCallahan/

ct-net-models

Downloads: 2

Diff of /README.md [09c10e] .. [b43c69]

Switch to unified view






## Description

This repository contains Python code to train and evaluate convolutional neural network models (CNNs)
on the task of multiple abnormality prediction from whole chest CT volumes.
Our model CT-Net83 achieves state of the art performance on this task
and is described in detail in our [Medical Image Analysis paper](https://doi.org/10.1016/j.media.2020.101857).
The paper is also available [on arXiv](https://arxiv.org/ftp/arxiv/papers/2002/2002.04752.pdf).
The models are implemented in PyTorch.

On the RAD-ChestCT data set of 36,316 volumes
from 19,993 patients, CT-Net83 achieves a test set AUROC >0.90 for 18 abnormalities,
with an average AUROC of 0.773 across 83 abnormalities. 

If you find this work useful in your research, please consider citing us:

Draelos R.L., et al. "Machine-Learning-Based Multiple Abnormality Prediction with Large-Scale Chest Computed Tomography Volumes." *Medical Image Analysis* (2020).

## Requirements

The requirements are specified in *ctnet_environment.yml* and include
PyTorch, numpy, pandas, sklearn, scipy, and matplotlib.

To create the conda environment run:

`conda env create -f ctnet_environment.yml`

The code can also be run using the Singularity container defined [in this repository](https://github.com/rachellea/research-container).

## Usage

To run a demo of the CT-Net83, CT-Net9, BodyConv, 3DConv, and ablated CT-Net models on
fake data, run this command:

`python main.py`

The RAD-ChestCT data set [is publicly available on Zenodo](https://zenodo.org/record/6406114).

Because the real dataset is large, currently this repository includes fake data files to enable demonstrating
the code and the required data formats. The fake data is located in *load_dataset/fakedata*.
The fake CTs were generated as follows: 

```
fakect = np.random.randint(low=-1000,high=1000,size=(10,10,10))
np.savez_compressed('FAKE000.npz',ct=fakect)
```

Note that 10 x 10 x 10 is too small for a real CT scan; the CT scans
in the RAD-ChestCT data set are on the order of 450 x 450 x 450 pixels.

## Organization

* *main.py* contains the experiment configurations needed to replicate the
results in the paper. The command `python main.py` will run a demo of the
CT-Net83, CT-Net9, BodyConv, 3DConv, and ablated CT-Net models on
fake data.
* *run_experiment.py* contains code for training and evaluting the models.
* *evaluate.py* contains code for calculating, organizing, and plotting performance
metrics including AUROC and average precision.
* *unit_tests.py* contains some unit tests. These tests can be run via `python unit_tests.py`
* *load_dataset/custom_datasets.py* contains the PyTorch Dataset class for the CT data.
* *load_dataset/utils.py* contains the code for preparing individual CT volumes, including
padding, cropping, normalizing pixel values, and performing data augmentation through
random flips and rotations.
* *load_dataset/fakedata* contains the fake data necessary to run the demo.
* *models/custom_models_ctnet.py* contains the CT-Net model definition.
* *models/custom_models_alternative.py* contains two alternative architectures,
BodyConv and 3DConv.
* *models/custom_models_ablation.py* contains the ablated variants of CT-Net.

## Comment on Data Parallelism

Currently the experiments in *main.py* are set up to replicate the paper results.
Several of the experiments use data parallelism which assumes that at least
2 GPUs are available. If you wish to run the demo on one GPU, then change batch_size to 1
and set data_parallel to False.

### Logo

The logo includes two Creative Commons icons from the Noun Project: [lungs](https://thenounproject.com/search/?q=chest+x+ray&i=945146) and
[gear](https://thenounproject.com/search/?q=AI&i=3092014).

	a/README.md		b/README.md
1	# ct-net-models	1
2
3	![Logo](ct-net-models-logo-small.png)
4
5	## Description	2	## Description
6		3
7	This repository contains Python code to train and evaluate convolutional neural network models (CNNs)	4	This repository contains Python code to train and evaluate convolutional neural network models (CNNs)
8	on the task of multiple abnormality prediction from whole chest CT volumes.	5	on the task of multiple abnormality prediction from whole chest CT volumes.
9	Our model CT-Net83 achieves state of the art performance on this task	6	Our model CT-Net83 achieves state of the art performance on this task
10	and is described in detail in our [Medical Image Analysis paper](https://doi.org/10.1016/j.media.2020.101857).	7	and is described in detail in our [Medical Image Analysis paper](https://doi.org/10.1016/j.media.2020.101857).
11	The paper is also available [on arXiv](https://arxiv.org/ftp/arxiv/papers/2002/2002.04752.pdf).	8	The paper is also available [on arXiv](https://arxiv.org/ftp/arxiv/papers/2002/2002.04752.pdf).
12	The models are implemented in PyTorch.	9	The models are implemented in PyTorch.
13		10
14	On the RAD-ChestCT data set of 36,316 volumes	11	On the RAD-ChestCT data set of 36,316 volumes
15	from 19,993 patients, CT-Net83 achieves a test set AUROC >0.90 for 18 abnormalities,	12	from 19,993 patients, CT-Net83 achieves a test set AUROC >0.90 for 18 abnormalities,
16	with an average AUROC of 0.773 across 83 abnormalities.	13	with an average AUROC of 0.773 across 83 abnormalities.
17		14
18	If you find this work useful in your research, please consider citing us:	15	If you find this work useful in your research, please consider citing us:
19		16
20	Draelos R.L., et al. "Machine-Learning-Based Multiple Abnormality Prediction with Large-Scale Chest Computed Tomography Volumes." Medical Image Analysis (2020).	17	Draelos R.L., et al. "Machine-Learning-Based Multiple Abnormality Prediction with Large-Scale Chest Computed Tomography Volumes." Medical Image Analysis (2020).
21		18
22	## Requirements	19	## Requirements
23		20
24	The requirements are specified in ctnet_environment.yml and include	21	The requirements are specified in ctnet_environment.yml and include
25	PyTorch, numpy, pandas, sklearn, scipy, and matplotlib.	22	PyTorch, numpy, pandas, sklearn, scipy, and matplotlib.
26		23
27	To create the conda environment run:	24	To create the conda environment run:
28		25
29	`conda env create -f ctnet_environment.yml`	26	`conda env create -f ctnet_environment.yml`
30		27
31	The code can also be run using the Singularity container defined [in this repository](https://github.com/rachellea/research-container).	28	The code can also be run using the Singularity container defined [in this repository](https://github.com/rachellea/research-container).
32		29
33	## Usage	30	## Usage
34		31
35	To run a demo of the CT-Net83, CT-Net9, BodyConv, 3DConv, and ablated CT-Net models on	32	To run a demo of the CT-Net83, CT-Net9, BodyConv, 3DConv, and ablated CT-Net models on
36	fake data, run this command:	33	fake data, run this command:
37		34
38	`python main.py`	35	`python main.py`
39		36
40	The RAD-ChestCT data set [is publicly available on Zenodo](https://zenodo.org/record/6406114).	37	The RAD-ChestCT data set [is publicly available on Zenodo](https://zenodo.org/record/6406114).
41		38
42	Because the real dataset is large, currently this repository includes fake data files to enable demonstrating	39	Because the real dataset is large, currently this repository includes fake data files to enable demonstrating
43	the code and the required data formats. The fake data is located in load_dataset/fakedata.	40	the code and the required data formats. The fake data is located in load_dataset/fakedata.
44	The fake CTs were generated as follows:	41	The fake CTs were generated as follows:
45		42
46	```	43	```
47	fakect = np.random.randint(low=-1000,high=1000,size=(10,10,10))	44	fakect = np.random.randint(low=-1000,high=1000,size=(10,10,10))
48	np.savez_compressed('FAKE000.npz',ct=fakect)	45	np.savez_compressed('FAKE000.npz',ct=fakect)
49	```	46	```
50		47
51	Note that 10 x 10 x 10 is too small for a real CT scan; the CT scans	48	Note that 10 x 10 x 10 is too small for a real CT scan; the CT scans
52	in the RAD-ChestCT data set are on the order of 450 x 450 x 450 pixels.	49	in the RAD-ChestCT data set are on the order of 450 x 450 x 450 pixels.
53		50
54	## Organization	51	## Organization
55		52
56	* main.py contains the experiment configurations needed to replicate the	53	* main.py contains the experiment configurations needed to replicate the
57	results in the paper. The command `python main.py` will run a demo of the	54	results in the paper. The command `python main.py` will run a demo of the
58	CT-Net83, CT-Net9, BodyConv, 3DConv, and ablated CT-Net models on	55	CT-Net83, CT-Net9, BodyConv, 3DConv, and ablated CT-Net models on
59	fake data.	56	fake data.
60	* run_experiment.py contains code for training and evaluting the models.	57	* run_experiment.py contains code for training and evaluting the models.
61	* evaluate.py contains code for calculating, organizing, and plotting performance	58	* evaluate.py contains code for calculating, organizing, and plotting performance
62	metrics including AUROC and average precision.	59	metrics including AUROC and average precision.
63	* unit_tests.py contains some unit tests. These tests can be run via `python unit_tests.py`	60	* unit_tests.py contains some unit tests. These tests can be run via `python unit_tests.py`
64	* load_dataset/custom_datasets.py contains the PyTorch Dataset class for the CT data.	61	* load_dataset/custom_datasets.py contains the PyTorch Dataset class for the CT data.
65	* load_dataset/utils.py contains the code for preparing individual CT volumes, including	62	* load_dataset/utils.py contains the code for preparing individual CT volumes, including
66	padding, cropping, normalizing pixel values, and performing data augmentation through	63	padding, cropping, normalizing pixel values, and performing data augmentation through
67	random flips and rotations.	64	random flips and rotations.
68	* load_dataset/fakedata contains the fake data necessary to run the demo.	65	* load_dataset/fakedata contains the fake data necessary to run the demo.
69	* models/custom_models_ctnet.py contains the CT-Net model definition.	66	* models/custom_models_ctnet.py contains the CT-Net model definition.
70	* models/custom_models_alternative.py contains two alternative architectures,	67	* models/custom_models_alternative.py contains two alternative architectures,
71	BodyConv and 3DConv.	68	BodyConv and 3DConv.
72	* models/custom_models_ablation.py contains the ablated variants of CT-Net.	69	* models/custom_models_ablation.py contains the ablated variants of CT-Net.
73		70
74	## Comment on Data Parallelism	71	## Comment on Data Parallelism
75		72
76	Currently the experiments in main.py are set up to replicate the paper results.	73	Currently the experiments in main.py are set up to replicate the paper results.
77	Several of the experiments use data parallelism which assumes that at least	74	Several of the experiments use data parallelism which assumes that at least
78	2 GPUs are available. If you wish to run the demo on one GPU, then change batch_size to 1	75	2 GPUs are available. If you wish to run the demo on one GPU, then change batch_size to 1
79	and set data_parallel to False.	76	and set data_parallel to False.
80		77
81	### Logo	78	### Logo
82		79
83	The logo includes two Creative Commons icons from the Noun Project: [lungs](https://thenounproject.com/search/?q=chest+x+ray&i=945146) and	80	The logo includes two Creative Commons icons from the Noun Project: [lungs](https://thenounproject.com/search/?q=chest+x+ray&i=945146) and
84	[gear](https://thenounproject.com/search/?q=AI&i=3092014).	81	[gear](https://thenounproject.com/search/?q=AI&i=3092014).