Rename "T1w" space to "anat"

[tsalo]

This stems from https://github.com/poldracklab/fmriprep/pull/2233#issuecomment-670717199, in which @effigies proposed that the T1w space should be renamed to "individual", to match BIDS terminology for participant-specific anatomical space (see here).

[effigies]

Thanks, Taylor. @oesteban, do you agree?

[oesteban]

I'm not particularly against it, but names will be considerably longer - which is not great.

[tsalo]

Would this apply to workflow names and variables as well? E.g., fmriprep.registration.init_bold_t1_trans_wf() --> fmriprep.registration.init_bold_individual_trans_wf().

EDIT: I assume we wouldn't use the scanner term in the code, since scanner can refer to native space for any datatype.

[effigies]

I think it would just be derivatives.

I'm okay with not doing this, if space-T1w is still BIDS conformant.

[oesteban]

BTW, if we push for individual, we'll need to update the config (see nipreps/niworkflows#540)

[tsalo]

I'd like to revisit this given that, in Nibabies, the primary anatomical modality may be T1w or T2w, so a general space label would be helpful for post-processing pipelines like XCP-D. This came up recently for QSIPrep/QSIRecon as well: https://github.com/PennLINC/qsiprep/issues/853.

I'm not sure anyone wants to use "individual" specifically, but what about something like space-anat?

[effigies]

I think anat is reasonable. We're increasingly using it internally to be T1w/T2w-agnostic.

[tsalo]

That sounds great. It seems like this could end up being distinct from T1w or T2w (at least for the secondary anatomical contrast). For example, with fMRIPrep, where T1w is the primary anatomical contrast, we could end up with the following:

sub-X_desc-preproc_T1w.nii.gz  # native T1w space
sub-X_desc-preproc_T2w.nii.gz  # native T2w space, different from T1w space
sub-X_space-anat_desc-preproc_T1w.nii.gz  # same as sub-X_desc-preproc_T1w.nii.gz
sub-X_space-anat_desc-preproc_T2w.nii.gz  # in native T1w space

For Nibabies, where T2w is the primary anatomical contrast, space-anat and T2w without a space entity would be the same instead:

sub-X_desc-preproc_T1w.nii.gz  # native T1w space
sub-X_desc-preproc_T2w.nii.gz  # native T2w space, different from T1w space
sub-X_space-anat_desc-preproc_T1w.nii.gz  # in native T2w space
sub-X_space-anat_desc-preproc_T2w.nii.gz  # same as sub-X_desc-preproc_T2w.nii.gz

[effigies]

I'd probably rather apply it everywhere than imply which image defines the space in other images by omitting it for the defining image.

[effigies]

Ah, just reread, and I agree with your post.

[tsalo]

@mgxd does this sound good to you for Nibabies?

[mgxd]

Since we support having either the T1w or T2w as the reference template, it's a bit trickier. ATM, the T1w/T2w labels are helpful when ingesting incoming precomputed derivatives, such as BIBSNet outputs (which produces masks/aseg files for both modalities if available).

[tsalo]

In Nibabies' case, whichever is the reference template would be the "anat" space. I could be misunderstanding the situation with BIBSNet. At least for XCP-D, looking for different contrasts based on the "anat" space would be much easier than the current approach, which involves looking for _T1w, _T2w, space-T2w_T1w, and space-T1w_T2w, and the combinations thereof (see here).

[mgxd]

Ah, guess I also misread your suggestion - adding space-anat in addition to space-T1w and space-T2w as a convenience for the anatomical template would be nice.

Is the idea to then apply space-anat to downstream outputs (segmentations, masks, etc)? If so, this will still affect the derivatives parsing in nibabies resulting in some ingestion heuristic like:

- Check for {space-anat} files
- Check metadata? to match to relevant modality (T1w/T2w)
- Check for {space-T1w} / {space-T2w} files (i.e. precomputed brain mask / aseg)

[tsalo]

I was hoping to use space-anat on downstream outputs as well. We could use the mod entity in cases where we expect multiple versions (from different contrasts) in anat space.

EDIT: Although, having just one anat-space brain mask, for example, would be much easier to deal with than modality-specific ones.

I am a little worried about duplicate files, but we could just not write out the same file with space-anat and no space entity. For example, if you have T2w as your primary anatomical contrast, you could either have sub-01_desc-preproc_T2w.nii.gz and sub-01_space-anat_desc-preproc_T2w.nii.gz even though they'd be the same image, or you could just have sub-01_space-anat_desc-preproc_T2w.nii.gz.

Here's what I was thinking the derivative files could look like (note the use of mod in the brain masks, which could also be applied to segmentations if necessary):

Scenario 1: T1w is primary anatomical contrast (fMRIPrep)

# Images
sub-01_desc-preproc_T1w.nii.gz                    # native T1w space. Diff from native T2w space.
sub-01_desc-preproc_T2w.nii.gz                    # native T2w space. Diff from native T1w space.
sub-01_space-T1w_mod-T1w_desc-brain_mask.nii.gz
sub-01_space-T2w_mod-T2w_desc-brain_mask.nii.gz
sub-01_space-anat_desc-preproc_T1w.nii.gz         # same as native T1w image
sub-01_space-anat_desc-preproc_T2w.nii.gz
sub-01_space-anat_mod-T1w_desc-brain_mask.nii.gz  # same as native T1w brain mask
sub-01_space-anat_mod-T2w_desc-brain_mask.nii.gz

# Transforms
sub-01_from-MNIInfant+1_to-anat_mode-image_xfm.h5
sub-01_from-T1w_to-anat_mode-image_xfm.h5         # identity
sub-01_from-T2w_to-anat_mode-image_xfm.h5
sub-01_from-anat_to-MNIInfant+1_mode-image_xfm.h5
sub-01_from-anat_to-T1w_mode-image_xfm.h5         # identity
sub-01_from-anat_to-T2w_mode-image_xfm.h5
sub-01_from-anat_to-fsnative_mode-image_xfm.txt
sub-01_from-fsnative_to-anat_mode-image_xfm.txt

Scenario 2: T2w is primary anatomical contrast (Nibabies)

# Images
sub-01_desc-preproc_T1w.nii.gz                    # native T1w space. Diff from native T2w space.
sub-01_desc-preproc_T2w.nii.gz                    # native T2w space. Diff from native T1w space.
sub-01_space-T1w_mod-T1w_desc-brain_mask.nii.gz
sub-01_space-T2w_mod-T2w_desc-brain_mask.nii.gz
sub-01_space-anat_desc-preproc_T1w.nii.gz
sub-01_space-anat_desc-preproc_T2w.nii.gz         # same as native T2w image
sub-01_space-anat_mod-T1w_desc-brain_mask.nii.gz
sub-01_space-anat_mod-T2w_desc-brain_mask.nii.gz  # same as native T2w brain mask

# Transforms
sub-01_from-MNIInfant+1_to-anat_mode-image_xfm.h5
sub-01_from-T1w_to-anat_mode-image_xfm.h5
sub-01_from-T2w_to-anat_mode-image_xfm.h5         # identity
sub-01_from-anat_to-MNIInfant+1_mode-image_xfm.h5
sub-01_from-anat_to-T1w_mode-image_xfm.h5
sub-01_from-anat_to-T2w_mode-image_xfm.h5         # identity
sub-01_from-anat_to-fsnative_mode-image_xfm.txt
sub-01_from-fsnative_to-anat_mode-image_xfm.txt