HW3: mriqc
Due 3/2.
Overview
Use mriqc and singularity to prepare quality control reports for the sample dataset at /scratch/psyc5171/exercises/mbdata/bids
.
Dataset
The dataset for this and subsequent pipeline demos 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_mriqc.sh
script to run mriqc - Submit your job
- When mriqc has successfully run, use git to add, commit, push, and pull request.
Notes
The minimal mriqc command is:
singularity run --cleanenv \
--bind ${BIDS_DIR}:/data \
--bind ${OUT_DIR}:/out \
/scratch/psyc5171/containers/mriqc_latest.sif \
/data /out participant
You need to provide two directories for this to work:
${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 mriqc (usemkdir
to create a new directory). For example, you might create the directory/scratch/${USER}/hw3/mriqc
to store the output, and would replace the string${OUT_DIR}
with this path, so the line would read--bind /scratch/${USER}/hw3/mriqc:/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.
git workarounds
-
To associate your clone with your GitHub username, run the command
git remote set-url origin \ https://${USER}@github.uconn.edu/${USER}/hw3.git
in your
hw3
directory. This will avoid theThe 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 usuallyvi
.- Press
i
to enter insertion mode and write your message - Press
ctrl-c
oresc
to exit insertion mode - Type
:wq
to save and quit or:q!
to quite without saving
- Press
-
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 mriqc. The guide also provides instructions for downloading the container image, but this has already been done for you.
- The mriqc webpage has additional documentation on the various options, and more detailed descriptions and references for the quality metrics.
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.
- mriqc 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 mriqc job. - Files can be deleted with the
rm
command. Directories (and the directories/files they contain) can be removed withrm -r
. Make sure you know what you are deleting before running this command!