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

Syntax for --output-spaces - specify (non)standard spaces #1604

Closed
oesteban opened this issue May 3, 2019 · 8 comments
Closed

Syntax for --output-spaces - specify (non)standard spaces #1604

oesteban opened this issue May 3, 2019 · 8 comments
Labels
effort: medium Estimated medium effort task impact: high Estimated high impact task UX
Milestone

Comments

@oesteban
Copy link
Member

oesteban commented May 3, 2019

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 oesteban added UX impact: high Estimated high impact task effort: medium Estimated medium effort task labels May 3, 2019
@oesteban oesteban added this to To do in pipelines via automation May 3, 2019
@oesteban oesteban moved this from To do to Awaiting for user input in pipelines May 3, 2019
@oesteban
Copy link
Member Author

Related: #1647

@oesteban oesteban added this to the 2.0.0 milestone Jul 11, 2019
@oesteban oesteban pinned this issue Oct 17, 2019
@hhoke
Copy link

hhoke commented Oct 28, 2019

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
Copy link
Member Author

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
Copy link

hhoke commented Oct 28, 2019

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 oesteban changed the title Nonstandard spaces Syntax for --output-spaces - specify (non)standard spaces Dec 3, 2019
@oesteban
Copy link
Member Author

oesteban commented Dec 4, 2019

@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
Copy link
Contributor

utooley commented Dec 5, 2019

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
Copy link
Member Author

oesteban commented Dec 5, 2019

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
Copy link
Contributor

utooley commented Dec 5, 2019

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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
effort: medium Estimated medium effort task impact: high Estimated high impact task UX
Projects
None yet
Development

No branches or pull requests

4 participants