Merge pull request #1802 from oesteban/docs/templateflow-1801

DOC: Improve documentation about TemplateFlow and Containers

Author: oesteban

README.rst

@@ -1,5 +1,5 @@
-fmriprep: A Robust Preprocessing Pipeline for fMRI Data
-=======================================================
+*fMRIPrep*: A Robust Preprocessing Pipeline for fMRI Data
+=========================================================
 
 This pipeline is developed by the `Poldrack lab at Stanford University
 <https://poldracklab.stanford.edu/>`_ for use at the `Center for Reproducible
@@ -43,7 +43,7 @@ About
 .. image:: https://github.com/oesteban/fmriprep/raw/38a63e9504ab67812b63813c5fe9af882109408e/docs/_static/fmriprep-workflow-all.png
 
 
-``fmriprep`` is a functional magnetic resonance imaging (fMRI) data
+*fMRIPrep* is a functional magnetic resonance imaging (fMRI) data
 preprocessing pipeline that is designed to provide an easily accessible,
 state-of-the-art interface that is robust to variations in scan acquisition
 protocols and that requires minimal user input, while providing easily
@@ -56,12 +56,12 @@ volume-based statistics, etc.
 
 .. note::
 
-   fmriprep performs minimal preprocessing.
+   *fMRIPrep* performs minimal preprocessing.
    Here we define 'minimal preprocessing'  as motion correction, field
    unwarping, normalization, bias field correction, and brain extraction.
    See the workflows_ for more details.
 
-The ``fmriprep`` pipeline uses a combination of tools from well-known software
+The *fMRIPrep* pipeline uses a combination of tools from well-known software
 packages, including FSL_, ANTs_, FreeSurfer_ and AFNI_.
 This pipeline was designed to provide the best software implementation for each
 state of preprocessing, and will be updated as newer and better neuroimaging
@@ -86,7 +86,7 @@ https://fmriprep.readthedocs.io/
 Principles
 ----------
 
-``fmriprep`` is built around three principles:
+*fMRIPrep* is built around three principles:
 
 1. **Robustness** - The pipeline adapts the preprocessing steps depending on
    the input dataset and should provide results as good as possible
@@ -97,22 +97,22 @@ Principles
    automatic fashion.
 3. **"Glass box"** philosophy - Automation should not mean that one should not
    visually inspect the results or understand the methods.
-   Thus, ``fmriprep`` provides visual reports for each subject, detailing the
+   Thus, *fMRIPrep* provides visual reports for each subject, detailing the
    accuracy of the most important processing steps.
    This, combined with the documentation, can help researchers to understand
    the process and decide which subjects should be kept for the group level
    analysis.
 
 
-Limitations and reasons not to use ``fmriprep``
------------------------------------------------
+Limitations and reasons not to use *fMRIPrep*
+---------------------------------------------
 
 1. Very narrow :abbr:`FoV (field-of-view)` images oftentimes do not contain
    enough information for standard image registration methods to work correctly.
    Also, problems may arise when extracting the brain from these data.
    Supporting these particular images is already a future line of the development
    road-map.
-2. ``fmriprep`` may also underperform for particular populations (e.g., infants) and
+2. *fMRIPrep* may also underperform for particular populations (e.g., infants) and
    non-human brains, although appropriate templates can be provided to overcome the
    issue.
 3. The "EPInorm" approach is currently not supported, although we plan to implement
@@ -131,6 +131,6 @@ Acknowledgements
 ----------------
 
 Please acknowledge this work by mentioning explicitly the name of this software
-(fmriprep) and the version, along with a link to the `GitHub repository
+(*fMRIPrep*) and the version, along with a link to the `GitHub repository
 <https://github.com/poldracklab/fmriprep>`_ or the Zenodo reference.
 For more details, please see :ref:`citation`.

docs/_static/sbatch.slurm

@@ -0,0 +1,60 @@
+#!/bin/bash
+#
+#SBATCH -J fmriprep
+#SBATCH --time=48:00:00
+#SBATCH -n 1
+#SBATCH --cpus-per-task=16
+#SBATCH --mem-per-cpu=4G
+#SBATCH -p normal,mygroup  # Queue names you can submit to
+# Outputs ----------------------------------
+#SBATCH -o log/%x-%A-%a.out
+#SBATCH -e log/%x-%A-%a.err
+#SBATCH --mail-user=%[email protected]
+#SBATCH --mail-type=ALL
+# ------------------------------------------
+
+BIDS_DIR="$STUDY/data"
+DERIVS_DIR="derivatives/fmriprep-1.5.0"
+
+# Prepare some writeable bind-mount points.
+TEMPLATEFLOW_HOST_HOME=$HOME/.cache/templateflow
+FMRIPREP_HOST_CACHE=$HOME/.cache/fmriprep
+mkdir -p ${TEMPLATEFLOW_HOST_HOME}
+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"
+
+# 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
+
+# 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"
+
+# Setup done, run the command
+echo Running task ${SLURM_ARRAY_TASK_ID}
+echo Commandline: $cmd
+eval $cmd
+exitcode=$?
+
+# Output results to a table
+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

docs/citing.rst

@@ -2,11 +2,11 @@
 
 .. _citation:
 
-===============
-Citing FMRIPREP
-===============
+=================
+Citing *fMRIPrep*
+=================
 
-Select which options you have run FMRIPREP with to generate custom language
+Select which options you have run *fMRIPrep* with to generate custom language
 we recommend to include in your paper.
 
 

docs/conf.py

@@ -76,7 +76,7 @@
 
 # General information about the project.
 project = 'fmriprep'
-author = 'The FMRIPREP developers'
+author = 'The fMRIPrep developers'
 copyright = '2016-%s, %s' % (datetime.now().year, author)
 
 # The version info for the project you're documenting, acts as replacement for

docs/contributors.rst

@@ -24,7 +24,8 @@ Patching working repositories
 In order to test new code without rebuilding the Docker image, it is
 possible to mount working repositories as source directories within the
 container.
-The `fmriprep-docker`_ script simplifies this for the most common repositories::
+The `Docker wrapper`_ script simplifies this
+for the most common repositories::
 
     -f PATH, --patch-fmriprep PATH
                           working fmriprep repository (default: None)
@@ -131,8 +132,8 @@ version string from the current repository state.
 
 To work in this image, replace ``poldracklab/fmriprep:latest`` with
 ``fmriprep`` in any of the above commands.
-This image may be accessed by the `fmriprep-docker`_ wrapper via the
-``-i`` flag, e.g., ::
+This image may be accessed by the `Docker wrapper`_
+via the ``-i`` flag, e.g., ::
 
     $ fmriprep-docker -i fmriprep --shell
 

docs/docker.rst

@@ -0,0 +1,115 @@
+.. include:: links.rst
+
+.. _run_docker:
+
+Running *fMRIPrep* via Docker containers
+========================================
+For every new version of *fMRIPrep* that is released, a corresponding Docker
+image is generated.
+The Docker image *becomes* a container when the execution engine loads the
+image and adds an extra layer that makes it *runnable*.
+In order to run *fMRIPrep* Docker images, the Docker Engine must be installed
+(see :ref:`installation_docker`).
+
+If you used *fMRIPrep* via Docker in the past, you might need to pull down a
+more recent version of the image: ::
+
+    $ docker pull poldracklab/fmriprep:<latest-version>
+
+You can run *fMRIPrep* interacting directly with the Docker Engine via the `docker run`
+command line, or you can use a lightweight wrapper we created for convenience.
+
+.. _docker_wrapper:
+
+Running *fMRIPrep* with the ``fmriprep-docker`` wrapper
+-------------------------------------------------------
+Before starting, make sure you
+`have the wrapper installed <installation.html#the-fmriprep-docker-wrapper>`__.
+When you run ``fmriprep-docker``, it will generate a Docker command line for you,
+print it out for reporting purposes, and then execute it without further action
+needed, e.g.::
+
+    $ fmriprep-docker /path/to/data/dir /path/to/output/dir participant
+    RUNNING: docker run --rm -it -v /path/to/data/dir:/data:ro \
+        -v /path/to_output/dir:/out poldracklab/fmriprep:1.0.0 \
+        /data /out participant
+    ...
+
+``fmriprep-docker`` accepts all of the typical options for *fMRIPrep* (see :ref:`usage`),
+automatically translating directories into Docker mount points.
+
+We have published a `step-by-step tutorial
+<http://reproducibility.stanford.edu/fmriprep-tutorial-running-the-docker-image/>`_
+illustrating how to run ``fmriprep-docker``. 
+This tutorial also provides valuable troubleshooting insights and advice on 
+what to do after *fMRIPrep* has run.
+
+
+Running *fMRIPrep* directly interacting with the Docker Engine
+--------------------------------------------------------------
+If you need a finer control over the container execution, or you feel comfortable
+with the Docker Engine, avoiding the extra software layer of the wrapper might be
+a good decision.
+
+**Accessing filesystems in the host within the container**.
+Containers are confined in a sandbox, so they can't access the host in any ways unless 
+you explicitly prescribe acceptable accesses to the host.
+The Docker Engine provides mounting filesystems into the container with the ``-v`` argument
+and the following syntax: ``-v some/path/in/host:/absolute/path/within/container:ro``,
+where the trailing ``:ro`` specifies that the mount is read-only.
+The mount permissions modifiers can be omitted, which means the mount will have read-write
+permissions.
+In general, you'll want to at least provide two mount-points: one set in read-only mode
+for the input data and one read/write to store the outputs.
+Potentially, you'll want to provide one or two more mount-points: one for the working
+directory, in case you need to debug some issue or reuse pre-cached results; and
+a :ref:`TemplateFlow` folder to preempt the download of your favorite templates in every
+run.
+
+**Running containers as a user**.
+By default, Docker will run the container as **root**.
+Some share systems my limit this feature and only allow running containers as a user.
+When the container is run as **root**, files written out to filesystems mounted from the
+host will have the user id ``1000`` by default.
+In other words, you'll need to be able to run as root in the host to change permissions
+or manage these files.
+Alternatively, running as a user allows preempting these permissions issues.
+It is possible to run as a user with the ``-u`` argument.
+In general, we will want to use the same user ID as the running user in the host to
+ensure the ownership of files written during the container execution.
+Therefore, you will generally run the container with ``-u $( id -u )``.
+
+You may also invoke ``docker`` directly::
+
+    $ docker run -ti --rm \
+        -v path/to/data:/data:ro \
+        -v path/to/output:/out \
+        poldracklab/fmriprep:<latest-version> \
+        /data /out/out \
+        participant
+
+For example: ::
+
+    $ docker run -ti --rm \
+        -v $HOME/ds005:/data:ro \
+        -v $HOME/ds005/derivatives:/out \
+        -v $HOME/tmp/ds005-workdir:/work \
+        poldracklab/fmriprep:<latest-version> \
+        /data /out/fmriprep-<latest-version> \
+        participant \
+        -w /work
+
+Once the Docker Engine arguments are written, the remainder of the command line follows
+the :ref:`usage`.
+In other words, the first section of the command line is all equivalent to the ``fmriprep``
+executable in a bare-metal installation: ::
+
+    $ docker run -ti --rm \                      | These lines
+        -v $HOME/ds005:/data:ro \                | are equivalent
+        -v $HOME/ds005/derivatives:/out \        | to the fmriprep
+        -v $HOME/tmp/ds005-workdir:/work \       | executable.
+        poldracklab/fmriprep:<latest-version> \  |
+        \
+        /data /out/fmriprep-<latest-version> \   | These lines
+        participant \                            | correspond to
+        -w /work                                 | fmriprep arguments.

docs/faq.rst

@@ -6,7 +6,6 @@ FAQ, Tips, and Tricks
 
 Should I run quality control of my images before running *fMRIPrep*?
 --------------------------------------------------------------------
-
 Yes. You should do so before any processing/analysis takes place.
 
 Oftentimes (more often than we would like), images have fatal artifacts and problems.
@@ -27,7 +26,6 @@ some kind of preprocessing (see next question).
 
 What if I find some images have undergone some pre-processing already (e.g., my T1w image is already skull-stripped)?
 ---------------------------------------------------------------------------------------------------------------------
-
 These images imply an unknown level of preprocessing (e.g. was it already bias-field corrected?),
 which makes it difficult to decide on best-practices for further processing.
 Hence, supporting such images was considered very low priority for *fMRIPrep*.
@@ -40,7 +38,6 @@ reverting to the original, defaced, T1w images to ensure more uniform preprocess
 
 My *fMRIPrep* run is hanging...
 -------------------------------
-
 When running on Linux platforms (or containerized environments, because they are built around
 Ubuntu), there is a Python bug that affects *fMRIPrep* that drives the Linux kernel to kill
 processes as a response to running out of memory.
@@ -62,7 +59,6 @@ Additionally, consider using the ``--low-mem`` flag, which will make some memory
 
 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*.
 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
@@ -117,7 +113,6 @@ In general, please be cautious of deleting files and mindful why a file may exis
 
 Running subjects in parallel
 ----------------------------
-
 When running several subjects in parallel, and depending on your settings, fMRIPrep may
 fall into race conditions.
 A symptomatic output looks like: ::
@@ -155,7 +150,6 @@ number of CPUs divided by the number of subjects is most efficient.
 
 A new version of *fMRIPrep* has been published, when should I upgrade?
 ----------------------------------------------------------------------
-
 We follow a philosophy of releasing very often, although the pace is slowing down
 with the maturation of the software.
 It is very likely that your version gets outdated over the extent of your study.
@@ -169,3 +163,16 @@ using the latest version of the tool.
 In any case, if you can find your release listed as *flagged* in `this file
 of our repo <https://github.com/poldracklab/fmriprep/blob/master/.versions.json>`__,
 then please update as soon as possible.
+
+What is *TemplateFlow* for?
+---------------------------
+*TemplateFlow* enables *fMRIPrep* to generate preprocessed outputs spatially normalized to
+a number of different neuroimaging templates (e.g. MNI).
+For further details, please check `its documentation section <spaces.html#templateflow>`__.
+
+I'm running *fMRIPrep* via Singularity containers - how can I troubleshoot problems?
+------------------------------------------------------------------------------------
+We have extended `this documentation <singularity.html>`__ to cover some of the most
+frequent issues other Singularity users have been faced with.
+Generally, users have found it hard to `get TemplateFlow and Singularity to work
+together <singularity.html#singularity-tf>`__.

docs/index.rst

@@ -15,13 +15,15 @@ Contents
    :maxdepth: 3
 
    installation
-   changes
    usage
+   docker
+   singularity
    workflows
    sdc
-   spaces
    outputs
+   spaces
    faq
    contributors
    citing
    api/index.rst
+   changes