Merge pull request #1901 from effigies/enh/floating_freesurfer

ENH: Add ``--fs-subjects-dir`` flag

Author: oesteban

.circleci/config.yml

@@ -113,8 +113,9 @@ jobs:
     steps:
       - restore_cache:
           keys:
-            - data-v6-{{ .Revision }}
-            - data-v6-
+            - data-v7-{{ .Branch }}-{{ .Revision }}
+            - data-v7-{{ .Branch }}
+            - data-v7-
       - run:
           name: Get test data from ds000005
           command: |
@@ -149,11 +150,11 @@ jobs:
       - run:
           name: Get FreeSurfer derivatives for ds000005
           command: |
-            if [[ ! -d /tmp/ds005/derivatives/freesurfer ]]; then
-              mkdir -p /tmp/ds005/derivatives
+            if [[ ! -d /tmp/ds005/freesurfer ]]; then
+              mkdir -p /tmp/ds005
               wget --retry-connrefused --waitretry=5 --read-timeout=20 --timeout=15 -t 0 -q \
                 -O ds005_derivatives_freesurfer.tar.gz "https://files.osf.io/v1/resources/fvuh8/providers/osfstorage/58fe59eb594d900250960180"
-              tar xvzf ds005_derivatives_freesurfer.tar.gz -C /tmp/ds005/derivatives
+              tar xvzf ds005_derivatives_freesurfer.tar.gz -C /tmp/ds005
             else
               echo "FreeSurfer derivatives of ds000005 were cached"
             fi
@@ -180,10 +181,10 @@ jobs:
             - ds054/nipype.cfg
             - ds210/nipype.cfg
       - save_cache:
-         key: data-v6-{{ .Revision }}-{{ epoch }}
+         key: data-v7-{{ .Branch }}-{{ .Revision }}-{{ epoch }}
          paths:
             - /tmp/data
-            - /tmp/ds005/derivatives/freesurfer
+            - /tmp/ds005/freesurfer
 
   test_pytest:
     machine:
@@ -325,13 +326,13 @@ jobs:
             - docker-v3-{{ .Branch }}-{{ .Revision }}
       - restore_cache:
           keys:
-            - data-v6-{{ .Revision }}
+            - data-v7-{{ .Branch }}-{{ .Revision }}
       - restore_cache:
           keys:
-            - ds005-anat-v16-{{ .Branch }}-{{ .Revision }}
-            - ds005-anat-v16-{{ .Branch }}
-            - ds005-anat-v16-master
-            - ds005-anat-v16-
+            - ds005-anat-v17-{{ .Branch }}-{{ .Revision }}
+            - ds005-anat-v17-{{ .Branch }}
+            - ds005-anat-v17-master
+            - ds005-anat-v17-
       - run:
           name: Setting up test
           command: |
@@ -362,6 +363,7 @@ jobs:
                 -e FMRIPREP_DEV 1 -u $(id -u) \
                 --config $PWD/nipype.cfg -w /tmp/ds005/work \
                 /tmp/data/ds005 /tmp/ds005/derivatives participant \
+                --fs-subjects-dir /tmp/ds005/freesurfer \
                 --skull-strip-template OASIS30ANTs:res-1 \
                 --output-spaces MNI152NLin2009cAsym MNI152NLin6Asym \
                 --sloppy --write-graph --mem_mb 4096 \
@@ -373,7 +375,7 @@ jobs:
             rm -rf /tmp/ds005/work/reportlets
             rm -rf /tmp/ds005/derivatives/fmriprep
       - save_cache:
-         key: ds005-anat-v16-{{ .Branch }}-{{ .Revision }}-{{ epoch }}
+         key: ds005-anat-v17-{{ .Branch }}-{{ .Revision }}-{{ epoch }}
          paths:
             - /tmp/ds005/work
 
@@ -389,6 +391,7 @@ jobs:
                 -e FMRIPREP_DEV 1 -u $(id -u) \
                 --config $PWD/nipype.cfg -w /tmp/ds005/work \
                 /tmp/data/ds005 /tmp/ds005/derivatives participant \
+                --fs-subjects-dir /tmp/ds005/freesurfer \
                 --sloppy --write-graph --use-syn-sdc --mem_mb 4096 \
                 --use-aroma \
                 --skull-strip-template OASIS30ANTs:res-1 \
@@ -399,7 +402,6 @@ jobs:
           name: Move intermediate results for second run
           command: |
             mkdir -p /tmp/ds005/derivatives_partial
-            sudo mv /tmp/ds005/derivatives/freesurfer /tmp/ds005/derivatives_partial
             sudo cp -a /tmp/ds005/work /tmp/ds005/work_partial
             sudo rm -rf /tmp/ds005/work_partial/fmriprep_wf/single_subject_01_wf/func_preproc_task_mixedgamblestask_run_02_wf/ica_aroma_wf
       - run:
@@ -418,6 +420,7 @@ jobs:
                 -e FMRIPREP_DEV 1 -u $(id -u) \
                 --config $PWD/nipype.cfg -w /tmp/ds005/work_partial \
                 /tmp/data/ds005 /tmp/ds005/derivatives_partial participant \
+                --fs-subjects-dir /tmp/ds005/freesurfer \
                 --sloppy --write-graph --use-syn-sdc --mem_mb 4096 \
                 --output-spaces MNI152NLin2009cAsym fsaverage5 fsnative MNI152NLin6Asym anat \
                 --aroma-melodic-dimensionality 2 --use-aroma \
@@ -479,7 +482,7 @@ jobs:
             - docker-v3-{{ .Branch }}-{{ .Revision }}
       - restore_cache:
           keys:
-            - data-v6-{{ .Revision }}
+            - data-v7-{{ .Branch }}-{{ .Revision }}
       - restore_cache:
           keys:
             - ds054-anat-v14-{{ .Branch }}-{{ .Revision }}
@@ -616,7 +619,7 @@ jobs:
             - docker-v3-{{ .Branch }}-{{ .Revision }}
       - restore_cache:
           keys:
-            - data-v6-{{ .Revision }}
+            - data-v7-{{ .Branch }}-{{ .Revision }}
       - restore_cache:
           keys:
             - ds210-anat-v12-{{ .Branch }}-{{ .Revision }}

docs/outputs.rst

@@ -90,7 +90,8 @@ conformed space for surface reconstruction (``fsnative``) is stored in::
 
 FreeSurfer derivatives
 ~~~~~~~~~~~~~~~~~~~~~~
-A FreeSurfer subjects directory is created in ``<output_dir>/freesurfer``::
+A FreeSurfer subjects directory is created in ``<output dir>/freesurfer``, or the
+directory indicated with the ``--fs-subjects-dir`` flag. ::
 
     <output_dir>/
         fmriprep/

docs/workflows.rst

@@ -202,7 +202,8 @@ All surface preprocessing may be disabled with the ``--fs-no-reconall`` flag.
     Surface processing will be skipped if the outputs already exist.
 
     In order to bypass reconstruction in *fMRIPrep*, place existing reconstructed
-    subjects in ``<output dir>/freesurfer`` prior to the run.
+    subjects in ``<output dir>/freesurfer`` prior to the run, or specify an external
+    subjects directory with the ``--fs-subjects-dir`` flag.
     *fMRIPrep* will perform any missing ``recon-all`` steps, but will not perform
     any steps whose outputs already exist.
 

fmriprep/cli/run.py

@@ -249,6 +249,10 @@ def get_parser():
         '--fs-license-file', metavar='PATH', type=Path,
         help='Path to FreeSurfer license key file. Get it (for free) by registering'
              ' at https://surfer.nmr.mgh.harvard.edu/registration.html')
+    g_fs.add_argument(
+        '--fs-subjects-dir', metavar='PATH', type=Path,
+        help='Path to existing FreeSurfer subjects directory to reuse. '
+             '(default: OUTPUT_DIR/freesurfer)')
 
     # Surface generation xor
     g_surfs = parser.add_argument_group('Surface preprocessing options')
@@ -673,6 +677,7 @@ def build_workflow(opts, retval):
         fmap_demean=opts.fmap_no_demean,
         force_syn=opts.force_syn,
         freesurfer=opts.run_reconall,
+        fs_subjects_dir=opts.fs_subjects_dir,
         hires=opts.hires,
         ignore=opts.ignore,
         layout=layout,

fmriprep/workflows/base.py

@@ -47,6 +47,7 @@ def init_fmriprep_wf(
     fmap_demean,
     force_syn,
     freesurfer,
+    fs_subjects_dir,
     hires,
     ignore,
     layout,
@@ -101,6 +102,7 @@ def init_fmriprep_wf(
                 fmap_demean=True,
                 force_syn=True,
                 freesurfer=True,
+                fs_subjects_dir=None,
                 hires=True,
                 ignore=[],
                 layout=BIDSLayout('.'),
@@ -221,6 +223,8 @@ def init_fmriprep_wf(
                 spaces=[s for s in output_spaces.keys() if s.startswith('fsaverage')] + [
                     'fsnative'] * ('fsnative' in output_spaces)),
             name='fsdir_run_' + run_uuid.replace('-', '_'), run_without_submitting=True)
+        if fs_subjects_dir is not None:
+            fsdir.inputs.subjects_dir = str(fs_subjects_dir.absolute())
 
     reportlets_dir = os.path.join(work_dir, 'reportlets')
     for subject_id in subject_list:

wrapper/fmriprep_docker.py

@@ -142,7 +142,7 @@ 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', 'template-resampling-grid',
-                            'fs-license-file', 'use-plugin'])
+                            'fs-license-file', 'fs-subjects-dir', 'use-plugin'])
 
     assert overlap == expected_overlap, "Clobbering options: {}".format(
         ', '.join(overlap - expected_overlap))
@@ -242,6 +242,10 @@ def get_parser():
         default=os.getenv('FS_LICENSE', None),
         help='Path to FreeSurfer license key file. Get it (for free) by registering'
              ' at https://surfer.nmr.mgh.harvard.edu/registration.html')
+    g_wrap.add_argument(
+        '--fs-subjects-dir', metavar='PATH', type=os.path.abspath,
+        help='Path to existing FreeSurfer subjects directory to reuse. '
+             '(default: OUTPUT_DIR/freesurfer)')
     g_wrap.add_argument(
         '--use-plugin', metavar='PATH', action='store', default=None,
         type=os.path.abspath, help='nipype plugin configuration file')
@@ -366,6 +370,10 @@ def main():
         main_args.append('/out')
     main_args.append(opts.analysis_level)
 
+    if opts.fs_subjects_dir:
+        command.extend(['-v', '{}:/opt/subjects'.format(opts.fs_subjects_dir)])
+        unknown_args.extend(['--fs-subjects-dir', '/opt/subjects'])
+
     if opts.work_dir:
         command.extend(['-v', ':'.join((opts.work_dir, '/scratch'))])
         unknown_args.extend(['-w', '/scratch'])