Merge pull request #317 from effigies/fmriprep_wrapper

[RTM] fmriprep-docker wrapper script

CHANGES.rst

@@ -8,6 +8,7 @@ Next release
 * [ENH] Sample functional series to subject and ``fsaverage`` surfaces (#391)
 * [ENH] Output spaces for functional data may be selected with ``--output-space`` option (#447)
 * [DEP] ``--skip-native`` functionality replaced by ``--output-space`` (#447)
+* [ENH] ``fmriprep-docker`` wrapper script simplifies running in a Docker environment (#317)
 
 0.3.2 (7th of April 2017)
 =========================

circle.yml

@@ -27,9 +27,11 @@ dependencies:
   override:
     - if [[ -e $HOME/docker/image.tar ]]; then docker load -i $HOME/docker/image.tar; fi
     - sed -i -E "s/(__version__ = )'[A-Za-z0-9.-]+'/\1'$CIRCLE_TAG'/" fmriprep/info.py
+    - sed -i -E "s/(__version__ = )'[A-Za-z0-9.-]+'/\1'$CIRCLE_TAG'/" wrapper/fmriprep_docker.py
     - e=1 && for i in {1..5}; do docker build --rm=false -t poldracklab/fmriprep:latest --build-arg BUILD_DATE=`date -u +"%Y-%m-%dT%H:%M:%SZ"` --build-arg VCS_REF=`git rev-parse --short HEAD` --build-arg VERSION=$CIRCLE_TAG . && e=0 && break || sleep 15; done && [ "$e" -eq "0" ] :
         timeout: 21600
     - mkdir -p $HOME/docker; docker save poldracklab/fmriprep:latest > $HOME/docker/image.tar
+    - pip install future && pip install --upgrade wrapper/
 test:
   override:
     - docker run -ti --rm=false --entrypoint="python" poldracklab/fmriprep:latest -m unittest discover test
@@ -38,8 +40,8 @@ test:
     - cat $HOME/docs/builddocs.log && if grep -q "ERROR" $HOME/docs/builddocs.log; then false; else true; fi
     - docker run -ti --rm=false -v $HOME/nipype.cfg:/root/.nipype/nipype.cfg:ro -v $HOME/data:/data:ro -v $HOME/ds054/scratch:/scratch -v $HOME/ds054/out:/out poldracklab/fmriprep:latest /data/ds054 /out/ participant --no-freesurfer --debug -w /scratch:
         timeout: 4800
-    - docker run -ti --rm=false -v $HOME/nipype.cfg:/root/.nipype/nipype.cfg:ro -v $HOME/data:/data:ro -v $HOME/ds005/scratch:/scratch -v $HOME/ds005/out:/out poldracklab/fmriprep:latest /data/ds005 /out/ participant --no-freesurfer --debug -w /scratch:
-       timeout: 4800
+    - fmriprep-docker -i poldracklab/fmriprep:latest --config $HOME/nipype.cfg -w $HOME/ds005/scratch $HOME/data/ds005 $HOME/ds005/out participant --no-freesurfer --debug:
+        timeout: 4800
     - find ~/ds054/scratch -not -name "*.svg" -not -name "*.html" -not -name "*.svg" -not -name "*.rst" -type f -delete
     - find ~/ds005/scratch -not -name "*.svg" -not -name "*.html" -not -name "*.svg" -not -name "*.rst" -type f -delete
 
@@ -61,3 +63,4 @@ deployment:
           timeout: 21600
       - printf "[distutils]\nindex-servers =\n    pypi\n\n[pypi]\nusername:$PYPI_USER\npassword:$PYPI_PASS\n" > ~/.pypirc
       - python setup.py sdist upload -r pypi
+      - cd wrapper && python setup.py sdist upload -r pypi

docs/contributors.rst

@@ -23,12 +23,27 @@ 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.
-In the docker container, the all Python packages are installed in
-``/usr/local/miniconda/lib/python3.6/site-packages``.
+The `fmriprep-docker`_ script simplifies this for the most common repositories::
 
-To patch in working repositories of FMRIPREP or its dependencies, for instance
-contained in ``$HOME/projects/``, add the following arguments to your docker
-command: ::
+    -f PATH, --patch-fmriprep PATH
+                          working fmriprep repository (default: None)
+    -n PATH, --patch-niworkflows PATH
+                          working niworkflows repository (default: None)
+    -p PATH, --patch-nipype PATH
+                          working nipype repository (default: None)
+
+For instance, if your repositories are contained in ``$HOME/projects``::
+
+    $ fmriprep-docker -f $HOME/projects/fmriprep/fmriprep \
+                      -n $HOME/projects/niworkflows/niworkflows \
+                      -p $HOME/projects/nipype/nipype \
+                      -i poldracklab/fmriprep:latest \
+                      $HOME/fullds005 $HOME/dockerout participant
+
+Note the ``-i`` flag allows you to specify an image.
+
+When invoking ``docker`` directly, the mount options must be specified
+with the ``-v`` flag::
 
     -v $HOME/projects/fmriprep/fmriprep:/usr/local/miniconda/lib/python3.6/site-packages/fmriprep:ro
     -v $HOME/projects/niworkflows/niworkflows:/usr/local/miniconda/lib/python3.6/site-packages/niworkflows:ro
@@ -41,8 +56,13 @@ For example, ::
         poldracklab/fmriprep:latest /data /out/out participant \
         -w /out/work/
 
-In order to work directly in the container, use ``--entrypoint=bash``, and
-omit the fmriprep arguments: ::
+In order to work directly in the container, pass the ``--shell`` flag to
+``fmriprep-docker``::
+
+    $ fmriprep-docker --shell $HOME/fullds005 $HOME/dockerout participant
+
+This is the equivalent of using ``--entrypoint=bash`` and omitting the fmriprep
+arguments in a ``docker`` command::
 
     $ docker run --rm -v $HOME/fullds005:/data:ro -v $HOME/dockerout:/out \
         -v $HOME/projects/fmriprep/fmriprep:/usr/local/miniconda/lib/python3.6/site-packages/fmriprep:ro --entrypoint=bash \
@@ -97,3 +117,7 @@ repository, located in ``~/projects/fmriprep``: ::
 
 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. ::
+
+    $ fmriprep-docker -i fmriprep --shell

docs/installation.rst

@@ -15,7 +15,19 @@ Make sure command-line `Docker is installed <https://docs.docker.com/engine/inst
 
 See `External Dependencies`_ for more information (e.g., specific versions) on what is included in the fmriprep Docker image.
 
-Now, assuming you have data, you can run fmriprep. You will need an active internet connection the first time. ::
+There are two ways to run fmriprep through Docker; the first, recommended way
+is to use the `fmriprep-docker`_ wrapper.
+This requires Python and an internet connection.
+
+To install::
+
+    $ pip install --user --upgrade fmriprep-docker
+
+To run::
+
+    $ fmriprep-docker /path/to/data/dir /path/to/output/dir participant
+
+The second way to run fmriprep is to invoke ``docker`` directly. ::
 
     $ docker run -ti --rm \
         -v filepath/to/data/dir:/data:ro \

docs/links.rst

@@ -8,3 +8,4 @@
 .. _`submillimeter reconstruction`: https://surfer.nmr.mgh.harvard.edu/fswiki/SubmillimeterRecon
 .. _GIFTI: https://www.nitrc.org/projects/gifti/
 .. _`Connectome Workbench`: https://www.humanconnectome.org/software/connectome-workbench.html
+.. _`fmriprep-docker`: https://pypi.python.org/pypi/fmriprep-docker

fmriprep/info.py

@@ -8,9 +8,9 @@
 
 __version__ = '99.99.99'
 __author__ = 'The CRN developers'
-__copyright__ = 'Copyright 2016, Center for Reproducible Neuroscience, Stanford University'
+__copyright__ = 'Copyright 2017, Center for Reproducible Neuroscience, Stanford University'
 __credits__ = ['Craig Moodie', 'Ross Blair', 'Oscar Esteban', 'Chris Gorgolewski', 'Shoshana Berleant',
-               'Russell A. Poldrack']
+               'Christopher J. Markiewicz', 'Russell A. Poldrack']
 __license__ = '3-clause BSD'
 __maintainer__ = 'Ross Blair'
 __email__ = '[email protected]'
@@ -24,6 +24,7 @@
     'https://pypi.python.org/packages/source/{name[0]}/{name}/{name}-{ver}.tar.gz'.format(
         name=__packagename__, ver=__version__))
 
+
 SETUP_REQUIRES = [
     'setuptools>=18.0',
     'numpy',
@@ -68,6 +69,6 @@
     'Intended Audience :: Science/Research',
     'Topic :: Scientific/Engineering :: Image Recognition',
     'License :: OSI Approved :: BSD License',
-    'Programming Language :: Python :: 2.7',
     'Programming Language :: Python :: 3.5',
+    'Programming Language :: Python :: 3.6',
 ]