Running mriqc

Tip

Try MRIQC online on OpenNeuro - without installation!

MRIQC is a BIDS-App [BIDSApps], and therefore it inherently understands the BIDS standard [BIDS] and follows the BIDS-Apps standard command line interface:

mriqc bids-root/ output-folder/ participant

That simple command runs MRIQC on all the T1w and BOLD images found under the BIDS-compliant folder bids-root/. The last participant keyword indicates that the first level analysis is run. (i.e. extracting the IQMs from the images retrieved within bids-root/). The second level (group) is automatically run if no particular subject is provided for analysis.

Note

If the argument --participant-label is not provided, then all subjects will be processed and the group level analysis will automatically be executed without need of running the command in item 3.

To specify one particular subject, the --participant-label argument can be used:

mriqc bids-root/ output-folder/ participant --participant-label S01 S02 S03

That command will run MRIQC only on the subjects indicated: only bids-root/sub-S01, bids-root/sub-S02, and bids-root/sub-S03 will be processed. In this case, the group level will not be triggered automatically. We generate the group level results (the group level report and the features CSV table) with:

mriqc bids-root/ output-folder/ group

Examples of the generated visual reports are found in The MRIQC Reports.

Warning

MRIQC by default attempts to upload anonymized quality metrics to a publicly accessible web server (mriqc.nimh.nih.gov). The uploaded data consists only of calculated quality metrics and scanning parameters. It removes all personal health information and participant identifiers. We try to collect this data to build normal distributions for improved outlier detection, but if you do not wish to participate you can disable the submission with the --no-sub flag.

BIDS data organization

The software automatically finds the data the input folder if it follows the BIDS standard [BIDS]. A fast and easy way to check that your dataset fulfills the BIDS standard is the BIDS validator.

BIDS-App levels

In the participant level, all individual images to be processed are run through the pipeline, and the MRIQC measures are extracted and the individual reports (see The MRIQC Reports) generated. In the group level, the IQMs extracted in first place are combined in a table and the group reports are generated.

Command line interface

MRIQC: MRI Quality Control

usage: mriqc [-h] [--version]
             [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
             [--session-id SESSION_ID [SESSION_ID ...]]
             [--run-id RUN_ID [RUN_ID ...]] [--task-id TASK_ID [TASK_ID ...]]
             [-m [{T1w,bold,T2w} [{T1w,bold,T2w} ...]]] [-w WORK_DIR]
             [--report-dir REPORT_DIR] [--verbose-reports] [--write-graph]
             [--dry-run] [--profile] [--use-plugin USE_PLUGIN] [--no-sub]
             [--email EMAIL] [-v] [--webapi-url WEBAPI_URL]
             [--webapi-port WEBAPI_PORT] [--upload-strict] [--n_procs N_PROCS]
             [--mem_gb MEM_GB] [--testing] [-f] [--ica] [--hmc-afni]
             [--hmc-fsl] [--fft-spikes-detector] [--fd_thres FD_THRES]
             [--ants-nthreads ANTS_NTHREADS] [--ants-settings ANTS_SETTINGS]
             [--deoblique] [--despike] [--start-idx START_IDX]
             [--stop-idx STOP_IDX] [--correct-slice-timing]
             bids_dir output_dir {participant,group} [{participant,group} ...]

Positional Arguments

bids_dir The directory with the input dataset formatted according to the BIDS standard.
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 theparticipant 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.

Named Arguments

–version show program’s version number and exit

Options for filtering BIDS queries

–participant_label, –participant-label
 one or more participant identifiers (the sub- prefix can be removed)
–session-id select a specific session to be processed
–run-id select a specific run to be processed
–task-id select a specific task to be processed
-m, –modalities
 

Possible choices: T1w, bold, T2w

select one of the supported MRI types

Instrumental options

-w, –work-dir
–report-dir
–verbose-reports
 
–write-graph Write workflow graph.
–dry-run Do not run the workflow.
–profile hook up the resource profiler callback to nipype
–use-plugin nipype plugin configuration file
–no-sub Turn off submission of anonymized quality metrics to MRIQC’s metrics repository.
–email Email address to include with quality metric submission.
-v, –verbose increases log verbosity for each occurence, debug level is -vvv
–webapi-url IP address where the MRIQC WebAPI is listening
–webapi-port port where the MRIQC WebAPI is listening
–upload-strict
 upload will fail if if upload is strict

Options to handle performance

–n_procs, –nprocs, –n_cpus, –nprocs
 number of threads
–mem_gb available total memory
–testing use testing settings for a minimal footprint
-f, –float32 Cast the input data to float32 if it’s represented in higher precision (saves space and improves perfomance)

Workflow configuration

–ica Run ICA on the raw data and include the componentsin the individual reports (slow but potentially very insightful)
–hmc-afni Use ANFI 3dvolreg for head motion correction (HMC) - default
–hmc-fsl Use FSL MCFLIRT instead of AFNI for head motion correction (HMC)
–fft-spikes-detector
 Turn on FFT based spike detector (slow).
–fd_thres motion threshold for FD computation

Specific settings for ANTs

–ants-nthreads
 number of threads that will be set in ANTs processes
–ants-settings
 path to JSON file with settings for ANTS

Specific settings for AFNI

–deoblique Deoblique the functional scans during head motion correction preprocessing
–despike Despike the functional scans during head motion correction preprocessing
–start-idx Initial volume in functional timeseries that should be considered for preprocessing
–stop-idx Final volume in functional timeseries that should be considered for preprocessing
–correct-slice-timing
 Perform slice timing correction

Running MRIQC on HPC clusters

Singularity containers

Requesting resources

We have profiled cores and memory usages with the resource profiler tool of nipype.

An MRIQC run of one subject (from the ABIDE) dataset, containing only one run, one BOLD task (resting-state) yielded the following report:

Using the MultiProc plugin of nipype with nprocs=10, the workflow nodes run across the available processors for 41.68 minutes. A memory peak of 8GB is reached by the end of the runtime, when the plotting nodes are fired up.

We also profiled MRIQC on a dataset with 8 tasks (one run per task), on ds030 of OpenfMRI:

Again, we used n_procs=10. The software run for roughly about the same time (47.11 min). Most of the run time, memory usage keeps around a maximum of 10GB. Since we saw a memory consumption of 1-2GB during the the 1-task example, a rule of thumb may be that each task takes around 1GB of memory.