ENH: Allow multiple {non,}standard spaces (--output-spaces)

.circleci/config.yml

@@ -381,6 +381,7 @@ jobs:
                 -e FMRIPREP_DEV 1 -u $(id -u) \
                 --config $PWD/nipype.cfg -w /tmp/ds005/work \
                 /tmp/data/ds005 /tmp/ds005/derivatives participant \
+                --output-spaces MNI152NLin2009cAsym MNI152NLin6Asym \
                 --sloppy --write-graph --mem_mb 4096 \
                 --nthreads 2 --anat-only -vv
       - run:

.circleci/ds005_outputs.txt

@@ -17,9 +17,11 @@ fmriprep/sub-01/anat/sub-01_desc-preproc_T1w.json
 fmriprep/sub-01/anat/sub-01_desc-preproc_T1w.nii.gz
 fmriprep/sub-01/anat/sub-01_dseg.nii.gz
 fmriprep/sub-01/anat/sub-01_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5
+fmriprep/sub-01/anat/sub-01_from-MNI152NLin6Asym_to-T1w_mode-image_xfm.h5
 fmriprep/sub-01/anat/sub-01_from-orig_to-T1w_mode-image_xfm.txt
 fmriprep/sub-01/anat/sub-01_from-T1w_to-fsnative_mode-image_xfm.txt
 fmriprep/sub-01/anat/sub-01_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5
+fmriprep/sub-01/anat/sub-01_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5
 fmriprep/sub-01/anat/sub-01_hemi-L_inflated.surf.gii
 fmriprep/sub-01/anat/sub-01_hemi-L_midthickness.surf.gii
 fmriprep/sub-01/anat/sub-01_hemi-L_pial.surf.gii
@@ -39,6 +41,14 @@ fmriprep/sub-01/anat/sub-01_space-MNI152NLin2009cAsym_dseg.nii.gz
 fmriprep/sub-01/anat/sub-01_space-MNI152NLin2009cAsym_label-CSF_probseg.nii.gz
 fmriprep/sub-01/anat/sub-01_space-MNI152NLin2009cAsym_label-GM_probseg.nii.gz
 fmriprep/sub-01/anat/sub-01_space-MNI152NLin2009cAsym_label-WM_probseg.nii.gz
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_desc-brain_mask.json
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_desc-brain_mask.nii.gz
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_desc-preproc_T1w.json
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_desc-preproc_T1w.nii.gz
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_dseg.nii.gz
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_label-CSF_probseg.nii.gz
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_label-GM_probseg.nii.gz
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_label-WM_probseg.nii.gz
 fmriprep/sub-01/func
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_AROMAnoiseICs.csv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_bold.dtseries.json
@@ -57,6 +67,14 @@ fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-MNI152NLin2009cAs
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-MNI152NLin2009cAsym_desc-preproc_bold.json
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-MNI152NLin2009cAsym_desc-smoothAROMAnonaggr_bold.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-MNI152NLin6Asym_boldref.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-MNI152NLin6Asym_desc-aparcaseg_dseg.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-MNI152NLin6Asym_desc-aseg_dseg.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-MNI152NLin6Asym_desc-brain_mask.json
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-MNI152NLin6Asym_desc-brain_mask.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-MNI152NLin6Asym_desc-preproc_bold.json
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-MNI152NLin6Asym_desc-preproc_bold.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-MNI152NLin6Asym_desc-smoothAROMAnonaggr_bold.nii.gz
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-T1w_boldref.nii.gz
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-T1w_desc-aparcaseg_dseg.nii.gz
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-T1w_desc-aseg_dseg.nii.gz
@@ -81,6 +99,14 @@ fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin2009cAs
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin2009cAsym_desc-preproc_bold.json
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin2009cAsym_desc-smoothAROMAnonaggr_bold.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_boldref.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_desc-aparcaseg_dseg.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_desc-aseg_dseg.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_desc-brain_mask.json
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_desc-brain_mask.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_desc-preproc_bold.json
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_desc-preproc_bold.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_desc-smoothAROMAnonaggr_bold.nii.gz
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-T1w_boldref.nii.gz
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-T1w_desc-aparcaseg_dseg.nii.gz
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-T1w_desc-aseg_dseg.nii.gz

.circleci/ds005_partial_outputs.txt

@@ -17,9 +17,11 @@ fmriprep/sub-01/anat/sub-01_desc-preproc_T1w.json
 fmriprep/sub-01/anat/sub-01_desc-preproc_T1w.nii.gz
 fmriprep/sub-01/anat/sub-01_dseg.nii.gz
 fmriprep/sub-01/anat/sub-01_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5
+fmriprep/sub-01/anat/sub-01_from-MNI152NLin6Asym_to-T1w_mode-image_xfm.h5
 fmriprep/sub-01/anat/sub-01_from-orig_to-T1w_mode-image_xfm.txt
 fmriprep/sub-01/anat/sub-01_from-T1w_to-fsnative_mode-image_xfm.txt
 fmriprep/sub-01/anat/sub-01_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5
+fmriprep/sub-01/anat/sub-01_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5
 fmriprep/sub-01/anat/sub-01_hemi-L_inflated.surf.gii
 fmriprep/sub-01/anat/sub-01_hemi-L_midthickness.surf.gii
 fmriprep/sub-01/anat/sub-01_hemi-L_pial.surf.gii
@@ -39,6 +41,14 @@ fmriprep/sub-01/anat/sub-01_space-MNI152NLin2009cAsym_dseg.nii.gz
 fmriprep/sub-01/anat/sub-01_space-MNI152NLin2009cAsym_label-CSF_probseg.nii.gz
 fmriprep/sub-01/anat/sub-01_space-MNI152NLin2009cAsym_label-GM_probseg.nii.gz
 fmriprep/sub-01/anat/sub-01_space-MNI152NLin2009cAsym_label-WM_probseg.nii.gz
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_desc-brain_mask.json
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_desc-brain_mask.nii.gz
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_desc-preproc_T1w.json
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_desc-preproc_T1w.nii.gz
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_dseg.nii.gz
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_label-CSF_probseg.nii.gz
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_label-GM_probseg.nii.gz
+fmriprep/sub-01/anat/sub-01_space-MNI152NLin6Asym_label-WM_probseg.nii.gz
 fmriprep/sub-01/func
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_AROMAnoiseICs.csv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_bold.dtseries.json
@@ -57,6 +67,14 @@ fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin2009cAs
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin2009cAsym_desc-preproc_bold.json
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin2009cAsym_desc-smoothAROMAnonaggr_bold.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_boldref.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_desc-aparcaseg_dseg.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_desc-aseg_dseg.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_desc-brain_mask.json
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_desc-brain_mask.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_desc-preproc_bold.json
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_desc-preproc_bold.nii.gz
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin6Asym_desc-smoothAROMAnonaggr_bold.nii.gz
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-T1w_boldref.nii.gz
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-T1w_desc-aparcaseg_dseg.nii.gz
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-T1w_desc-aseg_dseg.nii.gz

Dockerfile

@@ -164,10 +164,11 @@ ENV TEMPLATEFLOW_HOME="/opt/templateflow"
 RUN mkdir -p $TEMPLATEFLOW_HOME
 RUN pip install --no-cache-dir "templateflow>=0.1.3,<0.2.0a0" && \
     python -c "from templateflow import api as tfapi; \
-               tfapi.get('MNI152Lin'); \
+               tfapi.get('MNI152NLin6Asym'); \
                tfapi.get('MNI152NLin2009cAsym'); \
-               tfapi.get('OASIS30ANTs'); \
-               tfapi.get('NKI');"
+               tfapi.get('OASIS30ANTs');" && \
+    find $TEMPLATEFLOW_HOME -type d -exec chmod go=u {} + && \
+    find $TEMPLATEFLOW_HOME -type f -exec chmod go=u {} +
 
 # Installing dev requirements (packages that are not in pypi)
 WORKDIR /src/

docs/citing.rst

@@ -250,10 +250,6 @@ Presentations
 Other relevant references
 -------------------------
 
-  .. [Fonov2011] Fonov VS, Evans AC, Botteron K, Almli CR, McKinstry RC, Collins DL and BDCG,
-      Unbiased average age-appropriate atlases for pediatric studies, NeuroImage 54(1), 2011
-      doi:`10.1016/j.neuroimage.2010.07.033 <https://doi.org/10.1016/j.neuroimage.2010.07.033>`_.
-
   .. [Power2017] Power JD, Plitt M, Kundu P, Bandettini PA, Martin A (2017) Temporal interpolation alters
       motion in fMRI scans: Magnitudes and consequences for artifact detection. PLOS ONE 12(9): e0182939.
       doi:`10.1371/journal.pone.0182939 <https://doi.org/10.1371/journal.pone.0182939>`_.

docs/environment.yml

@@ -28,7 +28,7 @@ dependencies:
     - svgutils
     - nitime
     - nilearn!=0.5.0,!=0.5.1
+    - git+https://github.com/poldracklab/niworkflows.git@e8f677a0407fc312b7f3d87a4c47726ceb8cd975#egg=niworkflows
     - tedana>=0.0.5
-    - git+https://github.com/effigies/niworkflows.git@e6a277ee5e47be5f8148b136b7201c9beb8e70a3#egg=niworkflows
     - smriprep<0.3.0a0,>=0.2.0
     - templateflow<0.2.0a0,>=0.1.3

docs/usage.rst

@@ -7,7 +7,7 @@ Usage
    As of FMRIPREP 1.0.12, the software includes a tracking system
    to report usage statistics and errors. Users can opt-out using
    the ``--notrack`` command line argument.
-   
+
 
 Execution and the BIDS format
 =============================
@@ -38,6 +38,110 @@ Command-Line Arguments
    :nodefaultconst:
 
 
+.. _output-spaces:
+
+Defining standard and nonstandard spaces where data will be resampled
+=====================================================================
+
+The command line interface of fMRIPrep 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.
+
+Standard spaces
+"""""""""""""""
+
+When using fMRIPrep in a workflow that will investigate effects that span across
+analytical groupings, neuroimagers typically resample their data on to a standard,
+stereotactic coordinate system.
+The most extended standard space for fMRI analyses is generally referred to MNI.
+For instance, to instruct fMRIPrep to use the MNI template brain distributed with
+FSL as coordinate reference the option will read as follows: ``--output-spaces MNI152NLin6Asym``.
+By default, fMRIPrep uses ``MNI152NLin2009cAsym`` as spatial-standardization reference.
+Valid template identifiers (``MNI152NLin6Asym``, ``MNI152NLin2009cAsym``, etc.) come from
+the `TemplateFlow project <https://github.com/templateflow/templateflow>`__.
+
+Therefore, fMRIPrep will run nonlinear registration processes against the template
+T1w image corresponding to all the standard spaces supplied with the argument
+``--output-spaces``.
+By default, fMRIPrep will resample the preprocessed data on those spaces (labeling the
+corresponding outputs with the `space-<template-identifier>` BIDS entity) but keeping
+the original resolution of the BOLD 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 BOLD 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 BOLD resolution
+(say, e.g., 2x2x2.5 [mm]) for the case of ``MNI152NLin2009cAsym``.
+
+Other possible modifiers are, for instance, the ``cohort`` selector.
+Although currently there is no template in TemplateFlow with several cohorts,
+very soon we will integrate pediatric templates, for which ``cohort`` will
+function to select the appropriate age range.
+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.
+
+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
+""""""""""""""""""""""
+
+Although the functionality is not available yet, the interface of the
+``--output-spaces`` permits providing paths to custom templates that
+follow TemplateFlow's naming conventions
+(e.g. ``/path/to/custom/templates/tpl-MyCustom:res-2``).
+Following the example, at least the following files
+must be found under under ``/path/to/custom/templates/tpl-MyCustom``: ::
+
+  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
+
+Although a more comprehensive coverage of standard files would be advised.
+
+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 fMRIPrep to sample the
+    original BOLD data onto FreeSurfer's reconstructed surfaces for this
+    individual.
+  * **Additional nonstandard spaces** that will be supported in the future are
+    ``run``, ``func``, and ``sbref``.
+
+Modifiers are not allowed when providing nonstandard spaces.
+
+Preprocessing blocks depending on standard templates
+""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Some modules of the pipeline (e.g. the ICA-AROMA denoising, the generation of
+HCP compatible *grayordinates* files, or the *fieldmap-less* distortion correction)
+operate in specific template spaces.
+When selecting those modules to be included (using any of the following flags:
+``--use-aroma``, ``--cifti-outputs``, ``--use-syn-sdc``) will modify the list of
+output spaces to include the space identifiers they require, should the
+identifier not be found within the ``--output-spaces`` list already.
+In other words, running fMRIPrep with ``--output-spaces MNI152NLin6Asym:res-2
+--use-syn-sdc`` will expand the list of output spaces to be
+``MNI152NLin6Asym:res-2 MNI152NLin2009cAsym``.
+
+
 The docker wrapper CLI
 ======================
 
@@ -85,7 +189,7 @@ make your data available within that system first.
 
 For instance, here at the Poldrack Lab we use Stanford's
 :abbr:`HPC (high-performance computing)` system, called Sherlock.
-Sherlock enables `the following data transfer options 
+Sherlock enables `the following data transfer options
 <https://www.sherlock.stanford.edu/docs/user-guide/storage/data-transfer/>`_.
 
 Alternatively, more comprehensive solutions such as `Datalad