Note
Go to the end to download the full example code.
Quality Assurance¶
Simple example.
Example on how to run the quality assurance pre-processing using BrainPrep. See user guide for details.
Data¶
Let’s first get some anatomical data.
from pathlib import Path
from brainprep.datasets import IBCDataset
from brainprep.utils import Bunch
datadir = Path("/tmp/brainprep-data")
datadir.mkdir(parents=True, exist_ok=True)
dataset = IBCDataset(datadir)
data = Bunch(
sub01=dataset.fetch(
subject="01",
modality="anat|dwi|func",
),
sub02=dataset.fetch(
subject="02",
modality="anat|dwi|func",
),
)
print(data)
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-01/ses-00/anat/sub-01_ses-00
_T1w.nii.gz
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-01/ses-00/dwi/sub-01_ses-00_
dwi.nii.gz
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-01/ses-00/dwi/sub-01_ses-00_
dwi.bvec
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-01/ses-00/dwi/sub-01_ses-00_
dwi.bval
[info] - downloading: https://s3.amazonaws.com/openneuro.org/ds002685/dwi.json
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-01/ses-00/func/sub-01_ses-00
_task-ArchiStandard_dir-pa_bold.nii.gz
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/task-ArchiStandard_dir-pa_bold.j
son
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-01/ses-00/func/sub-01_ses-00
_task-ArchiStandard_dir-pa_sbref.nii.gz
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/task-ArchiStandard_dir-pa_sbref.
json
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-01/ses-00/func/sub-01_ses-00
_task-ArchiStandard_dir-pa_events.tsv
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-01/ses-00/func/sub-01_ses-00
_task-ArchiStandard_dir-ap_sbref.nii.gz
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/task-ArchiStandard_dir-ap_sbref.
json
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-02/ses-00/anat/sub-02_ses-00
_T1w.nii.gz
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-02/ses-00/dwi/sub-02_ses-00_
dwi.nii.gz
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-02/ses-00/dwi/sub-02_ses-00_
dwi.bvec
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-02/ses-00/dwi/sub-02_ses-00_
dwi.bval
[info] - downloading: https://s3.amazonaws.com/openneuro.org/ds002685/dwi.json
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-02/ses-00/func/sub-02_ses-00
_task-ArchiStandard_dir-pa_bold.nii.gz
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/task-ArchiStandard_dir-pa_bold.j
son
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-02/ses-00/func/sub-02_ses-00
_task-ArchiStandard_dir-pa_sbref.nii.gz
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/task-ArchiStandard_dir-pa_sbref.
json
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-02/ses-00/func/sub-02_ses-00
_task-ArchiStandard_dir-pa_events.tsv
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/sub-02/ses-00/func/sub-02_ses-00
_task-ArchiStandard_dir-ap_sbref.nii.gz
[info] - downloading:
https://s3.amazonaws.com/openneuro.org/ds002685/task-ArchiStandard_dir-ap_sbref.
json
Bunch(
sub01: Bunch(
description: PosixPath('/tmp/brainprep-data/rawdata/dataset_description.json')
anat: PosixPath('/tmp/brainprep-data/rawdata/sub-01/ses-00/anat/sub-01_ses-00_T1w.nii.gz')
dwi: PosixPath('/tmp/brainprep-data/rawdata/sub-01/ses-00/dwi/sub-01_ses-00_dwi.nii.gz')
bvec: PosixPath('/tmp/brainprep-data/rawdata/sub-01/ses-00/dwi/sub-01_ses-00_dwi.bvec')
bval: PosixPath('/tmp/brainprep-data/rawdata/sub-01/ses-00/dwi/sub-01_ses-00_dwi.bval')
func: PosixPath('/tmp/brainprep-data/rawdata/sub-01/ses-00/func/sub-01_ses-00_task-ArchiStandard_dir-pa_bold.nii.gz')
fmap: PosixPath('/tmp/brainprep-data/rawdata/sub-01/ses-00/fmap/sub-01_ses-00_task-ArchiStandard_dir-ap_sbref.nii.gz')
)
sub02: Bunch(
description: PosixPath('/tmp/brainprep-data/rawdata/dataset_description.json')
anat: PosixPath('/tmp/brainprep-data/rawdata/sub-02/ses-00/anat/sub-02_ses-00_T1w.nii.gz')
dwi: PosixPath('/tmp/brainprep-data/rawdata/sub-02/ses-00/dwi/sub-02_ses-00_dwi.nii.gz')
bvec: PosixPath('/tmp/brainprep-data/rawdata/sub-02/ses-00/dwi/sub-02_ses-00_dwi.bvec')
bval: PosixPath('/tmp/brainprep-data/rawdata/sub-02/ses-00/dwi/sub-02_ses-00_dwi.bval')
func: PosixPath('/tmp/brainprep-data/rawdata/sub-02/ses-00/func/sub-02_ses-00_task-ArchiStandard_dir-pa_bold.nii.gz')
fmap: PosixPath('/tmp/brainprep-data/rawdata/sub-02/ses-00/fmap/sub-02_ses-00_task-ArchiStandard_dir-ap_sbref.nii.gz')
)
)
Analysis¶
Let’s now perform the preprocessing using BrainPrep. As with many tutorials, we won’t execute the code directly here. However, feel free to set the ‘dryrun’ configuration to False to actually run each step and generate results on disk.
from brainprep.workflow import (
brainprep_quality_assurance,
brainprep_group_quality_assurance,
)
from brainprep.config import Config
from brainprep.reporting import RSTReport
outdir = Path("/tmp/brainprep-qa")
outdir.mkdir(parents=True, exist_ok=True)
with Config(dryrun=True, verbose=True):
for subject_data in data.values():
report = RSTReport()
brainprep_quality_assurance(
image_files=[
subject_data.anat,
subject_data.func,
subject_data.dwi
],
output_dir=outdir,
keep_intermediate=True,
)
print(report)
report = RSTReport()
brainprep_group_quality_assurance(
modalities=["T1w", 'bold', 'dwi'],
output_dir=outdir,
)
print(report)
[warn] - BIDS file name does not contain run key: sub-01_ses-00_T1w.nii.gz
[warn] - BIDS file name does not contain run key:
sub-01_ses-00_task-ArchiStandard_dir-pa_bold.nii.gz
[warn] - BIDS file name does not contain run key: sub-01_ses-00_dwi.nii.gz
[title] - Subject Level Quality Assurance...
[info] - setting workspace directory:
/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00/workspace
[command] - mriqc /tmp/brainprep-data/rawdata
/tmp/brainprep-qa/derivatives/quality_assurance participant -w
/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00/workspace --no-sub
--no-datalad-get --notrack --participant-label 01
[info] - checking output:
/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00/anat/sub-01_ses-00
_T1w.json
[info] - checking output:
/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00/func/sub-01_ses-00
_task-ArchiStandard_dir-pa_bold.json
[info] - checking output:
/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00/dwi/sub-01_ses-00_
dwi.json
[title] - Subject Level Quality Assurance done.
Bunch(
step1: Bunch(
module: 'brainprep.workflow.quality_assurance.brainprep_quality_assurance'
description: '\n Subject level quality assurance pre-processing workflow for MRI images.\n\n Applies MRIQC tool :footcite:p:`esteban2017mriqc` with subject level\n default settings.\n\n Parameters\n ----------\n image_files : list[File]\n Path to the input image files of one subject.\n output_dir : Directory\n Directory where the quality assurance related outputs will be saved\n (i.e., the root of your dataset).\n keep_intermediate : bool\n If True, retains intermediate results (i.e., the workspace); useful\n for debugging. Default False.\n **kwargs : dict\n entities: lsit[dict]\n Dictionaries of parsed BIDS entities.\n\n\n Returns\n -------\n Bunch\n A dictionary-like object containing:\n\n - iqm_files : list[File] — paths to the subject level Image Quality\n Metrics (IQMs).\n\n Notes\n -----\n This workflow assumes the input images are organized in BIDS.\n\n References\n ----------\n\n .. footbibliography::\n\n Examples\n --------\n >>> from brainprep.config import Config\n >>> from brainprep.reporting import RSTReport\n >>> from brainprep.workflow import brainprep_quality_assurance\n >>>\n >>> with Config(dryrun=True, verbose=False):\n ... report = RSTReport()\n ... outputs = brainprep_quality_assurance(\n ... image_files=[\n ... "/tmp/dataset/rawdata/sub-01/ses-01/anat/"\n ... "sub-01_ses-01_run-01_T1w.nii.gz",\n ... "/tmp/dataset/rawdata/sub-01/ses-01/dwi/"\n ... "sub-01_ses-01_run-01_dwi.nii.gz",\n ... ],\n ... output_dir="/tmp/dataset/derivatives",\n ... )\n >>> outputs\n Bunch(\n iqm_files: [PosixPath(\'...\'), PosixPath(\'...\')]\n )\n '
inputs: Bunch(
image_files: [PosixPath('/tmp/brainprep-data/rawdata/sub-01/ses-00/anat/sub-01_ses-00_T1w.nii.gz'), PosixPath('/tmp/brainprep-data/rawdata/sub-01/ses-00/func/sub-01_ses-00_task-ArchiStandard_dir-pa_bold.nii.gz'), PosixPath('/tmp/brainprep-data/rawdata/sub-01/ses-00/dwi/sub-01_ses-00_dwi.nii.gz')]
output_dir: PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00')
keep_intermediate: True
kwargs: {'entities': [{'sub': '01', 'ses': '00', 'modality': 'T1w', 'mod': 'T1w', 'run': '28236'}, {'sub': '01', 'ses': '00', 'task': 'ArchiStandard', 'dir': 'pa', 'modality': 'bold', 'mod': 'bold', 'run': '20876'}, {'sub': '01', 'ses': '00', 'modality': 'dwi', 'mod': 'dwi', 'run': '18444'}]}
)
outputs: Bunch(
iqm_files: [PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00/anat/sub-01_ses-00_T1w.json'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00/func/sub-01_ses-00_task-ArchiStandard_dir-pa_bold.json'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00/dwi/sub-01_ses-00_dwi.json')]
)
runtime: Bunch(
start: '2026-04-01 12:35:20.810778'
end: '2026-04-01 12:35:20.818084'
execution_time: 2.0294444444444444e-06
brainprep_version: '2.0.0'
platform: 'Linux-6.17.0-1008-azure-x86_64-with-glibc2.39'
hostname: 'runnervmrg6be'
)
config: Bunch(
verbose: True
dryrun: True
no_color: False
skip_run_check: False
cat12_file: PosixPath('/opt/cat12/standalone/cat_standalone.sh')
spm12_dir: PosixPath('/opt/cat12')
matlab_dir: PosixPath('/opt/MCR-2017b/v93')
tpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/tpm/TPM.nii')
darteltpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/toolbox/cat12/templates_MNI152NLin2009cAsym/Template_1_Dartel.nii')
)
)
step2: Bunch(
module: 'brainprep.interfaces.mriqc.subject_level_qa'
description: '\n Compute subject level Image Quality Metrics (IQMs) generated by MRIQC.\n\n Parameters\n ----------\n image_files : list[File]\n Path to the input image files.\n workspace_dir : Directory\n The workspace of the current processing.\n output_dir : Directory\n Directory where the IQMs will be saved.\n\n Returns\n -------\n command : list[str]\n Cross sectional quality analysis command-line.\n outputs : tuple[File | list[File]]\n - iqm_files : list[File] - IQM files.\n '
trace: 'brainprep.workflow.quality_assurance.brainprep_quality_assurance'
inputs: Bunch(
image_files: [PosixPath('/tmp/brainprep-data/rawdata/sub-01/ses-00/anat/sub-01_ses-00_T1w.nii.gz'), PosixPath('/tmp/brainprep-data/rawdata/sub-01/ses-00/func/sub-01_ses-00_task-ArchiStandard_dir-pa_bold.nii.gz'), PosixPath('/tmp/brainprep-data/rawdata/sub-01/ses-00/dwi/sub-01_ses-00_dwi.nii.gz')]
workspace_dir: PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00/workspace')
output_dir: PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00')
)
outputs: Bunch(
outputs: (['mriqc', '/tmp/brainprep-data/rawdata', '/tmp/brainprep-qa/derivatives/quality_assurance', 'participant', '-w', '/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00/workspace', '--no-sub', '--no-datalad-get', '--notrack', '--participant-label', '01'], ([PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00/anat/sub-01_ses-00_T1w.json'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00/func/sub-01_ses-00_task-ArchiStandard_dir-pa_bold.json'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-01/ses-00/dwi/sub-01_ses-00_dwi.json')],))
)
runtime: Bunch(
start: '2026-04-01 12:35:20.815408'
end: '2026-04-01 12:35:20.815562'
execution_time: 4.277777777777778e-08
brainprep_version: '2.0.0'
platform: 'Linux-6.17.0-1008-azure-x86_64-with-glibc2.39'
hostname: 'runnervmrg6be'
)
config: Bunch(
verbose: True
dryrun: True
no_color: False
skip_run_check: False
cat12_file: PosixPath('/opt/cat12/standalone/cat_standalone.sh')
spm12_dir: PosixPath('/opt/cat12')
matlab_dir: PosixPath('/opt/MCR-2017b/v93')
tpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/tpm/TPM.nii')
darteltpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/toolbox/cat12/templates_MNI152NLin2009cAsym/Template_1_Dartel.nii')
)
)
)
[warn] - BIDS file name does not contain run key: sub-02_ses-00_T1w.nii.gz
[warn] - BIDS file name does not contain run key:
sub-02_ses-00_task-ArchiStandard_dir-pa_bold.nii.gz
[warn] - BIDS file name does not contain run key: sub-02_ses-00_dwi.nii.gz
[title] - Subject Level Quality Assurance...
[info] - setting workspace directory:
/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00/workspace
[command] - mriqc /tmp/brainprep-data/rawdata
/tmp/brainprep-qa/derivatives/quality_assurance participant -w
/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00/workspace --no-sub
--no-datalad-get --notrack --participant-label 02
[info] - checking output:
/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00/anat/sub-02_ses-00
_T1w.json
[info] - checking output:
/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00/func/sub-02_ses-00
_task-ArchiStandard_dir-pa_bold.json
[info] - checking output:
/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00/dwi/sub-02_ses-00_
dwi.json
[title] - Subject Level Quality Assurance done.
Bunch(
step1: Bunch(
module: 'brainprep.workflow.quality_assurance.brainprep_quality_assurance'
description: '\n Subject level quality assurance pre-processing workflow for MRI images.\n\n Applies MRIQC tool :footcite:p:`esteban2017mriqc` with subject level\n default settings.\n\n Parameters\n ----------\n image_files : list[File]\n Path to the input image files of one subject.\n output_dir : Directory\n Directory where the quality assurance related outputs will be saved\n (i.e., the root of your dataset).\n keep_intermediate : bool\n If True, retains intermediate results (i.e., the workspace); useful\n for debugging. Default False.\n **kwargs : dict\n entities: lsit[dict]\n Dictionaries of parsed BIDS entities.\n\n\n Returns\n -------\n Bunch\n A dictionary-like object containing:\n\n - iqm_files : list[File] — paths to the subject level Image Quality\n Metrics (IQMs).\n\n Notes\n -----\n This workflow assumes the input images are organized in BIDS.\n\n References\n ----------\n\n .. footbibliography::\n\n Examples\n --------\n >>> from brainprep.config import Config\n >>> from brainprep.reporting import RSTReport\n >>> from brainprep.workflow import brainprep_quality_assurance\n >>>\n >>> with Config(dryrun=True, verbose=False):\n ... report = RSTReport()\n ... outputs = brainprep_quality_assurance(\n ... image_files=[\n ... "/tmp/dataset/rawdata/sub-01/ses-01/anat/"\n ... "sub-01_ses-01_run-01_T1w.nii.gz",\n ... "/tmp/dataset/rawdata/sub-01/ses-01/dwi/"\n ... "sub-01_ses-01_run-01_dwi.nii.gz",\n ... ],\n ... output_dir="/tmp/dataset/derivatives",\n ... )\n >>> outputs\n Bunch(\n iqm_files: [PosixPath(\'...\'), PosixPath(\'...\')]\n )\n '
inputs: Bunch(
image_files: [PosixPath('/tmp/brainprep-data/rawdata/sub-02/ses-00/anat/sub-02_ses-00_T1w.nii.gz'), PosixPath('/tmp/brainprep-data/rawdata/sub-02/ses-00/func/sub-02_ses-00_task-ArchiStandard_dir-pa_bold.nii.gz'), PosixPath('/tmp/brainprep-data/rawdata/sub-02/ses-00/dwi/sub-02_ses-00_dwi.nii.gz')]
output_dir: PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00')
keep_intermediate: True
kwargs: {'entities': [{'sub': '02', 'ses': '00', 'modality': 'T1w', 'mod': 'T1w', 'run': '20892'}, {'sub': '02', 'ses': '00', 'task': 'ArchiStandard', 'dir': 'pa', 'modality': 'bold', 'mod': 'bold', 'run': '27010'}, {'sub': '02', 'ses': '00', 'modality': 'dwi', 'mod': 'dwi', 'run': '14470'}]}
)
outputs: Bunch(
iqm_files: [PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00/anat/sub-02_ses-00_T1w.json'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00/func/sub-02_ses-00_task-ArchiStandard_dir-pa_bold.json'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00/dwi/sub-02_ses-00_dwi.json')]
)
runtime: Bunch(
start: '2026-04-01 12:35:20.829118'
end: '2026-04-01 12:35:20.835100'
execution_time: 1.6616666666666667e-06
brainprep_version: '2.0.0'
platform: 'Linux-6.17.0-1008-azure-x86_64-with-glibc2.39'
hostname: 'runnervmrg6be'
)
config: Bunch(
verbose: True
dryrun: True
no_color: False
skip_run_check: False
cat12_file: PosixPath('/opt/cat12/standalone/cat_standalone.sh')
spm12_dir: PosixPath('/opt/cat12')
matlab_dir: PosixPath('/opt/MCR-2017b/v93')
tpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/tpm/TPM.nii')
darteltpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/toolbox/cat12/templates_MNI152NLin2009cAsym/Template_1_Dartel.nii')
)
)
step2: Bunch(
module: 'brainprep.interfaces.mriqc.subject_level_qa'
description: '\n Compute subject level Image Quality Metrics (IQMs) generated by MRIQC.\n\n Parameters\n ----------\n image_files : list[File]\n Path to the input image files.\n workspace_dir : Directory\n The workspace of the current processing.\n output_dir : Directory\n Directory where the IQMs will be saved.\n\n Returns\n -------\n command : list[str]\n Cross sectional quality analysis command-line.\n outputs : tuple[File | list[File]]\n - iqm_files : list[File] - IQM files.\n '
trace: 'brainprep.workflow.quality_assurance.brainprep_quality_assurance'
inputs: Bunch(
image_files: [PosixPath('/tmp/brainprep-data/rawdata/sub-02/ses-00/anat/sub-02_ses-00_T1w.nii.gz'), PosixPath('/tmp/brainprep-data/rawdata/sub-02/ses-00/func/sub-02_ses-00_task-ArchiStandard_dir-pa_bold.nii.gz'), PosixPath('/tmp/brainprep-data/rawdata/sub-02/ses-00/dwi/sub-02_ses-00_dwi.nii.gz')]
workspace_dir: PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00/workspace')
output_dir: PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00')
)
outputs: Bunch(
outputs: (['mriqc', '/tmp/brainprep-data/rawdata', '/tmp/brainprep-qa/derivatives/quality_assurance', 'participant', '-w', '/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00/workspace', '--no-sub', '--no-datalad-get', '--notrack', '--participant-label', '02'], ([PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00/anat/sub-02_ses-00_T1w.json'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00/func/sub-02_ses-00_task-ArchiStandard_dir-pa_bold.json'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/sub-02/ses-00/dwi/sub-02_ses-00_dwi.json')],))
)
runtime: Bunch(
start: '2026-04-01 12:35:20.832576'
end: '2026-04-01 12:35:20.832707'
execution_time: 3.6388888888888895e-08
brainprep_version: '2.0.0'
platform: 'Linux-6.17.0-1008-azure-x86_64-with-glibc2.39'
hostname: 'runnervmrg6be'
)
config: Bunch(
verbose: True
dryrun: True
no_color: False
skip_run_check: False
cat12_file: PosixPath('/opt/cat12/standalone/cat_standalone.sh')
spm12_dir: PosixPath('/opt/cat12')
matlab_dir: PosixPath('/opt/MCR-2017b/v93')
tpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/tpm/TPM.nii')
darteltpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/toolbox/cat12/templates_MNI152NLin2009cAsym/Template_1_Dartel.nii')
)
)
)
[title] - Group Level Quality Assurance...
[command] - mriqc /tmp/brainprep-qa/rawdata
/tmp/brainprep-qa/derivatives/quality_assurance group --no-sub --no-datalad-get
--notrack
[info] - checking output:
/tmp/brainprep-qa/derivatives/quality_assurance/group_T1w.tsv
[info] - checking output:
/tmp/brainprep-qa/derivatives/quality_assurance/group_bold.tsv
[info] - checking output:
/tmp/brainprep-qa/derivatives/quality_assurance/group_dwi.tsv
[info] - checking output:
/tmp/brainprep-qa/derivatives/quality_assurance/group_T1w.tsv
[info] - checking output:
/tmp/brainprep-qa/derivatives/quality_assurance/group_bold.tsv
[info] - checking output:
/tmp/brainprep-qa/derivatives/quality_assurance/group_dwi.tsv
[title] - Group Level Quality Assurance done.
Bunch(
step1: Bunch(
module: 'brainprep.workflow.quality_assurance.brainprep_group_quality_assurance'
description: '\n Group-level quality assurance pre-processing.\n\n Summarizes the generated metrics :footcite:p:`esteban2017mriqc` and\n applies the following quality control:\n\n 1) Generate TSV tables of Image Quality Metrics (IQMs) generated by MRIQC.\n 2) Generate TSV tables of quality assurance metrics for different\n modalities.\n 3) Apply threshold-based quality checks on the selected quality metrics.\n 4) Generate a histogram showing the distribution of these quality metrics.\n\n The following quality metrics are considered:\n\n - TODO\n\n Parameters\n ----------\n modalities: list[str]\n The modalities in the current study.\n output_dir : Directory\n Directory where the quality assurance related outputs will be saved\n (i.e., the root of your dataset).\n keep_intermediate : bool\n If True, retains intermediate results (no effect on this workflow).\n Default False.\n\n Returns\n -------\n Bunch\n A dictionary-like object containing:\n\n - iqm_files : list[File] — paths to the selected set o group-level\n uncorrelated Image Quality Metrics (IQMs).\n\n Notes\n -----\n This workflow assumes the subject-level analyses have already been\n performed.\n\n References\n ----------\n\n .. footbibliography::\n\n Examples\n --------\n >>> from brainprep.config import Config\n >>> from brainprep.reporting import RSTReport\n >>> from brainprep.workflow import brainprep_group_quality_assurance\n >>>\n >>> with Config(dryrun=True, verbose=False):\n ... report = RSTReport()\n ... outputs = brainprep_group_quality_assurance(\n ... modalities=["T1w"],\n ... output_dir="/tmp/dataset/derivatives",\n ... )\n >>> outputs\n Bunch(\n iqm_files: [PosixPath(\'...\')]\n )\n '
inputs: Bunch(
modalities: ['T1w', 'bold', 'dwi']
output_dir: PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance')
keep_intermediate: False
)
outputs: Bunch(
iqm_files: [PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/group_T1w.tsv'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/group_bold.tsv'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/group_dwi.tsv')]
)
runtime: Bunch(
start: '2026-04-01 12:35:20.843889'
end: '2026-04-01 12:35:20.852801'
execution_time: 2.4755555555555557e-06
brainprep_version: '2.0.0'
platform: 'Linux-6.17.0-1008-azure-x86_64-with-glibc2.39'
hostname: 'runnervmrg6be'
)
config: Bunch(
verbose: True
dryrun: True
no_color: False
skip_run_check: False
cat12_file: PosixPath('/opt/cat12/standalone/cat_standalone.sh')
spm12_dir: PosixPath('/opt/cat12')
matlab_dir: PosixPath('/opt/MCR-2017b/v93')
tpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/tpm/TPM.nii')
darteltpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/toolbox/cat12/templates_MNI152NLin2009cAsym/Template_1_Dartel.nii')
)
)
step2: Bunch(
module: 'brainprep.interfaces.mriqc.group_level_qa'
description: '\n Compute group level Image Quality Metrics (IQMs) generated by MRIQC.\n\n Parameters\n ----------\n modalities: list[str]\n The modalities in the current study.\n output_dir : Directory\n Directory where the IQMs will be saved.\n\n Returns\n -------\n command : list[str]\n Group quality analysis command-line.\n outputs : tuple[File | list[File]]\n - iqm_files : list[File] - Group IQM files.\n '
trace: 'brainprep.workflow.quality_assurance.brainprep_group_quality_assurance'
inputs: Bunch(
modalities: ['T1w', 'bold', 'dwi']
output_dir: PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance')
)
outputs: Bunch(
outputs: (['mriqc', '/tmp/brainprep-qa/rawdata', '/tmp/brainprep-qa/derivatives/quality_assurance', 'group', '--no-sub', '--no-datalad-get', '--notrack'], ([PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/group_T1w.tsv'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/group_bold.tsv'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/group_dwi.tsv')],))
)
runtime: Bunch(
start: '2026-04-01 12:35:20.846782'
end: '2026-04-01 12:35:20.846825'
execution_time: 1.1944444444444444e-08
brainprep_version: '2.0.0'
platform: 'Linux-6.17.0-1008-azure-x86_64-with-glibc2.39'
hostname: 'runnervmrg6be'
)
config: Bunch(
verbose: True
dryrun: True
no_color: False
skip_run_check: False
cat12_file: PosixPath('/opt/cat12/standalone/cat_standalone.sh')
spm12_dir: PosixPath('/opt/cat12')
matlab_dir: PosixPath('/opt/MCR-2017b/v93')
tpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/tpm/TPM.nii')
darteltpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/toolbox/cat12/templates_MNI152NLin2009cAsym/Template_1_Dartel.nii')
)
)
step3: Bunch(
module: 'brainprep.interfaces.qualcheck.mriqc_metrics'
description: '\n Filter MRIQC group-level metrics according to modality-specific defaults.\n\n Each input file must follow the naming pattern ``group_<modality>.tsv``.\n Based on the modality extracted from the filename (e.g., T1w, bold, dwi),\n a predefined set of uncorrelated Image Quality Metrics (IQMs) is selected.\n The function then writes a filtered TSV file containing only those metrics\n to the specified output directory.\n\n Parameters\n ----------\n iqm_files : list[File]\n Paths to MRIQC group-level metrics files.\n output_dir : Directory\n Directory where the filtered metrics will be written.\n dryrun : bool\n If True, skip actual computation and file writing. Default False.\n\n Returns\n -------\n filter_iqm_files : list[File]\n Paths to the selected set of uncorrelated group-level IQMs.\n\n Raises\n ------\n ValueError\n If modality extracted from the filename is unsupported\n If the filename does not follow the expected pattern\n ``group_<modality>.tsv``.\n '
trace: 'brainprep.workflow.quality_assurance.brainprep_group_quality_assurance'
inputs: Bunch(
iqm_files: [PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/group_T1w.tsv'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/group_bold.tsv'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/group_dwi.tsv')]
output_dir: PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/quality_check')
dryrun: False
)
outputs: Bunch(
outputs: ([PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/group_T1w.tsv'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/group_bold.tsv'), PosixPath('/tmp/brainprep-qa/derivatives/quality_assurance/group_dwi.tsv')],)
)
runtime: Bunch(
start: '2026-04-01 12:35:20.851447'
end: '2026-04-01 12:35:20.851480'
execution_time: 9.166666666666668e-09
brainprep_version: '2.0.0'
platform: 'Linux-6.17.0-1008-azure-x86_64-with-glibc2.39'
hostname: 'runnervmrg6be'
)
config: Bunch(
verbose: True
dryrun: True
no_color: False
skip_run_check: False
cat12_file: PosixPath('/opt/cat12/standalone/cat_standalone.sh')
spm12_dir: PosixPath('/opt/cat12')
matlab_dir: PosixPath('/opt/MCR-2017b/v93')
tpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/tpm/TPM.nii')
darteltpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/toolbox/cat12/templates_MNI152NLin2009cAsym/Template_1_Dartel.nii')
)
)
)
CLI¶
Let’s now generate the same analysis using the CLI. The goal here is to translate the workflow calls into explicit shell commands. See user guide for details.
from pprint import pprint
commands = []
commands.append(
[
[
"brainprep", "subject-level-qa",
"--image-files",
f"{subject_data.anat},{subject_data.func},{subject_data.dwi}",
"--output-dir", str(outdir),
"--keep-intermediate",
] for subject_data in data.values()
]
)
commands.append(
[
[
"brainprep", "group-level-qa",
"--modalities", f"T1w,bold,dwi",
"--output-dir", str(outdir),
]
]
)
pprint(commands)
[[['brainprep',
'subject-level-qa',
'--image-files',
'/tmp/brainprep-data/rawdata/sub-01/ses-00/anat/sub-01_ses-00_T1w.nii.gz,/tmp/brainprep-data/rawdata/sub-01/ses-00/func/sub-01_ses-00_task-ArchiStandard_dir-pa_bold.nii.gz,/tmp/brainprep-data/rawdata/sub-01/ses-00/dwi/sub-01_ses-00_dwi.nii.gz',
'--output-dir',
'/tmp/brainprep-qa',
'--keep-intermediate'],
['brainprep',
'subject-level-qa',
'--image-files',
'/tmp/brainprep-data/rawdata/sub-02/ses-00/anat/sub-02_ses-00_T1w.nii.gz,/tmp/brainprep-data/rawdata/sub-02/ses-00/func/sub-02_ses-00_task-ArchiStandard_dir-pa_bold.nii.gz,/tmp/brainprep-data/rawdata/sub-02/ses-00/dwi/sub-02_ses-00_dwi.nii.gz',
'--output-dir',
'/tmp/brainprep-qa',
'--keep-intermediate']],
[['brainprep',
'group-level-qa',
'--modalities',
'T1w,bold,dwi',
'--output-dir',
'/tmp/brainprep-qa']]]
Container¶
Note that the commands generated by the CLI are not limited to being displayed for reference; they can also be executed directly within the workflow‑dedicated container. By running the commands inside the container, you benefit from a controlled runtime context where all necessary dependencies, libraries, and configuration files are already available. In practice, this means that once the CLI has produced the appropriate instructions, you can simply copy and run them inside the container to achieve the intended results. You can find the BrainPrep images on Docker Hub: Neurospin Docker Hub.
Total running time of the script: (0 minutes 16.986 seconds)
Estimated memory usage: 405 MB