Merge pull request #82 from ivadomed/nlm/nnunet_ms_lesion

Replace of seg_ms_lesion_mp2rage by UNIseg model on sct_deepseg
ivadomed · Sep 6, 2024 · 14ec175 · 14ec175
2 parents e7d6f13 + 0a0ff64
commit 14ec175
Show file tree

Hide file tree

Showing 12 changed files with 6,632 additions and 89 deletions.
diff --git a/README.md b/README.md
@@ -1,119 +1,86 @@
 # model_seg_ms_mp2rage
 
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8376754.svg)](https://doi.org/10.5281/zenodo.8376754)
-
-Model repository for MS lesion segmentation on MP2RAGE data as discussed [here](https://github.com/ivadomed/ivadomed/issues/821).
-This repository contains two models, one for spinal cord (SC) segmentation and one for MS lesion segmentation.
+Model repository for MS lesion segmentation on MP2RAGE data (UNIT1 contrast)
 
 ## Model overview 
 
-![model_overview](https://github.com/ivadomed/model_seg_ms_mp2rage/releases/download/r20211223/model_overview.png)
+![uniseg_update](https://github.com/ivadomed/model_seg_ms_mp2rage/assets/77469192/e4b5fbcc-03e9-4bc4-829e-604c32dbdd68)
 
-As of https://github.com/ivadomed/model_seg_ms_mp2rage/releases/tag/r20230210, five models are trained (with dropout and different seeds), to perform ensemble/bagging during inference and compute epistemic uncertainty.
+3D model trained with [nnUNetv2](https://github.com/MIC-DKFZ/nnUNet) framework.
 
 ## Dependencies
+[SCT 6.4](https://spinalcordtoolbox.com/)
 
-- [SCT](https://spinalcordtoolbox.com/) commit: 7fd2ea718751dd858840c3823c0830a910d9777c
-- [ivadomed](https://ivadomed.org) commit: git-master-93ba03df76d229d8a190c694f757da6c00efa545
-
-## Clone this repository
-
-~~~
-git clone https://github.com/ivadomed/model_seg_ms_mp2rage.git
-~~~
-
-## Get the data
-
-- [email protected]:datasets/basel-mp2rage
-- Commit: 93110d8ebb65398dcc6e4528bf548eb7828332f1
-
-### Example calls to get the data
-
-~~~
-git clone [email protected]:datasets/basel-mp2rage
-cd basel-mp2rage
-git annex get .
-cd ..
-~~~
-
-## Prepare the data
+## Datasets for training 
 
-The data need to be preprocessed before training. The preprocessing command is:
+- `basel-mp2rage`
+- `nih-ms-mp2rage`
+- `marseille-3t-mp2rage`
 
-~~~
-sct_run_batch -script <PATH_TO_REPOSITORY>/preprocessing/preprocess_data.sh -path-data <PATH_TO_DATA>/basel-mp2rage/ -path-output basel-mp2rage-preprocessed -jobs <JOBS>
-~~~
-
-This command will create a `data_processed_scseg` folder for the SC segmentation task and a 
-`data_processed_lesionseg` folder for the lesion segmentation task inside the `basel-mp2rage-preprocessed` 
-you specified. Each of these two folders contain only the required files for their respective task.
-
-After running the preprocessing, you can also run the quality-control (QC) script:
+## Installation 
+```bash
+sct_deepseg -install-task seg_sc_contrast_agnostic
 ```
-python preprocessing/qc_preprocess.py -s basel-mp2rage-preprocessed
+```bash
+sct_deepseg -install-task seg_ms_lesion_mp2rage 
 ```
-which i) logs resolutions and sizes for each subject image (both raw and cropped) for data exploration, 
-ii) performs basic shape checks for spinal cord (SC) cropped images and ground-truths (GTs), and 
-most importantly iii) checks if the dilated SC mask leaves out any lesions from the GT of each rater.
 
-## Training
+**Warning:** When running the MS lesion segmentation model, the image first need to be cropped around the spinal cord mask with a dilation of 30 mm in the axial plane and 5 mm in the Z-axis. 
 
-Spinal cord segmentation training was carried out with
-```
-ivadomed --train -c config/seg_sc.json
+## Launch MS lesion segmentation:
+1. Spinal cord segmentation 
+```bash
+sct_deepseg -i IMAGE_UNIT1 -task seg_sc_contrast_agnostic -o IMAGE_UNIT1_sc
 ```
-
-Lesion segmentation training was carried out with
+2. Cropping with dilation (for axial orientation images with 1mm isotropic resolution)
+```bash
+sct_crop_image -i IMAGE_UNIT1 -m IMAGE_UNIT1_sc -dilate 30x30x5 -o IMAGE_UNIT1_cropped
 ```
-ivadomed --train -c config/seg_lesion.json
+3. MS lesion segmentation 
+```bash
+sct_deepseg -i IMAGE_UNIT1_cropped -task seg_ms_lesion_mp2rage 
 ```
 
-> **Note**
-> See [hyperparameter optimization](https://github.com/ivadomed/model_seg_ms_mp2rage/issues/58)
+## Model implementation on Slicer
 
+1. Install [3D Slicer version 5.7.0](https://download.slicer.org/), then install the module [SlicerNNUnet](https://github.com/KitwareMedical/SlicerNNUnet) from the extensions explorer.
 
-## Get trained models
+<img src="https://github.com/spinalcordtoolbox/spinalcordtoolbox/assets/77469192/9d7964d2-66e3-464d-ac1a-04caaaced63b" width="300px;" alt=""/>
 
-```
-cp -r ~/duke/temp/uzay/saved_models_basel/seg_sc_output .
-cp -r ~/duke/temp/uzay/saved_models_basel/seg_lesion_output .
-```
 
-## Performance evaluation
+2. Download and unzip the [ nnUNetTrainer_seg_ms_lesion_mp2rage__nnUNetPlans__3d_fullres.zip](https://github.com/ivadomed/model_seg_ms_mp2rage/releases/tag/r20240610) file. (~120 Mb)
 
-To test a spinal cord segmentation model run
-```
-ivadomed --test -c config/seg_sc.json
-```
-
-To test a lesion segmentation model independently on the two rater's annotations
-```
-ivadomed --test -c config/test_on_rater1.json
-ivadomed --test -c config/test_on_rater2.json
-```
-
-Visualize predictions
-
-Update variable below:
-```
-SUBJECT_LIST=(002 017 025 058)
-PATH_MODEL=model_seg_lesion_mp2rage_20230124_204632
-```
-Then launch:
-```
-for SUBJECT in ${SUBJECT_LIST[@]}; do fsleyes -S ~/data.neuro/basel-mp2rage/sub-P${SUBJECT}/anat/sub-P${SUBJECT}_UNIT1.nii.gz ~/data.neuro/basel-mp2rage/derivatives/labels/sub-P${SUBJECT}/anat/sub-P${SUBJECT}_UNIT1_lesion-manualNeuroPoly.nii.gz -cm yellow ${PATH_MODEL}/pred_masks/sub-P${SUBJECT}_UNIT1_pred.nii.gz -cm red -a 50; done
+3. Unzip the `.zip` file and place it inside a folder named `Dataset403_seg_ms_lesion_mp2rage_1mm_322subj`. The final directory structure should look like this:
 ```
+Dataset403_seg_ms_lesion_mp2rage_1mm_322subj
+└── nnUNetTrainer_seg_ms_lesion_mp2rage__nnUNetPlans__3d_fullres
+    ├── dataset_fingerprint.json
+    ├── dataset.json
+    ├── dataset_split.md
+    ├── datasplits
+    │   ├── datasplit_basel-mp2rage.yaml
+    │   ├── datasplit_marseille-3t-mp2rage.yaml
+    │   └── datasplit_nih-ms-mp2rage.yaml
+    ├── fold_3
+    │   ├── checkpoint_final.pth
+    │   ├── debug.json
+    │   ├── progress.png
+    │   └── training_log_2024_3_14_20_35_08.txt
+    └── plans.json
+``` 
 
-## Segment an image
+4. nnUNet Install: Follow the instructions on first row of:
+![Slicer-UNIseg](https://github.com/ivadomed/model_seg_ms_mp2rage/assets/77469192/90207a02-f640-4624-b10d-1abbd6433ba6)
 
-To run inference:
-```
-ivadomed_segment_image -i IMAGE -m MODEL
-```
+5. Implementation
+- Navigate and select the Slicer friendly folder on `Model path`
+- Folds: Choose the fold 3
+- Apply `model_seg_ms_mp2rage` !! 🚀🚀🚀
 
-> **Warning**
-> When running the MS lesion segmentation model, the image first need to be cropped around the spinal cord with a dilation of 32 in the axial plane.
 
-## Ensemble
+## Acknowledgments
 
-Multiple models were trained with different seeds, and they can all be used at test-time to produce slightly different segmentations that can then be everaged (ensemble/bagging). See more details [here](https://github.com/ivadomed/model_seg_ms_mp2rage/issues/63#issuecomment-1409250538).
+- Charidimos Tsagkas (Translational Neuroradiology Section, National Institutes of Health, Bethesda, USA)
+- Daniel Reich (Translational Neuroradiology Section, National Institutes of Health, Bethesda, USA)
+- Cristina Granziera (Neurologic Clinic and Policlinic, University Hospital Basel and University of Basel, Basel, Switzerland)
+- Virginie Callot (Center for Magnetic Resonance in Biology and Medicine, CRMBM-CEMEREM, UMR 7339, CNRS, Aix-Marseille University, Marseille, France)