@@ -37,6 +37,107 @@ Command-Line Arguments
3737 :nodefault:
3838 :nodefaultconst:
3939
40+ Defining standard and nonstandard spaces where data will be resampled
41+ =====================================================================
42+
43+ The command line interface of fMRIPrep allows resampling the preprocessed data
44+ onto other output spaces.
45+ That is achieved using the ``--output-spaces `` argument, where standard and
46+ nonstandard spaces can be inserted.
47+
48+ Standard spaces
49+ ---------------
50+
51+ When using fMRIPrep in a workflow that will investigate effects that span across
52+ analytical groupings, neuroimagers typically resample their data on to a standard,
53+ stereotactic coordinate system.
54+ The most extended standard space for fMRI analyses is generally referred to MNI.
55+ For instance, to instruct fMRIPrep to use the MNI template brain distributed with
56+ FSL as coordinate reference the option will read as follows: ``--output-spaces MNI152NLin6Asym ``.
57+ By default, fMRIPrep uses ``MNI152NLin2009cAsym `` as spatial-standardization reference.
58+ Valid template identifiers (``MNI152NLin6Asym ``, ``MNI152NLin2009cAsym ``, etc.) come from
59+ the `TemplateFlow project <https://github.com/templateflow/templateflow >`__.
60+
61+ Therefore, fMRIPrep will run nonlinear registration processes against the template
62+ T1w image corresponding to all the standard spaces supplied with the argument
63+ ``--output-spaces ``.
64+ By default, fMRIPrep will resample the preprocessed data on those spaces (labeling the
65+ corresponding outputs with the `space-<template-identifier> ` BIDS entity) but keeping
66+ the original resolution of the BOLD data to produce smaller files, more consistent with
67+ the original data gridding.
68+ However, many users will be interested in utilizing a coarse gridding (typically 2mm isotropic)
69+ of the target template.
70+ Such a behavior can be achieved applying modifiers to the template identifier, separated by
71+ a ``: `` character.
72+ For instance, ``--output-spaces MNI152NLin6Asym:res-2 MNI152NLin2009cAsym `` will generate
73+ preprocessed BOLD 4D files on two standard spaces (``MNI152NLin6Asym ``,
74+ and ``MNI152NLin2009cAsym ``) with the template's 2mm isotropic resolution for
75+ the data on ``MNI152NLin6Asym `` space and the original BOLD resolution
76+ (say, e.g., 2x2x2.5 [mm]) for the case of ``MNI152NLin2009cAsym ``.
77+
78+ Other possible modifiers are, for instance, the ``cohort `` selector.
79+ Although currently there is no template in TemplateFlow with several cohorts,
80+ very soon we will integrate pediatric templates, for which ``cohort `` will
81+ function to select the appropriate age range.
82+ Therefore, in upcoming versions of fMRIPrep, it will be possible to run it with
83+ ``--output-spaces MNIPediatricAsym:res-2:cohort-2 `` where ``cohort-2 `` would select
84+ the template instance for the, say, 24-48 months old range.
85+
86+ When specifying surface spaces (e.g. ``fsaverage ``), the legacy identifiers from
87+ FreeSurfer will be supported (e.g. ``fsaverage5 ``) although the use of the density
88+ modifier would be preferred (i.e. ``fsaverage:den-10k `` for ``fsaverage5 ``).
89+
90+ Custom standard spaces
91+ ----------------------
92+
93+ Although the functionality is not available yet, the interface of the
94+ ``--output-spaces `` permits providing paths to custom templates that
95+ follow TemplateFlow's naming conventions
96+ (e.g. ``/path/to/custom/templates/tpl-MyCustom:res-2 ``).
97+ Following the example, at least the following files
98+ must be found under under ``/path/to/custom/templates/tpl-MyCustom ``: ::
99+
100+ tpl-MyCustom/
101+ template_description.json
102+ tpl-MyCustom_res-1_T1w.nii.gz
103+ tpl-MyCustom_res-1_desc-brain_mask.nii.gz
104+ tpl-MyCustom_res-2_T1w.nii.gz
105+ tpl-MyCustom_res-2_desc-brain_mask.nii.gz
106+
107+ Although a more comprehensive coverage of standard files would be advised.
108+
109+ Nonstandard spaces
110+ ------------------
111+
112+ Additionally, ``--output-spaces `` accepts identifiers of spatial references
113+ that do not generate *standardized * coordinate spaces:
114+
115+ * ``T1w `` or ``anat ``: data are resampled into the individual's anatomical
116+ reference generated with the T1w and T2w images available within the
117+ BIDS structure.
118+ * ``fsnative ``: similarly to the ``anat `` space for volumetric references,
119+ including the ``fsnative `` space will instruct fMRIPrep to sample the
120+ original BOLD data onto FreeSurfer's reconstructed surfaces for this
121+ individual.
122+ * **Additional nonstandard spaces ** that will be supported in the future are
123+ ``run ``, ``func ``, and ``sbref ``.
124+
125+ Modifiers are not allowed when providing nonstandard spaces.
126+
127+ Preprocessing blocks depending on standard templates
128+ ----------------------------------------------------
129+
130+ Some modules of the pipeline (e.g. the ICA-AROMA denoising, the generation of
131+ HCP compatible *grayordinates * files, or the *fieldmap-less * distortion correction)
132+ perform on specific template spaces.
133+ When selecting those modules to be included (using any of the following flags:
134+ ``--use-aroma ``, ``--cifti-outputs ``, ``--use-syn-sdc ``) will modify the list of
135+ output spaces to include the space identifiers they require, should the
136+ identifier not be found within the ``--output-spaces `` list already.
137+ In other words, running fMRIPrep with ``--output-spaces MNI152NLin6Asym:res-2
138+ --use-syn-sdc `` will expand the list of output spaces to be
139+ ``MNI152NLin6Asym:res-2 MNI152NLin2009cAsym ``.
140+
40141
41142The docker wrapper CLI
42143======================
0 commit comments