fmriprep: A Robust Preprocessing Pipeline for fMRI Data¶

Docker Container¶

Make sure command-line Docker is installed.

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.

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

For example:

$ docker run --rm -v $HOME/fullds005:/data:ro \
    -v $HOME/dockerout:/out -w /scratch \
    poldracklab/fmriprep:latest /data /out/out participant \
    -w /out/work/ --ignore fieldmaps

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 -v /var/run/docker.sock:/var/run/docker.sock \
    -v D:\host\path\where\to\ouptut\singularity\image:/output \
    --privileged -t --rm 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 \
    --participant_label label path/to/data/dir path/to/output/dir participant

For example:

$ singularity run ~/poldracklab_fmriprep_latest-2016-12-04-5b74ad9a4c4d.img \
    --participant_label sub-387 --nthreads 1 -w $WORK/lonestar/work \
    --ants-nthreads 16 --skull--strip-ants /work/04168/asdf/lonestar/ \
    $WORK/lonestar/output participant

Manually Prepared Environment¶

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_label sub-num participant

External Dependencies¶

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

• FSL (version 5.0.9)
• ANTs (version 2.1.0.Debian-Ubuntu_X64)
• AFNI (version Debian-16.2.07)
• C3D (version 1.0.0)

Execution and the BIDS format¶

The fmriprep workflow takes as principal input the path of the dataset that is to be processed. The only requirement to the input dataset is that it has a valid BIDS (Brain Imaging Data Structure) format. This can be easily checked online using the BIDS Validator.

The exact command to run fmriprep depends on the Installation method. The common parts of the command follow the BIDS-Apps definition. Example:

fmriprep data/bids_root/ out/ participant -w work/

Debugging¶

Logs and crashfiles are outputted into the <output dir>/logs directory. Information on how to customize and understand these files can be found on the nipype debugging page.

Support and communication¶

The documentation of this project is found here: http://fmriprep.readthedocs.org/en/latest/.

If you have a problem or would like to ask a question about how to use fmriprep, please submit a question to NeuroStars.org with an fmriprep tag. NeuroStars.org is a platform similar to StackOverflow but dedicated to neuroinformatics.

All previous fmriprep questions are available here: http://neurostars.org/t/fmriprep/

To participate in the fmriprep development-related discussions please use the following mailing list: http://mail.python.org/mailman/listinfo/neuroimaging Please add [fmriprep] to the subject line when posting on the mailing list.

All bugs, concerns and enhancement requests for this software can be submitted here: https://github.com/poldracklab/fmriprep/issues.

Basic workflow (no fieldmaps)¶

fmriprep‘s basic pipeline is used on datasets for which there are only t1ws and at least one functional (EPI) file, but no SBRefs or fieldmaps. To force using this pipeline on datasets that do include fieldmaps and SBRefs use the –ignore fieldmaps flag.

What It Does¶

High-level view of the basic pipeline:

BIDSDatasource¶

This node reads the BIDS-formatted t1 data.

t1w_preprocessing¶

The t1w_preprocessing sub-workflow finds the skull stripping mask and the white matter/gray matter/cerebrospinal fluid segments and finds a non-linear warp to the MNI space.

Brain extraction (ANTs).

Segmentation (FAST).

Animation showing T1 to MNI normalization (ANTs)

EPI_HMC¶

The EPI_HMC sub-workflow collects BIDS-formatted EPI files, performs head motion correction, and skullstripping.

Brain extraction (nilearn).

ref_epi_t1_registration¶

The ref_epi_t1_registration sub-workflow uses FSL FLIRT with the BBR cost function to find the transform that maps the EPI space into the T1-space.

Animation showing EPI to T1 registration (FSL FLIRT with BBR)

EPIMNITransformation¶

The EPIMNITransformation sub-workflow uses the transform from `EPIMeanNormalization`_ and a t1-to-MNI transform from t1w_preprocessing to map the EPI image to standardized MNI space. It also maps the t1w-based mask to MNI space.

Transforms are concatenated and applied all at once, with one interpolation step, so as little information is lost as possible.

ConfoundDiscoverer¶

Given a motion-corrected fMRI, a brain mask, MCFLIRT movement parameters and a segmentation, the ConfoundDiscoverer sub-workflow calculates potential confounds per volume.

Calculated confounds include the mean global signal, mean tissue class signal, tCompCor, aCompCor, Frawise Displacement, 6 motion parameters and DVARS.

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 following Python sources are kept in /root/src:

/root/src
├── fmriprep/
├── nipype/
└── niworkflows/

To patch in working repositories, for instance contained in $HOME/projects/, add the following arguments to your docker command:

-v $HOME/projects/fmriprep:/root/src/fmriprep:ro
-v $HOME/projects/niworkflows:/root/src/niworkflows:ro
-v $HOME/projects/nipype:/root/src/nipype:ro

For example,

$ docker run --rm -v $HOME/fullds005:/data:ro -v $HOME/dockerout:/out \
    -v $HOME/projects/fmriprep:/root/src/fmriprep:ro \
    poldracklab/fmriprep:latest /data /out/out participant \
    -w /out/work/ -t ds005

In order to work directly in the container, use --entrypoint=bash, and omit the fmriprep arguments:

$ docker run --rm -v $HOME/fullds005:/data:ro -v $HOME/dockerout:/out \
    -v $HOME/projects/fmriprep:/root/src/fmriprep:ro --entrypoint=bash \
    poldracklab/fmriprep:latest

$ docker run --rm -it --entrypoint=bash \
    -v $HOME/projects/fmriprep:/root/src/fmriprep \
    -v $HOME/projects/niworkflows:/root/src/niworkflows \
    -v $HOME/projects/nipype:/root/src/nipype \
    poldracklab/fmriprep:latest
root@03e5df018c5e:~# cd ~/src/fmriprep/
root@03e5df018c5e:~/src/fmriprep# pip install -e .
root@03e5df018c5e:~# cd ~/src/niworkflows/
root@03e5df018c5e:~/src/niworkflows# pip install -e .
root@03e5df018c5e:~# cd ~/src/nipype/
root@03e5df018c5e:~/src/nipype# pip install -e .

Adding dependencies¶

New dependencies to be inserted into the Docker image will either be Python or non-Python dependencies. Python dependencies may be added in three places, depending on whether the package is large or non-release versions are required. The image must be rebuilt after any dependency changes.

Python dependencies should generally be included in the REQUIRES list in fmriprep/info.py. If the latest version in PyPI is sufficient, then no further action is required.

For large Python dependencies where there will be a benefit to pre-compiled binaries, conda packages may also be added to the conda install line in the Dockerfile.

Finally, if a specific version of a repository needs to be pinned, edit the requirements.txt file. See the current file for examples.

Non-Python dependencies must also be installed in the Dockerfile, via a RUN command. For example, installing an apt package may be done as follows:

RUN apt-get update && \
    apt-get install -y <PACKAGE>

Rebuilding Docker image¶

If it is necessary to rebuild the Docker image, a local image named fmriprep may be built from within the working fmriprep repository, located in ~/projects/fmriprep:

~/projects/fmriprep$ docker build -t fmriprep .

To work in this image, replace poldracklab/fmriprep:latest with fmriprep in any of the above commands.