[REVIEW] Fallback to initial registration, if BBR fails

.circle/tests.sh

@@ -51,11 +51,11 @@ case ${CIRCLE_NODE_INDEX} in
     set -e
     [[ "$RET" -eq "1" ]]
     # Clean up
-    find ~/ds054/scratch -not -name "*.svg" -not -name "*.html" -not -name "*.rst" -type f -delete
+    find ~/ds054/scratch -not -name "*.svg" -not -name "*.html" -not -name "*.rst" -not -name "*.mat" -not -name "*.lta" -type f -delete
     rm -r $HOME/ds054/out/fmriprep/sub-100185/log
     ;;
   1)
     fmriprep-docker -i poldracklab/fmriprep:latest --config $HOME/nipype.cfg -w $HOME/ds005/scratch $HOME/data/ds005 $HOME/ds005/out participant --debug --write-graph --use-syn-sdc --use-aroma --ignore-aroma-denoising-errors
-    find ~/ds005/scratch -not -name "*.svg" -not -name "*.html" -not -name "*.rst" -type f -delete
+    find ~/ds005/scratch -not -name "*.svg" -not -name "*.html" -not -name "*.rst" -not -name "*.mat" -not -name "*.lta" -type f -delete
     ;;
 esac

docs/workflows.rst

@@ -37,6 +37,7 @@ slice-timing information and no fieldmap acquisitions):
                                 low_mem=False,
                                 anat_only=False,
                                 hires=True,
+                                use_bbr=True,
                                 bold2t1w_dof=9,
                                 fmap_bspline=False,
                                 fmap_demean=True,
@@ -198,6 +199,7 @@ BOLD preprocessing
                               medial_surface_nan=False,
                               debug=False,
                               low_mem=False,
+                              use_bbr=True,
                               bold2t1w_dof=9,
                               fmap_bspline=True,
                               fmap_demean=True,
@@ -296,13 +298,14 @@ EPI to T1w registration
 :mod:`fmriprep.workflows.bold.init_bold_reg_wf`
 
 .. workflow::
-    :graph2use: colored
+    :graph2use: orig
     :simple_form: yes
 
     from fmriprep.workflows.bold import init_bold_reg_wf
     wf = init_bold_reg_wf(freesurfer=True,
                           bold_file_size_gb=3,
                           omp_nthreads=1,
+                          use_bbr=True,
                           bold2t1w_dof=9)
 
 The reference EPI image of each run is aligned by the ``bbregister`` routine to the

fmriprep/cli/run.py

@@ -115,6 +115,12 @@ def get_parser():
              ' - fsnative: individual subject surface\n'
              ' - fsaverage*: FreeSurfer average meshes'
     )
+    g_conf.add_argument(
+        '--force-bbr', action='store_true', dest='use_bbr', default=None,
+        help='Always use boundary-based registration (no goodness-of-fit checks)')
+    g_conf.add_argument(
+        '--force-no-bbr', action='store_false', dest='use_bbr', default=None,
+        help='Do not use boundary-based registration (no goodness-of-fit checks)')
     g_conf.add_argument(
         '--template', required=False, action='store',
         choices=['MNI152NLin2009cAsym'], default='MNI152NLin2009cAsym',
@@ -310,6 +316,7 @@ def create_workflow(opts):
         medial_surface_nan=opts.medial_surface_nan,
         output_grid_ref=opts.output_grid_reference,
         hires=opts.hires,
+        use_bbr=opts.use_bbr,
         bold2t1w_dof=opts.bold2t1w_dof,
         fmap_bspline=opts.fmap_bspline,
         fmap_demean=opts.fmap_no_demean,

fmriprep/interfaces/reports.py

@@ -143,8 +143,11 @@ class FunctionalSummaryInputSpec(BaseInterfaceInputSpec):
                                         mandatory=True)
     pe_direction = traits.Enum(None, 'i', 'i-', 'j', 'j-', mandatory=True,
                                desc='Phase-encoding direction detected')
-    registration = traits.Enum('FLIRT', 'bbregister', mandatory=True,
+    registration = traits.Enum('FSL', 'FreeSurfer', mandatory=True,
                                desc='Functional/anatomical registration method')
+    fallback = traits.Bool(desc='Boundary-based registration rejected')
+    registration_dof = traits.Enum(6, 9, 12, desc='Registration degrees of freedom',
+                                   mandatory=True)
     output_spaces = traits.List(desc='Target spaces')
     confounds = traits.List(desc='Confounds collected')
 
@@ -153,18 +156,22 @@ class FunctionalSummary(SummaryInterface):
     input_spec = FunctionalSummaryInputSpec
 
     def _generate_segment(self):
+        dof = self.inputs.registration_dof
         stc = {True: 'Applied',
                False: 'Not applied',
                'TooShort': 'Skipped (too few volumes)'}[self.inputs.slice_timing]
-        stc = "Applied" if self.inputs.slice_timing else "Not applied"
         sdc = {'epi': 'Phase-encoding polarity (pepolar)',
                'fieldmap': 'Direct fieldmapping',
                'phasediff': 'Phase difference',
                'SyN': 'Symmetric normalization (SyN) - no fieldmaps',
                'None': 'None'}[self.inputs.distortion_correction]
-        reg = {'FLIRT': 'FLIRT with boundary-based registration (BBR) metric',
-               'bbregister': 'FreeSurfer boundary-based registration (bbregister)'
-               }[self.inputs.registration]
+        reg = {'FSL': [
+                   'FLIRT with boundary-based registration (BBR) metric - %d dof' % dof,
+                   'FLIRT rigid registration - 6 dof'],
+               'FreeSurfer': [
+                   'FreeSurfer boundary-based registration (bbregister) - %d dof' % dof,
+                   'FreeSurfer mri_coreg - %d dof' % dof],
+               }[self.inputs.registration][self.inputs.fallback]
         if self.inputs.pe_direction is None:
             pedir = 'MISSING - Assuming Anterior-Posterior'
         else:

fmriprep/viz/config.json

@@ -104,17 +104,29 @@
                 "title" : "Skull stripped EPI",
                 "description": "Skull stripped EPI"
             },
+            {
+                "name": "epi_mean_t1_registration/flirt",
+                "file_pattern": "func/.*_bold_flirt",
+                "title": "EPI to T1 registration",
+                "description": "FLIRT was used to generate transformations from EPI space to T1 Space - BBR refinement rejected"
+            },
+            {
+                "name": "epi_mean_t1_registration/coreg",
+                "file_pattern": "func/.*_bold_coreg",
+                "title": "EPI to T1 registration",
+                "description": "mri_coreg (FreeSurfer) was used to generate transformations from EPI space to T1 Space - bbregister refinement rejected"
+            },
             {
                 "name": "epi_mean_t1_registration/flt_bbr",
                 "file_pattern": "func/.*_bold_flt_bbr",
                 "title": "EPI to T1 registration",
-                "description": "EPI was used to generate transformations from EPI space to T1 Space - FAST segmentation used for BBR"
+                "description": "FLIRT was used to generate transformations from EPI space to T1 Space - FAST segmentation used for BBR"
             },
             {
                 "name": "epi_mean_t1_registration/bbr",
                 "file_pattern": "func/.*_bold_bbr",
                 "title": "EPI to T1 registration",
-                "description": "EPI was used to generate transformations from EPI space to T1 Space"
+                "description": "bbregister was used to generate transformations from EPI space to T1 Space"
             },
             {
                 "name": "ica_aroma",

fmriprep/workflows/base.py

@@ -34,7 +34,7 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
                      ignore, debug, low_mem, anat_only, longitudinal, omp_nthreads,
                      skull_strip_ants, skull_strip_template, work_dir, output_dir, bids_dir,
                      freesurfer, output_spaces, template, medial_surface_nan, hires,
-                     bold2t1w_dof, fmap_bspline, fmap_demean, use_syn, force_syn,
+                     use_bbr, bold2t1w_dof, fmap_bspline, fmap_demean, use_syn, force_syn,
                      use_aroma, ignore_aroma_err, output_grid_ref):
     """
     This workflow organizes the execution of FMRIPREP, with a sub-workflow for
@@ -68,6 +68,7 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
                               template='MNI152NLin2009cAsym',
                               medial_surface_nan=False,
                               hires=True,
+                              use_bbr=True,
                               bold2t1w_dof=9,
                               fmap_bspline=False,
                               fmap_demean=True,
@@ -128,6 +129,9 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
             Replace medial wall values with NaNs on functional GIFTI files
         hires : bool
             Enable sub-millimeter preprocessing in FreeSurfer
+        use_bbr : bool or None
+            Enable/disable boundary-based registration refinement.
+            If ``None``, test BBR result for distortion before accepting.
         bold2t1w_dof : 6, 9 or 12
             Degrees-of-freedom for BOLD-T1w registration
         fmap_bspline : bool
@@ -179,6 +183,7 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
                                                    template=template,
                                                    medial_surface_nan=medial_surface_nan,
                                                    hires=hires,
+                                                   use_bbr=use_bbr,
                                                    bold2t1w_dof=bold2t1w_dof,
                                                    fmap_bspline=fmap_bspline,
                                                    fmap_demean=fmap_demean,
@@ -206,8 +211,8 @@ def init_single_subject_wf(subject_id, task_id, name,
                            ignore, debug, low_mem, anat_only, longitudinal, omp_nthreads,
                            skull_strip_ants, skull_strip_template, reportlets_dir, output_dir,
                            bids_dir, freesurfer, output_spaces, template, medial_surface_nan,
-                           hires, bold2t1w_dof, fmap_bspline, fmap_demean, use_syn, force_syn,
-                           output_grid_ref, use_aroma, ignore_aroma_err):
+                           hires, use_bbr, bold2t1w_dof, fmap_bspline, fmap_demean, use_syn,
+                           force_syn, output_grid_ref, 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
@@ -243,6 +248,7 @@ def init_single_subject_wf(subject_id, task_id, name,
                                     low_mem=False,
                                     anat_only=False,
                                     hires=True,
+                                    use_bbr=True,
                                     bold2t1w_dof=9,
                                     fmap_bspline=False,
                                     fmap_demean=True,
@@ -302,6 +308,9 @@ def init_single_subject_wf(subject_id, task_id, name,
             Replace medial wall values with NaNs on functional GIFTI files
         hires : bool
             Enable sub-millimeter preprocessing in FreeSurfer
+        use_bbr : bool or None
+            Enable/disable boundary-based registration refinement.
+            If ``None``, test BBR result for distortion before accepting.
         bold2t1w_dof : 6, 9 or 12
             Degrees-of-freedom for BOLD-T1w registration
         fmap_bspline : bool
@@ -412,6 +421,7 @@ def init_single_subject_wf(subject_id, task_id, name,
                                                layout=layout,
                                                ignore=ignore,
                                                freesurfer=freesurfer,
+                                               use_bbr=use_bbr,
                                                bold2t1w_dof=bold2t1w_dof,
                                                reportlets_dir=reportlets_dir,
                                                output_spaces=output_spaces,