Hecktor22 tutorial (#1107)

Author: myron

auto3dseg/README.md

@@ -32,20 +32,21 @@
 ## Auto3DSeg Leaderboard Performance
 
 - **Auto3DSeg** won 1st place in MICCAI 2022 challenge **[HECKTOR 2022: Head and neck tumor segmentation and outcome prediction in PET/CT images](https://hecktor.grand-challenge.org/)**
-  - 1st place GTVp and GTVn segmentation (Task 1)
-- **Auto3DSeg** won 2nd place in MICCAI 2022 challenge **[INSTANCE22: The 2022 Intracranial Hemorrhage Segmentation Challenge on Non-Contrast head CT (NCCT)](https://instance.grand-challenge.org/)**
-  - 1st place in terms of Dice score
-- **Auto3DSeg** won a top-3 place in MICCAI 2022 challenge **[ISLES'22: Ischemic Stroke Lesion Segmentation Challenge](https://isles22.grand-challenge.org/)**
-  - The final results will announced at MICCAI 2022
+  - 1st place  (segmentation task)
+- **Auto3DSeg** got 2nd place in MICCAI 2022 challenge **[INSTANCE22: The 2022 Intracranial Hemorrhage Segmentation Challenge on Non-Contrast head CT (NCCT)](https://instance.grand-challenge.org/)**
+  - 1st rank in terms of Dice score
+- **Auto3DSeg** got 2nd place in MICCAI 2022 challenge **[ISLES'22: Ischemic Stroke Lesion Segmentation Challenge](https://isles22.grand-challenge.org/)**
+  - 1st rank in terms of Dice score
 
 We have demonstrated preliminary results of public datasets are described in the [tasks](tasks) folder.
 
-- [INSTANCE22](tasks/instance22)
-- [Beyond the Cranial Vault (BTCV) Abdomen Dataset](tasks/btcv)
+- [HECKTOR22](tasks/hecktor22/README.md)
+- [INSTANCE22](tasks/instance22/README.md)
+- [Beyond the Cranial Vault (BTCV) Abdomen Dataset](tasks/btcv/README.md)
 - Medical Segmentation Decathlon (MSD) Dataset
-        - [Task04 Task04_Hippocampus](tasks/msd/Task04_Hippocampus)
-	- [Task05 Prostate](tasks/msd/Task05_Prostate)
-	- [Task09 Spleen](tasks/msd/Task09_Spleen)
+        - [Task04 Task04_Hippocampus](tasks/msd/Task04_Hippocampus/README.md)
+	- [Task05 Prostate](tasks/msd/Task05_Prostate/README.md)
+	- [Task09 Spleen](tasks/msd/Task09_Spleen/README.md)
 
 ## A Two-Minute "Hello-World" Example
 

auto3dseg/tasks/hecktor22/README.md

@@ -0,0 +1,57 @@
+
+# HECKTOR22
+
+
+The HECKTOR22 dataset is from MICCAI 2022 challenge **[HEad and NeCK TumOR Segmentation and Outcome Prediction (HECKTOR22)](https://hecktor.grand-challenge.org)**. The solution described here won the 1st place in the HECKTOR22 challenge [(NVAUTO team)](https://hecktor.grand-challenge.org/final-leaderboard/):
+
+Andriy Myronenko, Md Mahfuzur Rahman Siddiquee, Dong Yang, Yufan He and Daguang Xu: "Automated head and neck tumor segmentation from 3D PET/CT". In MICCAI (2022). [arXiv](https://arxiv.org/abs/2209.10809)
+
+![hecktor_PET_CT](./hecktor_data.jpg)
+
+## Task overview
+
+The task is to segment 3D Head and Neck (H&N) tumors and lymph nodes classes from a pair of 3D CT and PET images.  The ground truth labels are provided for 524 cases with average 3D CT size of 512x512x200 voxels at 0.98x0.98x3 mm average resolution, and with average 3D PET size of 200x200x200 voxels at 4x4x4 mm. The CT and PET images where rigidly aligned to a common origin, but remain at different sizes and resolutions.
+
+
+## Auto3DSeg
+
+The HECKTOR22 tutorial is only supported for **SegResNet** algo (since currently it is the only algo with support of multi-resolution input images, such as CT and PET).
+Auto3DSeg runs a full workflow including data analysis, and multi-fold training. Please download the dataset into /data/hecktor22 folder first.
+
+
+### Running based on the input config
+
+The Auto3DSeg can be run using a config **input.yaml**
+
+```bash
+python -m monai.apps.auto3dseg AutoRunner run --input='./input.yaml' --algos='segresnet'
+```
+
+### Running from python
+
+Alternatively you can also run Auto3DSeg from a python script, where you can customize more options. Please see the comments in **hecktor22.py**
+```bash
+python hecktor22.py
+```
+
+
+## Validation performance: NVIDIA DGX-1 (8x V100 16G)
+
+The validation results can be obtained by running the training script with MONAI 1.1.0 on NVIDIA DGX-1 with (8x V100 16GB) GPUs. The results below are in terms of **Aggregated Dice**, which was used as the key metric in the challenge [1,2]. The values of the Aggregated Dice slightly differ from a conventional average Dice (which is used by Auto3DSeg by default for all tasks).
+
+
+| | Fold 0 | Fold 1 | Fold 2 | Fold 3 | Fold 4 | Avg |
+|:------:|:------:|:------:|:------:|:------:|:------:|:---:|
+| SegResNet | 0.7933 | 0.7862 | 0.7816 |0.8275 | 0.8059 | 0.7989 |
+
+
+## Data
+
+The HECKTOR22 challenge dataset [2,3] can be downloaded from [here](https://hecktor.grand-challenge.org) after the registration. Each user is responsible for checking the content of the datasets and the applicable licenses and determining if suitable for the intended use. The license for the HECKTOR22 dataset is different than MONAI license.
+
+## References
+[1] Andriy Myronenko, Md Mahfuzur Rahman Siddiquee, Dong Yang, Yufan He and Daguang Xu: "Automated head and neck tumor segmentation from 3D PET/CT". In MICCAI (2022). https://arxiv.org/abs/2209.10809
+
+[2] Andrearczyk, V., Oreiller, V., Boughdad, S., Rest, C.C.L., Elhalawani, H., Jreige, M., Prior, J.O., Valli`eres, M., Visvikis, D., Hatt, M., Depeursinge, A.: Overview of the HECKTOR Challenge at MICCAI 2022: Automatic Head and Neck Tumor Segmentation and Outcome Prediction in PET/CT (2023), https://arxiv.org/abs/2201.04138
+
+[3] Oreiller, V., Andrearczyk, V., Jreige, M., Boughdad, S., Elhalawani, H., Castelli, J., Valli`eres, M., Zhu, S., Xie, J., Peng, Y., Iantsen, A., Hatt, M., Yuan, Y., Ma, J., Yang, X., Rao, C., Pai, S., Ghimire, K., Feng, X. Naser, M.A., Fuller, C.D., Yousefirizi, F., Rahmim, A., Chen, H., Wang, L., Prior, J.O., Depeursinge, A.: Head and neck tumor segmentation in PET/CT: The HECKTOR challenge. Medical Image Analysis 77, 102336 (2022)

auto3dseg/tasks/hecktor22/hecktor22.py

@@ -0,0 +1,26 @@
+# Copyright (c) MONAI Consortium
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from monai.apps.auto3dseg import AutoRunner
+
+# the minimum required code is to create an AutoRunner() and call runner.run()
+# the algos must be set to 'segresnet' (since currently it's the only algo with support of multi-resolution input images, such as CT and PET)
+# here we also set ensemble=False (optional) to prevent inference on the testing set (since we do not use any testing sets, only the 5-fold cross validation)
+# for you own inference (and ensemble) you can provide a list of testing files in "hecktor22_folds.json"
+runner = AutoRunner(input='input.yaml', algos = 'segresnet', work_dir= './work_dir', ensemble=False)
+
+## optionally, we can use just 1-fold (for a quick training of a single model, instead of training 5 folds)
+# runner.set_num_fold(1)
+
+## optionally, we can define the path to the dataset here, instead of the one in input.yaml
+#runner.set_training_params({"dataroot" : '/data/hecktor22'})
+
+runner.run()