Merge pull request #2003 from mgxd/doc/fs-dir

DOC: Add ``--fs-subjects-dir`` usage to slurm example

Author: oesteban

docs/_static/sbatch.slurm

@@ -15,6 +15,7 @@
 
 BIDS_DIR="$STUDY/data"
 DERIVS_DIR="derivatives/fmriprep-1.5.0"
+LOCAL_FREESURFER_DIR="$STUDY/data/derivatives/freesurfer-6.0.1"
 
 # Prepare some writeable bind-mount points.
 TEMPLATEFLOW_HOST_HOME=$HOME/.cache/templateflow
@@ -25,27 +26,21 @@ mkdir -p ${FMRIPREP_HOST_CACHE}
 # Prepare derivatives folder
 mkdir -p ${BIDS_DIR}/${DERIVS_DIR}
 
-# This trick will help you reuse freesurfer results across pipelines and fMRIPrep versions
-mkdir -p ${BIDS_DIR}/derivatives/freesurfer-6.0.1
-if [ ! -d ${BIDS_DIR}/${DERIVS_DIR}/freesurfer ]; then
-    ln -s ${BIDS_DIR}/derivatives/freesurfer-6.0.1 ${BIDS_DIR}/${DERIVS_DIR}/freesurfer
-fi
-
 # Make sure FS_LICENSE is defined in the container.
 export SINGULARITYENV_FS_LICENSE=$HOME/.freesurfer.txt
 
 # Designate a templateflow bind-mount point
 export SINGULARITYENV_TEMPLATEFLOW_HOME="/templateflow"
-SINGULARITY_CMD="singularity run --cleanenv -B $BIDS_DIR:/data -B ${TEMPLATEFLOW_HOST_HOME}:${SINGULARITYENV_TEMPLATEFLOW_HOME} -B $L_SCRATCH:/work $STUDY/images/poldracklab_fmriprep_1.5.0.simg"
+SINGULARITY_CMD="singularity run --cleanenv -B $BIDS_DIR:/data -B ${TEMPLATEFLOW_HOST_HOME}:${SINGULARITYENV_TEMPLATEFLOW_HOME} -B $L_SCRATCH:/work -B ${LOCAL_FREESURFER_DIR}:/fsdir $STUDY/images/poldracklab_fmriprep_1.5.0.simg"
 
 # Parse the participants.tsv file and extract one subject ID from the line corresponding to this SLURM task.
 subject=$( sed -n -E "$((${SLURM_ARRAY_TASK_ID} + 1))s/sub-(\S*)\>.*/\1/gp" ${BIDS_DIR}/participants.tsv )
 
 # Remove IsRunning files from FreeSurfer
-find ${BIDS_DIR}/derivatives/freesurfer-6.0.1/sub-$subject/ -name "*IsRunning*" -type f -delete
+find ${LOCAL_FREESURFER_DIR}/sub-$subject/ -name "*IsRunning*" -type f -delete
 
 # Compose the command line
-cmd="${SINGULARITY_CMD} /data /data/${DERIVS_DIR} participant --participant-label $subject -w /work/ -vv --omp-nthreads 8 --nthreads 12 --mem_mb 30000 --output-spaces MNI152NLin2009cAsym:res-2 anat fsnative fsaverage5 --use-aroma"
+cmd="${SINGULARITY_CMD} /data /data/${DERIVS_DIR} participant --participant-label $subject -w /work/ -vv --omp-nthreads 8 --nthreads 12 --mem_mb 30000 --output-spaces MNI152NLin2009cAsym:res-2 anat fsnative fsaverage5 --use-aroma --fs-subjects-dir /fsdir"
 
 # Setup done, run the command
 echo Running task ${SLURM_ARRAY_TASK_ID}
@@ -57,4 +52,4 @@ exitcode=$?
 echo "sub-$subject   ${SLURM_ARRAY_TASK_ID}    $exitcode" \
       >> ${SLURM_JOB_NAME}.${SLURM_ARRAY_JOB_ID}.tsv
 echo Finished tasks ${SLURM_ARRAY_TASK_ID} with exit code $exitcode
-exit $exitcode
+exit $exitcode

docs/faq.rst

@@ -57,9 +57,18 @@ Please find more information regarding this error from discussions on
 
 Additionally, consider using the ``--low-mem`` flag, which will make some memory optimizations at the cost of disk space in the working directory.
 
+
+I have already run ``recon-all`` on my subjects, can I reuse my outputs?
+------------------------------------------------------------------------
+Yes, as long as the FreeSurfer_ version previously used was ``6.0.0`` or newer.
+If running with FreeSurfer, *fMRIPrep* checks if the output directory contains a ``freesurfer``
+directory and reuses the outputs found.
+Alternatively, you can use the ``--fs-subjects-dir`` flag to specify a different location for the existing FreeSurfer outputs.
+
+
 ERROR: it appears that ``recon-all`` is already running
 -------------------------------------------------------
-When running FreeSurfer_'s ``recon-all``, an error may say *it appears it is already running*.
+When running FreeSurfer's ``recon-all``, an error may say *it appears it is already running*.
 FreeSurfer creates files (called ``IsRunning.{rh,lh,lh+rh}``, under the ``scripts/`` folder)
 to determine whether it is already executing ``recon-all`` on that particular subject
 in another process, compute node, etc.
@@ -125,7 +134,7 @@ If you would like to run *fMRIPrep* in parallel on multiple subjects please use
 How much CPU time and RAM should I allocate for a typical fMRIPrep run?
 -----------------------------------------------------------------------
 The recommended way to run fMRIPrep is to process one subject per container instance. A typical preprocessing run
-without surface processing with freesurfer can be completed in about 2 hours with 4 CPUs or in about 1 hour with 16 CPUs.
+without surface processing with FreeSurfer can be completed in about 2 hours with 4 CPUs or in about 1 hour with 16 CPUs.
 More than 16 CPUs do not translate into faster processing times for a single subject. About 8GB of memory should be
 available for a single subject preprocessing run.
 

docs/usage.rst

@@ -37,7 +37,7 @@ Command-Line Arguments
    :nodefaultconst:
 
 
-The command-line interface of the docker wrapper 
+The command-line interface of the docker wrapper
 ------------------------------------------------
 
 .. argparse::
@@ -57,10 +57,10 @@ The FreeSurfer license
 To obtain a FreeSurfer license, simply register for free at
 https://surfer.nmr.mgh.harvard.edu/registration.html.
 
-When using manually-prepared environments or singularity, FreeSurfer will search 
-for a license key file first using the ``$FS_LICENSE`` environment variable and then 
-in the default path to the license key file (``$FREESURFER_HOME/license.txt``). 
-If using the ``--cleanenv`` flag and ``$FS_LICENSE`` is set, use ``--fs-license-file $FS_LICENSE`` 
+When using manually-prepared environments or singularity, FreeSurfer will search
+for a license key file first using the ``$FS_LICENSE`` environment variable and then
+in the default path to the license key file (``$FREESURFER_HOME/license.txt``).
+If using the ``--cleanenv`` flag and ``$FS_LICENSE`` is set, use ``--fs-license-file $FS_LICENSE``
 to pass the license file location to *fMRIPRep*.
 
 It is possible to run the docker container pointing the image to a local path