Merge pull request #23 from DCAN-Labs/adding_T1only_T2only_2022-10

Added T1-only and T2-only modes
DCAN-Labs · Nov 18, 2022 · f1faf5d · f1faf5d
2 parents d87402e + 87a4403
commit f1faf5d
Show file tree

Hide file tree

Showing 9 changed files with 776 additions and 379 deletions.
diff --git a/.gitignore b/.gitignore
@@ -11,5 +11,5 @@
 /src/img_processing/R_mask_holes_filled.nii.gz
 /src/img_processing/recombined_mask_LR.nii.gz
 /src/img_processing/Rmask.nii.gz
-/data/
+/data/*/
 **/trained_models
diff --git a/Dockerfile b/Dockerfile
@@ -113,8 +113,13 @@ ENV RESULTS_FOLDER="/opt/nnUNet/nnUNet_raw_data_base/nnUNet_trained_models"
 
 RUN mkdir -p /opt/nnUNet/nnUNet_raw_data_base/ /opt/nnUNet/nnUNet_raw_data_base/nnUNet_preprocessed /opt/nnUNet/nnUNet_raw_data_base/nnUNet_trained_models/nnUNet /home/cabinet/data
 #COPY trained_models/Task512_BCP_ABCD_Neonates_SynthSegDownsample.zip /opt/nnUNet/nnUNet_raw_data_base/nnUNet_trained_models/nnUNet
-RUN wget https://s3.msi.umn.edu/CABINET_data/Task512_BCP_ABCD_Neonates_SynthSegDownsample.zip -O /opt/nnUNet/nnUNet_raw_data_base/nnUNet_trained_models/nnUNet/Task512_BCP_ABCD_Neonates_SynthSegDownsample.zip
-RUN cd /opt/nnUNet/nnUNet_raw_data_base/nnUNet_trained_models/nnUNet && unzip -qq Task512_BCP_ABCD_Neonates_SynthSegDownsample.zip
+RUN wget https://s3.msi.umn.edu/CABINET_data/Task512_BCP_ABCD_Neonates_SynthSegDownsample.zip -O /opt/nnUNet/nnUNet_raw_data_base/nnUNet_trained_models/nnUNet/Task512_BCP_ABCD_Neonates_SynthSegDownsample.zip && \
+    wget https://s3.msi.umn.edu/CABINET_data/Task514_BCP_ABCD_Neonates_SynthSeg_T1Only.zip -O /opt/nnUNet/nnUNet_raw_data_base/nnUNet_trained_models/nnUNet/Task514_BCP_ABCD_Neonates_SynthSeg_T1Only.zip && \
+    wget https://s3.msi.umn.edu/CABINET_data/Task515_BCP_ABCD_Neonates_SynthSeg_T2Only.zip -O /opt/nnUNet/nnUNet_raw_data_base/nnUNet_trained_models/nnUNet/Task515_BCP_ABCD_Neonates_SynthSeg_T2Only.zip
+RUN cd /opt/nnUNet/nnUNet_raw_data_base/nnUNet_trained_models/nnUNet && \
+    unzip -qq Task512_BCP_ABCD_Neonates_SynthSegDownsample.zip && \
+    unzip -qq Task514_BCP_ABCD_Neonates_SynthSeg_T1Only.zip && \
+    unzip -qq Task515_BCP_ABCD_Neonates_SynthSeg_T2Only.zip
 COPY run.py /home/cabinet/run.py
 COPY src /home/cabinet/src
 COPY bin /home/cabinet/bin
@@ -131,6 +136,6 @@ RUN cp /home/cabinet/run.py /home/cabinet/cabinet
 
 RUN cd /home/cabinet/ && pip install -r requirements.txt 
 RUN cd /home/cabinet/ && chmod 555 -R run.py bin src parameter-file-application.json parameter-file-container.json cabinet data
-RUN chmod 666 /opt/nnUNet/nnUNet_raw_data_base/nnUNet_trained_models/nnUNet/3d_fullres/Task512_BCP_ABCD_Neonates_SynthSegDownsample/nnUNetTrainerV2__nnUNetPlansv2.1/postprocessing.json
+RUN chmod 666 /opt/nnUNet/nnUNet_raw_data_base/nnUNet_trained_models/nnUNet/3d_fullres/Task*/nnUNetTrainerV2__nnUNetPlansv2.1/postprocessing.json
 
 ENTRYPOINT ["cabinet"]
diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@ This [BIDS App](https://bids-apps.neuroimaging.io/about/) provides the utility o
 
 <br />
 
-![CABINET - Stages for MRI Processing](https://user-images.githubusercontent.com/102316699/198738919-189a8c5b-d58f-40c6-9734-01d9a966e219.png)
+![CABINET - Stages for MRI Processing](https://user-images.githubusercontent.com/102316699/200946315-4983870b-9c8e-4a5f-b344-47d0e1d674c1.png)
 
 
 <br />
@@ -41,7 +41,7 @@ Container hosted here: https://hub.docker.com/r/dcanumn/cabinet
 
 #### Docker
 
-    docker pull dcanumn/cabinet
+    docker pull dcanumn/cabinet:t1-only_t2-only
 
 <br />
 
@@ -52,49 +52,74 @@ The BIBSnet portion of CABINET needs a Volta (v), Ampere (a), or Turing (t) NVID
 ### Command-Line Arguments
 
 ```
-usage: CABINET [-h] -jargs PARAMETER_JSON [-participant PARTICIPANT_LABEL] [-age AGE_MONTHS] [-z]
-               [-end {prebibsnet,bibsnet,postbibsnet}] [-ses SESSION] [--overwrite]
-               [-start {prebibsnet,bibsnet,postbibsnet}] [-v] [--script-dir SCRIPT_DIR]
+usage: CABINET [-h] -jargs PARAMETER_JSON [-participant PARTICIPANT_LABEL]
+               [-age AGE_MONTHS] [-end {prebibsnet,bibsnet,postbibsnet}]
+               [-model MODEL] [--overwrite] [-ses SESSION]
+               [-start {prebibsnet,bibsnet,postbibsnet}] [-v] [-z]
+               [--script-dir SCRIPT_DIR]
                bids_dir output_dir {participant}
 
 positional arguments:
-  bids_dir              Valid absolute path to existing base study directory containing BIDS-valid input subject data
-                        directories. Example: /path/to/bids/input/
-  output_dir            Valid absolute path to existing derivatives directory to save each stage's outputs by subject
-                        session into. Example: /path/to/output/derivatives/
-  {participant}         Processing level. Currently the only choice is 'participant'.See BIDS-Apps specification.
+  bids_dir              Valid absolute path to existing base study directory
+                        containing BIDS-valid input subject data directories.
+                        Example: /path/to/bids/input/
+  output_dir            Valid absolute path to existing derivatives directory
+                        to save each stage's outputs by subject session into.
+                        Example: /path/to/output/derivatives/
+  {participant}         Processing level. Currently the only choice is
+                        'participant'. See BIDS-Apps specification.
 
 optional arguments:
   -h, --help            show this help message and exit
   -jargs PARAMETER_JSON, -params PARAMETER_JSON, --parameter-json PARAMETER_JSON
-                        Valid path to existing readable parameter .JSON file. See README.md and example parameter
-                        .JSON files for more information on parameters.
+                        Required. Valid path to existing readable parameter
+                        .JSON file. See README.md and example parameter .JSON
+                        files for more information on parameters.
   -participant PARTICIPANT_LABEL, --subject PARTICIPANT_LABEL, -sub PARTICIPANT_LABEL, --participant-label PARTICIPANT_LABEL
-                        The participant's unique subject identifier, without 'sub-'prefix. Example: 'ABC12345'
+                        The participant's unique subject identifier, without
+                        'sub-' prefix. Example: 'ABC12345'
   -age AGE_MONTHS, -months AGE_MONTHS, --age-months AGE_MONTHS
-                        Positive integer, the participant's age in months. For example, -age 5 would mean the
-                        participant is 5 months old.Include this argument unless the age in months is specified inthe
-                        participants.tsv file inside the BIDS input directory.
-  -z, --brain-z-size    Include this flag to infer participants' brain height (z) using the participants.tsv
-                        brain_z_size column. Otherwise, CABINET will estimate the brain height from the participant
-                        age and averages of a large sample of infant brain heights.
+                        Positive integer, the participant's age in months. For
+                        example, -age 5 would mean the participant is 5 months
+                        old. Include this argument unless the age in months is
+                        specified in the participants.tsv file inside the BIDS
+                        input directory.
   -end {prebibsnet,bibsnet,postbibsnet}, --ending-stage {prebibsnet,bibsnet,postbibsnet}
-                        Name of the stage to run last. By default, this will be the postbibsnet stage. Valid choices:
-                        prebibsnet, bibsnet, postbibsnet
-  -ses SESSION, --session SESSION, --session-id SESSION
-                        The name of the session to processes participant data for, without 'ses-'prefix. Example: baselineyear1
+                        Name of the stage to run last. By default, this will
+                        be the postbibsnet stage. Valid choices: prebibsnet,
+                        bibsnet, postbibsnet
+  -model MODEL, --model-number MODEL, --bibsnet-model MODEL
+                        Model/task number for BIBSnet. By default, this will 
+                        be inferred from CABINET/data/models.csv based on
+                        which data exists in the --bids-dir. BIBSnet will run 
+                        model 514 by default for T1w-only, model 515 for 
+                        T2w-only, and model 512 for both T1w and T2w.
   --overwrite, --overwrite-old
-                        Include this flag to overwrite any previous CABINET outputs in the derivatives sub-
-                        directories. Otherwise, by default CABINET will skip creating any CABINET output files that
-                        already exist in the sub-directories of derivatives.
+                        Include this flag to overwrite any previous CABINET
+                        outputs in the derivatives sub-directories. Otherwise,
+                        by default CABINET will skip creating any CABINET
+                        output files that already exist in the sub-directories
+                        of derivatives.
+  -ses SESSION, --session SESSION, --session-id SESSION
+                        The name of the session to processes participant data
+                        for. Example: baseline_year1
   -start {prebibsnet,bibsnet,postbibsnet}, --starting-stage {prebibsnet,bibsnet,postbibsnet}
-                        Name of the stage to run first. By default, this will be the prebibsnet stage. Valid choices:
-                        prebibsnet, bibsnet, postbibsnet
-  -v, --verbose         Include this flag to print detailed information and every command being run by CABINET to
-                        stdout. Otherwise CABINET will only print warnings, errors, and minimal output.
+                        Name of the stage to run first. By default, this will
+                        be the prebibsnet stage. Valid choices: prebibsnet,
+                        bibsnet, postbibsnet
+  -v, --verbose         Include this flag to print detailed information and
+                        every command being run by CABINET to stdout.
+                        Otherwise CABINET will only print warnings, errors,
+                        and minimal output.
+  -z, --brain-z-size    Include this flag to infer participants' brain height
+                        (z) using the participants.tsv brain_z_size column.
+                        Otherwise, CABINET will estimate the brain height from
+                        the participant age and averages of a large sample of
+                        infant brain heights.
   --script-dir SCRIPT_DIR
-                        Valid path to the existing parent directory of this run.py script. Include this argument if
-                        and only if you are running the script as a SLURM/SBATCH job.
+                        Valid path to the existing parent directory of this
+                        run.py script. Include this argument if and only if
+                        you are running the script as a SLURM/SBATCH job.
 ```
 
 <br />
@@ -109,7 +134,7 @@ The repository contains two parameter files, one recommended to run CABINET insi
 #### "common": parameters used by multiple stages within CABINET
 
 - `"fsl_bin_path"`: string, a valid absolute path to existing `bin` directory in [FMRIB Software Library](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/). Example: `"/opt/fsl-6.0.5.1/bin/"`
-- `"task_id"`: string, the name of the task performed by the participant to processes data for. This parameter can also be `null` for non-task data. Example: `nback`
+- `"task_id"`: string, the name of the task performed by the participant to processes data for. This parameter can also be `null` for non-task data. Example: `nback` (note: this is not utilized by cabinet yet, please designate it as null)
 
 #### "resource_management": parameters to determine resource use when running parallel scripts. These parameters are only needed for nibabies and XCPD.
 
@@ -118,7 +143,6 @@ The repository contains two parameter files, one recommended to run CABINET insi
 - `"nnUNet_predict_path"`: string, a valid path to nnUNet_predict executable file. Example: `"/opt/conda/bin/nnUNet_predict"`
 - `"code_dir"`: string, a valid path to directory containing BIBSnet python wrapper `run.py`. Example: `"/home/cabinet/SW/BIBSnet"`
 - `"singularity_image_path"`: string, a valid path to BIBSnet singularity image `.sif` file: Example: `"/home/cabinet/user/bibsnet.sif"`
-- `"task"`: string naming the BIBSnet task performed by the participant to processes data for. Examples: `"512"`
 
 #### "nibabies": [see here](https://nibabies.readthedocs.io/en/latest/index.html)
 
@@ -154,10 +178,10 @@ This has been primarily tested in Singularity. We are less able to provide techn
 
 ### Application
 
-We do not recommend running `CABINET` outside of the container for the following:
-1. Installing nnU-Net can be complicated
-2. Running it inside the container ensures you have the proper versions of all softwares
-3. It is hard to diagnose your errors if you are working in a different environment
+We do not recommend running `CABINET` outside of the container for the following reasons:
+1. Installing nnU-Net can be complicated.
+2. Running `CABINET` inside the container ensures you have the proper versions of all software.
+3. It is hard to diagnose your errors if you are working in a different environment.
 
 However, if you run `CABINET` outside of the container as an application, then you will need to do the following:
 1. Download the `data` directory from the `https://s3.msi.umn.edu/CABINET_data/data.zip` URL, unzip it, and move it into your cloned `CABINET` repository directory here: `CABINET/data/`
@@ -181,9 +205,18 @@ NOTE: `sub-` and `ses-` prefixes are currently required for `participant_id` and
 
 When running multiple subjects and/or sessions, the `participants.tsv` file in the `bids_dir` must include an `age` column. In that column, each row has one positive integer, the participant's age in months at that session.
 
-If the user wants to specify the brain height (shown below) for each subject session, then the user must also include an additional `"brain_z_size"` column. That column also must have a positive integer for each row, which is the size of the participant's brain along the z-axis in millimeters. Without a `brain_z_size` column, `CABINET` will calculate the `brain_z_size` value based on a table with [BCP](https://babyconnectomeproject.org/) participants' average head radius per age. That table is called `age_to_avg_head_radius_BCP.csv` under the `data` directory.
+<br />
+<img src="https://user-images.githubusercontent.com/102316699/184005162-0b1ebb76-3e5a-4bd3-b258-a686272e2ecc.png" width=555em style="margin-left: auto; margin-right: auto; display: block" />
+<br />
+
+If the user wants to specify the brain height (shown above) for each subject session, then the user must also include an additional `"brain_z_size"` column. That column also must have a positive integer for each row: the size of the participant's brain along the z-axis in millimeters. The `participants.tsv` file should look like the example below:
 
-<center><img src="https://user-images.githubusercontent.com/102316699/184005162-0b1ebb76-3e5a-4bd3-b258-a686272e2ecc.png" width=555em></center>
+| participant_id | session | age | brain_z_size |
+|:-:|:-:|:-:|:-:|
+| sub-123456 | ses-X | 1 | 120 |
+| sub-234567 | ses-X | 6 | 145 |
+
+Without a `brain_z_size` column, `CABINET` will calculate the `brain_z_size` value based on a table with [BCP](https://babyconnectomeproject.org/) participants' average head radius per age. That table is called `age_to_avg_head_radius_BCP.csv` under the `data` directory.
 
 <br />
 
@@ -203,6 +236,16 @@ Prepares the anatomical BIDS images for BIBSnet segmentation generation.
 
 Quickly and accurately segments an optimally-aligned T1 and T2 pair with a deep neural network trained via nnU-Net and SynthSeg with a large 0 to 8 month old infant MRI brain dataset.
 
+### BIBSnet Segmentation Models
+
+`data/models.csv` lists all available BIBSnet models to run. Below are the default BIBSnet models, all trained on manually-segmented 0- to 8-month-old BCP subjects' segmentations. 
+
+| Model | Description |
+|:-:|:--|
+| 512 | Default T1w and T2w model |
+| 514 | Default T1w-only model |
+| 515 | Default T2w-only model |
+
 <br />
 
 ## 3. PostBIBSnet

diff --git a/data/models.csv b/data/models.csv
@@ -0,0 +1,6 @@
+model_num,T1w,T2w,is_default,description,sørensen_dice_coefficient,image_augmentation,details
+512,TRUE,TRUE,TRUE,"Default model for both T1w and T2w",0.85,TRUE,"https://github.com/DCAN-Labs/dcan-nn-unet/blob/main/doc/tasks/512/Task512.md"
+513,TRUE,TRUE,FALSE,"Same as 512, but no image augmentation",0.89,FALSE,"https://github.com/DCAN-Labs/dcan-nn-unet/blob/main/doc/tasks/513/Task513.md"
+514,TRUE,FALSE,TRUE,"T1-only model","https://github.com/DCAN-Labs/dcan-nn-unet/blob/main/doc/tasks/514/514-by-age.md",TRUE,"https://github.com/DCAN-Labs/dcan-nn-unet/blob/main/doc/tasks/514/514.md"
+515,FALSE,TRUE,TRUE,"T2-only model","https://github.com/DCAN-Labs/dcan-nn-unet/blob/main/doc/tasks/515/515-by-age.md",TRUE,"https://github.com/DCAN-Labs/dcan-nn-unet/blob/main/doc/tasks/515/515.md"
+526,TRUE,TRUE,FALSE,"Same as 512, but trained on all data. No test set.","not applicable",TRUE,"not applicable"
diff --git a/parameter-file-application.json b/parameter-file-application.json
@@ -16,9 +16,7 @@
     "bibsnet": {
         "model": "3d_fullres",
         "nnUNet_predict_path": "/home/support/public/torch_cudnn8.2/bin/nnUNet_predict",
-        "code_dir": "/home/faird/shared/code/internal/pipelines/bibsnet/BIBSnet",
-        "singularity_image_path": "/home/feczk001/gconan/placeholder.txt",
-        "task": "512"
+        "code_dir": "/home/faird/shared/code/internal/pipelines/bibsnet/BIBSnet"
     },
 
     "nibabies": {

diff --git a/parameter-file-container.json b/parameter-file-container.json
@@ -16,9 +16,7 @@
     "bibsnet": {
         "model": "3d_fullres",
         "nnUNet_predict_path": "/opt/conda/bin/nnUNet_predict",
-        "code_dir": "/home/cabinet/SW/BIBSnet",
-        "singularity_image_path": "/home/feczk001/gconan/placeholder.txt",
-        "task": "512"
+        "code_dir": "/home/cabinet/SW/BIBSnet"
     },
 
     "nibabies": {