
# rocaseg - Robust Cartilage Segmentation from MRI

Source code for Panfilov et al. "Improving Robustness of Deep Learning Based Knee MRI Segmentation: Mixup and Adversarial Domain Adaptation", https://arxiv.org/abs/1908.04126v3.





### Important!

The camera-ready version contained a bug in Dice score computation for tibial cartilage on Dataset C. Please, refer to the arXiv version for the corrected values - https://arxiv.org/abs/1908.04126v3.

### Description

1. To reproduce the experiments from the article one needs to have access to
 OAI iMorphics, OKOA, and MAKNEE datasets.

2. Download code from this repository.
 
3. Create a fresh Conda environment using `environment.yml`. Install the downloaded
 code as a Python module.

4. `datasets/prepare_dataset_...` files show how the raw data is converted into the
 format supported by the training and the inference pipelines.
 
5. The structure of the project has to be as follows:
    ```
    ./project/
        | ./data_raw/  # raw scans and annotations
             | ./OAI_iMorphics_scans/
             | ./OAI_iMorphics_annotations/
             | ./OKOA/
             | ./MAKNEE/
        | ./data/  # preprocessed scans and annotations
        | ./src/ (this repository)
        | ./results/  # models' weights, intermediate and final results 
             | ./0_baseline/
                  | ./weights/
                  | ...
             | ./1_mixup/
             | ./2_mixup_nowd/
             | ./3_uda1/
             | ./4_uda2/
             | ./5_uda1_mixup_nowd/
    ```

6. File `scripts/runner.sh` contains the complete description of the workflow.

7. Statistical testing is implemented in `notebooks/Statistical_tests.ipynb`.

8. Pretrained models are available at https://drive.google.com/open?id=1f-gZ2wCf55OVjgA8oXd7xttGVW5DUUcU .

### Legal aspects

This code is freely available only for research purposes.

The software has not been certified as a medical device and, therefore, must not be used
for diagnostic purposes. 

Commercial use of the provided code and the pre-trained models is strictly prohibited,
since they were developed using the medical datasets under restrictive licenses.   

### Cite this work

```
@InProceedings{Panfilov_2019_ICCV_Workshops,
  author = {Panfilov, Egor and Tiulpin, Aleksei and Klein, Stefan and Nieminen, Miika T. and Saarakkala, Simo},
  title = {Improving Robustness of Deep Learning Based Knee MRI Segmentation: Mixup and Adversarial Domain Adaptation},
  booktitle = {The IEEE International Conference on Computer Vision (ICCV) Workshops},
  month = {Oct},
  year = {2019}
}
```

	a/README.md		b/README.md
1	# rocaseg - Robust Cartilage Segmentation from MRI	1	# rocaseg - Robust Cartilage Segmentation from MRI
2		2
3	Source code for Panfilov et al. "Improving Robustness of Deep Learning Based Knee MRI Segmentation: Mixup and Adversarial Domain Adaptation", https://arxiv.org/abs/1908.04126v3.	3	Source code for Panfilov et al. "Improving Robustness of Deep Learning Based Knee MRI Segmentation: Mixup and Adversarial Domain Adaptation", https://arxiv.org/abs/1908.04126v3.
4		4
5	<p align="center">	5
6	<img src="github_image.png" width="700" alt="Overview"/>	6
7	</p>
8
9	### Important!	7	### Important!
10		8
11	The camera-ready version contained a bug in Dice score computation for tibial cartilage on Dataset C. Please, refer to the arXiv version for the corrected values - https://arxiv.org/abs/1908.04126v3.	9	The camera-ready version contained a bug in Dice score computation for tibial cartilage on Dataset C. Please, refer to the arXiv version for the corrected values - https://arxiv.org/abs/1908.04126v3.
12		10
13	### Description	11	### Description
14		12
15	1. To reproduce the experiments from the article one needs to have access to	13	1. To reproduce the experiments from the article one needs to have access to
16	OAI iMorphics, OKOA, and MAKNEE datasets.	14	OAI iMorphics, OKOA, and MAKNEE datasets.
17		15
18	2. Download code from this repository.	16	2. Download code from this repository.
19		17
20	3. Create a fresh Conda environment using `environment.yml`. Install the downloaded	18	3. Create a fresh Conda environment using `environment.yml`. Install the downloaded
21	code as a Python module.	19	code as a Python module.
22		20
23	4. `datasets/prepare_dataset_...` files show how the raw data is converted into the	21	4. `datasets/prepare_dataset_...` files show how the raw data is converted into the
24	format supported by the training and the inference pipelines.	22	format supported by the training and the inference pipelines.
25		23
26	5. The structure of the project has to be as follows:	24	5. The structure of the project has to be as follows:
27	```	25	```
28	./project/	26	./project/
29	\| ./data_raw/ # raw scans and annotations	27	\| ./data_raw/ # raw scans and annotations
30	\| ./OAI_iMorphics_scans/	28	\| ./OAI_iMorphics_scans/
31	\| ./OAI_iMorphics_annotations/	29	\| ./OAI_iMorphics_annotations/
32	\| ./OKOA/	30	\| ./OKOA/
33	\| ./MAKNEE/	31	\| ./MAKNEE/
34	\| ./data/ # preprocessed scans and annotations	32	\| ./data/ # preprocessed scans and annotations
35	\| ./src/ (this repository)	33	\| ./src/ (this repository)
36	\| ./results/ # models' weights, intermediate and final results	34	\| ./results/ # models' weights, intermediate and final results
37	\| ./0_baseline/	35	\| ./0_baseline/
38	\| ./weights/	36	\| ./weights/
39	\| ...	37	\| ...
40	\| ./1_mixup/	38	\| ./1_mixup/
41	\| ./2_mixup_nowd/	39	\| ./2_mixup_nowd/
42	\| ./3_uda1/	40	\| ./3_uda1/
43	\| ./4_uda2/	41	\| ./4_uda2/
44	\| ./5_uda1_mixup_nowd/	42	\| ./5_uda1_mixup_nowd/
45	```	43	```
46		44
47	6. File `scripts/runner.sh` contains the complete description of the workflow.	45	6. File `scripts/runner.sh` contains the complete description of the workflow.
48		46
49	7. Statistical testing is implemented in `notebooks/Statistical_tests.ipynb`.	47	7. Statistical testing is implemented in `notebooks/Statistical_tests.ipynb`.
50		48
51	8. Pretrained models are available at https://drive.google.com/open?id=1f-gZ2wCf55OVjgA8oXd7xttGVW5DUUcU .	49	8. Pretrained models are available at https://drive.google.com/open?id=1f-gZ2wCf55OVjgA8oXd7xttGVW5DUUcU .
52		50
53	### Legal aspects	51	### Legal aspects
54		52
55	This code is freely available only for research purposes.	53	This code is freely available only for research purposes.
56		54
57	The software has not been certified as a medical device and, therefore, must not be used	55	The software has not been certified as a medical device and, therefore, must not be used
58	for diagnostic purposes.	56	for diagnostic purposes.
59		57
60	Commercial use of the provided code and the pre-trained models is strictly prohibited,	58	Commercial use of the provided code and the pre-trained models is strictly prohibited,
61	since they were developed using the medical datasets under restrictive licenses.	59	since they were developed using the medical datasets under restrictive licenses.
62		60
63	### Cite this work	61	### Cite this work
64		62
65	```	63	```
66	@InProceedings{Panfilov_2019_ICCV_Workshops,	64	@InProceedings{Panfilov_2019_ICCV_Workshops,
67	author = {Panfilov, Egor and Tiulpin, Aleksei and Klein, Stefan and Nieminen, Miika T. and Saarakkala, Simo},	65	author = {Panfilov, Egor and Tiulpin, Aleksei and Klein, Stefan and Nieminen, Miika T. and Saarakkala, Simo},
68	title = {Improving Robustness of Deep Learning Based Knee MRI Segmentation: Mixup and Adversarial Domain Adaptation},	66	title = {Improving Robustness of Deep Learning Based Knee MRI Segmentation: Mixup and Adversarial Domain Adaptation},
69	booktitle = {The IEEE International Conference on Computer Vision (ICCV) Workshops},	67	booktitle = {The IEEE International Conference on Computer Vision (ICCV) Workshops},
70	month = {Oct},	68	month = {Oct},
71	year = {2019}	69	year = {2019}
72	}	70	}
73	```	71	```