Running fmriprep


1. Write a batch script

We keep up-to-date Singularity images for fmriprep for the community. In order to run fmriprep in Oscar, you'll need to write a batch script. We provide an example below
~/src/ -- Filename and not part of the script!
#SBATCH -c 8
#SBATCH --mem=24G
#SBATCH --time 18:00:00
#SBATCH -J fmriprep
#SBATCH --output fmriprep-log-%J.txt
#---------CONFIGURE THESE VARIABLES--------------
#---------END OF VARIABLES------------------------
singularity run --cleanenv \
--bind ${root_dir}/${investigator}/study-${study_label}:/data \
--bind /gpfs/scratch/${USER}:/scratch \
--bind /gpfs/data/bnc/licenses:/licenses \
/gpfs/data/bnc/simgs/nipreps/fmriprep-${fmriprep_version}.sif \
/data/bids /data/bids/derivatives/fmriprep-${fmriprep_version} \
participant --participant-label ${participant_label} \
--fs-license-file /licenses/freesurfer-license.txt \
-w /scratch/fmriprep \
--omp-nthreads 16 --nthreads 16 --stop-on-first-crash

✋Understanding the batch script

  • The first part of the script configures the variables (e.g., number of cores, memory, etc) for your JOB
  • The second part invokes fmriprep singularity image. Keep in mind the following considerations:
    • Singularity containers run as your user, and therefore should have the same read/write permissions as your local user in the cluster
    • Singularity containers only share $HOME with the Oscar file system. Therefore, any other location that we want to read and write to/from, needs to be specified using the --bind hostfolder:containerfolder input. This includes any directory in your home directory that is a symbolic link. For instance $HOME/data usually points to /gpfs/data/<group> in that case we must bind /gpfs/data/<group>
    • You must specify the location inside the container of the FreeSurfer license.
fmriprep may fail for many reasons. Here are few tips:
  • Freesurfer is often difficult to get to completion, if it helps troubleshooting, you can turn FreeSurfer reconstruction off by adding the flag --fs-no-reconall
  • Familiarize yourself with the inputs and don't hesitate to ask the developers questions. Good places to look/ask for help are their GitHub issues and the Neurostars forum

2. Run the batch script

cd ~/src
For more information about managing your job, see the Oscar documentation
Let us know if you are interested in this documentation!

Getting a different version than what is installed in Oscar.

If you wish to use a version not available under /gpfs/data/bnc/simg/nipreps, you'll need to build the image. Singularity images can be large, therefore consider using a place with sufficient quota and changing the default location singularity uses to cache these files. Please see Oscar documentation.
To build the image, you can run:
singularity build fmriprep-${version}.sif docker://nipreps/fmriprep:${version}
Replace version in the command above with the desired docker tag. You can find the latest tags of fmriprep here
To support scientific reproducibility, it is recommended to use a specific tag e.g., 22.0.0 instead of latest