Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

MRIQC

https://doi.org/10.5281/zenodo.18728804
Run this notebook

Author: Monika Doerig

Date: 6 May 2025

License:

MIT License

Note: If this notebook uses neuroimaging tools from Neurocontainers, those tools retain their original licenses. Please see Neurodesk citation guidelines for details.

Citation and Resources:

Tools included in this workflow

MRIQC:

  • Esteban O, Birman D, Schaer M, Koyejo OO, Poldrack RA, Gorgolewski KJ; MRIQC: Advancing the Automatic Prediction of Image Quality in MRI from Unseen Sites; PLOS ONE 12(9):e0184661; doi:Esteban et al. (2017)

  • The documentation of this project is found here.

Dataset

Data from OpenNeuro: Flanker Dataset

  • Kelly AMC and Uddin LQ and Biswal BB and Castellanos FX and Milham MP (2018). Flanker task (event-related). OpenNeuro Dataset ds000102. [Dataset] doi: null

  • Kelly AM, Uddin LQ, Biswal BB, Castellanos FX, Milham MP. Competition between functional brain networks mediates behavioral variability. Neuroimage. 2008 Jan 1;39(1):527-37. doi: Kelly et al. (2008). Epub 2007 Aug 23. PMID: 17919929.

  • Mennes, M., Kelly, C., Zuo, X.N., Di Martino, A., Biswal, B.B., Castellanos, F.X., Milham, M.P. (2010). Inter-individual differences in resting-state functional connectivity predict task-induced BOLD activity. Neuroimage, 50(4):1690-701. doi: Mennes et al. (2010). Epub 2010 Jan 15. Erratum in: Neuroimage. 2011 Mar 1;55(1):434

  • Mennes, M., Zuo, X.N., Kelly, C., Di Martino, A., Zang, Y.F., Biswal, B., Castellanos, F.X., Milham, M.P. (2011). Linking inter-individual differences in neural activation and behavior to intrinsic brain dynamics. Neuroimage, 54(4):2950-9. doi: Mennes et al. (2011)

Introduction

In this notebook, we demonstrate the use of MRIQC for automated MRI quality assessment and include examples of the visual reports generated. By the end of this notebook, you will be able to:

  • Run MRIQC at the single-participant level

  • Run MRIQC at the group level

MRIQC is an open-source tool that extracts no-reference image quality metrics (IQMs) from structural (T1w and T2w), functional, and diffusion MRI data. It follows the Brain Imaging Data Structure (BIDS) standard and is built on a modular nipype workflow, integrating tools such as ANTs and AFNI while keeping preprocessing minimal to preserve the integrity of the original data. Reliability is continuously validated against diverse datasets to ensure robustness across varying acquisition parameters and subject populations.

Note: This notebook assumes your data is already in BIDS format. If you are running on an HPC, note that MRIQC has its $HOME variable hardcoded to /home/mriqc, which can cause problems on some systems. Run this before MRIQC:

export neurodesk_singularity_opts="--home $HOME:/home"

Load MRIQC and import python libraries

%%capture
! pip install beautifulsoup4
from bs4 import BeautifulSoup
from IPython.display import HTML, display
import os
import module
await module.load('mriqc/24.0.2') 
await module.list()
['mriqc/24.0.2']
!mriqc -h
usage: mriqc [-h] [--version] [-v] [--species {human,rat}]
             [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
             [--bids-filter-file PATH] [--session-id [SESSION_ID ...]]
             [--run-id [RUN_ID ...]] [--task-id [TASK_ID ...]]
             [-m [{T1w,T2w,bold,dwi} ...]] [--dsname DSNAME]
             [--bids-database-dir PATH] [--bids-database-wipe]
             [--no-datalad-get] [--nprocs NPROCS]
             [--omp-nthreads OMP_NTHREADS] [--mem MEMORY_GB] [--testing] [-f]
             [--pdb] [-w WORK_DIR] [--verbose-reports] [--reports-only]
             [--write-graph] [--dry-run] [--resource-monitor]
             [--use-plugin USE_PLUGIN] [--crashfile-format {txt,pklz}]
             [--no-sub] [--email EMAIL] [--webapi-url WEBAPI_URL]
             [--webapi-port WEBAPI_PORT] [--upload-strict] [--notrack]
             [--ants-float] [--ants-settings ANTS_SETTINGS]
             [--min-dwi-length MIN_LEN_DWI] [--min-bold-length MIN_LEN_BOLD]
             [--fft-spikes-detector] [--fd_thres FD_THRES] [--deoblique]
             [--despike] [--start-idx START_IDX] [--stop-idx STOP_IDX]
             bids_dir output_dir {participant,group} [{participant,group} ...]

MRIQC 24.1.0.dev0+gd5b13cb5.d20240826 Automated Quality Control and visual
reports for Quality Assessment of structural (T1w, T2w) and functional MRI of
the brain. IMPORTANT: Anonymized quality metrics (IQMs) will be submitted to
MRIQC's metrics repository. Submission of IQMs can be disabled using the
``--no-sub`` argument. Please visit
https://mriqc.readthedocs.io/en/latest/dsa.html to revise MRIQC's Data Sharing
Agreement.

positional arguments:
  bids_dir              The root folder of a BIDS valid dataset (sub-XXXXX
                        folders should be found at the top level in this
                        folder).
  output_dir            The directory where the output files should be stored.
                        If you are running group level analysis this folder
                        should be prepopulated with the results of the
                        participant level analysis.
  {participant,group}   Level of the analysis that will be performed. Multiple
                        participant level analyses can be run independently
                        (in parallel) using the same output_dir.

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -v, --verbose         Increases log verbosity for each occurrence, debug
                        level is -vvv. (default: 0)
  --species {human,rat}
                        Use appropriate template for population (default:
                        human)

Options for filtering BIDS queries:
  --participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...], --participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...], --participant-labels PARTICIPANT_LABEL [PARTICIPANT_LABEL ...], --participant_labels PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]
                        A space delimited list of participant identifiers or a
                        single identifier (the sub- prefix can be removed).
                        (default: None)
  --bids-filter-file PATH
                        a JSON file describing custom BIDS input filter using
                        pybids {<suffix>:{<entity>:<filter>,...},...}
                        (https://github.com/bids-standard/pybids/blob/master/b
                        ids/layout/config/bids.json) (default: None)
  --session-id [SESSION_ID ...]
                        Filter input dataset by session ID. (default: None)
  --run-id [RUN_ID ...]
                        DEPRECATED - This argument will be disabled. Use
                        ``--bids-filter-file`` instead. (default: None)
  --task-id [TASK_ID ...]
                        Filter input dataset by task ID. (default: None)
  -m [{T1w,T2w,bold,dwi} ...], --modalities [{T1w,T2w,bold,dwi} ...]
                        Filter input dataset by MRI type. (default: ('T1w',
                        'T2w', 'bold', 'dwi'))
  --dsname DSNAME       A dataset name. (default: None)
  --bids-database-dir PATH
                        Path to an existing PyBIDS database folder, for faster
                        indexing (especially useful for large datasets).
                        (default: None)
  --bids-database-wipe  Wipe out previously existing BIDS indexing caches,
                        forcing re-indexing. (default: False)
  --no-datalad-get      Disable attempting to get remote files in DataLad
                        datasets. (default: True)

Options to handle performance:
  --nprocs NPROCS, --n_procs NPROCS, --n_cpus NPROCS, -n-cpus NPROCS
                        Maximum number of simultaneously running parallel
                        processes executed by *MRIQC* (e.g., several instances
                        of ANTs' registration). However, when ``--nprocs`` is
                        greater or equal to the ``--omp-nthreads`` option, it
                        also sets the maximum number of threads that
                        simultaneously running processes may aggregate
                        (meaning, with ``--nprocs 16 --omp-nthreads 8`` a
                        maximum of two 8-CPU-threaded processes will be
                        running at a given time). Under this mode of
                        operation, ``--nprocs`` sets the maximum number of
                        processors that can be assigned work within an *MRIQC*
                        job, which includes all the processors used by
                        currently running single- and multi-threaded
                        processes. If ``None``, the number of CPUs available
                        will be automatically assigned (which may not be what
                        you want in, e.g., shared systems like a HPC cluster.
                        (default: None)
  --omp-nthreads OMP_NTHREADS, --ants-nthreads OMP_NTHREADS
                        Maximum number of threads that multi-threaded
                        processes executed by *MRIQC* (e.g., ANTs'
                        registration) can use. If ``None``, the number of CPUs
                        available will be automatically assigned (which may
                        not be what you want in, e.g., shared systems like a
                        HPC cluster. (default: None)
  --mem MEMORY_GB, --mem_gb MEMORY_GB, --mem-gb MEMORY_GB
                        Upper bound memory limit for MRIQC processes.
                        (default: None)
  --testing             Use testing settings for a minimal footprint.
                        (default: False)
  -f, --float32         Cast the input data to float32 if it's represented in
                        higher precision (saves space and improves
                        performance). (default: True)
  --pdb                 Open Python debugger (pdb) on exceptions. (default:
                        False)

Instrumental options:
  -w WORK_DIR, --work-dir WORK_DIR
                        Path where intermediate results should be stored.
                        (default:
                        /home/jovyan/workspace/books/examples/workflows/work)
  --verbose-reports
  --reports-only
  --write-graph         Write workflow graph. (default: False)
  --dry-run             Do not run the workflow. (default: False)
  --resource-monitor, --profile
                        Hook up the resource profiler callback to nipype.
                        (default: False)
  --use-plugin USE_PLUGIN
                        Nipype plugin configuration file. (default: None)
  --crashfile-format {txt,pklz}
                        Nipype crashfile format (default: txt)
  --no-sub              Turn off submission of anonymized quality metrics to
                        MRIQC's metrics repository. (default: False)
  --email EMAIL         Email address to include with quality metric
                        submission. (default: )
  --webapi-url WEBAPI_URL
                        IP address where the MRIQC WebAPI is listening.
                        (default: None)
  --webapi-port WEBAPI_PORT
                        Port where the MRIQC WebAPI is listening. (default:
                        None)
  --upload-strict       Upload will fail if upload is strict. (default: False)
  --notrack             Opt-out of sending tracking information of this run to
                        the NiPreps developers. This information helps to
                        improve MRIQC and provides an indicator of real world
                        usage crucial for obtaining funding. (default: False)

Specific settings for ANTs:
  --ants-float          Use float number precision on ANTs computations.
                        (default: False)
  --ants-settings ANTS_SETTINGS
                        Path to JSON file with settings for ANTs. (default:
                        None)

Diffusion MRI workflow configuration:
  --min-dwi-length MIN_LEN_DWI
                        Drop DWI runs with fewer orientations than this
                        threshold. (default: 7)

Functional MRI workflow configuration:
  --min-bold-length MIN_LEN_BOLD
                        Drop BOLD runs with fewer time points than this
                        threshold. (default: 5)
  --fft-spikes-detector
                        Turn on FFT based spike detector (slow). (default:
                        False)
  --fd_thres FD_THRES   Threshold on framewise displacement estimates to
                        detect outliers. (default: 0.2)
  --deoblique           Deoblique the functional scans during head motion
                        correction preprocessing. (default: False)
  --despike             Despike the functional scans during head motion
                        correction preprocessing. (default: False)
  --start-idx START_IDX
                        DEPRECATED Initial volume in functional timeseries
                        that should be considered for preprocessing. (default:
                        None)
  --stop-idx STOP_IDX   DEPRECATED Final volume in functional timeseries that
                        should be considered for preprocessing. (default:
                        None)

Data preparation

!datalad install https://github.com/OpenNeuroDatasets/ds000102.git
!cd ds000102 && datalad get sub-01 sub-02 sub-03
Cloning:   0%|                            | 0.00/2.00 [00:00<?, ? candidates/s]
Enumerating: 0.00 Objects [00:00, ? Objects/s]
                                              
Counting:   0%|                              | 0.00/27.0 [00:00<?, ? Objects/s]
                                                                               
Compressing:   0%|                           | 0.00/23.0 [00:00<?, ? Objects/s]
                                                                               
Receiving:   0%|                            | 0.00/2.15k [00:00<?, ? Objects/s]
                                                                               
Resolving:   0%|                               | 0.00/537 [00:00<?, ? Deltas/s]
[INFO   ] Remote origin not usable by git-annex; setting annex-ignore 
[INFO   ] https://github.com/OpenNeuroDatasets/ds000102.git/config download failed: Not Found 
[INFO   ] access to 1 dataset sibling s3-PRIVATE not auto-enabled, enable with:
| 		datalad siblings -d "/home/jovyan/workspace/books/examples/workflows/ds000102" enable -s s3-PRIVATE 
install(ok): /home/jovyan/workspace/books/examples/workflows/ds000102 (dataset)
Total:   0%|                                   | 0.00/204M [00:00<?, ? Bytes/s]
Total:   0%|                                  | 16.4k/204M [00:01<?, ? Bytes/s]
Get sub-03/a .. 3_T1w.nii.gz:   0%|  | 33.4k/10.7M [00:00<02:08, 83.1k Bytes/s]
Get sub-03/a .. 3_T1w.nii.gz:   1%|   | 85.6k/10.7M [00:00<00:57, 184k Bytes/s]
Total:   0%|                           | 120k/204M [00:01<54:51, 62.0k Bytes/s]
Get sub-03/a .. 3_T1w.nii.gz:   1%|    | 156k/10.7M [00:00<00:59, 176k Bytes/s]
Get sub-03/a .. 3_T1w.nii.gz:   2%|    | 225k/10.7M [00:01<00:44, 233k Bytes/s]
Total:   0%|                            | 416k/204M [00:02<19:28, 174k Bytes/s]
Get sub-03/a .. 3_T1w.nii.gz:   8%|▎   | 817k/10.7M [00:01<00:10, 954k Bytes/s]
Get sub-03/a .. 3_T1w.nii.gz:  14%|▎ | 1.50M/10.7M [00:01<00:05, 1.70M Bytes/s]
Total:   1%|▍                         | 2.99M/204M [00:02<03:17, 1.02M Bytes/s]
Get sub-03/a .. 3_T1w.nii.gz:  50%|▉ | 5.31M/10.7M [00:01<00:00, 6.73M Bytes/s]
Get sub-03/a .. 3_T1w.nii.gz:  76%|█▌| 8.16M/10.7M [00:02<00:00, 9.20M Bytes/s]
Total:   5%|█▎                        | 10.3M/204M [00:03<01:04, 3.00M Bytes/s]
                                                                               
Get sub-03/a .. 3_T1w.nii.gz: 100%|██████████| 10.7M/10.7M [00:00<?, ? Bytes/s]
                                                                               
Get sub-03/f .. _bold.nii.gz:   0%|          | 16.4k/28.8M [00:00<?, ? Bytes/s]
Get sub-03/f .. _bold.nii.gz:   9%|▏ | 2.55M/28.8M [00:00<00:01, 25.3M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  18%|▎ | 5.17M/28.8M [00:00<00:02, 11.5M Bytes/s]
Total:   9%|██▎                       | 18.5M/204M [00:04<00:44, 4.14M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  37%|▋ | 10.6M/28.8M [00:00<00:01, 12.6M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  46%|▉ | 13.3M/28.8M [00:01<00:01, 12.8M Bytes/s]
Total:  13%|███▍                      | 26.8M/204M [00:05<00:33, 5.35M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  65%|█▎| 18.8M/28.8M [00:01<00:00, 12.6M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  75%|█▍| 21.6M/28.8M [00:01<00:00, 12.7M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  84%|█▋| 24.3M/28.8M [00:01<00:00, 12.8M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  93%|█▊| 26.9M/28.8M [00:02<00:00, 12.7M Bytes/s]
                                                                               
Get sub-03/f .. _bold.nii.gz: 100%|██████████| 28.8M/28.8M [00:00<?, ? Bytes/s]
Total:  19%|█████                     | 39.5M/204M [00:06<00:25, 6.55M Bytes/s]
Get sub-03/f .. _bold.nii.gz:   0%|          | 16.4k/28.8M [00:00<?, ? Bytes/s]
Get sub-03/f .. _bold.nii.gz:  11%|▏ | 3.08M/28.8M [00:00<00:01, 15.0M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  17%|▎ | 4.87M/28.8M [00:00<00:02, 11.0M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  26%|▌ | 7.36M/28.8M [00:00<00:01, 11.5M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  33%|▋ | 9.42M/28.8M [00:00<00:01, 10.9M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  40%|▊ | 11.6M/28.8M [00:01<00:01, 10.8M Bytes/s]
Total:  26%|██████▊                   | 53.3M/204M [00:07<00:21, 7.08M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  54%|█ | 15.6M/28.8M [00:01<00:01, 12.7M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  63%|█▎| 18.2M/28.8M [00:01<00:01, 9.98M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  71%|█▍| 20.3M/28.8M [00:01<00:00, 10.0M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  78%|█▌| 22.5M/28.8M [00:02<00:00, 10.2M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  85%|█▋| 24.5M/28.8M [00:02<00:00, 11.3M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  92%|█▊| 26.4M/28.8M [00:02<00:00, 9.35M Bytes/s]
Get sub-03/f .. _bold.nii.gz:  99%|█▉| 28.6M/28.8M [00:02<00:00, 9.76M Bytes/s]
                                                                               
Get sub-03/f .. _bold.nii.gz: 100%|██████████| 28.8M/28.8M [00:00<?, ? Bytes/s]
Total:  33%|████████▋                 | 68.2M/204M [00:09<00:18, 7.52M Bytes/s]
Get sub-01/a .. 1_T1w.nii.gz:   0%|          | 16.4k/10.6M [00:00<?, ? Bytes/s]
Get sub-01/a .. 1_T1w.nii.gz:  29%|▌ | 3.09M/10.6M [00:00<00:00, 15.0M Bytes/s]
Get sub-01/a .. 1_T1w.nii.gz:  47%|▉ | 4.94M/10.6M [00:00<00:00, 11.5M Bytes/s]
Get sub-01/a .. 1_T1w.nii.gz:  70%|█▍| 7.45M/10.6M [00:00<00:00, 11.8M Bytes/s]
Get sub-01/a .. 1_T1w.nii.gz:  93%|█▊| 9.85M/10.6M [00:00<00:00, 14.5M Bytes/s]
                                                                               
Get sub-01/a .. 1_T1w.nii.gz: 100%|██████████| 10.6M/10.6M [00:00<?, ? Bytes/s]
                                                                               
Get sub-01/f .. _bold.nii.gz:   0%|          | 16.4k/28.1M [00:00<?, ? Bytes/s]
Get sub-01/f .. _bold.nii.gz:  11%|▏ | 3.09M/28.1M [00:00<00:01, 16.9M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  21%|▍ | 5.82M/28.1M [00:00<00:01, 13.5M Bytes/s]
Total:  42%|███████████               | 86.4M/204M [00:11<00:15, 7.81M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  37%|▋ | 10.4M/28.1M [00:00<00:01, 14.0M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  46%|▉ | 12.9M/28.1M [00:00<00:01, 13.3M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  53%|█ | 15.0M/28.1M [00:01<00:01, 12.2M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  63%|█▎| 17.7M/28.1M [00:01<00:00, 12.5M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  74%|█▍| 20.6M/28.1M [00:01<00:00, 13.0M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  82%|█▋| 23.1M/28.1M [00:01<00:00, 12.6M Bytes/s]
Total:  51%|█████████████▉             | 105M/204M [00:12<00:11, 8.31M Bytes/s]
                                                                               
Get sub-01/f .. _bold.nii.gz: 100%|██████████| 28.1M/28.1M [00:00<?, ? Bytes/s]
                                                                               
Get sub-01/f .. _bold.nii.gz:   0%|          | 16.4k/28.1M [00:00<?, ? Bytes/s]
Get sub-01/f .. _bold.nii.gz:  11%|▏ | 3.07M/28.1M [00:00<00:01, 18.8M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  22%|▍ | 6.12M/28.1M [00:00<00:01, 14.4M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  30%|▌ | 8.40M/28.1M [00:00<00:01, 12.9M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  35%|▋ | 9.91M/28.1M [00:00<00:01, 13.4M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  45%|▉ | 12.6M/28.1M [00:00<00:01, 13.2M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  54%|█ | 15.2M/28.1M [00:01<00:01, 12.9M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  63%|█▎| 17.8M/28.1M [00:01<00:00, 12.8M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  72%|█▍| 20.3M/28.1M [00:01<00:00, 12.6M Bytes/s]
Total:  64%|█████████████████▏         | 130M/204M [00:14<00:08, 8.72M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  90%|█▊| 25.4M/28.1M [00:01<00:00, 12.4M Bytes/s]
Get sub-01/f .. _bold.nii.gz:  98%|█▉| 27.7M/28.1M [00:02<00:00, 12.0M Bytes/s]
                                                                               
Get sub-01/f .. _bold.nii.gz: 100%|██████████| 28.1M/28.1M [00:00<?, ? Bytes/s]
                                                                               
Get sub-02/a .. 2_T1w.nii.gz:   0%|          | 16.4k/10.7M [00:00<?, ? Bytes/s]
Get sub-02/a .. 2_T1w.nii.gz:  29%|▌ | 3.08M/10.7M [00:00<00:00, 17.9M Bytes/s]
Get sub-02/a .. 2_T1w.nii.gz:  56%|█ | 6.03M/10.7M [00:00<00:00, 14.0M Bytes/s]
Get sub-02/a .. 2_T1w.nii.gz:  79%|█▌| 8.44M/10.7M [00:00<00:00, 12.9M Bytes/s]
Get sub-02/a .. 2_T1w.nii.gz:  96%|█▉| 10.3M/10.7M [00:00<00:00, 14.1M Bytes/s]
                                                                               
Get sub-02/a .. 2_T1w.nii.gz: 100%|██████████| 10.7M/10.7M [00:00<?, ? Bytes/s]
                                                                               
Get sub-02/f .. _bold.nii.gz:   0%|          | 16.4k/29.2M [00:00<?, ? Bytes/s]
Get sub-02/f .. _bold.nii.gz:  11%|▏ | 3.10M/29.2M [00:00<00:01, 14.8M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  17%|▎ | 4.90M/29.2M [00:00<00:01, 16.1M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  24%|▍ | 7.13M/29.2M [00:00<00:01, 13.2M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  34%|▋ | 9.88M/29.2M [00:00<00:01, 13.2M Bytes/s]
Total:  78%|████████████████████▉      | 159M/204M [00:17<00:05, 8.90M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  51%|█ | 14.8M/29.2M [00:01<00:01, 12.3M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  59%|█▏| 17.2M/29.2M [00:01<00:01, 11.9M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  67%|█▎| 19.6M/29.2M [00:01<00:00, 11.9M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  75%|█▌| 21.9M/29.2M [00:01<00:00, 11.7M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  83%|█▋| 24.3M/29.2M [00:01<00:00, 11.6M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  92%|█▊| 27.0M/29.2M [00:02<00:00, 12.0M Bytes/s]
                                                                               
Get sub-02/f .. _bold.nii.gz: 100%|██████████| 29.2M/29.2M [00:00<?, ? Bytes/s]
                                                                               
Get sub-02/f .. _bold.nii.gz:   0%|          | 16.4k/29.2M [00:00<?, ? Bytes/s]
Get sub-02/f .. _bold.nii.gz:  10%|▏ | 2.91M/29.2M [00:00<00:00, 28.9M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  25%|▍ | 7.27M/29.2M [00:00<00:01, 13.3M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  33%|▋ | 9.50M/29.2M [00:00<00:01, 12.3M Bytes/s]
Total:  92%|████████████████████████▊  | 188M/204M [00:20<00:01, 9.14M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  50%|█ | 14.7M/29.2M [00:01<00:01, 12.5M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  59%|█▏| 17.3M/29.2M [00:01<00:00, 12.5M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  68%|█▎| 19.8M/29.2M [00:01<00:00, 12.3M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  76%|█▌| 22.2M/29.2M [00:01<00:00, 12.0M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  84%|█▋| 24.5M/29.2M [00:01<00:00, 11.8M Bytes/s]
Get sub-02/f .. _bold.nii.gz:  93%|█▊| 27.3M/29.2M [00:02<00:00, 12.2M Bytes/s]
                                                                               
Get sub-02/f .. _bold.nii.gz: 100%|██████████| 29.2M/29.2M [00:00<?, ? Bytes/s]
get(ok): sub-03/anat/sub-03_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-03/func/sub-03_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-03/func/sub-03_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-01/anat/sub-01_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-01/func/sub-01_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-01/func/sub-01_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-02/anat/sub-02_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-02/func/sub-02_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-02/func/sub-02_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-03 (directory)
get(ok): sub-01 (directory)
get(ok): sub-02 (directory)
action summary:
  get (ok: 12)

The following section outlines key MRIQC command-line options used in this analysis. These include required positional arguments for specifying input and output directories, as well as optional flags for performance optimization and report generation. For a complete list of available options, refer to the official documentation.

Positional Arguments

  • bids_dir: The root folder of a BIDS valid dataset (sub-XXXXX folders should be found at the top level in this folder).

  • output_dir: The directory where the output files should be stored. If you are running group level analysis this folder should be prepopulated with the results of the participant level analysis.

  • analysis_level: Possible choices: participant, group

Level of the analysis that will be performed. Multiple participant level analyses can be run independently (in parallel) using the same output_dir.

  • -v, --verbose: Increases log verbosity for each occurrence, debug level is -vvv.

Options to handle performance

  • --nprocs, --n_procs, --n_cpus, -n-cpus Maximum number of simultaneously running parallel processes executed by MRIQC (e.g., several instances of ANTs’ registration). However, when --nprocs is greater or equal to the --omp-nthreads option, it also sets the maximum number of threads that simultaneously running processes may aggregate (meaning, with --nprocs 16 --omp-nthreads 8 a maximum of two 8-CPU-threaded processes will be running at a given time). Under this mode of operation, --nprocs sets the maximum number of processors that can be assigned work within an MRIQC job, which includes all the processors used by currently running single- and multi-threaded processes. If None, the number of CPUs available will be automatically assigned (which may not be what you want in, e.g., shared systems like a HPC cluster.

  • --mem, --mem_gb, --mem-gb: Upper bound memory limit for MRIQC processes.

Instrumental options

  • -w, --work-dir: Path where intermediate results should be stored.

  • --verbose-reports: Generate verbose HTML reports with additional details

  • --no-sub: Turn off submission of anonymized quality metrics to MRIQC’s metrics repository.

! Warning:

--no-sub and --notrack may be necessary in environments with limited internet access, where automatic submission of quality metrics to MRIQC's web server and tracking data to NiPreps developers may fail or trigger runtime errors.

Participant-level Analysis

%%bash

# Exit immediately if a command fails
set -e

# Set the number of threads for ITK (Image Processing Toolkit) to use
export ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=6
# Set the directory for matplotlib configuration to avoid conflicts
export MPLCONFIGDIR=~/matplotlib-mpldir

# Run MRIQC
mriqc ds000102 \
        MRIQC \
        participant \
        --participant-label sub-01 sub-02 sub-03 \
        --no-sub \
        --work-dir MRIQC_workdir \
        --nprocs 6 \
        --mem-gb 10 \
        --verbose-reports \
        -v
Fetching long content....
/opt/conda/lib/python3.11/site-packages/nilearn/plotting/displays/_slicers.py:420: UserWarning: empty mask
  xmin_, xmax_, ymin_, ymax_, zmin_, zmax_ = get_mask_bounds(
/opt/conda/lib/python3.11/site-packages/nilearn/plotting/displays/_slicers.py:420: UserWarning: empty mask
  xmin_, xmax_, ymin_, ymax_, zmin_, zmax_ = get_mask_bounds(

Group-level Analysis

%%bash

# Exit immediately if a command fails
set -e

mriqc ds000102 \
        MRIQC \
        group \
        --no-sub \
        --work-dir MRIQC_workdir \
        --nprocs 6 \
        --mem-gb 10 \
        --verbose-reports \
        -v                           
------------------------------------------------------------------
  Running MRIQC version 24.1.0.dev0+gd5b13cb5.d20240826
  ----------------------------------------------------------------

  NOTICE
  Copyright © The NiPreps Developers.
  
  This product includes software developed by
  the NiPreps Community (https://nipreps.org/).
  
  Portions of this software were developed at the Department of
  Psychology at Stanford University, Stanford, CA, US.
  
  This software contains code ultimately derived from the
  PCP Quality Assessment Protocol (QAP;
  http://preprocessed-connectomes-project.org/quality-assessment-protocol)
  by C. Craddock, S. Giavasis, D. Clark, Z. Shezhad, and J. Pellman.
  
  This software is also distributed as a Docker container image.
  The bootstrapping file for the image ("Dockerfile") is licensed
  under the MIT License.

  ----------------------------------------------------------------

  * BIDS dataset path: /home/jovyan/workspace/books/examples/workflows/ds000102.
  * Output folder: MRIQC.
  * Analysis levels: ['group'].
------------------------------------------------------------------

2026-10-05 15:01:35 | IMPORTANT | mriqc            | DataLad dataset identified, attempting to `datalad get` unavailable files.
get(ok): sub-17/anat/sub-17_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-06/anat/sub-06_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-20/anat/sub-20_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-10/func/sub-10_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-23/func/sub-23_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-04/func/sub-04_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-21/func/sub-21_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-04/func/sub-04_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-26/func/sub-26_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-22/func/sub-22_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-09/anat/sub-09_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-25/func/sub-25_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-24/anat/sub-24_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-16/func/sub-16_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-12/anat/sub-12_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-15/func/sub-15_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-14/func/sub-14_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-07/anat/sub-07_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-07/func/sub-07_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-04/anat/sub-04_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-05/func/sub-05_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-13/func/sub-13_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-11/anat/sub-11_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-20/func/sub-20_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-23/anat/sub-23_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-10/func/sub-10_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-21/func/sub-21_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-08/func/sub-08_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-11/func/sub-11_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-08/anat/sub-08_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-09/func/sub-09_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-16/func/sub-16_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-12/func/sub-12_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-24/func/sub-24_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-06/func/sub-06_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-25/anat/sub-25_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-19/anat/sub-19_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-10/anat/sub-10_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-21/anat/sub-21_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-13/func/sub-13_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-11/func/sub-11_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-22/anat/sub-22_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-14/func/sub-14_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-15/anat/sub-15_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-07/func/sub-07_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-18/func/sub-18_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-24/func/sub-24_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-12/func/sub-12_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-17/func/sub-17_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-17/func/sub-17_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-08/func/sub-08_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-16/anat/sub-16_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-13/anat/sub-13_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-19/func/sub-19_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-25/func/sub-25_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-19/func/sub-19_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-26/func/sub-26_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-20/func/sub-20_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-06/func/sub-06_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-26/anat/sub-26_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-18/anat/sub-18_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-15/func/sub-15_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-18/func/sub-18_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-05/anat/sub-05_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-05/func/sub-05_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-22/func/sub-22_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-14/anat/sub-14_T1w.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-09/func/sub-09_task-flanker_run-1_bold.nii.gz (file) [from s3-PUBLIC...]
get(ok): sub-23/func/sub-23_task-flanker_run-2_bold.nii.gz (file) [from s3-PUBLIC...]
action summary:
  get (notneeded: 9, ok: 69)
2026-10-05 15:03:29 | IMPORTANT | mriqc            | Extracting metadata and entities for 26 input runs of modality 't1w'...
2026-10-05 15:03:29 | IMPORTANT | mriqc            | File size ('t1w'): 0.01|0.01 GB [maximum|average].
2026-10-05 15:03:29 | IMPORTANT | mriqc            | Extracting metadata and entities for 52 input runs of modality 'bold'...
2026-10-05 15:03:29 | IMPORTANT | mriqc            | File size ('bold'): 0.03|0.03 GB [maximum|average].
2026-10-05 15:03:29 | INFO     | mriqc            | MRIQC config file: /home/jovyan/workspace/books/examples/workflows/MRIQC_workdir/config-20261005-150133_5114d69b-647f-4992-9d6b-820845f37280.toml.
------------------------------------------------------------------
Generating group reports
------------------------------------------------------------------

2026-10-05 15:03:29 | INFO     | mriqc            | Generated summary TSV table for T1w data: /home/jovyan/workspace/books/examples/workflows/MRIQC/group_T1w.tsv
2026-10-05 15:03:29 | INFO     | mriqc            | Group-T1w report generated: /home/jovyan/workspace/books/examples/workflows/MRIQC/group_T1w.html
2026-10-05 15:03:30 | INFO     | mriqc            | Generated summary TSV table for bold data: /home/jovyan/workspace/books/examples/workflows/MRIQC/group_bold.tsv
2026-10-05 15:03:30 | INFO     | mriqc            | Group-bold report generated: /home/jovyan/workspace/books/examples/workflows/MRIQC/group_bold.html
2026-10-05 15:03:30 | INFO     | mriqc            | Group level finished successfully.
2026-10-05 15:03:30 | INFO     | mriqc            | Generating BIDS derivatives metadata.
----------------------------------------------------------------
  MRIQC completed (elapsed time 00h 01min 56s).
----------------------------------------------------------------

MRIQC Visual Reports

MRIQC automatically generates individual and group-level reports to support the quality assessment of MRI data.

Individual reports include mosaic views of anatomical or functional images along various cutting planes, along with overlays like segmentation contours or motion estimates. These visuals help quickly screen for artifacts or other issues. They are especially useful for reviewing images that may have been flagged as low-quality by the automated classifier.

Group reports compile quality metrics across all subjects and display interactive scatter plots for each image quality metric (IQM). These plots make it easy to spot outliers—clicking on any point in the scatter plot refers to the corresponding individual report for that subject.

These embedded reports offer an intuitive way to explore quality metrics and support decisions about excluding or further examining specific runs or subjects.

Anatomical Report

# Helper function to display MRIQC HTML reports with inline SVG figures

def display_mriqc_report(report_path):
    report_dir = os.path.dirname(report_path)
    with open(report_path) as f:
        soup = BeautifulSoup(f, 'html.parser')
    # Inline each figure where the report embeds it, and drop the "Get figure file" links:
    # both point into MRIQC/, which is not published with this page, and would 404.
    for tag in soup.find_all(class_='svg-reportlet'):
        svg_path = os.path.join(report_dir, tag.get('src') or tag.get('data', ''))
        if os.path.exists(svg_path):
            with open(svg_path) as svg_file:
                svg_soup = BeautifulSoup(svg_file.read(), 'html.parser')
                tag.replace_with(svg_soup)
    for small in soup.find_all('small'):
        if small.get_text().startswith('Get figure file'):
            small.decompose()
    for tag in soup(['button', 'nav', 'head']):
        tag.decompose()
    display(HTML(str(soup)))
display_mriqc_report('./MRIQC/sub-01_T1w.html')
Loading...

Functional Report

display_mriqc_report('./MRIQC/sub-02_task-flanker_run-1_bold.html')
Loading...

Group functional report

with open('./MRIQC/group_bold.html', 'r') as f:
    html = f.read()

display(HTML(html))
Loading...

Dependencies in Jupyter/Python

  • Using the package watermark to document system environment and software versions used in this notebook, alongside the Neurodesktop version extracted from the JUPYTER_IMAGE or NEURODESKTOP_VERSION environment variables.

import os

%load_ext watermark

%watermark
%watermark --iversions

neurodesktop_version = (
    os.environ.get('JUPYTER_IMAGE', '').split(':')[-1] or
    os.environ.get('NEURODESKTOP_VERSION', 'unknown')
)

print(f"Neurodesktop version: {neurodesktop_version}")
Last updated: 2026-10-05T15:03:31.780782+00:00

Python implementation: CPython
Python version       : 3.13.15
IPython version      : 9.17.1

Compiler    : GCC 15.3.0
OS          : Linux
Release     : 6.8.0-111-generic
Machine     : x86_64
Processor   : x86_64
CPU cores   : 16
Architecture: 64bit

IPython: 9.17.1
bs4    : 4.15.0

Neurodesktop version: 2026-09-28
References
  1. 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. 10.1371/journal.pone.0184661
  2. Kelly, A. M. C., Uddin, L. Q., Biswal, B. B., Castellanos, F. X., & Milham, M. P. (2008). Competition between functional brain networks mediates behavioral variability. NeuroImage, 39(1), 527–537. 10.1016/j.neuroimage.2007.08.008
  3. Mennes, M., Kelly, C., Zuo, X.-N., Di Martino, A., Biswal, B. B., Castellanos, F. X., & Milham, M. P. (2010). Inter-individual differences in resting-state functional connectivity predict task-induced BOLD activity. NeuroImage, 50(4), 1690–1701. 10.1016/j.neuroimage.2010.01.002
  4. Mennes, M., Zuo, X.-N., Kelly, C., Di Martino, A., Zang, Y.-F., Biswal, B., Castellanos, F. X., & Milham, M. P. (2011). Linking inter-individual differences in neural activation and behavior to intrinsic brain dynamics. NeuroImage, 54(4), 2950–2959. 10.1016/j.neuroimage.2010.10.046
Neurodesk
Neurodesk Tools Demo
Neurodesk
Magic Commands