Merge pull request #1278 from emdupre/split_reg_wf

[RF] Split BOLD-T1w registration into calculation/application workflows

Author: effigies

Dockerfile

@@ -114,6 +114,7 @@ RUN conda install -y mkl=2018.0.3 mkl-service;  sync &&\
                      pandas=0.23.0 \
                      libxml2=2.9.4 \
                      libxslt=1.1.29 \
+                     graphviz=2.40.1 \
                      traits=4.6.0; sync &&  \
     chmod -R a+rX /usr/local/miniconda; sync && \
     chmod +x /usr/local/miniconda/bin/*; sync && \
@@ -127,8 +128,7 @@ RUN python -c "from matplotlib import font_manager" && \
 # Installing Ubuntu packages and cleaning up
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
-                    git=1:2.7.4-0ubuntu1 \
-                    graphviz=2.38.0-12ubuntu2 && \
+                    git=1:2.7.4-0ubuntu1 && \
     apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
 # Install latest pandoc
@@ -183,4 +183,3 @@ LABEL org.label-schema.build-date=$BUILD_DATE \
       org.label-schema.vcs-url="https://github.com/poldracklab/fmriprep" \
       org.label-schema.version=$VERSION \
       org.label-schema.schema-version="1.0"
-

docs/workflows.rst

@@ -128,7 +128,7 @@ to be run through ``fmriprep``.
 
 Longitudinal processing
 ~~~~~~~~~~~~~~~~~~~~~~~
-In the case of multiple T1w images (across sessions and/or runs), T1w images are 
+In the case of multiple T1w images (across sessions and/or runs), T1w images are
 merged into a single template image using FreeSurfer's `mri_robust_template`_.
 This template may be *unbiased*, or equidistant from all source images, or
 aligned to the first image (determined lexicographically by session label).
@@ -448,9 +448,9 @@ EPI to T1w registration
         use_bbr=True,
         bold2t1w_dof=9)
 
-The reference :abbr:`EPI (echo-planar imaging)` image of each run is aligned
-by the ``bbregister`` routine to the reconstructed subject using the gray/white
-matter boundary (FreeSurfer's ``?h.white`` surfaces).
+The alignment between the reference :abbr:`EPI (echo-planar imaging)` image
+of each run and the reconstructed subject using the gray/white matter boundary
+(FreeSurfer's ``?h.white`` surfaces) is calculated by the ``bbregister`` routine.
 
 .. figure:: _static/EPIT1Normalization.svg
     :scale: 100%
@@ -459,7 +459,9 @@ matter boundary (FreeSurfer's ``?h.white`` surfaces).
 
 If FreeSurfer processing is disabled, FSL ``flirt`` is run with the
 :abbr:`BBR (boundary-based registration)` cost function, using the
-``fast`` segmentation to establish the gray/white matter boundary. After :abbr:`BBR (boundary-based registration)` is run, the resulting affine transform will be compared to the initial transform found by FLIRT. Excessive deviation will result in rejecting the BBR refinement and accepting the original, affine registration.
+``fast`` segmentation to establish the gray/white matter boundary.
+After :abbr:`BBR (boundary-based registration)` is run, the resulting affine transform will be compared to the initial transform found by FLIRT.
+Excessive deviation will result in rejecting the BBR refinement and accepting the original, affine registration.
 
 EPI to MNI transformation
 ~~~~~~~~~~~~~~~~~~~~~~~~~

fmriprep/workflows/bold/__init__.py

@@ -24,7 +24,10 @@
 from .hmc import init_bold_hmc_wf
 from .stc import init_bold_stc_wf
 from .t2s import init_bold_t2s_wf
-from .registration import init_bold_reg_wf
+from .registration import (
+    init_bold_t1_trans_wf,
+    init_bold_reg_wf,
+)
 from .resampling import (
     init_bold_mni_trans_wf,
     init_bold_surf_wf,

fmriprep/workflows/bold/base.py

@@ -34,7 +34,7 @@
 from .hmc import init_bold_hmc_wf
 from .stc import init_bold_stc_wf
 from .t2s import init_bold_t2s_wf
-from .registration import init_bold_reg_wf
+from .registration import init_bold_t1_trans_wf, init_bold_reg_wf
 from .resampling import (
     init_bold_surf_wf,
     init_bold_mni_trans_wf,
@@ -211,6 +211,7 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
         * :py:func:`~fmriprep.workflows.bold.stc.init_bold_stc_wf`
         * :py:func:`~fmriprep.workflows.bold.hmc.init_bold_hmc_wf`
         * :py:func:`~fmriprep.workflows.bold.t2s.init_bold_t2s_wf`
+        * :py:func:`~fmriprep.workflows.bold.registration.init_bold_t1_trans_wf`
         * :py:func:`~fmriprep.workflows.bold.registration.init_bold_reg_wf`
         * :py:func:`~fmriprep.workflows.bold.confounds.init_bold_confounds_wf`
         * :py:func:`~fmriprep.workflows.bold.confounds.init_ica_aroma_wf`
@@ -404,15 +405,22 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
                                    mem_gb=mem_gb['filesize'],
                                    omp_nthreads=omp_nthreads)
 
-    # mean BOLD registration to T1w
+    # calculate BOLD registration to T1w
     bold_reg_wf = init_bold_reg_wf(name='bold_reg_wf',
                                    freesurfer=freesurfer,
                                    use_bbr=use_bbr,
                                    bold2t1w_dof=bold2t1w_dof,
                                    mem_gb=mem_gb['resampled'],
                                    omp_nthreads=omp_nthreads,
-                                   use_compression=False,
-                                   use_fieldwarp=(fmaps is not None or use_syn))
+                                   use_compression=False)
+
+    # apply BOLD registration to T1w
+    bold_t1_trans_wf = init_bold_t1_trans_wf(name='bold_t1_trans_wf',
+                                             freesurfer=freesurfer,
+                                             use_fieldwarp=(fmaps is not None or use_syn),
+                                             mem_gb=mem_gb['resampled'],
+                                             omp_nthreads=omp_nthreads,
+                                             use_compression=False)
 
     # get confounds
     bold_confounds_wf = init_bold_confs_wf(
@@ -476,22 +484,25 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
             ('outputnode.bold_file', 'inputnode.bold_file')]),
         # EPI-T1 registration workflow
         (inputnode, bold_reg_wf, [
-            ('bold_file', 'inputnode.name_source'),
-            ('t1_preproc', 'inputnode.t1_preproc'),
             ('t1_brain', 'inputnode.t1_brain'),
-            ('t1_mask', 'inputnode.t1_mask'),
             ('t1_seg', 'inputnode.t1_seg'),
-            ('t1_aseg', 'inputnode.t1_aseg'),
-            ('t1_aparc', 'inputnode.t1_aparc'),
             # Undefined if --no-freesurfer, but this is safe
             ('subjects_dir', 'inputnode.subjects_dir'),
             ('subject_id', 'inputnode.subject_id'),
             ('t1_2_fsnative_reverse_transform', 'inputnode.t1_2_fsnative_reverse_transform')]),
-        (bold_split, bold_reg_wf, [('out_files', 'inputnode.bold_split')]),
-        (bold_hmc_wf, bold_reg_wf, [('outputnode.xforms', 'inputnode.hmc_xforms')]),
-        (bold_reg_wf, outputnode, [('outputnode.bold_t1', 'bold_t1'),
-                                   ('outputnode.bold_aseg_t1', 'bold_aseg_t1'),
-                                   ('outputnode.bold_aparc_t1', 'bold_aparc_t1')]),
+        (inputnode, bold_t1_trans_wf, [
+            ('bold_file', 'inputnode.name_source'),
+            ('t1_brain', 'inputnode.t1_brain'),
+            ('t1_mask', 'inputnode.t1_mask'),
+            ('t1_aseg', 'inputnode.t1_aseg'),
+            ('t1_aparc', 'inputnode.t1_aparc')]),
+        (bold_split, bold_t1_trans_wf, [('out_files', 'inputnode.bold_split')]),
+        (bold_hmc_wf, bold_t1_trans_wf, [('outputnode.xforms', 'inputnode.hmc_xforms')]),
+        (bold_reg_wf, bold_t1_trans_wf, [
+            ('outputnode.itk_bold_to_t1', 'inputnode.itk_bold_to_t1')]),
+        (bold_t1_trans_wf, outputnode, [('outputnode.bold_t1', 'bold_t1'),
+                                        ('outputnode.bold_aseg_t1', 'bold_aseg_t1'),
+                                        ('outputnode.bold_aparc_t1', 'bold_aparc_t1')]),
         (bold_reg_wf, summary, [('outputnode.fallback', 'fallback')]),
         # SDC (or pass-through workflow)
         (inputnode, bold_sdc_wf, [
@@ -502,6 +513,8 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
             ('outputnode.ref_image_brain', 'inputnode.bold_ref_brain'),
             ('outputnode.bold_mask', 'inputnode.bold_mask')]),
         (bold_sdc_wf, bold_reg_wf, [
+            ('outputnode.bold_ref_brain', 'inputnode.ref_bold_brain')]),
+        (bold_sdc_wf, bold_t1_trans_wf, [
             ('outputnode.bold_ref_brain', 'inputnode.ref_bold_brain'),
             ('outputnode.bold_mask', 'inputnode.ref_bold_mask'),
             ('outputnode.out_warp', 'inputnode.fieldwarp')]),
@@ -598,14 +611,14 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
 
             # Replace EPI-to-T1w registration inputs
             workflow.disconnect([
-                (bold_sdc_wf, bold_reg_wf, [
+                (bold_sdc_wf, bold_t1_trans_wf, [
                     ('outputnode.bold_ref_brain', 'inputnode.ref_bold_brain'),
                     ('outputnode.bold_mask', 'inputnode.ref_bold_mask')]),
             ])
             workflow.connect([
                 (bold_hmc_wf, bold_t2s_wf, [
                     ('outputnode.xforms', 'inputnode.hmc_xforms')]),
-                (bold_t2s_wf, bold_reg_wf, [
+                (bold_t2s_wf, bold_t1_trans_wf, [
                     ('outputnode.t2s_map', 'inputnode.ref_bold_brain'),
                     ('outputnode.oc_mask', 'inputnode.ref_bold_mask')]),
             ])
@@ -624,8 +637,9 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
             (bold_bold_trans_wf, boldmask_to_t1w, [
                 ('outputnode.bold_mask', 'input_image')]),
             (bold_reg_wf, boldmask_to_t1w, [
-                ('outputnode.bold_mask_t1', 'reference_image'),
                 ('outputnode.itk_bold_to_t1', 'transforms')]),
+            (bold_t1_trans_wf, boldmask_to_t1w, [
+                ('outputnode.bold_mask_t1', 'reference_image')]),
             (boldmask_to_t1w, outputnode, [
                 ('output_image', 'bold_mask_t1')]),
         ])
@@ -736,7 +750,7 @@ def init_func_preproc_wf(bold_file, ignore, freesurfer,
                 ('subjects_dir', 'inputnode.subjects_dir'),
                 ('subject_id', 'inputnode.subject_id'),
                 ('t1_2_fsnative_forward_transform', 'inputnode.t1_2_fsnative_forward_transform')]),
-            (bold_reg_wf, bold_surf_wf, [('outputnode.bold_t1', 'inputnode.source_file')]),
+            (bold_t1_trans_wf, bold_surf_wf, [('outputnode.bold_t1', 'inputnode.source_file')]),
             (bold_surf_wf, outputnode, [('outputnode.surfaces', 'surfaces')]),
         ])