Skip to content

Commit

Permalink
(Still buggy) finalizing merge
Browse files Browse the repository at this point in the history 
Merge branch 'main' of github.com:DCAN-Labs/CABINET into merging

- CABINET can now run multiple subjects/sessions or subjects with no sessions
- Added issue templates
- BIDSified the application by moving args from param file to argparse
- Updated README.md to reflect these changes
- Implemented age-to-average-head-radius inference from table

Conflicts:
	README.md
  • Loading branch information
@GregConan
GregConan committed Aug 23, 2022
2 parents 0c9380d + 7e99600 commit 820ac10
Show file tree
Hide file tree
Showing 7 changed files with 169 additions and 217 deletions.
40 changes: 40 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
name: Bug Report
description: File a report to help us improve
labels: ["bug", "triage"]
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to fill out this bug report!
- type: textarea
id: what-happened
attributes:
label: What happened?
description: Also tell us, what did you expect to happen?
placeholder: Tell us what you see!
validations:
required: true
- type: textarea
id: command
attributes:
label: What command did you use?
description: This helps us replicate the problem. This will be automatically formatted into code, so no need for backticks.
render: shell
validations:
required: true
- type: input
id: version
attributes:
label: What version of CABINET are you using?
validations:
required: true
- type: textarea
id: logs
attributes:
label: Relevant log output
description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
render: shell
- type: textarea
id: addinfo
attributes:
label: Add any additional information or context about the problem here.
5 changes: 5 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
blank_issues_enabled: true
contact_links:
- name: Questions
url: https://github.com/CABINET
about: Please ask and answer questions related to CABINET usage here.
29 changes: 29 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
name: Feature Request
description: Suggest an idea for this project
labels: ["enhancement"]
body:
- type: markdown
attributes:
value: |
Ideas for improvements are always appreciated!
- type: textarea
id: summary
attributes:
label: A short summary of what you would like to see in CABINET.
validations:
required: true
- type: dropdown
id: interest
attributes:
label: Do you have any interest in helping implement the feature?
description: Help is always welcome :)
options:
- Yes!
- Yes, but I would need guidance
- No :(
validations:
required: true
- type: textarea
id: addinfo
attributes:
label: Add any additional information or context about the request here.
180 changes: 92 additions & 88 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,28 +10,37 @@ This [BIDS App](https://bids-apps.neuroimaging.io/about/) provides the utility o
4. [Nibabies](https://nibabies.readthedocs.io/en/latest/index.html) (FUTURE)
5. [XCP-D](https://xcp-d.readthedocs.io/en/latest/) (FUTURE)

<br />

![CABINET - Stages for MRI Processing](https://user-images.githubusercontent.com/102316699/177638055-14894a92-9cb6-4a70-a649-71f61d47f3d6.png)

<br />

## Dependencies

docker or singularity (depending on what containerization software you will use for execution)

<br />

## Installation

Developers can benefit from running the application outside of the container for testing. For users interested in producing segmentations, we recommend one use the container instead
We strongly recommend that users interested in producing segmentations run the containerized version of `CABINET`. However, developers may sometimes benefit from running the application outside of the container for testing.

<br />

### Container

Container hosted here:
Container hosted here: https://hub.docker.com/r/dcanumn/cabinet

#### Singularity

singularity pull cabinet.sif docker://path/to/docker/image #TODO FILL IN ACTUAL PATH
singularity pull cabinet.sif docker://dcanumn/cabinet

#### Docker

docker pull path/to/docker/image
docker pull dcanumn/cabinet

<br />

## Usage

Expand All @@ -40,96 +49,66 @@ The BIBSnet portion of CABINET needs a Volta (v), Ampere (a), or Turing (t) NVID
### Command-Line Arguments

```
usage: run.py [-h] -jargs PARAMETER_JSON -participant PARTICIPANT_LABEL [-ses SESSION] [-age AGE_MONTHS] [-v]
[--overwrite] [-start {prebibsnet,bibsnet,postbibsnet}] [-end {prebibsnet,bibsnet,postbibsnet}]
[--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.
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.
-participant PARTICIPANT_LABEL, --subject PARTICIPANT_LABEL, -sub PARTICIPANT_LABEL, --participant-label PARTICIPANT_LABEL
The participant's unique subject
identifier, without 'sub-'prefix.
Example: 'ABC12345'
-ses SESSION, --session SESSION, --session-id SESSION
The name of the session to processes
participant data for. Example:
baseline_year1
-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 in the
participants.tsv file inside the BIDS
input directory.
-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.
--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.
-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
-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
--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.
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]
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.
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.
-participant PARTICIPANT_LABEL, --subject PARTICIPANT_LABEL, -sub PARTICIPANT_LABEL, --participant-label PARTICIPANT_LABEL
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.
-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. Example: baseline_year1
--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.
-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.
--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.
```

### Example paramater file fields: segmentation container
<br />

### Parameter `.JSON` File

The repository contains two parameter files, one recommended to run CABINET inside its container and one recommended to run outside:

- Inside Container: `parameter-file-container.json`
- Outside Container: `parameter-file-application.json`

#### "common": parameters used by multiple stages within CABINET

- `"fsl_bin_path"`: string, a valid absolute path to existing `bin` directory in [FreeSurferLearner (FSL)](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`

#### "resource_management": parameters to determine resource use when running parallel scripts. These parameters are only needed for nibabies and XCPD.
#### "preBIBSnet": parameters used only for the preBIBSnet stage
- `"brain_z_size"`: positive integer, the size of the participant's brain along the z axis in mm. Example: `110`

![brainzsize2](https://user-images.githubusercontent.com/102316699/184005162-0b1ebb76-3e5a-4bd3-b258-a686272e2ecc.png)

#### "BIBSnet": parameters used only for the BIBSnet stage
- `"model"`: string, the model to run. Example: `"3d_fullres"`
Expand All @@ -142,6 +121,7 @@ The BIBSnet portion of CABINET needs a Volta (v), Ampere (a), or Turing (t) NVID

#### "XCPD": [see here](https://xcp-d.readthedocs.io/en/latest/)

<br />

### Container

Expand All @@ -156,7 +136,7 @@ This has been primarily tested in Singularity. We are less able to provide techn
-v /path/to/output:/out \
-v /path/to/param_file.json:param_file.json \
docker_image:version /input /output participant -jargs /param_file.json \
-end postbibsnet --participant_label subject_id -ses session_id -age age_months -v
-end postbibsnet -v


#### Singularity
Expand All @@ -166,9 +146,27 @@ This has been primarily tested in Singularity. We are less able to provide techn
-B /path/to/output:/output \
-B /path/to/param_file.json:/param_file.json \
/home/faird/shared/code/internal/pipelines/cabinet_container/cabinet_1_3_2.sif \
/input /output participant -jargs /param_file.json -end postbibsnet \
--participant_label subject_id -ses session_id -age age_months -v
/input /output participant -jargs /param_file.json -end postbibsnet -v

<br />

### Application

We do not recommend running `CABINET` outside of the container.

<br />

## Multiple Participant Requirements

### `participants.tsv`

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.

<center><img src="https://user-images.githubusercontent.com/102316699/184005162-0b1ebb76-3e5a-4bd3-b258-a686272e2ecc.png" width=555em></center>

<br />

## 1. PreBIBSnet

Expand All @@ -179,11 +177,14 @@ Prepares the anatomical BIDS images for BIBSnet segmentation generation.
3. Crops the neck and shoulders out of the images
4. Registers the T2 to the T1 either via traditional transform or ACPC-alignment. Optimal method gets chosen via eta-squared calculation

<br />

## 2. BIBSnet

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.

<br />

## 3. PostBIBSnet

1. Generates a left-right mask and dilates it
Expand All @@ -192,11 +193,14 @@ Quickly and accurately segments an optimally-aligned T1 and T2 pair with a deep
4. Generates a mask of the segmentation from the native T1 space segmentation
5. Renames the native T1 space segmentation and mask to BIDS standard naming conventions to feed into Nibabies

<br />

## 4. Nibabies (FUTURE)

Infant fmriprep image processing

<br />

## 5. XCP-D (FUTURE)

DCANBOLDProc and Executive Summary
Loading

0 comments on commit 820ac10

Please sign in to comment.