Installation

There are four ways to use fmriprep: on the free cloud service OpenNeuro.org, in a Docker Container, in a Singularity Container, or in a Manually Prepared Environment. Using OpenNeuro or a local container method is highly recommended. Once you are ready to run fmriprep, see Usage for details.

OpenNeuro

fmriprep is available on the free cloud platform OpenNeuro.org. After uploading your BIDS-compatible dataset to OpenNeuro you will be able to run fmriprep for free using OpenNeuro servers. This is the easiest way to run fmriprep, as there is no installation required.

Docker Container

In order to run fmriprep in a Docker container, Docker must be installed. Once Docker is installed, the recommended way to run fmriprep is to use the fmriprep-docker wrapper, which requires Python and an Internet connection.

To install:

$ pip install --user --upgrade fmriprep-docker

When run, fmriprep-docker will generate a Docker command line for you, print it out for reporting purposes, and then run the command, 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 --no-freesurfer
...

You may also invoke docker directly:

$ docker run -ti --rm \
    -v filepath/to/data/dir:/data:ro \
    -v filepath/to/output/dir:/out \
    poldracklab/fmriprep:latest \
    /data /out/out \
    participant --no-freesurfer

For example:

$ docker run -ti --rm \
    -v $HOME/fullds005:/data:ro \
    -v $HOME/dockerout:/out \
    poldracklab/fmriprep:latest \
    /data /out/out \
    participant \
    --ignore fieldmaps --no-freesurfer

See External Dependencies for more information (e.g., specific versions) on what is included in the latest Docker images.

If the flag --no-freesurfer is not set, then FreeSurfer will require a proper license file (see The FreeSurfer license).

Singularity Container

For security reasons, many HPCs (e.g., TACC) do not allow Docker containers, but do allow Singularity containers. In this case, start with a machine (e.g., your personal computer) with Docker installed. Use 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

Beware of the back slashes, expected for Windows systems. For *nix users the command translates as follows:

$ docker run --privileged -t --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /absolute/path/to/output/folder:/output \
    singularityware/docker2singularity \
    poldracklab/fmriprep:latest

Transfer the resulting Singularity image to the HPC, for example, using scp.

$ scp poldracklab_fmriprep_latest-*.img user@hcpserver.edu:/path/to/downloads

If the data to be preprocessed is also on the HPC, you are ready to run fmriprep.

$ singularity run path/to/singularity/image.img \
    path/to/data/dir path/to/output/dir \
    participant \
    --participant-label label

For example:

$ 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 \
    --ants-nthreads 16

Note

Singularity by default exposes all environment variables from the host inside the container. 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:

$ 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 \
  --ants-nthreads 16

Manually Prepared Environment

Note

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 system’s $PATH.

If you have pip installed, install fmriprep

$ pip install fmriprep

If you have your data on hand, you are ready to run fmriprep:

$ fmriprep data/dir output/dir participant --participant-label label

The FreeSurfer license

FMRIPREP will run FreeSurfer unless the --no-freesurfer command-line argument is provided. Therefore, make sure there is a valid FreeSurfer available to FMRIPREP or opt-out otherwise.

Getting a FreeSurfer license is free, register a new key 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).

It is possible to run the docker container pointing the image to a local path where a valid license file is stored. For example, if the license is stored in the $HOME/.licenses/freesurfer/license.txt file on the host system:

$ docker run -ti --rm \
    -v $HOME/fullds005:/data:ro \
    -v $HOME/dockerout:/out \
    -v $HOME/.licenses/freesurfer/license.txt:/opt/freesurfer/license.txt \
    poldracklab/fmriprep:latest \
    /data /out/out \
    participant \
    --ignore fieldmaps

Using FreeSurfer can also be enabled when using fmriprep-docker:

$ fmriprep-docker --fs-license-file $HOME/.licenses/freesurfer/license.txt \
    /path/to/data/dir /path/to/output/dir participant
RUNNING: docker run --rm -it -v /path/to/data/dir:/data:ro \
    -v /home/user/.licenses/freesurfer/license.txt:/opt/freesurfer/license.txt \
    -v /path/to_output/dir:/out poldracklab/fmriprep:1.0.0 \
    /data /out participant
...

If the environment variable $FS_LICENSE is set in the host system, then it will automatically used by fmriprep-docker. For instance, the following would be equivalent to the latest example:

$ export FS_LICENSE=$HOME/.licenses/freesurfer/license.txt
$ fmriprep-docker /path/to/data/dir /path/to/output/dir participant
RUNNING: docker run --rm -it -v /path/to/data/dir:/data:ro \
    -v /home/user/.licenses/freesurfer/license.txt:/opt/freesurfer/license.txt \
    -v /path/to_output/dir:/out poldracklab/fmriprep:1.0.0 \
    /data /out participant
...

External Dependencies

fmriprep is implemented using nipype, but it requires some other neuroimaging software tools:

  • FSL (version 5.0.9)
  • ANTs (version 2.2.0 - NeuroDocker build)
  • AFNI (version Debian-16.2.07)
  • C3D (version 1.0.0)
  • FreeSurfer (version 6.0.1)
  • ICA-AROMA (version 0.4.1-beta)