Syntax for ``--output-spaces`` - specify (non)standard spaces

[oesteban]

Comes from https://github.com/poldracklab/fmriprep/pull/1596/files#r280788899

With the implementation of the --output-spaces command line argument, we opened the door to better specify how the user wants their output data in terms of spaces and gridding.

After discussion on #1588, an interface was defined to standard target templates. This issue will focus on specifying the keywords and associated semantics for non-standard spaces.

Currently, fMRIPrep only supports T1w space, which has been given an alias anat. This means that using --output-spaces anat (or --output-spaces T1w), will lead to generating BOLD runs aligned with the anatomical reference created by fMRIPrep. By default, these runs are resampled in their native resolution (i.e., not in the anatomical's resolution).

Here and in #1376, @a3sha2 proposed generating BOLD series in their native space. That would be a new keyword we would need to define (and so on, so forth).

Some ideas I'm currently entertaining is to have run, func and (bold/sb)ref as potential options for such native space. I would shy away from native as we are also using it as a modifier and one could see --output-spaces MNI152Lin:native native which seems weird.

Pinging @satra, @edickie for a BIDS perspective.

[oesteban]

Related: #1647

[hhoke]

Let's say I want to have my EPI data in the T1w space, with 1mm isotropic voxel size. Is there currently a way to do this? I tried the following and it produced 1mm-resolution data in the MNI152NLin2009cAsym space, but the T1w space output used the voxel sizes from the EPI/BOLD data, as usual. (It produced the outputs I described but subsequently crashed because I used 'fs6' instead of 'fsaverage')

singularity run --cleanenv -B /tmp:/tmp /images/fmriprep-1.4.1.simg /subdir/BIDS_SAMPLE_SUBJNAME-fmriprep /subdir/BIDS_SAMPLE_SUBJNAME-fmriprep/derivatives/1.4.1-final participant --participant-label SUBJNAME --work-dir /subdir/BIDS_SAMPLE_SUBJNAME-fmriprep/derivatives/1.4.1-final -vv --omp-nthreads 8 --nthreads 16 --fd-spike-threshold 0.5 --notrack --return-all-components --resource-monitor --output-spaces T1w:res-1 fs6 --template-resampling-grid 1mm --force-bbr --use-syn-sdc --cifti-output --fs-license-file /ncf/nrg/sw/apps/freesurfer/6.0.0/license.txt

[oesteban]

Hi @hhoke, this is a great question. At this point you can't do that. What kind of language would you suggest for the --output-spaces in your use-case?

[hhoke]

That's a shame! It's something we need for our lab's pipeline. What's your timeline for adding this feature? Is it a matter of tacking something on to existing abstractions or will it require serious reworking?

T1w:res-1 seems to make sense to me. I like the idea of being able to specify different resolutions per output space. It was somewhat frustrating that T1w:res-1 actually isn't an available option, but the program started running anyway! Off the top of my head T1w for the default behavior, T1w:res-T1w for matchingT1w and T1w:res-func as a redundant way to get the current default behavior. I'm also somewhat confused as to exactly what --template-resampling-grid 1mm is doing.

[oesteban]

@hhoke The --template-resampling-grid 1mm option will disappear (see #1898)

I think it would be interesting to have more strict rules, with a wider portfolio of behaviors for this command-line argument. @effigies was not in favor of creating a whole new language for this, but I'm afraid we will need to.

I think one should be able to do the following:

--output-spaces \
    MNI152NLIn2009cAsym:res-1:res-2:res-iso1.2mm:res-bold \
    T1w:res-native:res-bold \
    func:res-native:res-iso2.0mm \
    session:res-iso2.0mm

where we have one output in standardized space, one subject space, and two scanner spaces.

Resolutions work as follow:

• res-<label found in template>: uses the given template grid. In case of overlap (e.g., the unfortunate situation where the template has a _res-bold_ component, the template selector takes precedence.
• res-native: the native resolution of this run. So for T1w:res-native this means the T1w-reference's resolution and for func:res-native means this particular BOLD-run's resolution.
• res-IsoX.Xmm: allows generating an isotropic grid if X.X (units) size. Default units would be mm, but that can be changed to other units (I'm thinking of rodents here).

Then, users would be able to concatenate an arbitrary number of res- modifiers, to generate several resamplings of the same data. Then the command above will generate:

• BOLD data in MNI152NLIn2009cAsym space, with 4 different resolutions. Two of them matching the resolution of the res-1 and res-2 variants of the template (direct matching of BIDS-like entity), one with 1.2mm isotropic resolution covering the FoV of the template reference and finally one with whatever it was the original resolution of this BOLD run.
• BOLD data aligned to the same-subject T1w reference, with two resolutions: the T1w template resolution and the BOLD run's.
• BOLD data in its original gridding (func:res-native) and with 2.0mm isotropic resolution (func:res-iso2.0mm).
• BOLD data in a session-subject space. This would only admit the arbitrary isotropic resolution form (runs across the session might have different resolutions).

Regarding the allowed space identifiers, they could take:

• Any template ID in TemplateFlow for standard spaces
• anat or T1w for the T1w anatomical reference
• func for this particular functional run
• session an average space across all bold runs and tasks in the protocol
• task an average space across all runs of each particular task being processed (works with task filtering of the bids query).

I'm just thinking out loud. Opinions to move forward?
/cc @effigies @mgxd @poldracklab/fmriprep-docusprint-leaders

[utooley]

After reading through this once or twice, the general idea seems understandable to me. Two aspects are a little unclear:

1. How would the resolution modifier interact with additional modifiers such as cohort for the pediatric templates? It seems like : is used as a delimiter for both, so would you be looking at MNIPediatricAsym:res-1:res-2:cohort-2 or MNIPediatricAsym:cohort-2:res-1:res-2? The latter makes more sense to me, but the current docs suggest the former.

2. For fMRIprep users who aren't versed in TemplateFlow and where to find the templates, additional explanation in the docs of how to figure out what res-1 and res-2 of a given template actually output might be useful. Also, I assume that res-01 and res-1 evaluate to the same thing (seeing that the pediatric template has res-1 while others have 01).

[oesteban]

Thanks for the super-timely feedback!

• How would the resolution modifier interact with additional modifiers such as cohort for the pediatric templates? It seems like : is used as a delimiter for both, so would you be looking at MNIPediatricAsym:res-1:res-2:cohort-2 or MNIPediatricAsym:cohort-2:res-1:res-2? The latter makes more sense to me, but the current docs suggest the former.

I think the ordering of the cohort selector does not impede a univocal interpretation. But, in relation to #1817, one might want to normalize to two cohorts and have varying sets of outputs:

--output-spaces \
    MNIPediatricAsym:cohort-5:cohort-6:res-2:res-iso1.6mm

Would produce res-2 and 1.6 isotropic outputs in both cohorts (5 and 6). However, if you want different outputs:

--output-spaces \
    MNIPediatricAsym:cohort-5:res-2 \
    MNIPediatricAsym:cohort-6:res-iso1.6mm

Then it will generate the res-2 for the cohort 5 and the 1.6mm isotropic for the cohort 6.

How does this idea sound? And, is there something I'm not seeing about the ordering of the cohort- particle?

• For fMRIprep users who aren't versed in TemplateFlow and where to find the templates, additional explanation in the docs of how to figure out what res-1 and res-2 of a given template actually output might be useful.

Totally. We are working quite a bit on the documentation of TemplateFlow, which will help to describe this, and some updates on fMRIPrep's documentation will be necessary linking to TemplateFlow's.

Also, I assume that res-01 and res-1 evaluate to the same thing (seeing that the pediatric template has res-1 while others have 01).

This is a good point too. By the looks of this bids-standard/bids-specification#301 it seems that the resolution value will not be an index anymore - meaning, TemplateFlow will need to be updated.

[utooley]

I think the ordering of the cohort selector does not impede a univocal interpretation. But, in relation to #1817, one might want to normalize to two cohorts and have varying sets of outputs:

--output-spaces \
    MNIPediatricAsym:cohort-5:cohort-6:res-2:res-iso1.6mm

Would produce res-2 and 1.6 isotropic outputs in both cohorts (5 and 6). However, if you want different outputs:

--output-spaces \
    MNIPediatricAsym:cohort-5:res-2 \
    MNIPediatricAsym:cohort-6:res-iso1.6mm

Then it will generate the res-2 for the cohort 5 and the 1.6mm isotropic for the cohort 6.

How does this idea sound? And, is there something I'm not seeing about the ordering of the cohort- particle?

This sounds great, and is very clear! The place I saw the other order of cohort selector was in the docs, where it specifies that:

Therefore, in upcoming versions of fMRIPrep, it will be possible to run it with --output-spaces MNIPediatricAsym:res-2:cohort-2 where cohort-2 would select the template instance for the, say, 24-48 months old range.

This might lead people to think that you have to first specify res, and then cohort.

Re: TemplateFlow, I had seen that PR and the discussion of how res-<index> could get confusing makes sense to me!