Skip to content

FMRIPrep

FMRIPrep is a preprocessing tool for FMRI data

Homepage Version(s): Container

FMRIPrep is a commonly used FMRI pre-processing program that is distributed and runs as an Apptainer/Singularity container.

Using FMRIPrep on RCC resources#

To use FMRIPrep on RCC resources, you will first need to download and build the Singularity/Apptainer container. This is done by using the following command:

1
$ apptainer build fmriprep-latest.simg docker://nipreps/fmriprep:latest

Note

We recommend that you use the latest FMRIPrep available unless you have reason to do otherwise.
If you want to use a different version, you can build it with this command: 

1
$ apptainer build fmriprep-<version>.simg docker://nipreps/fmriprep:<version>
Be sure to replace <version> with the version number you want to use: 1.5.0 for example.

Running FMRIPrep jobs#

You can submit non-interactive batch mode FMRIPrep jobs to the scheduler. This is the preferred way to submit long-running preprocessing jobs.

Example Job using a tutorial#

The following is an example of a batch job submission script (job.sh) that will run a FMRIPrep preprocessing job on data provided by this FMRIPrep tutorial.

  1. First, we need to set up the tools necessary to download the data. This will be datalad. Datalad is best installed in a conda environment. We can do that with the following commands:

    1
2
3
4
5
6
7
8
9
    module purge
module load anaconda/3.11.5

conda create --prefix=~/dataladenv

## Be sure to type "y" when prompted

source activate ~/dataladenv
conda install -c conda-forge datalad

  2. Now that we have to tools to download the data, we need to run the download script for the example data provided here. We should also prepare a dedicated folder for the data:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
    ## Set up dedicated folder

mkdir tutorialdata
cd tutorialdata

## Download dataset

datalad install https://github.com/OpenNeuroDatasets/ds000102.git

## Now you'll need to tell datalad to get ALL the .nii.gz files
cd ds000102
datalad get .

## Now get back to the main tutorialdata folder
cd ..

    Now that we have the data downloaded, we need to prepare the working directory. FMRIPrep will use this as a temporary and intermediate file directory.

    1
    mkdir working

  3. Now we can deactivate the datalad environment

    1
    source deactivate

  4. Next, we need to prepare the FMRIPrep job submission folder. Assuming we've already downloaded the FMRIPrep container to our home directory and it is at ~/fmriprep-latest.simg, we can use the following script, which we will save to a file called job.sh:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
    #!/bin/bash
#SBATCH -J JOBNAMEHERE
#SBATCH -n 1
#SBATCH --cpus-per-task=20
#SBATCH -N 1
#SBATCH -A genacc_q
#SBATCH --mem=64G
#SBATCH --mail-type=ALL
#SBATCH -t 7-00:00:00

## Unload all modules
ml purge

## We'll need to MANUALLY type out the webproxy variables so they have a schema
## FMRIPrep often downloads TemplateFlow templates...so we need to be able to get those
export APPTAINERENV_https_proxy=http://web-proxy.rcc.fsu.edu:3128

## Now, export the license file for FreeSurfer
export FS_LICENSE=/gpfs/research/software/freesurfer/freesurfer/license.txt
export DATA_DIR=~/tutorialdata

## Now, set up the requisite variables
export BIDS_ROOT_DIR=~/tutorialdata/ds000102
export WORKDIR=~/tutorialdata/working
export IMAGE=~/fmriprep-latest.simg

## Now, bind the data directory and work directory into the container
export APPTAINER_BINDPATH="${DATA_DIR},${WORKDIR}"

apptainer run \
 -B ${FS_LICENSE} \
 ${IMAGE} \
 $BIDS_ROOT_DIR \
 $BIDS_ROOT_DIR/derivatives \
 participant \
 --n_cpus $SLURM_CPUS_PER_TASK \
 --omp-nthreads $SLURM_CPUS_PER_TASK \
 --skip-bids-validation \
 --fs-license-file ${FS_LICENSE} \
 -w $WORKDIR

  5. Finally, we can run sbatch job.sh

All output should be placed in ~/tutorialdata/ds000102/derivatives and all temp files/intermediate data should be written to ~/tutorialdata/working.

Using directories aside from your Home Directory for job I/O#

In some cases, it may turn out that you don't have enough space for your data in your home directory. If this is the case, you can place the data on your HPC storage research partition, such as /gpfs/research/<YOUR_LAB_NAME_HERE> if you or your lab group have purchased space, or you can use scratch space /gpfs/research/scratch/<YOUR_FSUID>. In this case, you will need to change the following variables in the above script:

Warning

If you are planning to use a directory for your working and data directories OTHER than your home directory, you must explicitly bind those directories into the container.

The above script does this for you by creating the DATA_DIR and WORK_DIR environment variables and adding them to APPTAINER_BINDPATH. APPTAINER_BINDPATH is a variable that Apptainer uses to determine bind paths.

Warning

If you are planning to use a directory for your working and data directories OTHER than your home directory, then you must explicitly tell FMRIPrep which path to use for it's working directory in addition to binding it into the container.

You can do this by setting the -w parameter in your FMRIPrep job script.

Using purchased research volumes#

1
2
3
4
5
export DATA_DIR=/gpfs/research/<YOUR_LAB_NAME_HERE>/tutorialdata

## Now, set up the requisite variables
export BIDS_ROOT_DIR=/gpfs/research/<YOUR_LAB_NAME_HERE>/tutorialdata/ds000102
export WORKDIR=/gpfs/research/<YOUR_LAB_NAME_HERE>/tutorialdata/working

Using general access scratch space#

1
2
3
4
5
export DATA_DIR=/gpfs/research/scratch/<YOUR_FSUID>/tutorialdata

## Now, set up the requisite variables
export BIDS_ROOT_DIR=/gpfs/research/scratch/<YOUR_FSUID>/tutorialdata/ds000102
export WORKDIR=/gpfs/research/scratch/<YOUR_FSUID>/tutorialdata/working