Skip to content

DOCS: add brief neurodocker tutorial #2464

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Feb 24, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions doc/links_names.txt
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@
.. _EPD: http://www.enthought.com/products/epd.php
.. _Traits: http://code.enthought.com/projects/traits/
.. _Miniconda: https://conda.io/miniconda.html
.. _neurodocker: https://github.com/kaczmarj/neurodocker

.. Python imaging projects
.. _PyMVPA: http://www.pymvpa.org
Expand Down Expand Up @@ -105,6 +106,7 @@
.. _macports: http://www.macports.org/
.. _Vagrant: http://www.vagrantup.com/
.. _Docker: http://www.docker.io/
.. _Singularity: http://singularity.lbl.gov/
.. _Virtualbox: https://www.virtualbox.org/

.. Functional imaging labs
Expand Down
12 changes: 7 additions & 5 deletions doc/users/install.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,14 @@ This page covers the necessary steps to install Nipype.
Using docker
~~~~~~~~~~~~

You can follow the `Nipype tutorial <https://miykael.github.io/nipype_tutorial/>`_
To get started using Docker, you can follow the `Nipype tutorial
<https://miykael.github.io/nipype_tutorial/>`_, or pull the `nipype/nipype`
image from Docker hub::

or use this docker container: `docker pull nipype/nipype`
docker pull nipype/nipype

or if you want to build custom docker containers with specific versions of
software see `Neurodocker <https://github.com/kaczmarj/neurodocker>`_
You may also build custom docker containers with specific versions of software
using Neurodocker_ (see the :doc:`neurodocker`).

Using conda
~~~~~~~~~~~
Expand Down Expand Up @@ -108,7 +110,7 @@ Interface Dependencies
Nipype provides wrappers around many neuroimaging tools and contains some
algorithms. These tools will need to be installed for Nipype to run. You can
create containers with different versions of these tools installed using
`Neurodocker <https://github.com/kaczmarj/neurodocker>`_
Neurodocker_ (see the :doc:`neurodocker`).

Installation for developers
---------------------------
Expand Down
112 changes: 112 additions & 0 deletions doc/users/neurodocker.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
.. _neurodocker_tutorial:

====================
Neurodocker tutorial
====================

This page covers the steps to create containers with Neurodocker_.

Neurodocker_ is a command-line program that enables users to generate Docker_
containers that include neuroimaging software. These containers can be
converted to Singularity_ containers for use in high-performance computing
centers.

Requirements:

* Docker_
* Internet connection


Usage
-----

To view the Neurodocker help message
::
docker run --rm kaczmarj/neurodocker:v0.3.2 generate --help

1. Users must specify a base Docker image and the package manager. Any Docker
image on DockerHub can be used as your base image. Common base images
include ``debian:stretch``, ``ubuntu:16.04``, ``centos:7``, and the various
``neurodebian`` images. If users would like to install software from the
NeuroDebian repositories, it is recommended to use a ``neurodebian`` base
image. The package manager is ``apt`` or ``yum``, depending on the base
image.
2. Next, users should configure the container to fit their needs. This includes
installing neuroimaging software, installing packages from the chosen package
manager, installing Python and Python packages, copying files from the local
machine into the container, and other operations. The list of supported
neuroimaging software packages is available in the ``neurodocker`` help
message.
3. The ``neurodocker`` command will generate a Dockerfile. This Dockerfile can
be used to build a Docker image with the ``docker build`` command.


Create a Dockerfile with FSL, Python 3.6, and Nipype
----------------------------------------------------

This command prints a Dockerfile (the specification for a Docker image) to the
terminal.
::
$ docker run --rm kaczmarj/neurodocker:v0.3.2 generate \
--base debian:stretch --pkg-manager apt \
--fsl version=5.0.10 \
--miniconda env_name=neuro \
conda_install="python=3.6 traits" \
pip_install="nipype"


Build the Docker image
----------------------

The Dockerfile can be saved and used to build the Docker image
::
$ docker run --rm kaczmarj/neurodocker:v0.3.2 generate \
--base debian:stretch --pkg-manager apt \
--fsl version=5.0.10 \
--miniconda env_name=neuro \
conda_install="python=3.6 traits" \
pip_install="nipype" > Dockerfile
$ docker build --tag my_image .
$ # or
$ docker build --tag my_image - < Dockerfile


Use NeuroDebian
---------------

This example installs AFNI and ANTs from the NeuroDebian repositories. It also
installs ``git`` and ``vim``.
::
$ docker run --rm kaczmarj/neurodocker:v0.3.2 generate \
--base neurodebian:stretch --pkg-manager apt \
--install afni ants git vim

Note: the ``--install`` option will install software using the package manager.
Because the NeuroDebian repositories are enabled in the chosen base image, AFNI
and ANTs may be installed using the package manager. ``git`` and ``vim`` are
available in the default repositories.


Other examples
--------------

Create a container with ``dcm2niix``, Nipype, and jupyter notebook. Install
Miniconda as a non-root user, and activate the Miniconda environment upon
running the container.
::
$ docker run --rm kaczmarj/neurodocker:v0.3.2 generate \
--base centos:7 --pkg-manager yum \
--dcm2niix version=master \
--user neuro \
--miniconda env_name=neuro conda_install="jupyter traits nipype" \
> Dockerfile
$ docker build --tag my_nipype - < Dockerfile


Copy local files into a container.
::
$ docker run --rm kaczmarj/neurodocker:v0.3.2 generate \
--base ubuntu:16.04 --pkg-manager apt \
--copy relative/path/to/source.txt /absolute/path/to/destination.txt

.. include:: ../links_names.txt