ENH: fsLR output space, cifti output in HCP grayordinate space

.circleci/config.yml

@@ -395,7 +395,7 @@ jobs:
                 --sloppy --write-graph --use-syn-sdc --mem_mb 4096 \
                 --use-aroma \
                 --skull-strip-template OASIS30ANTs:res-1 \
-                --output-spaces MNI152NLin2009cAsym fsaverage5 fsnative MNI152NLin6Asym anat \
+                --output-spaces fsLR MNI152NLin2009cAsym fsaverage5 fsnative MNI152NLin6Asym anat \
                 --use-plugin /home/circleci/src/fmriprep/.circleci/legacy.yml \
                 --nthreads 2 --cifti-output -vv
       - run:
@@ -422,7 +422,7 @@ jobs:
                 /tmp/data/ds005 /tmp/ds005/derivatives_partial participant \
                 --fs-subjects-dir /tmp/ds005/freesurfer \
                 --sloppy --write-graph --use-syn-sdc --mem_mb 4096 \
-                --output-spaces MNI152NLin2009cAsym fsaverage5 fsnative MNI152NLin6Asym anat \
+                --output-spaces fsLR MNI152NLin2009cAsym fsaverage5 fsnative MNI152NLin6Asym anat \
                 --aroma-melodic-dimensionality 2 --use-aroma \
                 --nthreads 2 --cifti-output -vv
       - run:

.circleci/ds005_outputs.txt

@@ -51,13 +51,17 @@ 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
-fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_bold.dtseries.nii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_desc-confounds_regressors.json
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_desc-confounds_regressors.tsv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_desc-MELODIC_mixing.tsv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-fsaverage5_hemi-L.func.gii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-fsaverage5_hemi-R.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-fsaverage_hemi-L.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-fsaverage_hemi-R.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-fsLR_den-32k_hemi-L.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-fsLR_den-32k_hemi-R.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-fsLR_den-91k_bold.dtseries.json
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-fsLR_den-91k_bold.dtseries.nii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-fsnative_hemi-L.func.gii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-fsnative_hemi-R.func.gii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-MNI152NLin2009cAsym_boldref.nii.gz
@@ -83,13 +87,17 @@ fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-T1w_desc-brain_ma
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-T1w_desc-preproc_bold.json
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-T1w_desc-preproc_bold.nii.gz
 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
-fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_bold.dtseries.nii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_desc-confounds_regressors.json
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_desc-confounds_regressors.tsv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_desc-MELODIC_mixing.tsv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsaverage5_hemi-L.func.gii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsaverage5_hemi-R.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsaverage_hemi-L.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsaverage_hemi-R.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsLR_den-32k_hemi-L.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsLR_den-32k_hemi-R.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsLR_den-91k_bold.dtseries.json
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsLR_den-91k_bold.dtseries.nii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsnative_hemi-L.func.gii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsnative_hemi-R.func.gii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin2009cAsym_boldref.nii.gz

.circleci/ds005_partial_outputs.txt

@@ -51,13 +51,17 @@ 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
-fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_bold.dtseries.nii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_desc-confounds_regressors.json
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_desc-confounds_regressors.tsv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_desc-MELODIC_mixing.tsv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsaverage5_hemi-L.func.gii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsaverage5_hemi-R.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsaverage_hemi-L.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsaverage_hemi-R.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsLR_den-32k_hemi-L.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsLR_den-32k_hemi-R.func.gii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsLR_den-91k_bold.dtseries.json
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsLR_den-91k_bold.dtseries.nii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsnative_hemi-L.func.gii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsnative_hemi-R.func.gii
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-MNI152NLin2009cAsym_boldref.nii.gz

Dockerfile

@@ -75,6 +75,7 @@ RUN apt-get update && \
                     fsl-mni152-templates=5.0.7-2 \
                     afni=16.2.07~dfsg.1-5~nd16.04+1 \
                     convert3d \
+                    connectome-workbench \
                     git-annex-standalone && \
     apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 

REFERENCES.md

@@ -29,6 +29,7 @@
 | Framewise displacement | | https://nipype.readthedocs.io/en/latest/interfaces/generated/nipype.algorithms.confounds.html#framewisedisplacement |
 | **Other**
 | a/tCompCor | https://doi.org/10.1016/j.neuroimage.2007.04.042 | http://nipype.readthedocs.io/en/latest/interfaces/generated/nipype.algorithms.confounds.html#compcor |
+| Connectome Workbench | | https://humanconnectome.org/software/connectome-workbench
 | phdiff2fmap | https://doi.org/10.1006/nimg.2001.1054 | https://fmriprep.readthedocs.io/en/stable/sdc/estimation.html#fmriprep.interfaces.fmap.phdiff2fmap |
 | nibabel | https://doi.org/10.5281/zenodo.60808 | https://github.com/nipy/nibabel/ |
 | nilearn | https://doi.org/10.3389/fninf.2014.00014 | https://github.com/nilearn/nilearn/ |

docs/links.rst

@@ -12,6 +12,7 @@
 .. _AFNI: https://afni.nimh.nih.gov/
 .. _GIFTI: https://www.nitrc.org/projects/gifti/
 .. _`Connectome Workbench`: https://www.humanconnectome.org/software/connectome-workbench.html
+.. _`HCP Pipelines`: https://humanconnectome.org/software/hcp-mr-pipelines/
 .. _`Docker wrapper`: https://pypi.python.org/pypi/fmriprep-docker
 .. _`Docker Engine`: https://www.docker.com/products/container-runtime
 .. _`Docker installation`: https://docs.docker.com/install/

docs/outputs.rst

@@ -17,7 +17,7 @@ Derivatives specification (see `BIDS Derivatives RC1`_).
 2. **Derivatives (preprocessed data)** the input fMRI data ready for
    analysis, i.e., after the various preparation procedures
    have been applied.
-   For example, :abbr:`INU (intensity non-uniformity)`-corrected versions 
+   For example, :abbr:`INU (intensity non-uniformity)`-corrected versions
    of the T1-weighted image (per subject), the brain mask,
    or :abbr:`BOLD (blood-oxygen level dependent)`
    images after head-motion correction, slice-timing correction and aligned into
@@ -140,20 +140,26 @@ mid-thickness surface mesh::
 
 Surface output spaces include ``fsnative`` (full density subject-specific mesh),
 ``fsaverage`` and the down-sampled meshes ``fsaverage6`` (41k vertices) and
-``fsaverage5`` (10k vertices, default).
+``fsaverage5`` (10k vertices, default). Additionally, the BOLD can be resampled to
+``fsLR`` surfaces, a hybrid version of the ``fsaverage`` atlas with both hemispheres
+in precise geographic correspondence, with varying mesh densities: 32k (default), 59k, and 164k.
 
 **Grayordinates files**.
 CIFTI is a container format that holds both volumetric (regularly sampled in a grid)
 and surface (sampled on a triangular mesh) samples.
-Sub-cortical time series are volumetric (supported spaces: ``MNI152NLin2009cAsym``), while cortical
-time series are sampled on the surface (supported spaces: ``fsaverage5``, ``fsaverage6``).
-If CIFTI outputs are requested (with the ``--cifti-outputs`` argument),
-the BOLD series are also saved as ``dtseries.nii`` CIFTI2 files::
+Sub-cortical time series are volumetric (supported spaces: ``MNI152NLin6Asym``), while cortical
+time series are sampled to surface (supported spaces: ``fsLR``).
+If CIFTI outputs are requested (with the ``--cifti-outputs`` argument), the BOLD series are also
+saved as ``dtseries.nii`` CIFTI2 files::
 
   sub-<subject_label>/
     func/
       sub-<subject_label>_[specifiers]_bold.dtseries.nii
 
+CIFTI output resolution can be specified as an optional parameter after ``--cifti-output``.
+By default, '91k' outputs are produced and match up to the standard `HCP Pipelines`_ CIFTI
+output (91282 grayordinates @ 2mm). However, '170k' outputs are also possible, and produce
+higher resolution CIFTI output (170494 grayordinates @ 1.6mm).
 
 **Extracted confounding time series**.
 For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with *fMRIPrep*, an
@@ -231,7 +237,7 @@ Confound regressors description
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 **Basic confounds**. The most commonly used confounding time series:
 
-- Estimated head-motion parameters: 
+- Estimated head-motion parameters:
   ``trans_x``, ``trans_y``, ``trans_z``, ``rot_x``, ``rot_y``, ``rot_z`` - the 6 rigid-body motion
   parameters (3 translations and 3 rotation), estimated relative to a reference image;
 

docs/spaces.rst

@@ -50,7 +50,8 @@ 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``).
+modifier would be preferred (i.e., ``fsaverage:den-10k`` for ``fsaverage5``). When
+selecting ``fsLR`` surface space without a density label, ``fsLR:den-32k`` will be used.
 
 Custom standard spaces
 """"""""""""""""""""""

docs/workflows.rst

@@ -538,6 +538,15 @@ Surfaces are generated for the "subject native" surface, as well as transformed
 ``fsaverage`` template space.
 All surface outputs are in GIFTI format.
 
+HCP Grayordinates
+~~~~~~~~~~~~~~~~~
+If CIFTI output is enabled, the motion-corrected functional timeseries (in T1w space) is first
+sampled to the high resolution 164k vertex (per hemisphere) ``fsaverage``. Following that,
+the resampled timeseries is sampled to `HCP Pipelines_`'s ``fsLR`` mesh (with the left and
+right hemisphere aligned) using `Connectome Workbench`_'s ``-metric-resample`` to generate a
+surface timeseries for each hemisphere. These surfaces are then combined with corresponding
+volumetric timeseries to create a CIFTI2 file.
+
 .. _bold_confounds:
 
 Confounds estimation

fmriprep/cli/run.py

@@ -232,8 +232,11 @@ def get_parser():
     g_surfs.add_argument('--no-submm-recon', action='store_false', dest='hires',
                          help='disable sub-millimeter (hires) reconstruction')
     g_surfs_xor = g_surfs.add_mutually_exclusive_group()
-    g_surfs_xor.add_argument('--cifti-output', action='store_true', default=False,
-                             help='output BOLD files as CIFTI dtseries')
+    g_surfs_xor.add_argument('--cifti-output', nargs='?', const='91k', default=False,
+                             choices=('91k', '170k'),
+                             help='output preprocessed BOLD as a CIFTI dense timeseries. '
+                             'Optionally, the number of grayordinate can be specified '
+                             '(default is 91k, which equates to 2mm resolution)')
     g_surfs_xor.add_argument('--fs-no-reconall',
                              action='store_false', dest='run_reconall',
                              help='disable FreeSurfer surface preprocessing.')
@@ -700,14 +703,6 @@ def parse_spaces(opts):
     # Set the default template to 'MNI152NLin2009cAsym'
     output_spaces = opts.output_spaces or OrderedDict([('MNI152NLin2009cAsym', {})])
 
-    FS_SPACES = set(['fsnative', 'fsaverage', 'fsaverage6', 'fsaverage5'])
-    if opts.run_reconall and not list(FS_SPACES.intersection(output_spaces.keys())):
-        print("""\
-Although ``--fs-no-reconall`` was not set (i.e., FreeSurfer is to be run), no FreeSurfer \
-output space (valid values are: %s) was selected. Adding default "fsaverage5" to the \
-list of output spaces.""" % ', '.join(FS_SPACES), file=stderr)
-        output_spaces['fsaverage5'] = {}
-
     # Validity of some inputs
     # ERROR check if use_aroma was specified, but the correct template was not
     if opts.use_aroma and 'MNI152NLin6Asym' not in output_spaces:
@@ -717,18 +712,32 @@ def parse_spaces(opts):
 The argument "MNI152NLin6Asym:res-2" has been automatically added to the list of output spaces \
 (option ``--output-spaces``).""", file=stderr)
 
-    if opts.cifti_output and 'MNI152NLin2009cAsym' not in output_spaces:
-        if 'MNI152NLin2009cAsym' not in output_spaces:
-            output_spaces['MNI152NLin2009cAsym'] = {'res': 2}
-            print("""Option ``--cifti-output`` requires functional images to be resampled to \
-``MNI152NLin2009cAsym`` space. Such template identifier has been automatically added to the \
-list of output spaces (option "--output-space").""", file=stderr)
-        if not [s for s in output_spaces if s in ('fsaverage5', 'fsaverage6')]:
-            output_spaces['fsaverage5'] = {}
-            print("""Option ``--cifti-output`` requires functional images to be resampled to \
-``fsaverage`` space. The argument ``fsaverage:den-10k`` (a.k.a ``fsaverage5``) has been \
-automatically added to the list of output spaces (option ``--output-space``).""", file=stderr)
+    if opts.cifti_output:
+        grayords = {'91k': '32k', '170k': '59k'}  # CIFTI total grayords to surface densities
+        output_spaces['fsLR'] = {'den': grayords[opts.cifti_output]}
+        if 'MNI152NLin6Asym' not in output_spaces:
+            output_spaces['MNI152NLin6Asym'] = {'res': '2'}
+            print("""\
+Option ``--cifti-output`` requires functional images to be resampled to \
+``MNI152NLin6Asym`` space. This space has been automatically added to the list of output \
+spaces (option ``--output-spaces``).""", file=stderr)
+
+    if 'fsLR' in output_spaces:
+        output_spaces['fsLR'] = {'den': output_spaces.get('fsLR', {}).get('den') or '32k'}
+        # resample to fsLR from highest density fsaverage
+        output_spaces['fsaverage'] = {'den': '164k'}
+        print("""\
+To generate "fsLR" surfaces, functional images are first resampled to ``fsaverage:den-164k``. \
+This space has been automatically added to the list of output spaces \
+(option ``--output-spaces``).""", file=stderr)
 
+    FS_SPACES = set(('fsnative', 'fsaverage', 'fsaverage6', 'fsaverage5'))
+    if opts.run_reconall and not FS_SPACES.intersection(output_spaces.keys()):
+        print("""\
+Although ``--fs-no-reconall`` was not set (i.e., FreeSurfer is to be run), no FreeSurfer \
+output space (valid values are: %s) was selected. Adding default "fsaverage5" to the \
+list of output spaces.""" % ', '.join(FS_SPACES), file=stderr)
+        output_spaces['fsaverage5'] = {}
     return output_spaces