Merge pull request #1063 from poldracklab/chrisfilo-patch-2

[DOC] Improving documentation on using Singularity

Author: oesteban

docs/installation.rst

@@ -66,16 +66,35 @@ what is included in the latest Docker images.
 Singularity Container
 =====================
 
-For security reasons, many HPCs (e.g., TACC) do not allow Docker containers, but do allow `Singularity <https://github.com/singularityware/singularity>`_ containers.
+For security reasons, many HPCs (e.g., TACC) do not allow Docker containers, but do
+allow `Singularity <https://github.com/singularityware/singularity>`_ containers.
+
+Preparing a Singularity image (Singularity version >= 2.5)
+----------------------------------------------------------
+If the version of Singularity on your HPC is modern enough you can create Singularity
+image directly on the HCP.
+This is as simple as: ::
+
+    $ singularity build /my_images/fmriprep-<version>.simg docker://poldracklab/mriqc:<version>
+    
+Where ``<version>`` should be replaced with the desired version of fMRIPrep that you want to download.
+
+
+Preparing a Singularity image (Singularity version < 2.5)
+---------------------------------------------------------
 In this case, start with a machine (e.g., your personal computer) with Docker installed.
-Use `docker2singularity <https://github.com/singularityware/docker2singularity>`_ to create a singularity image. You will need an active internet connection and some time. ::
+Use `docker2singularity <https://github.com/singularityware/docker2singularity>`_ to 
+create a singularity image.
+You will need an active internet connection and some time. ::
 
     $ docker run --privileged -t --rm \
         -v /var/run/docker.sock:/var/run/docker.sock \
         -v D:\host\path\where\to\output\singularity\image:/output \
         singularityware/docker2singularity \
-        poldracklab/fmriprep:latest
+        poldracklab/fmriprep:<version>
 
+Where ``<version>`` should be replaced with the desired version of fMRIPrep that you want 
+to download.
 
 Beware of the back slashes, expected for Windows systems.
 For \*nix users the command translates as follows: ::
@@ -84,46 +103,69 @@ For \*nix users the command translates as follows: ::
         -v /var/run/docker.sock:/var/run/docker.sock \
         -v /absolute/path/to/output/folder:/output \
         singularityware/docker2singularity \
-        poldracklab/fmriprep:latest
+        poldracklab/fmriprep:<version>
 
 
 Transfer the resulting Singularity image to the HPC, for example, using ``scp``. ::
 
-    $ scp poldracklab_fmriprep_latest-*.img [email protected]:/path/to/downloads
+    $ scp poldracklab_fmriprep*.img [email protected]:/my_images
+
+Running a Singularity Image
+---------------------------
 
 If the data to be preprocessed is also on the HPC, you are ready to run fmriprep. ::
 
-    $ singularity run path/to/singularity/image.img \
+    $ singularity run --clearenv /my_images/fmriprep-1.1.2.simg \
         path/to/data/dir path/to/output/dir \
         participant \
         --participant-label label
 
-For example: ::
+.. note::
 
-    $ singularity run ~/poldracklab_fmriprep_latest-2016-12-04-5b74ad9a4c4d.img \
+   Singularity by default `exposes all environment variables from the host inside 
+   the container <https://github.com/singularityware/singularity/issues/445>`_.
+   Because of this your host libraries (such as nipype) could be accidentally used 
+   instead of the ones inside the container - if they are included in ``PYTHONPATH``.
+   To avoid such situation we recommend using the ``--clearenv`` singularity flag 
+   in production use. For example: ::
+
+      $ singularity run --clearenv ~/poldracklab_fmriprep_latest-2016-12-04-5b74ad9a4c4d.img \
         /work/04168/asdf/lonestar/ $WORK/lonestar/output \
         participant \
         --participant-label 387 --nthreads 16 -w $WORK/lonestar/work \
         --omp-nthreads 16
 
-.. note::
 
-   Singularity by default `exposes all environment variables from the host inside the container <https://github.com/singularityware/singularity/issues/445>`_.
-   Because of this your host libraries (such as nipype) could be accidentally used instead of the ones inside the container - if they are included in PYTHONPATH.
-   To avoid such situation we recommend unsetting PYTHONPATH in production use. For example: ::
+    or, unset the ``PYTHONPATH`` variable before running: ::
 
-      $ PYTHONPATH="" singularity run ~/poldracklab_fmriprep_latest-2016-12-04-5b74ad9a4c4d.img \
+      $ unset PYTHONPATH; singularity run ~/poldracklab_fmriprep_latest-2016-12-04-5b74ad9a4c4d.img \
         /work/04168/asdf/lonestar/ $WORK/lonestar/output \
         participant \
         --participant-label 387 --nthreads 16 -w $WORK/lonestar/work \
         --omp-nthreads 16
 
+
+.. note::
+
+   Depending on how Singularity is configured on your cluster it might or might not 
+   automatically bind (mount or expose) host folders to the container. 
+   If this is not done automatically you will need to bind the necessary folders using 
+   the ``-B <host_folder>:<container_folder>`` Singularity argument.
+   For example: ::
+
+      $ singularity run --clearenv -B /work:/work ~/poldracklab_fmriprep_latest-2016-12-04-5b74ad9a4c4d.simg \
+        /work/my_dataset/ /work/my_dataset/derivatives/fmriprep \
+        participant \
+        --participant-label 387 --nthreads 16 \
+        --omp-nthreads 16
+
 Manually Prepared Environment
 =============================
 
-.. note::
+.. warning::
 
-   This method is not recommended! Make sure you would rather do this than use a `Docker Container`_ or a `Singularity Container`_.
+   This method is not recommended! Make sure you would rather do this than 
+   use a `Docker Container`_ or a `Singularity Container`_.
 
 Make sure all of fmriprep's `External Dependencies`_ are installed.
 These tools must be installed and their binaries available in the
@@ -149,9 +191,11 @@ FMRIPREP uses FreeSurfer tools, which require a license to run.
 To obtain a FreeSurfer license, simply register for free at
 https://surfer.nmr.mgh.harvard.edu/registration.html.
 
-When using manually-prepared environments, 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``).
+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 ``--clearenv`` 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
 where a valid license file is stored.
@@ -193,7 +237,7 @@ would be equivalent to the latest example: ::
 External Dependencies
 =====================
 
-``fmriprep`` is implemented using nipype_, but it requires some other neuroimaging
+FMRIPrep is implemented using nipype_, but it requires some other neuroimaging
 software tools:
 
 - FSL_ (version 5.0.9)