Lab Tutorials

2.4 Quality Control with MRIQC

2 min read

MRIQC extracts no-reference IQMs (image quality metrics) from structural (T1w and T2w) and functional MRI (magnetic resonance imaging) data.

MRIQC is an open-source project, developed under the following software engineering principles:

  1. Modularity and integrability: MRIQC implements a nipype workflow to integrate modular sub-workflows that rely upon third party software toolboxes such as ANTs and AFNI.

  2. Minimal preprocessing: the MRIQC workflows should be as minimal as possible to estimate the IQMs on the original data or their minimally processed derivatives.

  3. Interoperability and standards: MRIQC follows the the brain imaging data structure (BIDS), and it adopts the BIDS-App standard.

  4. Reliability and robustness: the software undergoes frequent vetting sprints by testing its robustness against data variability (acquisition parameters, physiological differences, etc.) using images from OpenfMRI. Its reliability is permanently checked and maintained with CircleCI.

A sample script to run mriqc via singularity:

#!/bin/bash
 
# check if in a cluster environment
if env | grep -i cluster > /dev/null; then
    # 2. project directory (depending on the mount folder)
    proj_dir=/path/to/project_id/ #linux cluster
    ncpus=8
    mriqc_img=$HOME/mriqc23
else
    # 2. project directory (at lora server)
    proj_dir=/dss/project_folder/ #Lora virtual machine
    ncpus=8
    mriqc_img=$HOME/mriqc23.simg
fi
 
# project name
proj_name=bisection_mri
 
# 3. working directory 
scratch_dir=$proj_dir/tmp/$proj_name
 
export MPLCONFIGDIR=$scratch_dir  #matplotlib temp folder
 
# check if the folder exists
if [ ! -d "$scratch_dir" ]; then
    mkdir "$scratch_dir"
fi
# 4. bids directory
bids_dir=$proj_dir/$proj_name
 
# linux cluster sandbox 
singularity run \
    --bind $bids_dir \
    --bind $scratch_dir \
    $mriqc_img $bids_dir $bids_dir/derivatives/mriqc \
    participant \
    --participant-label $1 \
    --no-sub \
    --nprocs $ncpus \
    --omp-nthreads 8 \
    --verbose-reports \
    -w $scratch_dir

After running subject-wise, you can run group analysis, which will generate a group summary.

Running MRIQC for the first time

Because of a weird quirk in how MRIQC uses TemplateFlow, the first time each user runs MRIQC on the PNI server, MRIQC will need access to the internet to download some TemplateFlow files. The problem is that our compute nodes (i.e. the nodes used by Slurm) do not have access to the internet. However, the head node does. What this means is the first time each individual user runs MRIQC, you should run it on the head node, not using Slurm. After that, any subsequent time you run MRIQC (even if it is for a different project), you can use Slurm.

How to mark outliers

Key indicators are framewise displacement (FD), temporal SNR, the spatial root mean square after temporal differencing (DVARS). Rule of thumbs: FD > 0.3, DVARS > 50, temporal SNR < 30.

Graph View