Merge pull request #1040 from oesteban/enh/mni-2mm-resolution

[ENH] Revise resampling grid for template outputs

Author: oesteban

.circleci/config.yml

@@ -330,6 +330,7 @@ jobs:
                 --debug --write-graph --use-syn-sdc --use-aroma \
                 --ignore-aroma-denoising-errors --mem_mb 4096 \
                 --output-space T1w template fsaverage5 \
+                --template-resampling-grid native \
                 --nthreads 2 -vv
             sudo find /tmp/ds005/work -not -name "*.svg" -not -name "*.html" -not -name "*.rst" \
                 -not -name "*.mat" -not -name "*.lta" -type f -delete
@@ -416,6 +417,7 @@ jobs:
                 /tmp/data/ds054 /tmp/ds054/derivatives participant \
                 --fs-no-reconall --debug --force-syn \
                 --output-space T1w template \
+                --template-resampling-grid 2mm \
                 --mem_mb 4096 --nthreads 2 -vv
       - run:
           name: Checking outputs of fMRIPrep
@@ -519,6 +521,7 @@ jobs:
                 --config $PWD/nipype.cfg -w /tmp/ds000210/work \
                 /tmp/data/ds000210 /tmp/ds000210/derivatives participant \
                 --fs-no-reconall --t2s-coreg --use-syn-sdc \
+                --template-resampling-grid native \
                 --debug --write-graph --mem_mb 4096 --nthreads 2 -vv 
       - run:
           name: Checking outputs of fMRIPrep

docs/workflows.rst

@@ -45,7 +45,7 @@ is presented below:
                                 fmap_demean=True,
                                 use_syn=True,
                                 force_syn=True,
-                                output_grid_ref=None,
+                                template_out_grid='native',
                                 use_aroma=False,
                                 ignore_aroma_err=False)
 
@@ -241,7 +241,7 @@ BOLD preprocessing
                               fmap_demean=True,
                               use_syn=True,
                               force_syn=True,
-                              output_grid_ref=None,
+                              template_out_grid='native',
                               use_aroma=False,
                               ignore_aroma_err=False)
 
@@ -449,7 +449,7 @@ EPI to MNI transformation
         template='MNI152NLin2009cAsym',
         mem_gb=1,
         omp_nthreads=1,
-        output_grid_ref=None)
+        template_out_grid='native')
 
 This sub-workflow concatenates the transforms calculated upstream (see
 `Head-motion estimation`_, `Susceptibility Distortion Correction (SDC)`_ --if
@@ -461,6 +461,16 @@ It also maps the T1w-based mask to MNI space.
 Transforms are concatenated and applied all at once, with one interpolation (Lanczos)
 step, so as little information is lost as possible.
 
+The output space grid can be specified using the ``template_out_grid`` argument.
+This option accepts the following (``str``) values:
+
+  * ``'native'``: the original resolution of the BOLD image will be used.
+  * ``'1mm'``: uses the 1:math:`\times`1:math:`\times`1 [mm] version of the template.
+  * ``'2mm'``: uses the 2:math:`\times`2:math:`\times`2 [mm] version of the template.
+  * **Path to arbitrary reference file**: the output will be resampled on a grid with
+    same resolution as this reference.
+
+
 EPI sampled to FreeSurfer surfaces
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 :mod:`fmriprep.workflows.bold.resampling.init_bold_surf_wf`

fmriprep/cli/run.py

@@ -132,8 +132,15 @@ def get_parser():
         choices=['MNI152NLin2009cAsym'], default='MNI152NLin2009cAsym',
         help='volume template space (default: MNI152NLin2009cAsym)')
     g_conf.add_argument(
-        '--output-grid-reference', required=False, action='store', default=None,
-        help='Grid reference image for resampling BOLD files to volume template space. '
+        '--output-grid-reference', required=False, action='store',
+        help='Deprecated after FMRIPREP 1.0.8. Please use --template-resampling-grid instead.')
+    g_conf.add_argument(
+        '--template-resampling-grid', required=False, action='store', default='native',
+        help='Keyword ("native", "1mm", or "2mm") or path to an existing file. '
+             'Allows to define a reference grid for the resampling of BOLD images in template '
+             'space. Keyword "native" will use the original BOLD grid as reference. '
+             'Keywords "1mm" and "2mm" will use the corresponding isotropic template '
+             'resolutions. If a path is given, the grid of that image will be used. '
              'It determines the field of view and resolution of the output images, '
              'but is not used in normalization.')
     g_conf.add_argument(
@@ -416,6 +423,13 @@ def build_workflow(opts, retval):
         uuid=run_uuid)
     )
 
+    template_out_grid = opts.template_resampling_grid
+    if opts.output_grid_reference is not None:
+        logger.warning(
+            'Option --output-grid-reference is deprecated, please use '
+            '--template-resampling-grid')
+        template_out_grid = template_out_grid or opts.output_grid_reference
+
     retval['workflow'] = init_fmriprep_wf(
         subject_list=subject_list,
         task_id=opts.task_id,
@@ -435,7 +449,7 @@ def build_workflow(opts, retval):
         output_spaces=opts.output_space,
         template=opts.template,
         medial_surface_nan=opts.medial_surface_nan,
-        output_grid_ref=opts.output_grid_reference,
+        template_out_grid=template_out_grid,
         hires=opts.hires,
         use_bbr=opts.use_bbr,
         bold2t1w_dof=opts.bold2t1w_dof,

fmriprep/workflows/base.py

@@ -35,7 +35,7 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
                      omp_nthreads, skull_strip_template, work_dir, output_dir, bids_dir,
                      freesurfer, output_spaces, template, medial_surface_nan, hires,
                      use_bbr, bold2t1w_dof, fmap_bspline, fmap_demean, use_syn, force_syn,
-                     use_aroma, ignore_aroma_err, output_grid_ref):
+                     use_aroma, ignore_aroma_err, template_out_grid):
     """
     This workflow organizes the execution of FMRIPREP, with a sub-workflow for
     each subject.
@@ -78,7 +78,7 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
                               force_syn=True,
                               use_aroma=False,
                               ignore_aroma_err=False,
-                              output_grid_ref=None)
+                              template_out_grid='native')
 
 
     Parameters
@@ -148,8 +148,9 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
             Perform ICA-AROMA on MNI-resampled functional series
         ignore_aroma_err : bool
             Do not fail on ICA-AROMA errors
-        output_grid_ref : str or None
-            Path of custom reference image for normalization
+        template_out_grid : str
+            Keyword ('native', '1mm' or '2mm') or path of custom reference
+            image for normalization
 
     """
     fmriprep_wf = pe.Workflow(name='fmriprep_wf')
@@ -190,7 +191,7 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
                                                    fmap_demean=fmap_demean,
                                                    use_syn=use_syn,
                                                    force_syn=force_syn,
-                                                   output_grid_ref=output_grid_ref,
+                                                   template_out_grid=template_out_grid,
                                                    use_aroma=use_aroma,
                                                    ignore_aroma_err=ignore_aroma_err)
 
@@ -213,7 +214,7 @@ def init_single_subject_wf(subject_id, task_id, name,
                            omp_nthreads, skull_strip_template, reportlets_dir, output_dir,
                            bids_dir, freesurfer, output_spaces, template, medial_surface_nan,
                            hires, use_bbr, bold2t1w_dof, fmap_bspline, fmap_demean, use_syn,
-                           force_syn, output_grid_ref, use_aroma, ignore_aroma_err):
+                           force_syn, template_out_grid, use_aroma, ignore_aroma_err):
     """
     This workflow organizes the preprocessing pipeline for a single subject.
     It collects and reports information about the subject, and prepares
@@ -255,7 +256,7 @@ def init_single_subject_wf(subject_id, task_id, name,
                                     fmap_demean=True,
                                     use_syn=True,
                                     force_syn=True,
-                                    output_grid_ref=None,
+                                    template_out_grid='native',
                                     use_aroma=False,
                                     ignore_aroma_err=False)
 
@@ -322,8 +323,9 @@ def init_single_subject_wf(subject_id, task_id, name,
             If fieldmaps are present and enabled, this is not run, by default.
         force_syn : bool
             **Temporary**: Always run SyN-based SDC
-        output_grid_ref : str or None
-            Path of custom reference image for normalization
+        template_out_grid : str
+            Keyword ('native', '1mm' or '2mm') or path of custom reference
+            image for normalization
         use_aroma : bool
             Perform ICA-AROMA on MNI-resampled functional series
         ignore_aroma_err : bool
@@ -437,7 +439,7 @@ def init_single_subject_wf(subject_id, task_id, name,
                                                use_syn=use_syn,
                                                force_syn=force_syn,
                                                debug=debug,
-                                               output_grid_ref=output_grid_ref,
+                                               template_out_grid=template_out_grid,
                                                use_aroma=use_aroma,
                                                ignore_aroma_err=ignore_aroma_err)
 

fmriprep/workflows/bold/base.py

@@ -51,7 +51,7 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
                          output_spaces, template, output_dir, omp_nthreads,
                          fmap_bspline, fmap_demean, use_syn, force_syn,
                          use_aroma, ignore_aroma_err, medial_surface_nan,
-                         debug, low_mem, output_grid_ref, layout=None):
+                         debug, low_mem, template_out_grid, layout=None):
     """
     This workflow controls the functional preprocessing stages of FMRIPREP.
 
@@ -78,7 +78,7 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
                                   use_syn=True,
                                   force_syn=True,
                                   low_mem=False,
-                                  output_grid_ref=None,
+                                  template_out_grid='native',
                                   medial_surface_nan=False,
                                   use_aroma=False,
                                   ignore_aroma_err=False)
@@ -136,8 +136,9 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
             Enable debugging outputs
         low_mem : bool
             Write uncompressed .nii files in some cases to reduce memory usage
-        output_grid_ref : str or None
-            Path of custom reference image for normalization
+        template_out_grid : str
+            Keyword ('native', '1mm' or '2mm') or path of custom reference
+            image for normalization
         layout : BIDSLayout
             BIDSLayout structure to enable metadata retrieval
 
@@ -565,7 +566,7 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
             template=template,
             mem_gb=mem_gb['resampled'],
             omp_nthreads=omp_nthreads,
-            output_grid_ref=output_grid_ref,
+            template_out_grid=template_out_grid,
             use_compression=not (low_mem and use_aroma),
             use_fieldwarp=fmaps is not None,
             name='bold_mni_trans_wf'

fmriprep/workflows/bold/resampling.py

@@ -161,7 +161,8 @@ def select_target(subject_id, space):
 
 def init_bold_mni_trans_wf(template, mem_gb, omp_nthreads,
                            name='bold_mni_trans_wf',
-                           output_grid_ref=None, use_compression=True,
+                           template_out_grid='2mm',
+                           use_compression=True,
                            use_fieldwarp=False):
     """
     This workflow samples functional images to the MNI template in a "single shot"
@@ -175,7 +176,7 @@ def init_bold_mni_trans_wf(template, mem_gb, omp_nthreads,
         wf = init_bold_mni_trans_wf(template='MNI152NLin2009cAsym',
                                     mem_gb=3,
                                     omp_nthreads=1,
-                                    output_grid_ref=None)
+                                    template_out_grid='native')
 
     **Parameters**
 
@@ -187,8 +188,9 @@ def init_bold_mni_trans_wf(template, mem_gb, omp_nthreads,
             Maximum number of threads an individual process may use
         name : str
             Name of workflow (default: ``bold_mni_trans_wf``)
-        output_grid_ref : str or None
-            Path of custom reference image for normalization
+        template_out_grid : str
+            Keyword ('native', '1mm' or '2mm') or path of custom reference
+            image for normalization.
         use_compression : bool
             Save registered BOLD series as ``.nii.gz``
         use_fieldwarp : bool
@@ -292,14 +294,19 @@ def _aslist(in_value):
         (merge, outputnode, [('out_file', 'bold_mni')]),
     ])
 
-    if output_grid_ref is None:
+    if template_out_grid == 'native':
         workflow.connect([
             (gen_ref, mask_mni_tfm, [('out_file', 'reference_image')]),
             (gen_ref, bold_to_mni_transform, [('out_file', 'reference_image')]),
         ])
+    elif template_out_grid == '1mm' or template_out_grid == '2mm':
+        mask_mni_tfm.inputs.reference_image = op.join(
+            nid.get_dataset(template_str), '%s_brainmask.nii.gz' % template_out_grid)
+        bold_to_mni_transform.inputs.reference_image = op.join(
+            nid.get_dataset(template_str), '%s_T1.nii.gz' % template_out_grid)
     else:
-        mask_mni_tfm.inputs.reference_image = output_grid_ref
-        bold_to_mni_transform.inputs.reference_image = output_grid_ref
+        mask_mni_tfm.inputs.reference_image = template_out_grid
+        bold_to_mni_transform.inputs.reference_image = template_out_grid
     return workflow
 
 

fmriprep/workflows/tests/test_base.py

@@ -38,7 +38,7 @@ def test_single_subject_wf(self, _):
                                          ignore_aroma_err=False,
                                          use_syn=True,
                                          force_syn=True,
-                                         output_grid_ref=None)
+                                         template_out_grid='native')
         wfbasic.write_graph()
         self._assert_mandatory_inputs_set(wfbasic)
 

wrapper/fmriprep_docker.py

@@ -21,6 +21,7 @@
 import os
 import re
 import subprocess
+from warnings import warn
 
 standard_library.install_aliases()
 
@@ -168,8 +169,8 @@ def merge_help(wrapper_help, target_help):
 
     # Make sure we're not clobbering options we don't mean to
     overlap = set(w_flags).intersection(t_flags)
-    expected_overlap = set(['h', 'version', 'w', 'output-grid-reference',
-                            'fs-license-file'])
+    expected_overlap = set(['h', 'version', 'w', 'template-resampling-grid',
+                            'output-grid-reference', 'fs-license-file'])
     assert overlap == expected_overlap, "Clobbering options: {}".format(
         ', '.join(overlap - expected_overlap))
 
@@ -244,10 +245,18 @@ def get_parser():
         'Standard options that require mapping files into the container')
     g_wrap.add_argument('-w', '--work-dir', action='store',
                         help='path where intermediate results should be stored')
-    g_wrap.add_argument('--output-grid-reference', required=False, action='store',
-                        type=os.path.abspath,
-                        help='Grid reference image for resampling BOLD files to volume template '
-                             'space.')
+    g_wrap.add_argument(
+        '--output-grid-reference', required=False, action='store', type=os.path.abspath,
+        help='Deprecated after FMRIPREP 1.0.8. Please use --template-resampling-grid instead.')
+    g_wrap.add_argument(
+        '--template-resampling-grid', required=False, action='store', type=str,
+        help='Keyword ("native", "1mm", or "2mm") or path to an existing file. '
+             'Allows to define a reference grid for the resampling of BOLD images in template '
+             'space. Keyword "native" will use the original BOLD grid as reference. '
+             'Keywords "1mm" and "2mm" will use the corresponding isotropic template '
+             'resolutions. If a path is given, the grid of that image will be used. '
+             'It determines the field of view and resolution of the output images, '
+             'but is not used in normalization.')
     g_wrap.add_argument(
         '--fs-license-file', metavar='PATH', type=os.path.abspath,
         default=os.getenv('FS_LICENSE', None),
@@ -370,10 +379,16 @@ def main():
         command.extend(['-v', ':'.join((opts.config,
                                         '/root/.nipype/nipype.cfg', 'ro'))])
 
-    if opts.output_grid_reference:
-        target = '/imports/' + os.path.basename(opts.output_grid_reference)
-        command.extend(['-v', ':'.join((opts.output_grid_reference, target, 'ro'))])
-        unknown_args.extend(['--output-grid-reference', target])
+    template_target = opts.template_resampling_grid or opts.output_grid_reference
+    if template_target is not None:
+        if opts.output_grid_reference is not None:
+            warn('Option --output-grid-reference is deprecated, please use '
+                 '--template-resampling-grid', DeprecationWarning)
+        if template_target not in ['native', '2mm' '1mm']:
+            target = '/imports/' + os.path.basename(template_target)
+            command.extend(['-v', ':'.join((os.path.abspath(
+                template_target), target, 'ro'))])
+        unknown_args.extend(['--template-resampling-grid', template_target])
 
     if opts.shell:
         command.append('--entrypoint=bash')