2.4 Quality Control with MRIQC

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:

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.
Minimal preprocessing: the MRIQC workflows should be as minimal as possible to estimate the IQMs on the original data or their minimally processed derivatives.
Interoperability and standards: MRIQC follows the the brain imaging data structure (BIDS), and it adopts the BIDS-App standard.
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.

mriqc vs fmriprep qc — two layers

The two tools answer different questions and run at different times:

MRIQC runs on the raw BIDS dataset before any preprocessing, computes no-reference image quality metrics (IQMs) directly on the original acquisitions, and helps decide whether each scan or subject should be included in the study.

fMRIPrep’s QC report is produced after preprocessing — it shows you whether registration, normalisation, susceptibility distortion correction and confound extraction worked correctly on each subject. It tells you about the success of the pipeline, not the quality of the raw data. Both layers are useful: use MRIQC to set exclusion criteria up front, and fMRIPrep’s report to catch downstream failures before you trust the derivatives.

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 --cleanenv \
    --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 (tSNR), and the spatial root mean square after temporal differencing (DVARS). Common rules of thumb:

FD: censor frames above $0.5$ mm for task fMRI and $0.2$ mm for resting-state (Power et al., 2012; Power et al., 2014). Exclude a run if more than ~20% of frames exceed the threshold, or if mean FD > 0.2 mm.
DVARS: standardised DVARS > 1.5 marks a spike (the default fMRIPrep threshold). Raw DVARS thresholds are scanner-dependent and should not be transferred across datasets.
tSNR: there is no universal cutoff; inspect the distribution across subjects in the group report rather than a single number. Values dropping well below the cohort median (e.g. > 2 SD lower) deserve scrutiny.

thresholds are defaults, not absolutes

These cutoffs are convenient starting points, not ground truth. The IQM definitions in MRIQC (Esteban et al., 2017) are no-reference — they characterise the image, not its fitness for a specific analysis. Always inspect distributions on your own data and pre-register exclusion rules when possible.

Running MRIQC

MRIQC follows the BIDS-App convention: it expects a valid BIDS dataset and writes derivatives to an output folder. Like fMRIPrep, it runs in two stages — participant (one subject at a time, producing per-subject HTML and JSON IQMs) and group (aggregates the participant outputs into joint distributions).

pin the version

Reproducibility matters: always pin a concrete MRIQC version. This tutorial uses 24.0.2. Check https://hub.docker.com/r/nipreps/mriqc/tags for newer stable tags, and pin the same tag in containers, papers, and methods sections.

Setting up environment variables

We use environment variables throughout, so the same script works on a laptop, a workstation, or an HPC cluster. Adjust the paths to your project layout.

# project-level paths (edit these)
export BIDS_DIR=/path/to/your/bids_dataset
export DERIVS_DIR=$BIDS_DIR/derivatives
export WORK_DIR=$HOME/scratch/mriqc_work
export MRIQC_VERSION=24.0.2
 
# matplotlib cache (avoids permission errors on HPC)
export MPLCONFIGDIR=$WORK_DIR/.matplotlib
 
mkdir -p $DERIVS_DIR/mriqc $WORK_DIR $MPLCONFIGDIR

Pull the container

Apptainer / Singularity (preferred on HPC):

apptainer build $HOME/containers/mriqc-${MRIQC_VERSION}.sif \
    docker://nipreps/mriqc:${MRIQC_VERSION}

Docker (on a laptop or workstation):

docker pull nipreps/mriqc:${MRIQC_VERSION}

Participant-level run

This processes one subject and writes per-subject IQMs and HTML reports into $DERIVS_DIR/mriqc.

Apptainer:

SUBJECT=001
 
apptainer run --cleanenv \
    --bind $BIDS_DIR \
    --bind $DERIVS_DIR \
    --bind $WORK_DIR \
    $HOME/containers/mriqc-${MRIQC_VERSION}.sif \
    $BIDS_DIR $DERIVS_DIR/mriqc participant \
    --participant-label $SUBJECT \
    --nprocs 8 --omp-nthreads 8 \
    --mem-gb 16 \
    --no-sub \
    --verbose-reports \
    -w $WORK_DIR

Docker (equivalent invocation):

docker run --rm \
    -v $BIDS_DIR:/data:ro \
    -v $DERIVS_DIR/mriqc:/out \
    -v $WORK_DIR:/work \
    nipreps/mriqc:${MRIQC_VERSION} \
    /data /out participant \
    --participant-label 001 \
    --nprocs 8 --omp-nthreads 8 \
    --mem-gb 16 \
    --no-sub \
    -w /work

--no-sub

Disables the anonymous IQM upload to the MRIQC web service. Remove it if you want to contribute your IQMs to the public database for crowd-sourced normative comparisons.

Group-level run

Once every subject has finished, run the group stage. It is fast and produces group_T1w.html, group_bold.html, and matching TSVs that pool the IQMs across the cohort.

apptainer run --cleanenv \
    --bind $BIDS_DIR --bind $DERIVS_DIR --bind $WORK_DIR \
    $HOME/containers/mriqc-${MRIQC_VERSION}.sif \
    $BIDS_DIR $DERIVS_DIR/mriqc group \
    -w $WORK_DIR

SLURM array (HPC)

The participant stage parallelises trivially across subjects. Below is a SLURM array script analogous to the one in 2.3 fmriPrep with Docker.

#!/bin/bash
#SBATCH --job-name=mriqc
#SBATCH --get-user-env
#SBATCH --clusters=cm4
#SBATCH --partition=cm4_tiny
#SBATCH -t 04:00:00
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=1
#SBATCH --cpus-per-task=8
#SBATCH --mem=16G
#SBATCH --array=1-23%6
#SBATCH --mail-user=your@email
#SBATCH --mail-type=BEGIN,END,FAIL
#SBATCH -o logs/mriqc-%A_%a.log
 
module load slurm_setup
module load apptainer
 
export BIDS_DIR=$HOME/studies/Your_Study
export DERIVS_DIR=$BIDS_DIR/derivatives
export WORK_DIR=$SCRATCH/mriqc_work_${SLURM_ARRAY_TASK_ID}
export MRIQC_VERSION=24.0.2
export MPLCONFIGDIR=$WORK_DIR/.matplotlib
mkdir -p $DERIVS_DIR/mriqc $WORK_DIR $MPLCONFIGDIR
 
SUBJECT=$(printf "%03d" $SLURM_ARRAY_TASK_ID)
 
apptainer run --cleanenv \
    --bind $BIDS_DIR --bind $DERIVS_DIR --bind $WORK_DIR \
    $HOME/containers/mriqc-${MRIQC_VERSION}.sif \
    $BIDS_DIR $DERIVS_DIR/mriqc participant \
    --participant-label $SUBJECT \
    --nprocs 8 --omp-nthreads 8 \
    --mem-gb 16 \
    --no-sub \
    -w $WORK_DIR
 
echo "Subject $SUBJECT finished at $(date)"

After all array tasks complete, run the group stage once on the head node (it needs all participant outputs visible).

templateflow on offline compute nodes

On HPC clusters whose compute nodes lack internet, MRIQC’s first run will fail because TemplateFlow tries to download templates. Pre-cache them by running the participant stage once on the login node with a tiny subject, or set SINGULARITYENV_TEMPLATEFLOW_HOME (APPTAINERENV_TEMPLATEFLOW_HOME) to a pre-populated shared location. After that, all array jobs work offline.

Reading the HTML reports

Each participant gets one HTML per anatomical and per BOLD run, plus a JSON with the raw IQMs. Open them in a browser. Below is the short version of what to look at; full definitions are in the MRIQC docs and Esteban et al. (2017).

T1w / T2w report

Background noise (bg_*, qi_2): distribution of intensities in the air outside the head. A clean background is approximately chi-distributed; ghosts or wrap-around show up as extra modes.
INU (inu_*): intensity non-uniformity (bias field) estimated by N4. Large values indicate strong B1 inhomogeneity that segmentation will struggle with.
CJV (coefficient of joint variation): mixes GM and WM intensity overlap; lower is better (Ganzetti et al., 2016).
EFC (entropy-focus criterion): ghosting and blurring; lower is better (Atkinson et al., 1997).
SNR-d (Dietrich SNR): signal-to-noise estimated against the air background; higher is better.
Mosaic view: scroll through the slices. Look for wrap-around, motion ringing, fat shifts, and dental artefacts near the orbitofrontal cortex.

BOLD report

tSNR: voxelwise mean / SD across time. Inspect the spatial map — large drop-outs near sinuses are expected, but global tSNR collapse signals trouble.
FD (framewise displacement): mean and trace; spikes correspond to head motion (Power et al., 2012).
DVARS: standardised by default (std_dvars); spikes co-localised with FD spikes indicate motion-driven signal changes (Power et al., 2012, 2014).
AOR (aor): mean fraction of voxels flagged as outliers per volume by AFNI’s 3dToutcount. AQI (aqi): AFNI’s quality index from 3dTqual — mean Spearman distance of each volume from the run median; both lower is better.
GSR (ghost-to-signal ratio): Nyquist (N/2) ghost intensity in EPI; elevated values mean reconstruction or coil issues.
Carpet plot: time × voxel heatmap of the BOLD series with FD and DVARS traces. Vertical stripes = motion events, horizontal bands = physiological cycles, slow drifts = scanner instability.
FBER (foreground-background energy ratio) and EFC: spatial quality metrics analogous to the T1w versions.

start with the carpet plot

The carpet plot is the single most informative visualisation in the report. If it looks clean and the FD trace is quiet, the rest of the IQMs will usually agree.

Group-level outputs

The group stage writes group_T1w.html and group_bold.html plus matching TSVs (group_T1w.tsv, group_bold.tsv). Each panel shows the distribution of one IQM across all scans, with each subject as a point. This is where you spot outliers in context:

Hover over any point to see the subject/session/run identifier and the value.
A subject that sits in the tail of multiple IQMs (e.g. high mean FD, high DVARS, low tSNR) is a stronger exclusion candidate than one that is extreme on a single metric.
Compare your distributions to the public MRIQC web API (or the values in Esteban et al., 2017, Table 2) as a sanity check that your overall acquisition is in the expected range.

The TSV files plug directly into pandas for custom thresholding:

import pandas as pd
 
bold = pd.read_csv("derivatives/mriqc/group_bold.tsv", sep="\t")
tsnr_cutoff = bold["tsnr"].median() - 2 * bold["tsnr"].std()
exclude = bold.query("fd_mean > 0.2 or tsnr < @tsnr_cutoff")
print(exclude[["bids_name", "fd_mean", "tsnr", "dvars_std"]])

What to do with the results

QC decisions should be principled, documented, and ideally pre-registered. A practical workflow:

Pre-register exclusion rules before looking at the data: e.g. “runs with mean FD > 0.2 mm or > 20% of frames with FD > 0.5 mm will be excluded; subjects losing more than one run will be dropped.” This protects against analytic flexibility.
Inspect every report at least briefly. Automated thresholds miss issues IQMs cannot quantify — wrap-around, severe geometric distortion, susceptibility drop-outs in your ROI. The mosaic and carpet plots catch these.
Flag, do not silently drop. Keep a qc_notes.tsv (or participants.tsv columns) recording every QC decision and its rationale. Future-you and reviewers will thank you.
Re-run when it is fixable. Conversion errors, missing fieldmaps, or wrong IntendedFor entries cause spurious QC failures. Fix the BIDS metadata and re-run MRIQC before excluding.
Drop the scan, not the subject, when possible. If one of three runs is bad but the other two are clean, exclude the run only.

motion is not the only enemy

Coverage problems, signal drop-out in target regions, and reconstruction artefacts can sink an analysis even with quiet FD/DVARS. Always pair IQM thresholds with a visual pass.

Next steps

With QC done, head over to 2.3 fmriPrep with Docker for preprocessing. Downstream confound handling is covered in 5.2 Confound Selection, and statistical thresholding in 5.3 Visualization and Statistical Thresholding with Nilearn.

References and further reading

MRIQC docs: https://mriqc.readthedocs.io/
Esteban, O., Birman, D., Schaer, M., Koyejo, O. O., Poldrack, R. A., & Gorgolewski, K. J. (2017). MRIQC: Advancing the automatic prediction of image quality in MRI from unseen sites. PLoS ONE, 12(9), e0184661.
Power, J. D., Barnes, K. A., Snyder, A. Z., Schlaggar, B. L., & Petersen, S. E. (2012). Spurious but systematic correlations in functional connectivity MRI networks arise from subject motion. NeuroImage, 59(3), 2142–2154.
Power, J. D., Mitra, A., Laumann, T. O., Snyder, A. Z., Schlaggar, B. L., & Petersen, S. E. (2014). Methods to detect, characterize, and remove motion artifact in resting state fMRI. NeuroImage, 84, 320–341.
Ganzetti, M., Wenderoth, N., & Mantini, D. (2016). Quantitative evaluation of intensity inhomogeneity correction methods for structural MR brain images. Neuroinformatics, 14(1), 5–21. doi:10.1007/s12021-015-9277-2
Atkinson, D., Hill, D. L. G., Stoyle, P. N. R., Summers, P. E., & Keevil, S. F. (1997). Automatic correction of motion artifacts in magnetic resonance images using an entropy focus criterion. IEEE Transactions on Medical Imaging, 16(6), 903–910. doi:10.1109/42.650886

fMRI Tutorials

Explorer

2.4 Quality Control with MRIQC

Running MRIQC for the first time

How to mark outliers

Running MRIQC

Setting up environment variables

Pull the container

Participant-level run

Group-level run

SLURM array (HPC)

Reading the HTML reports

T1w / T2w report

BOLD report

Group-level outputs

What to do with the results

Next steps

References and further reading

Graph View

Table of Contents

Backlinks