44
55Defining standard and nonstandard spaces where data will be resampled
66=====================================================================
7-
8- The command line interface of fMRIPrep allows resampling the preprocessed data
7+ The command line interface of *fMRIPrep * allows resampling the preprocessed data
98onto other output spaces.
109That is achieved using the ``--output-spaces `` argument, where standard and
1110nonstandard spaces can be inserted.
1211
12+ .. important ::
13+ *fMRIPrep * will reduce the amount of output spaces to just spaces listed in ``--output-spaces ``,
14+ even if other options require resampling the preprocessed data into intermediary spaces.
15+
1316Standard spaces
1417"""""""""""""""
15-
16- When using fMRIPrep in a workflow that will investigate effects that span across
18+ When using *fMRIPrep * in a workflow that will investigate effects that span across
1719analytical groupings, neuroimagers typically resample their data on to a standard,
1820stereotactic coordinate system.
1921The most extended standard space for fMRI analyses is generally referred to MNI.
20- For instance, to instruct fMRIPrep to use the MNI template brain distributed with
22+ For instance, to instruct * fMRIPrep * to use the MNI template brain distributed with
2123FSL as coordinate reference the option will read as follows: ``--output-spaces MNI152NLin6Asym ``.
22- By default, fMRIPrep uses ``MNI152NLin2009cAsym `` as spatial-standardization reference.
24+ By default, * fMRIPrep * uses ``MNI152NLin2009cAsym `` as spatial-standardization reference.
2325Valid template identifiers (``MNI152NLin6Asym ``, ``MNI152NLin2009cAsym ``, etc.) come from
2426the `TemplateFlow project <https://github.com/templateflow/templateflow >`__.
2527
26- Therefore, fMRIPrep will run nonlinear registration processes against the template
28+ Therefore, * fMRIPrep * will run nonlinear registration processes against the template
2729T1w image corresponding to all the standard spaces supplied with the argument
2830``--output-spaces ``.
29- By default, fMRIPrep will resample the preprocessed data on those spaces (labeling the
31+ By default, * fMRIPrep * will resample the preprocessed data on those spaces (labeling the
3032corresponding outputs with the `space-<template-identifier> ` BIDS entity) but keeping
3133the original resolution of the BOLD data to produce smaller files, more consistent with
3234the original data gridding.
@@ -39,14 +41,26 @@ preprocessed BOLD 4D files on two standard spaces (``MNI152NLin6Asym``,
3941and ``MNI152NLin2009cAsym ``) with the template's 2mm isotropic resolution for
4042the data on ``MNI152NLin6Asym `` space and the original BOLD resolution
4143(say, e.g., 2x2x2.5 [mm]) for the case of ``MNI152NLin2009cAsym ``.
44+ This is equivalent to saying
45+ ``--output-spaces MNI152NLin6Asym:res-2 MNI152NLin2009cAsym:res-native ``.
4246
4347Other possible modifiers are, for instance, the ``cohort `` selector.
44- Although currently there is no template in TemplateFlow with several cohorts,
45- very soon we will integrate pediatric templates, for which ``cohort `` will
46- function to select the appropriate age range.
47- Therefore, in upcoming versions of fMRIPrep, it will be possible to run it with
48- ``--output-spaces MNIPediatricAsym:res-2:cohort-2 `` where ``cohort-2 `` would select
49- the template instance for the, say, 24-48 months old range.
48+ For instance, ``--output-spaces MNIPediatricAsym:res-1:cohort-2 `` selects
49+ the resolution ``1 `` of ``cohort-2 `` which, for the ``MNIPediatricAsym ``
50+ template, corresponds to the `prepuberty phase
51+ <https://github.com/templateflow/tpl-MNIPediatricAsym/blob/bcf77616f547f327ee53c01dadf689ab6518a097/template_description.json#L22-L26> `__
52+ (4.5--8.5 years old).
53+
54+ Space modifiers such as ``res `` are combinatorial:
55+ ``--output-spaces MNIPediatricAsym:cohort-1:cohort-2:res-native:res-1 `` will
56+ generate conversions for the following combinations:
57+
58+ * cohort ``1 `` and "native" resolution (meaning, the original BOLD resolution),
59+ * cohort ``1 `` and resolution ``1 `` of the template,
60+ * cohort ``2 `` and "native" resolution (meaning, the original BOLD resolution), and
61+ * cohort ``2 `` and resolution ``1 `` of the template.
62+
63+ Please mind that the selected resolutions specified must exist within TemplateFlow.
5064
5165When specifying surface spaces (e.g., ``fsaverage ``), the legacy identifiers from
5266FreeSurfer will be supported (e.g., ``fsaverage5 ``) although the use of the density
@@ -55,13 +69,12 @@ selecting ``fsLR`` surface space without a density label, ``fsLR:den-32k`` will
5569
5670Custom standard spaces
5771""""""""""""""""""""""
58-
5972Although the functionality is not available yet, the interface of the
6073``--output-spaces `` permits providing paths to custom templates that
6174follow TemplateFlow's naming conventions
6275(e.g., ``/path/to/custom/templates/tpl-MyCustom:res-2 ``).
6376Following the example, at least the following files
64- must be found under under ``/path/to/custom/templates/tpl-MyCustom ``: : :
77+ must be found under under ``/path/to/custom/templates/tpl-MyCustom ``::
6578
6679 tpl-MyCustom/
6780 template_description.json
@@ -74,15 +87,14 @@ Although a more comprehensive coverage of standard files would be advised.
7487
7588Nonstandard spaces
7689""""""""""""""""""
77-
7890Additionally, ``--output-spaces `` accepts identifiers of spatial references
7991that do not generate *standardized * coordinate spaces:
8092
8193 * ``T1w `` or ``anat ``: data are resampled into the individual's anatomical
8294 reference generated with the T1w and T2w images available within the
8395 BIDS structure.
8496 * ``fsnative ``: similarly to the ``anat `` space for volumetric references,
85- including the ``fsnative `` space will instruct fMRIPrep to sample the
97+ including the ``fsnative `` space will instruct * fMRIPrep * to sample the
8698 original BOLD data onto FreeSurfer's reconstructed surfaces for this
8799 individual.
88100 * ``func ``, ``bold ``, ``run ``, ``boldref `` or ``sbref `` can be used to
@@ -96,15 +108,14 @@ Modifiers are not allowed when providing nonstandard spaces.
96108
97109Preprocessing blocks depending on standard templates
98110""""""""""""""""""""""""""""""""""""""""""""""""""""
99-
100111Some modules of the pipeline (e.g., the ICA-AROMA denoising, the generation of
101112HCP compatible *grayordinates * files, or the *fieldmap-less * distortion correction)
102113operate in specific template spaces.
103114When selecting those modules to be included (using any of the following flags:
104115``--use-aroma ``, ``--cifti-outputs ``, ``--use-syn-sdc ``) will modify the list of
105116output spaces to include the space identifiers they require, should the
106117identifier not be found within the ``--output-spaces `` list already.
107- In other words, running fMRIPrep with ``--output-spaces MNI152NLin6Asym:res-2
118+ In other words, running * fMRIPrep * with ``--output-spaces MNI152NLin6Asym:res-2
108119--use-syn-sdc `` will expand the list of output spaces to be
109120``MNI152NLin6Asym:res-2 MNI152NLin2009cAsym ``.
110121
@@ -143,22 +154,19 @@ To do so, follow the next steps.
143154 1. By default, a mirror of *TemplateFlow * to store the resources will be
144155 created in ``$HOME/.cache/templateflow ``.
145156 You can modify such a configuration with the ``TEMPLATEFLOW_HOME ``
146- environment variable, e.g.:
147- ::
148-
157+ environment variable, e.g.::
158+
149159 $ export TEMPLATEFLOW_HOME=$HOME/.templateflow
150-
160+
151161 2. Install the client within your favorite Python 3 environment (this can
152- be done in your login-node, or in a host with Internet access,
153- without need for Docker/Singularity):
154- ::
155-
162+ be done in your login-node, or in a host with Internet access,
163+ without need for Docker/Singularity)::
164+
156165 $ python -m pip install -U templateflow
157-
166+
158167 3. Use the ``get() `` utility of the client to pull down all the templates you'll
159- want to use. For example:
160- ::
161-
168+ want to use. For example::
169+
162170 $ python -c "from templateflow.api import get; get(['MNI152NLin2009cAsym', 'MNI152NLin6Asym', 'OASIS30ANTs', 'MNIPediatricAsym', 'MNIInfant'])"
163171
164172After pulling down the resources you'll need, you will just need to make sure your
0 commit comments