Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

workflow updates to allow T2w without T1w #153

Merged
merged 18 commits into from
Jan 12, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .github/workflows/python-testing.yml
Original file line number Diff line number Diff line change
Expand Up @@ -77,5 +77,11 @@ jobs:
- name: Test cropseg bids, with path override, left hemi
run: |
$HIPPUNFOLD - test_out participant -np --modality cropseg --path_cropseg test_data/data_cropseg_1hemi/sub-{subject}_hemi-{hemi}_dseg.nii.gz --hemi L
- name: Test T2w with T1w template registration
run: |
$HIPPUNFOLD test_data/bids_singleT2w test_out participant -np --modality T2w --t1_reg_template
- name: Test T2w with additional T1w output space
run: |
$HIPPUNFOLD test_data/bids_singleT2w test_out participant -np --modality T2w --output_space T1w


34 changes: 12 additions & 22 deletions docs/tutorials/standardBIDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,37 +20,40 @@ prefixing the command with `singularity run`. This will expect
└── sub-002/
...

The `--modality` flag is required to specify which input image type should be used and in most cases, T1w should be most robust (though other types are supported!).

The T1w image is used to register to a standardized
template (CITI168), making it possible to reorient, upsample, and crop
around the left and right hippocampi (this is referred to within
HippUnfold as `space-corobl`). Note that only the T1w image needs to
have a whole-brain field of view. By default, any additional input images
are coregistered and preprocessed, but this can be skipped with the
flags `--skip_coreg` and `--skip_preproc`, repsectively.
HippUnfold as `space-corobl`). Note that the T1w image should
have a whole-brain field of view.

More examples of possible BIDS-compliant datasets can be found in
[hippunfold/test\_data/](https://github.com/khanlab/hippunfold/tree/master/test_data).

## Different input modalities

By default, HippUnfold expects the `PATH_TO_BIDS_DIR` to contain at least
one T1w file for segmenting intrahippocampal
structures like the SRLM. However, we have
also provided models trained with T1w, T2w, or DWI data, or, users can input
their own custom manual segmentations for unfolding, which can be
specified with the `--modality` flag. For example:

hippunfold PATH_TO_BIDS_DIR PATH_TO_OUTPUT_DIR participant --modality T1w
hippunfold PATH_TO_BIDS_DIR PATH_TO_OUTPUT_DIR participant --modality T2w

would work for a dataset with only T1w images, like this one:
would work for a dataset with only T2w images, like this one:

PATH_TO_BIDS_DIR/
└── sub-001/
└── anat/
└── sub-001_T1w.nii.gz
└── sub-001_T2w.nii.gz
...

Note that specifying a manual segmentation (eg. `--modality segT1w`)
expects to additionally find a file with the suffix `_dseg` which should
Note that in this case, registration to a T2w CITI168 template will be performed with the input T2w image. In some cases it may be preferrable to use a T1w image for registration to the standard CITI168 template. A T1w image can be registered to both the input T2w and T1w CITI168 template with the `--t1_reg_template` flag. This is typically most robust as long as a full brain FOV T1w image is available. If this registering is still failing then it may be improved with the `--rigid-reg-template` flag.

Specifying a manual segmentation (eg. `--modality segT1w`)
expects to additionally find an input file with the suffix `_dseg` which should
contain labels following the protocol outlined
[here](https://ars.els-cdn.com/content/image/1-s2.0-S1053811917309977-mmc1.pdf).
More details are provided on using manual segmentations on the following
Expand Down Expand Up @@ -84,17 +87,4 @@ This will search for any any files following the naming scheme and fill
in `{subject}` IDs for any files it can. Alternatively, `{subject}` IDs
can be provided in a list with the `--participant_label` flag.

## No T1w images

It is difficult to automatically reorient and crop images appropriately
without a whole-brain T1w image, which we recommend collecting as a part
of any acquisition protocol when possible. However, if this is not
possible, the T2w image may be used instead by specifying it as the T1w
with the `--path_T1w` flag. This registration may fail, and is
especially likely to fail if the T2w images are not whole-brain. This
can sometimes be ameliorated with the `--rigid_reg_template` flag.

Alternatively, if you do not have a standard T1w scan, consider manually
orienting and/or cropping your data and following the examples outlined
in the [Specialized scans
tutorial](specializedScans.md).
20 changes: 10 additions & 10 deletions hippunfold/config/snakebids.yml
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,6 @@ parse_args:
- segT1w
- segT2w
- cropseg
- neonateT1w

--derivatives:
help: 'Path to the derivatives folder (e.g. for finding manual segs) (default: %(default)s) '
Expand Down Expand Up @@ -179,7 +178,10 @@ parse_args:
default: 'CITI168'
help: 'Set the template to use for registration to coronal oblique. (default: %(default)s)'


--t1_reg_template:
help: 'Use T1w to register to template space, instead of the segmentation modality. Note: this was the default behavior prior to v1.0.0. (default: %(default)s)'
default: false
action: store_true

--use_gpu:
help: 'Enable gpu for inference by setting resource gpus=1 in run_inference rule (default: %(default)s)'
Expand All @@ -193,12 +195,9 @@ parse_args:

--output_spaces:
choices:
- 'cropT1w'
- 'corobl'
default:
- 'cropT1w'
- 'T1w'
nargs: '+'
help: 'Sets the output space for results (default: %(default)s)'
help: 'Sets additional output spaces for results (default: %(default)s)'

--output_density:
choices:
Expand Down Expand Up @@ -261,10 +260,11 @@ singularity:
ants: 'docker://kaczmarj/ants:2.3.4'

xfm_identity: resources/identity_xfm.txt
template: dHCP
template: CITI168
template_files:
CITI168:
T1w: resources/CITI168/T1w_head_700um.nii.gz
T2w: resources/CITI168/T2w_head_700um.nii.gz
xfm_corobl: resources/CITI168/CoronalOblique_rigid.txt
crop_ref: resources/CITI168/T2w_300umCoronalOblique_hemi-{hemi}.nii.gz
crop_refT1w: resources/CITI168/T1w_300umCoronalOblique_hemi-{hemi}.nii.gz
Expand Down Expand Up @@ -399,7 +399,6 @@ laplace_labels:


output_spaces:
- cropT1w

participant_label:
exclude_participant_label:
Expand All @@ -418,4 +417,5 @@ skip_coreg: False
keep_work: False
skip_inject_template_labels: False
force_nnunet_model: False
root: results
t1_reg_template: False
root: results
Binary file not shown.
64 changes: 53 additions & 11 deletions hippunfold/workflow/Snakefile
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,63 @@ from snakebids import bids
configfile: "config/snakebids.yml"


# make adjustments to input params:
# right now hippb500 or cropseg cannot use T1w output space
if config["modality"] == "hippb500" or config["modality"] == "cropseg":
config["output_spaces"] = ["corobl"]
# consider moving this logic to another smk file to clean-up

if config["skip_inject_template_labels"]:
config["autotop_labels"] = ["hipp"]

# get list of inputs to limit to (T1w + modalities)
limit_to_list = set()
if "cropT1w" in config["output_spaces"]:
ref_spaces = []
crop_ref_spaces = []
template_modality = False

# if no additional output spaces chosen, then empty list:
if config["output_spaces"] == None:
config["output_spaces"] = []

# set the lists used for output spaces
if (
config["modality"] == "T1w"
or config["modality"] == "segT1w"
or "T1w" in config["output_spaces"]
):
ref_spaces.append("T1w")
crop_ref_spaces.append("cropT1w")
limit_to_list.add("T1w")
if (
config["modality"] == "T2w"
or config["modality"] == "segT2w"
or "T2w" in config["output_spaces"]
):
ref_spaces.append("T2w")
crop_ref_spaces.append("cropT2w")
limit_to_list.add("T2w")
if (
config["modality"] == "hippb500"
or config["modality"] == "cropseg"
or "corobl" in config["output_spaces"]
):
ref_spaces.append("corobl")
crop_ref_spaces.append("corobl")


# set the modality to use for template registration
if "T2w" in config["modality"]:
if config["t1_reg_template"]:
limit_to_list.add("T1w")
template_modality = "T1w"
else:
template_modality = "T2w"

elif "T1w" in config["modality"]:
template_modality = "T1w"


# only generate hipp surface if skipping template injection
# i.e. drop dentate
if config["skip_inject_template_labels"]:
config["autotop_labels"] = ["hipp"]


if config["modality"][:3] == "seg": # if modality is segT2w, then add seg and T2w
# add seg (if chosen) and the modality to the inputs
if config["modality"][:3] == "seg": # if modality is segT2w, then add seg
limit_to_list.add("seg")
limit_to_list.add(config["modality"][3:])
else:
Expand Down Expand Up @@ -95,7 +137,7 @@ include: "rules/warps.smk"
include: "rules/shape_inject.smk"
include: "rules/gifti.smk"
include: "rules/subfields.smk"
include: "rules/resample_final_to_crop_t1.smk"
include: "rules/resample_final_to_crop_native.smk"


rule all:
Expand Down
Loading