Merge pull request #919 from feilong/patch-1

[ENH] Allow turning off random seeding for ANTs brain extraction

Author: oesteban

docs/workflows.rst

@@ -30,6 +30,7 @@ is presented below:
                                 output_dir='.',
                                 bids_dir='.',
                                 skull_strip_template='OASIS',
+                                skull_strip_fixed_seed=False,
                                 template='MNI152NLin2009cAsym',
                                 output_spaces=['T1w', 'fsnative',
                                               'template', 'fsaverage5'],
@@ -68,6 +69,7 @@ T1w/T2w preprocessing
                               output_spaces=['T1w', 'fsnative',
                                              'template', 'fsaverage5'],
                               skull_strip_template='OASIS',
+                              skull_strip_fixed_seed=False,
                               freesurfer=True,
                               longitudinal=False,
                               debug=False,

fmriprep/cli/run.py

@@ -176,6 +176,9 @@ def get_parser():
     g_ants.add_argument('--skull-strip-template', action='store', default='OASIS',
                         choices=['OASIS', 'NKI'],
                         help='select ANTs skull-stripping template (default: OASIS))')
+    g_ants.add_argument('--skull-strip-fixed-seed', action='store_true',
+                        help='do not use a random seed for skull-stripping - will ensure '
+                             'run-to-run replicability when used with --omp-nthreads 1')
 
     # Fieldmap options
     g_fmap = parser.add_argument_group('Specific options for handling fieldmaps')
@@ -517,6 +520,7 @@ def build_workflow(opts, retval):
         t2s_coreg=opts.t2s_coreg,
         omp_nthreads=omp_nthreads,
         skull_strip_template=opts.skull_strip_template,
+        skull_strip_fixed_seed=opts.skull_strip_fixed_seed,
         work_dir=work_dir,
         output_dir=output_dir,
         bids_dir=bids_dir,

fmriprep/workflows/anatomical.py

@@ -55,7 +55,7 @@
 def init_anat_preproc_wf(skull_strip_template, output_spaces, template, debug,
                          freesurfer, longitudinal, omp_nthreads, hires, reportlets_dir,
                          output_dir, num_t1w,
-                         name='anat_preproc_wf'):
+                         skull_strip_fixed_seed=False, name='anat_preproc_wf'):
     r"""
     This workflow controls the anatomical preprocessing stages of FMRIPREP.
 
@@ -119,6 +119,9 @@ def init_anat_preproc_wf(skull_strip_template, output_spaces, template, debug,
             Directory in which to save derivatives
         name : str, optional
             Workflow name (default: anat_preproc_wf)
+        skull_strip_fixed_seed : bool
+            Do not use a random seed for skull-stripping - will ensure
+            run-to-run replicability when used with --omp-nthreads 1 (default: ``False``)
 
 
     **Inputs**
@@ -562,7 +565,8 @@ def _set_threads(in_list, maximum):
     return workflow
 
 
-def init_skullstrip_ants_wf(skull_strip_template, debug, omp_nthreads, name='skullstrip_ants_wf'):
+def init_skullstrip_ants_wf(skull_strip_template, debug, omp_nthreads,
+                            skull_strip_fixed_seed=False, name='skullstrip_ants_wf'):
     r"""
     This workflow performs skull-stripping using ANTs' ``BrainExtraction.sh``
 
@@ -581,6 +585,9 @@ def init_skullstrip_ants_wf(skull_strip_template, debug, omp_nthreads, name='sku
             Enable debugging outputs
         omp_nthreads : int
             Maximum number of threads an individual process may use
+        skull_strip_fixed_seed : bool
+            Do not use a random seed for skull-stripping - will ensure
+            run-to-run replicability when used with --omp-nthreads 1 (default: ``False``)
 
     **Inputs**
 
@@ -633,7 +640,7 @@ def init_skullstrip_ants_wf(skull_strip_template, debug, omp_nthreads, name='sku
 
     t1_skull_strip = pe.Node(
         BrainExtraction(dimension=3, use_floatingpoint_precision=1, debug=debug,
-                        keep_temporary_files=1),
+                        keep_temporary_files=1, use_random_seeding=not skull_strip_fixed_seed),
         name='t1_skull_strip', n_procs=omp_nthreads)
 
     t1_skull_strip.inputs.brain_template = brain_template

fmriprep/workflows/base.py

@@ -33,9 +33,9 @@
 from .bold import init_func_preproc_wf
 
 
-def init_fmriprep_wf(subject_list, task_id, run_uuid,
+def init_fmriprep_wf(subject_list, task_id, run_uuid, work_dir, output_dir, bids_dir,
                      ignore, debug, low_mem, anat_only, longitudinal, t2s_coreg,
-                     omp_nthreads, skull_strip_template, work_dir, output_dir, bids_dir,
+                     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):
@@ -56,6 +56,9 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
         wf = init_fmriprep_wf(subject_list=['fmripreptest'],
                               task_id='',
                               run_uuid='X',
+                              work_dir='.',
+                              output_dir='.',
+                              bids_dir='.',
                               ignore=[],
                               debug=False,
                               low_mem=False,
@@ -64,9 +67,7 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
                               t2s_coreg=False,
                               omp_nthreads=1,
                               skull_strip_template='OASIS',
-                              work_dir='.',
-                              output_dir='.',
-                              bids_dir='.',
+                              skull_strip_fixed_seed=False,
                               freesurfer=True,
                               output_spaces=['T1w', 'fsnative',
                                             'template', 'fsaverage5'],
@@ -94,6 +95,12 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
             Task ID of BOLD series to preprocess, or ``None`` to preprocess all
         run_uuid : str
             Unique identifier for execution instance
+        work_dir : str
+            Directory in which to store workflow execution state and temporary files
+        output_dir : str
+            Directory in which to save derivatives
+        bids_dir : str
+            Root directory of BIDS dataset
         ignore : list
             Preprocessing steps to skip (may include "slicetiming", "fieldmaps")
         debug : bool
@@ -111,12 +118,9 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
             Maximum number of threads an individual process may use
         skull_strip_template : str
             Name of ANTs skull-stripping template ('OASIS' or 'NKI')
-        work_dir : str
-            Directory in which to store workflow execution state and temporary files
-        output_dir : str
-            Directory in which to save derivatives
-        bids_dir : str
-            Root directory of BIDS dataset
+        skull_strip_fixed_seed : bool
+            Do not use a random seed for skull-stripping - will ensure
+            run-to-run replicability when used with --omp-nthreads 1
         freesurfer : bool
             Enable FreeSurfer surface reconstruction (may increase runtime)
         output_spaces : list
@@ -176,6 +180,9 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
         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,
@@ -184,9 +191,7 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
                                                    t2s_coreg=t2s_coreg,
                                                    omp_nthreads=omp_nthreads,
                                                    skull_strip_template=skull_strip_template,
-                                                   reportlets_dir=reportlets_dir,
-                                                   output_dir=output_dir,
-                                                   bids_dir=bids_dir,
+                                                   skull_strip_fixed_seed=skull_strip_fixed_seed,
                                                    freesurfer=freesurfer,
                                                    output_spaces=output_spaces,
                                                    template=template,
@@ -218,10 +223,10 @@ def init_fmriprep_wf(subject_list, task_id, run_uuid,
     return fmriprep_wf
 
 
-def init_single_subject_wf(subject_id, task_id, name,
+def init_single_subject_wf(subject_id, task_id, name, reportlets_dir, output_dir, bids_dir,
                            ignore, debug, low_mem, anat_only, longitudinal, t2s_coreg,
-                           omp_nthreads, skull_strip_template, reportlets_dir, output_dir,
-                           bids_dir, freesurfer, output_spaces, template, medial_surface_nan,
+                           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, template_out_grid,
                            use_aroma, aroma_melodic_dim, ignore_aroma_err):
@@ -241,25 +246,26 @@ def init_single_subject_wf(subject_id, task_id, name,
 
         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,
+                                    name='single_subject_wf',
                                     reportlets_dir='.',
                                     output_dir='.',
                                     bids_dir='.',
+                                    ignore=[],
+                                    debug=False,
+                                    low_mem=False,
+                                    anat_only=False,
+                                    longitudinal=False,
+                                    t2s_coreg=False,
+                                    omp_nthreads=1,
                                     skull_strip_template='OASIS',
+                                    skull_strip_fixed_seed=False,
+                                    freesurfer=True,
                                     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,
@@ -297,6 +303,9 @@ def init_single_subject_wf(subject_id, task_id, name,
             Maximum number of threads an individual process may use
         skull_strip_template : str
             Name of ANTs skull-stripping template ('OASIS' or 'NKI')
+        skull_strip_fixed_seed : bool
+            Do not use a random seed for skull-stripping - will ensure
+            run-to-run replicability when used with --omp-nthreads 1
         reportlets_dir : str
             Directory in which to save reportlets
         output_dir : str
@@ -423,6 +432,7 @@ def init_single_subject_wf(subject_id, task_id, name,
     # Preprocessing of T1w (includes registration to MNI)
     anat_preproc_wf = init_anat_preproc_wf(name="anat_preproc_wf",
                                            skull_strip_template=skull_strip_template,
+                                           skull_strip_fixed_seed=skull_strip_fixed_seed,
                                            output_spaces=output_spaces,
                                            template=template,
                                            debug=debug,

fmriprep/workflows/tests/test_base.py

@@ -22,6 +22,7 @@ def test_single_subject_wf(self, _):
                                          t2s_coreg=False,
                                          omp_nthreads=1,
                                          skull_strip_template='OASIS',
+                                         skull_strip_fixed_seed=False,
                                          reportlets_dir='.',
                                          output_dir='.',
                                          bids_dir='.',