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

1. Fork and clone this repository to the cluster.
2. Edit the sbatch_mriqc.sh script to run mriqc
3. Submit your job
4. 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 (use mkdir 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 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 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 with rm -r. Make sure you know what you are deleting before running this command!