.. include:: links.rst .. _output-spaces: Defining standard and nonstandard spaces where data will be resampled ===================================================================== The command line interface of *PETPrep* allows resampling the preprocessed data onto other output spaces. That is achieved using the ``--output-spaces`` argument, where standard and nonstandard spaces can be inserted. .. important:: *PETPrep* writes derivatives only for the output spaces listed in ``--output-spaces``. Some options may add internal spaces required by the workflow, but those spaces are not written as derivatives unless they are also requested explicitly. .. _TemplateFlow: *TemplateFlow* """""""""""""" *TemplateFlow* is a software library and a repository of neuroimaging templates that allows end-user applications such as *PETPrep* to flexibly query and pull template and atlas information. In other words, *TemplateFlow* enables *PETPrep* to access a wide range of templates (and also custom templates, see below). Therefore, *TemplateFlow* is central to define *PETPrep*'s interface regarding template and atlas prior-knowledge. For more general information about *TemplateFlow*, visit `TemplateFlow.org `__. Standard spaces """"""""""""""" When using *PETPrep* in a workflow that will investigate effects that span across analytical groupings, neuroimagers typically resample their data onto a standard, stereotactic coordinate system. The most widely used standard space for PET analyses is generally referred to as MNI. For instance, to instruct *PETPrep* to use the MNI template brain distributed with FSL as coordinate reference the option will read as follows: ``--output-spaces MNI152NLin6Asym``. By default, *PETPrep* writes derivatives in ``MNI152NLin2009cAsym`` at native PET resolution and in the individual anatomical reference (``T1w``). Valid template identifiers (``MNI152NLin6Asym``, ``MNI152NLin2009cAsym``, etc.) come from the `TemplateFlow repository `__. For each requested standard output space, *PETPrep* will resample the preprocessed PET data into that space, labeling the corresponding outputs with the ``space-`` BIDS entity. By default, the resampled outputs keep the original resolution of the PET data to produce smaller files, more consistent with the original data gridding. However, many users will be interested in utilizing a coarse gridding (typically 2mm isotropic) of the target template. Such a behavior can be achieved applying modifiers to the template identifier, separated by a ``:`` character. For instance, ``--output-spaces MNI152NLin6Asym:res-2 MNI152NLin2009cAsym`` will generate preprocessed PET 4D files on two standard spaces (``MNI152NLin6Asym``, and ``MNI152NLin2009cAsym``) with the template's 2mm isotropic resolution for the data on ``MNI152NLin6Asym`` space and the original PET resolution (say, e.g., 2x2x2.5 [mm]) for the case of ``MNI152NLin2009cAsym``. This is equivalent to saying ``--output-spaces MNI152NLin6Asym:res-2 MNI152NLin2009cAsym:res-native``. .. danger:: Please remember that the ``resolution`` entity of *TemplateFlow* is an **index**, and therefore, ``res-2`` does not necessarily mean 2mm isotropic - although, it coincidentally does in the example above. However, it may not be the case. For instance, ``MNI152NLin6Asym:res-3`` contains a template with 0.5mm isotropic voxels. Other possible modifiers are, for instance, the ``cohort`` selector. For instance, ``--output-spaces MNIPediatricAsym:res-1:cohort-2`` selects the resolution ``1`` of ``cohort-2`` which, for the ``MNIPediatricAsym`` template, corresponds to the `prepuberty phase `__ (4.5--8.5 years old). Space modifiers such as ``res`` are combinatorial: ``--output-spaces MNIPediatricAsym:cohort-1:cohort-2:res-native:res-1`` will generate conversions for the following combinations: * cohort ``1`` and "native" resolution (meaning, the original PET resolution), * cohort ``1`` and resolution ``1`` of the template, * cohort ``2`` and "native" resolution (meaning, the original PET resolution), and * cohort ``2`` and resolution ``1`` of the template. Please mind that the selected resolutions specified must exist within TemplateFlow. When specifying surface spaces (e.g., ``fsaverage``), the legacy identifiers from FreeSurfer will be supported (e.g., ``fsaverage5``) although the use of the density modifier would be preferred (i.e., ``fsaverage:den-10k`` for ``fsaverage5``). Custom standard spaces """""""""""""""""""""" To make your custom templates visible by *PETPrep*, and usable via the ``--output-spaces`` argument, please store your template under *TemplateFlow*'s home directory. The default *TemplateFlow*'s home directory is ``$HOME/.cache/templateflow`` and that path can be changed by setting the ``$TEMPLATEFLOW_HOME`` environment variable. A minimal example of the necessary files for a template called ``MyCustom`` (and therefore callable via, e.g., ``--output-spaces MyCustom``) follows:: $TEMPLATEFLOW_HOME/ tpl-MyCustom/ template_description.json tpl-MyCustom_res-1_T1w.nii.gz tpl-MyCustom_res-1_desc-brain_mask.nii.gz tpl-MyCustom_res-2_T1w.nii.gz tpl-MyCustom_res-2_desc-brain_mask.nii.gz For further information about how custom templates must be organized and corresponding naming, please check `the TemplateFlow tutorials `__. Nonstandard spaces """""""""""""""""" Additionally, ``--output-spaces`` accepts identifiers of spatial references that do not generate *standardized* coordinate spaces: * ``T1w`` or ``anat``: data are resampled into the individual's anatomical reference generated with the T1w and T2w images available within the BIDS structure. * ``fsnative``: similarly to the ``anat`` space for volumetric references, including the ``fsnative`` space will instruct *PETPrep* to sample the original PET data onto FreeSurfer's reconstructed surfaces for this individual. * ``petref`` requests PET data in the PET reference grid. For multi-frame PET series, the preprocessed PET output is resampled into this grid with head-motion correction applied. Modifiers are not allowed when providing nonstandard spaces. Preprocessing blocks depending on standard templates """""""""""""""""""""""""""""""""""""""""""""""""""" Some modules of the pipeline operate in specific template spaces even when those spaces are not requested as derivatives. *PETPrep* always adds ``MNI152NLin2009cAsym`` to the internal list of spaces because several workflows require that anatomical normalization. If CIFTI outputs are requested with ``--cifti-output``, *PETPrep* also adds ``MNI152NLin6Asym`` internally at the resolution required by the selected grayordinates density. Atlas-based segmentation options selected with ``--seg`` may also add the corresponding atlas template to the list of spaces so that the atlas and its labels can be warped into anatomical space. Spaces added only to satisfy these workflow requirements are used internally. They are not written as PET derivatives unless the space was also explicitly requested with ``--output-spaces``.