Running MRIQC

This page describes MRIQC itself, independent of any particular computer. For submitting it as a batch job on the SCC, see Running MRIQC on the SCC.

The options below are those of MRIQC 24.0.0. Options change between releases, so check your own version with:

[scc4]$ mriqc --help

The Basic Call

MRIQC takes three positional arguments, always in this order:

[scc4]$ mriqc <bids_dir> <output_dir> <analysis_level>

Argument	Meaning
`bids_dir`	Root of a BIDS-valid dataset — the directory holding the `sub-*` folders.
`output_dir`	Where reports and metrics are written. Created if it does not exist.
`analysis_level`	`participant`, `group`, or both.

A minimal run over a whole dataset:

[scc4]$ mriqc /data/bids /data/bids/derivatives/mriqc participant

Everything else is optional. In practice you will always want to set at least the performance options, because their defaults are unsafe on a shared machine — see Controlling Resources.

The Two Analysis Levels

MRIQC runs in two passes, and you need both to get the full picture.

participant does the real work: it computes the image quality metrics (IQMs) for each scan and writes one self-contained HTML report per scan, plus a .json file of that scan's IQMs. This is the expensive step. Participant runs are independent, so you can process subjects in any order, or several at once in parallel, as long as they all write to the same output_dir.

group is cheap. It reads the .json files already sitting in output_dir and pools them into one summary report and one .tsv table per modality, letting you see each scan's metrics against the rest of the sample. It has nothing to do until the participant level has finished, so run it last.

You can pass both levels in one command, which is convenient for a small dataset processed on one machine. For anything larger you will run participant as many parallel jobs and then group once, on its own, afterwards.

Choosing What Gets Processed

By default MRIQC processes every subject and every T1w, T2w, BOLD and DWI image it finds. These options narrow that down.

Option	What it does	When to use it
`--participant-label LABEL`	Process only the named subjects. The `sub-` prefix is optional.	Testing on one subject before committing to the whole study; re-running the few that failed; splitting a dataset across parallel jobs.
`--session-id ID`	Keep only these sessions.	Longitudinal studies where you only care about one timepoint.
`--task-id ID`	Keep only these functional tasks.	A dataset with several tasks when you only need QC on one.
`-m`, `--modalities {T1w,T2w,bold,dwi}`	Keep only these image types. Defaults to all four.	You only collected some of them, or you want anatomical QC now and functional QC later.
`--bids-filter-file PATH`	A JSON file expressing an arbitrary PyBIDS query.	Selection the flags above cannot express — a specific acquisition or run. This also replaces the deprecated `--run-id`.

Controlling Resources

Set these explicitly. Left alone, --nprocs and --omp-nthreads grab as many CPUs as the machine appears to have, which on a shared or scheduled system means MRIQC will happily use cores that were never allocated to it. MRIQC's own help text flags this.

Option	What it does	When to change it
`--nprocs N`	Total CPUs MRIQC may use across all the processes it runs at once.	Always. Match it to the cores you were actually given.
`--omp-nthreads N`	Maximum threads any single multi-threaded process (e.g. ANTs registration) may use.	Always. See the interaction below.
`--mem GB`	Upper bound on memory MRIQC will allow itself.	Whenever the machine or scheduler imposes a memory limit — this makes MRIQC throttle itself instead of being killed.
`--work-dir PATH`	Where intermediate files go. Defaults to `work/` under your current directory.	Almost always; see below.
`--float32`	Cast higher-precision input to float32. On by default.	Rarely — turn it off only if you specifically need full input precision.

The two thread options interact, and the interaction is the part people get wrong. --nprocs is the total budget; --omp-nthreads is the per-process cap. MRIQC fits as many processes as the budget allows:

--nprocs 16 --omp-nthreads 8 → two 8-thread processes at a time.
--nprocs 16 --omp-nthreads 1 → sixteen single-threaded processes.

More processes finishes a many-subject dataset sooner; more threads per process finishes an individual scan sooner. With several subjects to get through, favour more processes.

The Work Directory

--work-dir is worth setting deliberately. The default (./work) puts potentially large intermediate files wherever you happened to be standing when you typed the command.

Point it at fast, temporary storage with room to spare. Keep it if a run fails and you want to inspect or resume it; delete it once the reports look right, since MRIQC does not clean up after itself.

By default, MRIQC uploads your anonymized IQMs to a public metrics repository. This is intentional on MRIQC's part — the repository is a research resource — but it is a network transfer of data derived from your scans, so it is your decision to make rather than one to discover later.

Option	What it does
`--no-sub`	Turn the upload off.
`--email ADDRESS`	Attach an email address to the submission.
`--notrack`	Separately opt out of usage telemetry sent to the NiPreps developers.

If your data are governed by an IRB protocol or data-use agreement that does not contemplate this, pass --no-sub. MRIQC's Data Sharing Agreement describes exactly what is sent. The example script in Running MRIQC on the SCC passes --no-sub.

Modality-Specific Tuning

Defaults are sensible; reach for these when your data are unusual.

Functional (BOLD):

Option	Default	Purpose
`--fd_thres MM`	`0.2`	Framewise-displacement threshold above which a volume counts as an outlier. Raise it for populations that simply move more, so the reported outlier fraction stays informative rather than saturated.
`--min-bold-length N`	`5`	Skip runs with fewer time points. Lower it to QC very short runs that would otherwise be dropped silently.

Diffusion (DWI): --min-dwi-length N (default 7) drops runs with fewer gradient orientations than this.

Registration: --ants-float uses single-precision in ANTs, and --ants-settings PATH supplies your own ANTs parameters. Both are for unusual cases only.

Non-human data: --species rat selects a rat template instead of the human default.

This is not an exhaustive list. MRIQC exposes further tuning options for unusual data and workflows — see the MRIQC documentation for the full set, or run mriqc --help.