HW5: fmriprep

Due 3/15. Members of the fmriprep presentation group are exempt from this homework as a course requirement, but might want to use this as an opportunity to process their own data.

Overview

Use singularity and the fmriprep container at /scratch/psyc5171/containers/fmriprep_1.5.9.sif to preprocess some fMRI data.

You can apply fmriprep to either

The example dataset at /scratch/psyc5171/exercises/mbdata/bids OR
The dataset that you have identified for your final presentation

Demo Dataset

The demo dataset is adapted from ds001544 and contains a single subject and session with T1w, T2w, bold/sbref, and epi fieldmap modalities. Note that the scans have been renamed from the original dataset and some of the metadata has been modified.

Exercise

Fork and clone this repository to the cluster.
Edit the sbatch_fmriprep.sh script to run fmriprep. You should use the following non default options:
- --cifti-output to generate a CIFTI dense timeseries, containing both cortical surface and subcortical volume data
Submit your job
When fmriprep has successfully run, use git to add, commit, push, and pull request.

Usage Notes

The minimal fmriprep command is:

singularity run --cleanenv \
--bind ${BIDS_DIR}:/data \
--bind ${OUT_DIR}:/out \
/scratch/psyc5171/containers/fmriprep_1.5.9.sif \
/data /out participant

For surface processing using FreeSurfer (default, and required by the --cifti-output option), the path (with respect to the container) to a FreeSurfer license file must be provided using the --fs-license-file option. You can register for your own free license at https://surfer.nmr.mgh.harvard.edu/registration.html or use the license file at /scratch/psyc5171/exercises/mbdata/bids/code/license.txt. One approach is to create a code directory in the bids folder and place the license file there. You can then provide this file as --fs-license-file /data/code/license.txt. If you use FreeSurfer/fmriprep outside of class, please register for a license.

You need to provide two directories for processing:

${BIDS_DIR} is the full path to the BIDS folder. Since mriqc does not modify the input BIDS folder, you do not need to copy the input data to your own directory.
${OUT_DIR} is the full path to a directory where the output files will go. This directory needs to be under your control and exist prior to running fmriprep (use mkdir to create a new directory). For example, you might create the directory /scratch/${USER}/hw5/fmriprep to store the output, and would replace the string ${OUT_DIR} with this path, so the line would read --bind /scratch/${USER}/hw5/fmriprep:/out.
The command above needs to be in a SLURM script. You can adapt a script from your previous homework as a starting point. Don't forget to include the module load singularity command in your SLURM script.
See the slides for notes on resource needs. If you adjust the mriqc --nprocs option to use 2 or 3 processors, the script should not take more than 1 hour to run.

You should also review the options for controlling CPU and memory usage and harmonize these with the resources requested in your SLURM request.

Processing your own data

For your own dataset with multiple subjects, you have at least two options for managing performance:

Process all subjects in one job. This will make use of the parallel processing capabilities of fmriprep, but will generally require a long job runtime.
Process one subject in each job. To do this, add the option --participant_label $1 to your fmriprep command. When submitting your job using sbatch, specify the subject ID to process without sub-, e.g.

sbatch sbatch_fmriprep.sh 01

will process sub-01. You can submit a job for each subject and up to 8 jobs will run at once. $1 is a special variable that refers to the first argument given to your sbatch_fmriprep.sh script.

I recommend the second approach since your jobs can execute faster and job failure on a single subject will not affect processing for the others.

git workarounds

To associate your clone with your GitHub username, run the command
```
 git remote set-url origin \
 https://${USER}@github.uconn.edu/${USER}/hw5.git
```
in your hw5 directory. This will avoid the The requested URL returned error: 403 Forbidden while accessing error when pushing.
Use the command unset SSH_ASKPASS prior to pushing to avoid the error (gnome-ssh-askpass:19484): Gtk-WARNING **: cannot open display:
When committing, you can specify a short commit message on the command line with the -m option: git commit -m 'commit message'. If you do not do this, the default editor will open so you can write your commit message. The default is usually vi.
- Press i to enter insertion mode and write your message
- Press ctrl-c or esc to exit insertion mode
- Type :wq to save and quit or :q! to quite without saving
The command git status will show files that have changed since the last commit.
The command git log will show the commit history

Resources

The BIRC computing guide has some more detailed instructions on running fmriprep. The guide also provides instructions for downloading the container image, but this has already been done for you.
The fmriprep webpage has additional documentation on the various options, and more detailed descriptions and references for various pipeline steps and outputs.

Troubleshooting

Consult your sbatch log files for clues to the cause of errors, e.g. missing files.
It is sometimes neccessary to remove partial outputs from your mriqc output directory in order to successfully rerun the pipeline.
fmriprep and many other BIDS Apps will create a work directory that stores temporary files. It can be helpful to also remove this directory before rerunning a failed fmriprep job.
Files can be deleted with the rm command. Directories (and the directories/files they contain) can be removed with rm -r. Make sure you know what you are deleting before running this command!

hw5/README.md