
# Hippocampus Segmentation from MRI using V-Net
In this repo, hippocampus segmentation from MRI is performed 
using a Convolutional Neural Network (CNN) architecture based on
[V-Net](https://arxiv.org/abs/1606.04797).
The dataset is publicly available from the 
[Medical Segmentation Decathlon Challenge](http://medicaldecathlon.com/),
and can be downloaded from 
[here](https://drive.google.com/drive/folders/1HqEgzS8BV2c7xYNrZdEAnrHk7osJJ--2).

The [PyTorch](https://pytorch.org/) library has been used to write the model architecture 
and performing the training and validation. 
[SimpleITK](https://simpleitk.org/) has been exploited to handle I/O of medical images. 
3D Data Augmentation has been made by employing [torchio](https://arxiv.org/abs/2003.04696).

A 5-folders cross validation has been performed on the training set, yielding a 
Mean Multi Dice Coefficient of 0.8727 +/- 0.0364, a Dice Coefficient for 
Anterior Hippocampus of 0.8821 +/- 0.0363 and a Dice Coefficient for 
Posterior Hippocampus of 0.8634 +/- 0.0415.
The results are reported as "mean +/- std". 

Meshes and images reported in the ```images``` folder have been obtained exploiting 
[ITK-SNAP](http://www.itksnap.org/).

### Quality Measures
<table>
<tr>
<th colspan="4">Results</th>
</tr>
<tr>
<th> Model </th>
<th> Mean Dice per case </th>
<th> Dice per case (Anterior) </th>
<th> Dice per case (Posterior) </th>
</tr>
<tr>
<td>3D V-Net (no data augmentation)</td>
<td>0.8727 +/- 0.0364</td>
<td>0.8821 +/- 0.0363</td>
<td>0.8634 +/- 0.0415</td>
</tr>
<tr>
<td>3D V-Net (with data augmentation)</td>
<td> 0.8761 +/- 0.0374 </td>
<td> 0.8875 +/- 0.0354 </td>
<td> 0.8647 +/- 0.0455 </td>
</tr>
</table>

### Confusion Matrices
#### No Data Augmentation
<table>
<tr>
<th>Confusion Matrix </th>
<th>Normalized Confusion Matrix</th>
</tr>
<tr>
<th>
<img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/conf_matrix_no_norm_no_augm_torchio.png?raw=true" alt="Confusion Matrix (Cross-validation)" width="400"/>
</th>
<th>
<img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/conf_matrix_normalized_row_no_augm_torchio.png?raw=true" alt="Normalized Confusion Matrix (Cross-validation)" width="400"/>
</th>
<tr>
</table>

#### With Data Augmentation
<table>
<tr>
<th>Confusion Matrix </th>
<th>Normalized Confusion Matrix</th>
</tr>
<tr>
<th>
<img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchioimages/conf_matrix_no_norm_augm.png?raw=true" alt="Confusion Matrix (Cross-validation)" width="400"/>
</th>
<th>
<img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/conf_matrix_normalized_row_augm.png?raw=true" alt="Normalized Confusion Matrix (Cross-validation)" width="400"/>
</th>
<tr>
</table>


### TODO List
- [x] Automatic Download of dataset
- [x] CNN Architecture Definition
- [x] 3D Data Loader for Nifti files
- [x] Definition of loss functions
- [x] Training loop
- [x] Cross-validation on Train set
- [x] Command Line Interface for training 
- [x] Command Line Interface for validation 
- [x] 3D Data Augmentation 
- [ ] Tuning of Optimal Parameters for 3D Data Augmentation
- [ ] Validation on Test set

## Usage
Use ```python setup.py install``` for installing this package.
A complete run (dataset download, train, validation) of the package may be the following:
```console
git clone https://github.com/Nicolik/HippocampusSegmentationMRI.git
cd HippocampusSegmentationMRI
python setup.py install
python run/download.py
python run/train.py 
python run/validate.py
```
### Dataset
If you want to download the original dataset, run ```run/download.py```.
The syntax is as follows:
```console
python run/download.py --dir=path/to/dataset/dir
```
### Training
If you simply want to perform the training, run ```run/train.py```.
The syntax is as follows:
```console
python run/train.py --epochs=NUM_EPOCHS --batch=BATCH_SIZE --workers=NUM_WORKERS --lr=LR
```
If you want to edit the configuration, you can also modify the ```config/config.py``` file. 
In particular, consider the class ```SemSegMRIConfig```. 
If you want to play with data augmentation (built with ```torchio```), 
modify the ```config/augm.py``` file.

### Validation
If you want to perform the cross-validation, run ```run/validate.py``` or ```run/validate_torchio.py```.
The syntax is as follows:
```console
python run/validate.py --dir=path/to/logs/dir --write=WRITE --verbose=VERBOSE
```
```console
python run/validate_torchio.py --dir=path/to/logs/dir --verbose=VERBOSE
```
The former adopts a loop from scratch, whereas the latter exploits the DataLoader created upon ```torchio```. 

## Output Results
### Sample Images (Training set)
#### Ground Truth Images
<table>
<tr>
<th>Ground Truth - MRI 327 (1)</th>
<th>Ground Truth - MRI 327 (2)</th>
</tr>
<tr>
<td><img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/327_gt_01.png?raw=true" alt="Ground Truth - MRI 327 (1)" width="250"/></td>
<td><img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/327_gt_02.png?raw=true" alt="Ground Truth - MRI 327 (2)" width="250"/></td>
</tr>
</table>

#### Predicted Images
<table>
<tr>
<th>Prediction   - MRI 327 (1)</th>
<th>Prediction   - MRI 327 (2)</th>
</tr>
<tr>
<td><img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchioimages/327_pred_01.png?raw=true" alt="Prediction   - MRI 327 (1)" width="250"/></td>
<td><img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/327_pred_02.png?raw=true" alt="Prediction   - MRI 327 (2)" width="250"/></td>
</tr>
</table>

### Sample Images (Test set)
#### Predicted Images
<table>
<tr>
<th>Prediction   - MRI 283 (1)</th>
<th>Prediction   - MRI 283 (2)</th>
</tr>
<tr>
<td><img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/283_pred_01.png?raw=true" alt="Prediction   - MRI 283 (1)" width="250"/></td>
<td><img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/283_pred_02.png?raw=true" alt="Prediction   - MRI 283 (2)" width="250"/></td>
</tr>
</table>

	a/README.md		b/README.md
1	# Hippocampus Segmentation from MRI using V-Net	1	# Hippocampus Segmentation from MRI using V-Net
2	In this repo, hippocampus segmentation from MRI is performed	2	In this repo, hippocampus segmentation from MRI is performed
3	using a Convolutional Neural Network (CNN) architecture based on	3	using a Convolutional Neural Network (CNN) architecture based on
4	[V-Net](https://arxiv.org/abs/1606.04797).	4	[V-Net](https://arxiv.org/abs/1606.04797).
5	The dataset is publicly available from the	5	The dataset is publicly available from the
6	[Medical Segmentation Decathlon Challenge](http://medicaldecathlon.com/),	6	[Medical Segmentation Decathlon Challenge](http://medicaldecathlon.com/),
7	and can be downloaded from	7	and can be downloaded from
8	[here](https://drive.google.com/drive/folders/1HqEgzS8BV2c7xYNrZdEAnrHk7osJJ--2).	8	[here](https://drive.google.com/drive/folders/1HqEgzS8BV2c7xYNrZdEAnrHk7osJJ--2).
9		9
10	The [PyTorch](https://pytorch.org/) library has been used to write the model architecture	10	The [PyTorch](https://pytorch.org/) library has been used to write the model architecture
11	and performing the training and validation.	11	and performing the training and validation.
12	[SimpleITK](https://simpleitk.org/) has been exploited to handle I/O of medical images.	12	[SimpleITK](https://simpleitk.org/) has been exploited to handle I/O of medical images.
13	3D Data Augmentation has been made by employing [torchio](https://arxiv.org/abs/2003.04696).	13	3D Data Augmentation has been made by employing [torchio](https://arxiv.org/abs/2003.04696).
14		14
15	A 5-folders cross validation has been performed on the training set, yielding a	15	A 5-folders cross validation has been performed on the training set, yielding a
16	Mean Multi Dice Coefficient of 0.8727 +/- 0.0364, a Dice Coefficient for	16	Mean Multi Dice Coefficient of 0.8727 +/- 0.0364, a Dice Coefficient for
17	Anterior Hippocampus of 0.8821 +/- 0.0363 and a Dice Coefficient for	17	Anterior Hippocampus of 0.8821 +/- 0.0363 and a Dice Coefficient for
18	Posterior Hippocampus of 0.8634 +/- 0.0415.	18	Posterior Hippocampus of 0.8634 +/- 0.0415.
19	The results are reported as "mean +/- std".	19	The results are reported as "mean +/- std".
20		20
21	Meshes and images reported in the ```images``` folder have been obtained exploiting	21	Meshes and images reported in the ```images``` folder have been obtained exploiting
22	[ITK-SNAP](http://www.itksnap.org/).	22	[ITK-SNAP](http://www.itksnap.org/).
23		23
24	### Quality Measures	24	### Quality Measures
25	<table>	25	<table>
26	<tr>	26	<tr>
27	<th colspan="4">Results</th>	27	<th colspan="4">Results</th>
28	</tr>	28	</tr>
29	<tr>	29	<tr>
30	<th> Model </th>	30	<th> Model </th>
31	<th> Mean Dice per case </th>	31	<th> Mean Dice per case </th>
32	<th> Dice per case (Anterior) </th>	32	<th> Dice per case (Anterior) </th>
33	<th> Dice per case (Posterior) </th>	33	<th> Dice per case (Posterior) </th>
34	</tr>	34	</tr>
35	<tr>	35	<tr>
36	<td>3D V-Net (no data augmentation)</td>	36	<td>3D V-Net (no data augmentation)</td>
37	<td>0.8727 +/- 0.0364</td>	37	<td>0.8727 +/- 0.0364</td>
38	<td>0.8821 +/- 0.0363</td>	38	<td>0.8821 +/- 0.0363</td>
39	<td>0.8634 +/- 0.0415</td>	39	<td>0.8634 +/- 0.0415</td>
40	</tr>	40	</tr>
41	<tr>	41	<tr>
42	<td>3D V-Net (with data augmentation)</td>	42	<td>3D V-Net (with data augmentation)</td>
43	<td> 0.8761 +/- 0.0374 </td>	43	<td> 0.8761 +/- 0.0374 </td>
44	<td> 0.8875 +/- 0.0354 </td>	44	<td> 0.8875 +/- 0.0354 </td>
45	<td> 0.8647 +/- 0.0455 </td>	45	<td> 0.8647 +/- 0.0455 </td>
46	</tr>	46	</tr>
47	</table>	47	</table>
48		48
49	### Confusion Matrices	49	### Confusion Matrices
50	#### No Data Augmentation	50	#### No Data Augmentation
51	<table>	51	<table>
52	<tr>	52	<tr>
53	<th>Confusion Matrix </th>	53	<th>Confusion Matrix </th>
54	<th>Normalized Confusion Matrix</th>	54	<th>Normalized Confusion Matrix</th>
55	</tr>	55	</tr>
56	<tr>	56	<tr>
57	<th>	57	<th>
58	<img src="images/conf_matrix_no_norm_no_augm_torchio.png" alt="Confusion Matrix (Cross-validation)" width="400"/>	58	<img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/conf_matrix_no_norm_no_augm_torchio.png?raw=true" alt="Confusion Matrix (Cross-validation)" width="400"/>
59	</th>	59	</th>
60	<th>	60	<th>
61	<img src="images/conf_matrix_normalized_row_no_augm_torchio.png" alt="Normalized Confusion Matrix (Cross-validation)" width="400"/>	61	<img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/conf_matrix_normalized_row_no_augm_torchio.png?raw=true" alt="Normalized Confusion Matrix (Cross-validation)" width="400"/>
62	</th>	62	</th>
63	<tr>	63	<tr>
64	</table>	64	</table>
65		65
66	#### With Data Augmentation	66	#### With Data Augmentation
67	<table>	67	<table>
68	<tr>	68	<tr>
69	<th>Confusion Matrix </th>	69	<th>Confusion Matrix </th>
70	<th>Normalized Confusion Matrix</th>	70	<th>Normalized Confusion Matrix</th>
71	</tr>	71	</tr>
72	<tr>	72	<tr>
73	<th>	73	<th>
74	<img src="images/conf_matrix_no_norm_augm.png" alt="Confusion Matrix (Cross-validation)" width="400"/>	74	<img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchioimages/conf_matrix_no_norm_augm.png?raw=true" alt="Confusion Matrix (Cross-validation)" width="400"/>
75	</th>	75	</th>
76	<th>	76	<th>
77	<img src="images/conf_matrix_normalized_row_augm.png" alt="Normalized Confusion Matrix (Cross-validation)" width="400"/>	77	<img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/conf_matrix_normalized_row_augm.png?raw=true" alt="Normalized Confusion Matrix (Cross-validation)" width="400"/>
78	</th>	78	</th>
79	<tr>	79	<tr>
80	</table>	80	</table>
81		81
82		82
83	### TODO List	83	### TODO List
84	- [x] Automatic Download of dataset	84	- [x] Automatic Download of dataset
85	- [x] CNN Architecture Definition	85	- [x] CNN Architecture Definition
86	- [x] 3D Data Loader for Nifti files	86	- [x] 3D Data Loader for Nifti files
87	- [x] Definition of loss functions	87	- [x] Definition of loss functions
88	- [x] Training loop	88	- [x] Training loop
89	- [x] Cross-validation on Train set	89	- [x] Cross-validation on Train set
90	- [x] Command Line Interface for training	90	- [x] Command Line Interface for training
91	- [x] Command Line Interface for validation	91	- [x] Command Line Interface for validation
92	- [x] 3D Data Augmentation	92	- [x] 3D Data Augmentation
93	- [ ] Tuning of Optimal Parameters for 3D Data Augmentation	93	- [ ] Tuning of Optimal Parameters for 3D Data Augmentation
94	- [ ] Validation on Test set	94	- [ ] Validation on Test set
95		95
96	## Usage	96	## Usage
97	Use ```python setup.py install``` for installing this package.	97	Use ```python setup.py install``` for installing this package.
98	A complete run (dataset download, train, validation) of the package may be the following:	98	A complete run (dataset download, train, validation) of the package may be the following:
99	```console	99	```console
100	git clone https://github.com/Nicolik/HippocampusSegmentationMRI.git	100	git clone https://github.com/Nicolik/HippocampusSegmentationMRI.git
101	cd HippocampusSegmentationMRI	101	cd HippocampusSegmentationMRI
102	python setup.py install	102	python setup.py install
103	python run/download.py	103	python run/download.py
104	python run/train.py	104	python run/train.py
105	python run/validate.py	105	python run/validate.py
106	```	106	```
107	### Dataset	107	### Dataset
108	If you want to download the original dataset, run ```run/download.py```.	108	If you want to download the original dataset, run ```run/download.py```.
109	The syntax is as follows:	109	The syntax is as follows:
110	```console	110	```console
111	python run/download.py --dir=path/to/dataset/dir	111	python run/download.py --dir=path/to/dataset/dir
112	```	112	```
113	### Training	113	### Training
114	If you simply want to perform the training, run ```run/train.py```.	114	If you simply want to perform the training, run ```run/train.py```.
115	The syntax is as follows:	115	The syntax is as follows:
116	```console	116	```console
117	python run/train.py --epochs=NUM_EPOCHS --batch=BATCH_SIZE --workers=NUM_WORKERS --lr=LR	117	python run/train.py --epochs=NUM_EPOCHS --batch=BATCH_SIZE --workers=NUM_WORKERS --lr=LR
118	```	118	```
119	If you want to edit the configuration, you can also modify the ```config/config.py``` file.	119	If you want to edit the configuration, you can also modify the ```config/config.py``` file.
120	In particular, consider the class ```SemSegMRIConfig```.	120	In particular, consider the class ```SemSegMRIConfig```.
121	If you want to play with data augmentation (built with ```torchio```),	121	If you want to play with data augmentation (built with ```torchio```),
122	modify the ```config/augm.py``` file.	122	modify the ```config/augm.py``` file.
123		123
124	### Validation	124	### Validation
125	If you want to perform the cross-validation, run ```run/validate.py``` or ```run/validate_torchio.py```.	125	If you want to perform the cross-validation, run ```run/validate.py``` or ```run/validate_torchio.py```.
126	The syntax is as follows:	126	The syntax is as follows:
127	```console	127	```console
128	python run/validate.py --dir=path/to/logs/dir --write=WRITE --verbose=VERBOSE	128	python run/validate.py --dir=path/to/logs/dir --write=WRITE --verbose=VERBOSE
129	```	129	```
130	```console	130	```console
131	python run/validate_torchio.py --dir=path/to/logs/dir --verbose=VERBOSE	131	python run/validate_torchio.py --dir=path/to/logs/dir --verbose=VERBOSE
132	```	132	```
133	The former adopts a loop from scratch, whereas the latter exploits the DataLoader created upon ```torchio```.	133	The former adopts a loop from scratch, whereas the latter exploits the DataLoader created upon ```torchio```.
134		134
135	## Output Results	135	## Output Results
136	### Sample Images (Training set)	136	### Sample Images (Training set)
137	#### Ground Truth Images	137	#### Ground Truth Images
138	<table>	138	<table>
139	<tr>	139	<tr>
140	<th>Ground Truth - MRI 327 (1)</th>	140	<th>Ground Truth - MRI 327 (1)</th>
141	<th>Ground Truth - MRI 327 (2)</th>	141	<th>Ground Truth - MRI 327 (2)</th>
142	</tr>	142	</tr>
143	<tr>	143	<tr>
144	<td><img src="images/327_gt_01.png" alt="Ground Truth - MRI 327 (1)" width="250"/></td>	144	<td><img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/327_gt_01.png?raw=true" alt="Ground Truth - MRI 327 (1)" width="250"/></td>
145	<td><img src="images/327_gt_02.png" alt="Ground Truth - MRI 327 (2)" width="250"/></td>	145	<td><img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/327_gt_02.png?raw=true" alt="Ground Truth - MRI 327 (2)" width="250"/></td>
146	</tr>	146	</tr>
147	</table>	147	</table>
148		148
149	#### Predicted Images	149	#### Predicted Images
150	<table>	150	<table>
151	<tr>	151	<tr>
152	<th>Prediction - MRI 327 (1)</th>	152	<th>Prediction - MRI 327 (1)</th>
153	<th>Prediction - MRI 327 (2)</th>	153	<th>Prediction - MRI 327 (2)</th>
154	</tr>	154	</tr>
155	<tr>	155	<tr>
156	<td><img src="images/327_pred_01.png" alt="Prediction - MRI 327 (1)" width="250"/></td>	156	<td><img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchioimages/327_pred_01.png?raw=true" alt="Prediction - MRI 327 (1)" width="250"/></td>
157	<td><img src="images/327_pred_02.png" alt="Prediction - MRI 327 (2)" width="250"/></td>	157	<td><img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/327_pred_02.png?raw=true" alt="Prediction - MRI 327 (2)" width="250"/></td>
158	</tr>	158	</tr>
159	</table>	159	</table>
160		160
161	### Sample Images (Test set)	161	### Sample Images (Test set)
162	#### Predicted Images	162	#### Predicted Images
163	<table>	163	<table>
164	<tr>	164	<tr>
165	<th>Prediction - MRI 283 (1)</th>	165	<th>Prediction - MRI 283 (1)</th>
166	<th>Prediction - MRI 283 (2)</th>	166	<th>Prediction - MRI 283 (2)</th>
167	</tr>	167	</tr>
168	<tr>	168	<tr>
169	<td><img src="images/283_pred_01.png" alt="Prediction - MRI 283 (1)" width="250"/></td>	169	<td><img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/283_pred_01.png?raw=true" alt="Prediction - MRI 283 (1)" width="250"/></td>
170	<td><img src="images/283_pred_02.png" alt="Prediction - MRI 283 (2)" width="250"/></td>	170	<td><img src="https://github.com/Nicolik/HippocampusSegmentationMRI/blob/torchio/images/283_pred_02.png?raw=true" alt="Prediction - MRI 283 (2)" width="250"/></td>
171	</tr>	171	</tr>
172	</table>	172	</table>