Merge tag '20.0.1'

20.0.1 (February 27, 2020)

Bug-fix release in 20.0.x series.

This release includes fixes for rare images with invalid qform matrices and some minor
improvements in report readability and inclusion of common templates in the Docker image.

  * FIX: Handle qforms with invalid quaternions (nipreps/niworkflows#466)
  * FIX: update niworkflows location (#2005)
  * ENH: Display errors as summary/details elements in reports (nipreps/niworkflows#464)
  * DOC: Add ``--fs-subjects-dir`` usage to slurm example (#2003)
  * CI: Test that Docker image can run a common set of output spaces without network access (#1997)

Author: effigies

.circleci/config.yml

@@ -365,6 +365,7 @@ jobs:
                 sudo setfacl -m group:$(id -gn):rwx /tmp/ds005/work
             fmriprep-docker -i poldracklab/fmriprep:latest \
                 -e FMRIPREP_DEV 1 -u $(id -u) \
+                --network none \
                 --config $PWD/nipype.cfg -w /tmp/ds005/work \
                 /tmp/data/ds005 /tmp/ds005/derivatives participant \
                 --fs-subjects-dir /tmp/ds005/freesurfer \
@@ -393,6 +394,7 @@ jobs:
                 sudo setfacl -m group:$(id -gn):rwx /tmp/ds005/work
             fmriprep-docker -i poldracklab/fmriprep:latest \
                 -e FMRIPREP_DEV 1 -u $(id -u) \
+                --network none \
                 --config $PWD/nipype.cfg -w /tmp/ds005/work \
                 /tmp/data/ds005 /tmp/ds005/derivatives participant \
                 --fs-subjects-dir /tmp/ds005/freesurfer \
@@ -422,6 +424,7 @@ jobs:
             rm /tmp/data/ds005/sub-01/func/*_run-01_*
             fmriprep-docker -i poldracklab/fmriprep:latest \
                 -e FMRIPREP_DEV 1 -u $(id -u) \
+                --network none \
                 --config $PWD/nipype.cfg -w /tmp/ds005/work_partial \
                 /tmp/data/ds005 /tmp/ds005/derivatives_partial participant \
                 --fs-subjects-dir /tmp/ds005/freesurfer \

CHANGES.rst

@@ -1,3 +1,19 @@
+20.0.1 (February 27, 2020)
+==========================
+Bug-fix release in 20.0.x series.
+
+This release includes fixes for rare images with invalid qform matrices and some minor
+improvements in report readability and inclusion of common templates in the Docker image.
+
+  * FIX: Handle qforms with invalid quaternions (`nipreps/niworkflows#466`_)
+  * FIX: update niworkflows location (#2005)
+  * ENH: Display errors as summary/details elements in reports (`nipreps/niworkflows#464`_)
+  * DOC: Add ``--fs-subjects-dir`` usage to slurm example (#2003)
+  * CI: Test that Docker image can run a common set of output spaces without network access (#1997)
+
+.. _`nipreps/niworkflows#464`: https://github.com/nipreps/niworkflows/pull/464
+.. _`nipreps/niworkflows#466`: https://github.com/nipreps/niworkflows/pull/466
+
 20.0.0 (February 24, 2020)
 ==========================
 The major release of 2020 is here!

Dockerfile

@@ -170,7 +170,10 @@ RUN pip install --no-cache-dir "$( grep templateflow fmriprep-setup.cfg | xargs
                tfapi.get('MNI152NLin6Asym', atlas=None, resolution=[1, 2], \
                          desc='brain', extension=['.nii', '.nii.gz']); \
                tfapi.get('MNI152NLin2009cAsym', atlas=None, extension=['.nii', '.nii.gz']); \
-               tfapi.get('OASIS30ANTs', extension=['.nii', '.nii.gz']);" && \
+               tfapi.get('OASIS30ANTs', extension=['.nii', '.nii.gz']); \
+               tfapi.get('fsLR', space='fsaverage', density='164k'); \
+               tfapi.get('fsLR', space=None, density='32k'); \
+               tfapi.get('MNI152NLin6Asym', resolution=2, atlas='HCP', suffix='dseg')" && \
     rm fmriprep-setup.cfg && \
     find $HOME/.cache/templateflow -type d -exec chmod go=u {} + && \
     find $HOME/.cache/templateflow -type f -exec chmod go=u {} +

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/conf.py

@@ -342,7 +342,7 @@
     "bids": ("https://bids-standard.github.io/pybids/", None),
     "nibabel": ("https://nipy.org/nibabel/", None),
     "nipype": ("https://nipype.readthedocs.io/en/latest/", None),
-    "niworkflows": ("https://poldracklab.github.io/niworkflows/", None),
+    "niworkflows": ("https://www.nipreps.org/niworkflows/", None),
     "sdcflows": ("https://www.nipreps.org/sdcflows/", None),
     "smriprep": ("https://poldracklab.github.io/smriprep/", None),
     "templateflow": ("https://www.templateflow.org/python-client", None),

docs/contributors.rst

@@ -16,7 +16,7 @@ installation_ guide for the basic procedure for running).
 
 It will be assumed the developer has a working repository in
 ``$HOME/projects/fmriprep``, and examples are also given for
-`niworkflows <https://github.com/poldracklab/niworkflows>`_ and
+`niworkflows <https://github.com/nipreps/niworkflows>`_ and
 `nipype`_.
 
 Patching working repositories
@@ -149,7 +149,7 @@ development environment, we have an experimental setup with `code-server
 
 1. Build the Docker image
 ~~~~~~~~~~~~~~~~~~~~~~~~~
-We will use the ``Dockerfile_devel`` file to build 
+We will use the ``Dockerfile_devel`` file to build
 our development docker image::
 
     $ cd $HOME/projects/fmriprep

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

setup.cfg

@@ -24,7 +24,7 @@ install_requires =
     nibabel >= 3.0.1
     nipype >= 1.3.1
     nitime
-    niworkflows ~= 1.1.7
+    niworkflows ~= 1.1.8
     numpy
     pandas
     psutil >= 5.4

wrapper/fmriprep_docker.py

@@ -296,6 +296,9 @@ def get_parser():
                        help='Set custom environment variable within container')
     g_dev.add_argument('-u', '--user', action='store',
                        help='Run container as a given user/uid')
+    g_dev.add_argument('--network', action='store',
+                       help='Run container with a different network driver '
+                            '("none" to simulate no internet connection)')
 
     return parser
 
@@ -434,6 +437,9 @@ def main():
     if opts.shell:
         command.append('--entrypoint=bash')
 
+    if opts.network:
+        command.append('--network=' + opts.network)
+
     command.append(opts.image)
 
     # Override help and version to describe underlying program