revise documentation & add mcflirt flag

Author: oesteban

.circleci/config.yml

@@ -537,7 +537,7 @@ jobs:
                 -e FMRIPREP_DEV 1 \
                 --config $PWD/nipype.cfg -w /tmp/ds054/work \
                 /tmp/data/ds054 /tmp/ds054/derivatives participant \
-                --fs-no-reconall --sloppy \
+                --fs-no-reconall --sloppy --hmc-use-mcflirt \
                 --output-space T1w template \
                 --template-resampling-grid 2mm \
                 --mem_mb 4096 --nthreads 2 -vv
@@ -778,7 +778,7 @@ workflows:
             - get_regression_data
           filters:
             branches:
-              ignore: 
+              ignore:
                 - /docs?\/.*/
                 - /ds005\/.*/
                 - /ds054\/.*/

docs/workflows.rst

@@ -19,38 +19,40 @@ is presented below:
     :simple_form: yes
 
     from fmriprep.workflows.base import init_single_subject_wf
-    wf = init_single_subject_wf(subject_id='test',
-                                name='single_subject_wf',
-                                task_id='',
-                                longitudinal=False,
-                                t2s_coreg=False,
-                                omp_nthreads=1,
-                                freesurfer=True,
-                                reportlets_dir='.',
-                                output_dir='.',
-                                bids_dir='.',
-                                skull_strip_template='OASIS',
-                                skull_strip_fixed_seed=False,
-                                template='MNI152NLin2009cAsym',
-                                output_spaces=['T1w', 'fsnative',
-                                              'template', 'fsaverage5'],
-                                medial_surface_nan=False,
-                                cifti_output=False,
-                                ignore=[],
-                                debug=False,
-                                low_mem=False,
-                                anat_only=False,
-                                hires=True,
-                                use_bbr=True,
-                                bold2t1w_dof=9,
-                                fmap_bspline=False,
-                                fmap_demean=True,
-                                use_syn=True,
-                                force_syn=True,
-                                template_out_grid='native',
-                                use_aroma=False,
-                                aroma_melodic_dim=None,
-                                ignore_aroma_err=False)
+    wf = init_single_subject_wf(
+        subject_id='test',
+        name='single_subject_wf',
+        task_id='',
+        longitudinal=False,
+        t2s_coreg=False,
+        omp_nthreads=1,
+        freesurfer=True,
+        reportlets_dir='.',
+        output_dir='.',
+        bids_dir='.',
+        skull_strip_template='OASIS',
+        skull_strip_fixed_seed=False,
+        template='MNI152NLin2009cAsym',
+        output_spaces=['T1w', 'fsnative', 'template', 'fsaverage5'],
+        medial_surface_nan=False,
+        cifti_output=False,
+        ignore=[],
+        debug=False,
+        low_mem=False,
+        anat_only=False,
+        hires=True,
+        use_bbr=True,
+        bold2t1w_dof=9,
+        fmap_bspline=False,
+        fmap_demean=True,
+        use_syn=True,
+        force_syn=True,
+        template_out_grid='native',
+        use_aroma=False,
+        aroma_melodic_dim=None,
+        ignore_aroma_err=False,
+        use_mcflirt=False,
+    )
 
 
 T1w/T2w preprocessing
@@ -248,30 +250,32 @@ BOLD preprocessing
     :simple_form: yes
 
     from fmriprep.workflows.bold import init_func_preproc_wf
-    wf = init_func_preproc_wf('/completely/made/up/path/sub-01_task-nback_bold.nii.gz',
-                              omp_nthreads=1,
-                              ignore=[],
-                              freesurfer=True,
-                              reportlets_dir='.',
-                              output_dir='.',
-                              template='MNI152NLin2009cAsym',
-                              output_spaces=['T1w', 'fsnative',
-                                             'template', 'fsaverage5'],
-                              medial_surface_nan=False,
-                              cifti_output=False,
-                              debug=False,
-                              low_mem=False,
-                              use_bbr=True,
-                              t2s_coreg=False,
-                              bold2t1w_dof=9,
-                              fmap_bspline=True,
-                              fmap_demean=True,
-                              use_syn=True,
-                              force_syn=True,
-                              template_out_grid='native',
-                              use_aroma=False,
-                              aroma_melodic_dim=None,
-                              ignore_aroma_err=False)
+    wf = init_func_preproc_wf(
+        '/completely/made/up/path/sub-01_task-nback_bold.nii.gz',
+        omp_nthreads=1,
+        ignore=[],
+        freesurfer=True,
+        reportlets_dir='.',
+        output_dir='.',
+        template='MNI152NLin2009cAsym',
+        output_spaces=['T1w', 'fsnative', 'template', 'fsaverage5'],
+        medial_surface_nan=False,
+        cifti_output=False,
+        debug=False,
+        low_mem=False,
+        use_bbr=True,
+        t2s_coreg=False,
+        bold2t1w_dof=9,
+        fmap_bspline=True,
+        fmap_demean=True,
+        use_syn=True,
+        force_syn=True,
+        template_out_grid='native',
+        use_aroma=False,
+        aroma_melodic_dim=None,
+        ignore_aroma_err=False,
+        use_mcflirt=False,
+    )
 
 Preprocessing of :abbr:`BOLD (blood-oxygen level-dependent)` files is
 split into multiple sub-workflows described below.
@@ -332,6 +336,7 @@ Head-motion estimation
 
     from fmriprep.workflows.bold import init_bold_hmc_wf
     wf = init_bold_hmc_wf(
+        use_mcflirt=False,
         mem_gb=1,
         omp_nthreads=1)
 

fmriprep/cli/run.py

@@ -160,6 +160,10 @@ def get_parser():
         '--medial-surface-nan', required=False, action='store_true', default=False,
         help='Replace medial wall values with NaNs on functional GIFTI files. Only '
         'performed for GIFTI files mapped to a freesurfer subject (fsaverage or fsnative).')
+    g_conf.add_argument(
+        '--hmc-use-mcflirt', required=False, action='store_true', default=False,
+        help='Head-Motion Correction (HMC) - use FSL\'s ``mcflirt`` instead '
+        'of AFNI\'s ``3dVolreg``.')
 
     # ICA_AROMA options
     g_aroma = parser.add_argument_group('Specific options for running ICA_AROMA')
@@ -554,6 +558,7 @@ def build_workflow(opts, retval):
         use_aroma=opts.use_aroma,
         aroma_melodic_dim=opts.aroma_melodic_dimensionality,
         ignore_aroma_err=opts.ignore_aroma_denoising_errors,
+        use_mcflirt=opts.hmc_use_mcflirt,
     )
     retval['return_code'] = 0
 

fmriprep/workflows/base.py

@@ -38,7 +38,8 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid, work_dir, output_dir, bids
                      omp_nthreads, skull_strip_template, skull_strip_fixed_seed,
                      freesurfer, output_spaces, template, medial_surface_nan, cifti_output, hires,
                      use_bbr, bold2t1w_dof, fmap_bspline, fmap_demean, use_syn, force_syn,
-                     use_aroma, ignore_aroma_err, aroma_melodic_dim, template_out_grid):
+                     use_aroma, ignore_aroma_err, aroma_melodic_dim, template_out_grid,
+                     use_mcflirt):
     """
     This workflow organizes the execution of FMRIPREP, with a sub-workflow for
     each subject.
@@ -84,7 +85,8 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid, work_dir, output_dir, bids
                               use_aroma=False,
                               ignore_aroma_err=False,
                               aroma_melodic_dim=None,
-                              template_out_grid='native')
+                              template_out_grid='native',
+                              use_mcflirt=False)
 
 
     Parameters
@@ -162,6 +164,8 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid, work_dir, output_dir, bids
         template_out_grid : str
             Keyword ('native', '1mm' or '2mm') or path of custom reference
             image for normalization
+        use_mcflirt : bool
+            Use FSL ``mcflirt`` for head motion correction, instead of AFNI ``3dVolreg``.
 
     """
     fmriprep_wf = Workflow(name='fmriprep_wf')
@@ -177,37 +181,40 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid, work_dir, output_dir, bids
 
     reportlets_dir = os.path.join(work_dir, 'reportlets')
     for subject_id in subject_list:
-        single_subject_wf = init_single_subject_wf(subject_id=subject_id,
-                                                   task_id=task_id,
-                                                   name="single_subject_" + subject_id + "_wf",
-                                                   reportlets_dir=reportlets_dir,
-                                                   output_dir=output_dir,
-                                                   bids_dir=bids_dir,
-                                                   ignore=ignore,
-                                                   debug=debug,
-                                                   low_mem=low_mem,
-                                                   anat_only=anat_only,
-                                                   longitudinal=longitudinal,
-                                                   t2s_coreg=t2s_coreg,
-                                                   omp_nthreads=omp_nthreads,
-                                                   skull_strip_template=skull_strip_template,
-                                                   skull_strip_fixed_seed=skull_strip_fixed_seed,
-                                                   freesurfer=freesurfer,
-                                                   output_spaces=output_spaces,
-                                                   template=template,
-                                                   medial_surface_nan=medial_surface_nan,
-                                                   cifti_output=cifti_output,
-                                                   hires=hires,
-                                                   use_bbr=use_bbr,
-                                                   bold2t1w_dof=bold2t1w_dof,
-                                                   fmap_bspline=fmap_bspline,
-                                                   fmap_demean=fmap_demean,
-                                                   use_syn=use_syn,
-                                                   force_syn=force_syn,
-                                                   template_out_grid=template_out_grid,
-                                                   use_aroma=use_aroma,
-                                                   aroma_melodic_dim=aroma_melodic_dim,
-                                                   ignore_aroma_err=ignore_aroma_err)
+        single_subject_wf = init_single_subject_wf(
+            subject_id=subject_id,
+            task_id=task_id,
+            name="single_subject_" + subject_id + "_wf",
+            reportlets_dir=reportlets_dir,
+            output_dir=output_dir,
+            bids_dir=bids_dir,
+            ignore=ignore,
+            debug=debug,
+            low_mem=low_mem,
+            anat_only=anat_only,
+            longitudinal=longitudinal,
+            t2s_coreg=t2s_coreg,
+            omp_nthreads=omp_nthreads,
+            skull_strip_template=skull_strip_template,
+            skull_strip_fixed_seed=skull_strip_fixed_seed,
+            freesurfer=freesurfer,
+            output_spaces=output_spaces,
+            template=template,
+            medial_surface_nan=medial_surface_nan,
+            cifti_output=cifti_output,
+            hires=hires,
+            use_bbr=use_bbr,
+            bold2t1w_dof=bold2t1w_dof,
+            fmap_bspline=fmap_bspline,
+            fmap_demean=fmap_demean,
+            use_syn=use_syn,
+            force_syn=force_syn,
+            template_out_grid=template_out_grid,
+            use_aroma=use_aroma,
+            aroma_melodic_dim=aroma_melodic_dim,
+            ignore_aroma_err=ignore_aroma_err,
+            use_mcflirt=use_mcflirt,
+        )
 
         single_subject_wf.config['execution']['crashdump_dir'] = (
             os.path.join(output_dir, "fmriprep", "sub-" + subject_id, 'log', run_uuid)
@@ -229,7 +236,7 @@ def init_single_subject_wf(subject_id, task_id, name, reportlets_dir, output_dir
                            freesurfer, output_spaces, template, medial_surface_nan,
                            cifti_output, hires, use_bbr, bold2t1w_dof, fmap_bspline, fmap_demean,
                            use_syn, force_syn, template_out_grid,
-                           use_aroma, aroma_melodic_dim, ignore_aroma_err):
+                           use_aroma, aroma_melodic_dim, ignore_aroma_err, use_mcflirt):
     """
     This workflow organizes the preprocessing pipeline for a single subject.
     It collects and reports information about the subject, and prepares
@@ -276,7 +283,8 @@ def init_single_subject_wf(subject_id, task_id, name, reportlets_dir, output_dir
                                     template_out_grid='native',
                                     use_aroma=False,
                                     aroma_melodic_dim=None,
-                                    ignore_aroma_err=False)
+                                    ignore_aroma_err=False,
+                                    use_mcflirt=False)
 
     Parameters
 
@@ -353,6 +361,8 @@ def init_single_subject_wf(subject_id, task_id, name, reportlets_dir, output_dir
             Perform ICA-AROMA on MNI-resampled functional series
         ignore_aroma_err : bool
             Do not fail on ICA-AROMA errors
+        use_mcflirt : bool
+            Use FSL ``mcflirt`` for head motion correction, instead of AFNI ``3dVolreg``.
 
     Inputs
 
@@ -491,7 +501,8 @@ def init_single_subject_wf(subject_id, task_id, name, reportlets_dir, output_dir
                                                use_aroma=use_aroma,
                                                aroma_melodic_dim=aroma_melodic_dim,
                                                ignore_aroma_err=ignore_aroma_err,
-                                               num_bold=len(subject_data['bold']))
+                                               num_bold=len(subject_data['bold']),
+                                               use_mcflirt=use_mcflirt)
 
         workflow.connect([
             (anat_preproc_wf, func_preproc_wf,

fmriprep/workflows/bold/base.py

@@ -53,7 +53,7 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
                          use_aroma, ignore_aroma_err, aroma_melodic_dim,
                          medial_surface_nan, cifti_output,
                          debug, low_mem, template_out_grid,
-                         layout=None, num_bold=1):
+                         use_mcflirt, layout=None, num_bold=1):
     """
     This workflow controls the functional preprocessing stages of FMRIPREP.
 
@@ -86,6 +86,7 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
                                   use_aroma=False,
                                   ignore_aroma_err=False,
                                   aroma_melodic_dim=None,
+                                  use_mcflirt=False,
                                   num_bold=1)
 
     **Parameters**
@@ -146,6 +147,8 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
         template_out_grid : str
             Keyword ('native', '1mm' or '2mm') or path of custom reference
             image for normalization
+        use_mcflirt : bool
+            Use FSL ``mcflirt`` for head motion correction, instead of AFNI ``3dVolreg``.
         layout : BIDSLayout
             BIDSLayout structure to enable metadata retrieval
         num_bold : int
@@ -403,7 +406,8 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
                          mem_gb=mem_gb['filesize'] * 3)
 
     # HMC on the BOLD
-    bold_hmc_wf = init_bold_hmc_wf(name='bold_hmc_wf',
+    bold_hmc_wf = init_bold_hmc_wf(use_mcflirt=use_mcflirt,
+                                   name='bold_hmc_wf',
                                    mem_gb=mem_gb['filesize'],
                                    omp_nthreads=omp_nthreads)