Usage

The QSIPrep preprocessing workflow takes as principal input the path of the dataset that is to be processed. The input dataset is required to be in valid BIDS format at least one diffusion MRI series. The T1w image and the DWI may be in separate BIDS <session> folders for a given subject. We highly recommend that you validate your dataset with the free, online BIDS Validator.

The exact command to run QSIPrep depends on the Installation method. The common parts of the command are similar to the BIDS-Apps definition.

Example:

qsiprep data/bids_root/ out/ participant -w work/ --output-resolution 2

Command-Line Arguments

QSIPrep v26.0.0: q-Space Image Preprocessing workflows

usage: qsiprep [-h] [--skip-bids-validation]
               [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
               [--session-id SESSION_ID [SESSION_ID ...]]
               [--bids-filter-file FILE] [--bids-database-dir PATH]
               [--nprocs NPROCS] [--omp-nthreads OMP_NTHREADS]
               [--mem MEMORY_MB] [--low-mem] [--use-plugin FILE] [--sloppy]
               [--anat-only] [--dwi-only] [--boilerplate-only]
               [--reports-only]
               [--ignore {fieldmaps,t2w,phase} [{fieldmaps,t2w,phase} ...]]
               [--infant] [--longitudinal]
               [--subject-anatomical-reference {first-lex,unbiased,sessionwise,first-alphabetically}]
               [--skip-anat-based-spatial-normalization]
               [--anat-modality {T1w,T2w,none}] [--b0-threshold B0_THRESHOLD]
               [--dwi-denoise-window DWI_DENOISE_WINDOW]
               [--denoise-method {dwidenoise,patch2self,none}]
               [--unringing-method {none,mrdegibbs,rpg}] [--dwi-no-biascorr]
               [--b1-biascorrect-stage {final,none,legacy}]
               [--no-b0-harmonization] [--denoise-after-combining]
               [--separate-all-dwis]
               [--distortion-group-merge {concat,average,none}]
               [--anatomical-template {MNI152NLin2009cAsym}]
               --output-resolution OUTPUT_RESOLUTION
               [--b0-to-t1w-transform {Rigid,Affine}]
               [--intramodal-template-iters INTRAMODAL_TEMPLATE_ITERS]
               [--intramodal-template-transform {Rigid,Affine,BSplineSyN,SyN}]
               [--fs-license-file PATH]
               [--b0-motion-corr-to {iterative,first}]
               [--hmc-transform {Affine,Rigid}]
               [--hmc-model {none,3dSHORE,eddy,tensor}]
               [--eddy-config EDDY_CONFIG] [--shoreline-iters SHORELINE_ITERS]
               [--pepolar-method {TOPUP,DRBUDDI,TOPUP+DRBUDDI}]
               [--fmap-bspline] [--fmap-no-demean]
               [--use-syn-sdc [{warn,error}]] [--force-syn] [--version] [-v]
               [-w WORK_DIR] [--resource-monitor] [--config-file FILE]
               [--write-graph] [--stop-on-first-crash] [--notrack]
               [--debug {fieldmaps,pdb,all} [{fieldmaps,pdb,all} ...]]
               bids_dir output_dir {participant}

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 output path for the outcomes of preprocessing and visual reports

analysis_level

Possible choices: participant

Processing stage to be run, only “participant” in the case of QSIPrep (for now).

Options for filtering BIDS queries

--skip-bids-validation

Assume the input dataset is BIDS compliant and skip the validation

Default: False

--participant-label

A space delimited list of participant identifiers or a single identifier (the sub- prefix can be removed)

--session-id

A space delimited list of session identifiers or a single identifier (the ses- prefix can be removed)

--bids-filter-file

A JSON file describing custom BIDS input filters using PyBIDS. For further details, please check out https://fmriprep.readthedocs.io/en/26.0.0/faq.html#how-do-I-select-only-certain-files-to-be-input-to-fMRIPrep

--bids-database-dir

Path to a PyBIDS database folder, for faster indexing (especially useful for large datasets). Will be created if not present.

Options to handle performance

--nprocs, --nthreads, --n-cpus

Maximum number of threads across all processes

--omp-nthreads

Maximum number of threads per-process

--mem, --mem-mb

Upper bound memory limit for QSIPrep processes

--low-mem

Attempt to reduce memory usage (will increase disk usage in working directory)

Default: False

--use-plugin, --nipype-plugin-file

Nipype plugin configuration file

--sloppy

Use low-quality tools for speed - TESTING ONLY

Default: False

Options for performing only a subset of the workflow

--anat-only

Run anatomical workflows only

Default: False

--dwi-only

ignore anatomical (T1w/T2w) data and process DWIs only

Default: False

--boilerplate-only, --boilerplate

Generate boilerplate only

Default: False

--reports-only

Only generate reports, don’t run workflows. This will only rerun report aggregation, not reportlet generation for specific nodes.

Default: False

Workflow configuration

--ignore

Possible choices: fieldmaps, t2w, phase

Ignore selected aspects of the input dataset to disable corresponding parts of the workflow (a space delimited list)

Default: []

--infant

Configure pipelines to process infant brains. If using this parameter, the anatomical-template will be changed to MNIInfant. The appropriate MNIInfant cohort will be selected based on the participant’s age.

Default: False

--longitudinal

Treat dataset as longitudinal - may increase runtime

--subject-anatomical-reference

Possible choices: first-lex, unbiased, sessionwise, first-alphabetically

How to define subject-specific anatomical space. sessionwise will produce one anatomical space per session. The others combine anatomical data across sessions to define one anatomical space per subject. The “first-alphabetically” option is deprecated in favor of “first-lex”.

Default: 'first-lex'

--skip-anat-based-spatial-normalization

skip running the anat-based normalization to template space. Default is to run the normalization.

Default: False

--anat-modality

Possible choices: T1w, T2w, none

Modality to use as the anatomical reference. Images of this contrast will be skull stripped and segmented for use in the visual reports. If –infant, T2w is forced.

Default: 'T1w'

--b0-threshold

any value in the .bval file less than this will be considered a b=0 image. Current default threshold = 100; this threshold can be lowered or increased. Note, setting this too high can result in inaccurate results.

Default: 100

--dwi-denoise-window

Window size in voxels for image-based denoising: odd integer or “auto”. Any non-“auto” value must be an odd, positive integer. If using the “dwidenoise” denoising method, the “auto” option will calculate a window size based on the number of volumes according to the method described by the dwidenoise documentation. If using the “patch2self” denoising method, this argument will not be used.

Default: auto

--denoise-method

Possible choices: dwidenoise, patch2self, none

Image-based denoising method. Either “dwidenoise” (MRtrix), “patch2self” (DIPY) or “none”. (default: dwidenoise)

Default: 'dwidenoise'

--unringing-method

Possible choices: none, mrdegibbs, rpg

Method for Gibbs-ringing removal.

none: no action
mrdegibbs: use mrdegibbs from mrtrix3
rpg: Gibbs from TORTOISE, suggested for partial Fourier acquisitions (default: none).

--dwi-no-biascorr

DEPRECATED: see –b1-biascorrect-stage

Default: False

--b1-biascorrect-stage

Possible choices: final, none, legacy

Which stage to apply B1 bias correction. The default “final” will apply it after all the data has been resampled to its final space. “none” will skip B1 bias correction and “legacy” will behave consistent with qsiprep < 0.17. For prescan-normalized data, we recommend using “none”, as bias correction may introduce artifacts on normalized data.

Default: 'final'

--no-b0-harmonization

skip re-scaling dwi scans to have matching b=0 intensities

Default: False

--denoise-after-combining

run dwidenoise after combining dwis, but before motion correction

Default: False

--separate-all-dwis

don’t attempt to combine dwis from multiple runs. Each will be processed separately.

Default: False

--distortion-group-merge

Possible choices: concat, average, none

How to combine images across distorted groups.

concat: append images in the 4th dimension
average: if a whole sequence was duplicated in both PE
directions, average the corrected images of the same q-space coordinate
none: Default. Keep distorted groups separate

Default: 'none'

--anatomical-template

Possible choices: MNI152NLin2009cAsym

volume template space (default: MNI152NLin2009cAsym)

Default: 'MNI152NLin2009cAsym'

--output-resolution

the isotropic voxel size in mm the data will be resampled to after preprocessing. If set to a lower value than the original voxel size, your data will be upsampled using BSpline interpolation.

Options for dwi-to-Anatomical coregistration

--b0-to-t1w-transform

Possible choices: Rigid, Affine

Degrees of freedom when registering b0 to anatomical images. 6 degrees (rotation and translation) are used by default.

Default: 'Rigid'

--intramodal-template-iters

Number of iterations for finding the midpoint image from the b0 templates from all groups. Has no effect if there is only one group. If 0, all b0 templates are directly registered to the t1w image.

Default: 0

--intramodal-template-transform

Possible choices: Rigid, Affine, BSplineSyN, SyN

Transformation used for building the intramodal template.

Default: 'BSplineSyN'

Specific options for FreeSurfer preprocessing

--fs-license-file: Path to FreeSurfer license key file. Get it (for free) by registering at https://surfer.nmr.mgh.harvard.edu/registration.html

Specific options for motion correction and coregistration

--b0-motion-corr-to

Possible choices: iterative, first

align to the “first” b0 volume or do an “iterative” registration of all b0 images to their midpoint image (default: iterative)

Default: 'iterative'

--hmc-transform

Possible choices: Affine, Rigid

transformation to be optimized during head motion correction (default: affine)

Default: 'Affine'

--hmc-model

Possible choices: none, 3dSHORE, eddy, tensor

model used to generate target images for hmc. If “none” the non-b0 images will be warped using the same transform as their nearest b0 image. If “3dSHORE”, SHORELine will be used. if “tensor”, SHORELine iterations with a tensor model will be used

Default: 'eddy'

--eddy-config

path to a json file with settings for the call to eddy. If no json is specified, a default one will be used. The current default json can be found here: https://github.com/PennLINC/qsiprep/blob/main/qsiprep/data/eddy_params.json

--shoreline-iters

number of SHORELine iterations. (default: 2)

Default: 2

Specific options for handling fieldmaps

--pepolar-method

Possible choices: TOPUP, DRBUDDI, TOPUP+DRBUDDI

select which SDC method to use for PEPOLAR fieldmaps (default: TOPUP)

Default: 'TOPUP'

--fmap-bspline

Fit a B-Spline field using least-squares (experimental)

Default: False

--fmap-no-demean

Do not remove median (within mask) from fieldmap

Default: True

Specific options for SyN distortion correction

--use-syn-sdc

Possible choices: warn, error

Use fieldmap-less distortion correction based on anatomical image; if unable, error (default) or warn based on optional argument.

Default: False

--force-syn

EXPERIMENTAL/TEMPORARY: Use SyN correction in addition to fieldmap correction, if available

Default: False

Other options

--version

show program’s version number and exit

-v, --verbose

Increases log verbosity for each occurrence, debug level is -vvv

Default: 0

-w, --work-dir

Path where intermediate results should be stored

Default: /home/docs/checkouts/readthedocs.org/user_builds/qsiprep/checkouts/26.0.0/docs/work

--resource-monitor

Enable Nipype’s resource monitoring to keep track of memory and CPU usage

Default: False

--config-file

Use pre-generated configuration file. Values in file will be overridden by command-line arguments.

--write-graph

Write workflow graph.

Default: False

--stop-on-first-crash

Force stopping on first crash, even if a work directory was specified.

Default: False

--notrack

Opt-out of sending tracking information of this run to the QSIPrep developers. This information helps to improve QSIPrep and provides an indicator of real world usage crucial for obtaining funding.

Default: False

--debug

Possible choices: fieldmaps, pdb, all

Debug mode(s) to enable. ‘all’ is alias for all available modes.

Infant mode

If --infant is used, the pipeline will select an MNIInfant template with the appropriate cohort based on the participant’s age.

--infant is only compatible with --subject-anatomical-reference sessionwise.

Note

QSIPrep’s cohort selection is derived from Nibabies.

Participant Ages

QSIPrep will attempt to automatically extract participant ages (in months) from the BIDS layout. Specifically, these two files will be checked:

Sessions file: <bids-root>/<subject>/<subject>_sessions.tsv

Participants file: <bids-root>/participants.tsv

Either file should include age (or if you wish to be more explicit: age_months) columns, and it is recommended to have an accompanying JSON file to further describe these fields, and explicitly state the values are in months.

Preparing data for QSIPrep

QSIPrep is a BIDS App, meaning that it expects the data to be in BIDS format. However, QSIPrep does contain some idiosyncrasies that mean that the data may need to be prepared in a specific way.

Siemens Reverse Phase-Encoded “Field Maps”

Reverse phase-encoded images are a common acquisition for distortion correction. For a dMRI scan, this would mean acquiring one or more volumes of b=0 images with the opposite phase encoding direction of the main dMRI scan.

It can be hard to acquire a scan that only contains b=0 volumes with Siemens scanners, so researchers often acquire a short dMRI run with a mix of b=0 and b>0 volumes. QSIPrep expects these short scans to be in the fmap directory, instead of the dwi directory. If you acquire data like this, you should organize your data as below:

sub-<label>/
    ses-<label>/
        dwi/
            sub-<label>_ses-<label>_dir-AP_dwi.nii.gz
            sub-<label>_ses-<label>_dir-AP_dwi.bval
            sub-<label>_ses-<label>_dir-AP_dwi.bvec
            sub-<label>_ses-<label>_dir-AP_dwi.json
        fmap/
            sub-<label>_ses-<label>_dir-PA_epi.nii.gz
            sub-<label>_ses-<label>_dir-PA_epi.bval
            sub-<label>_ses-<label>_dir-PA_epi.bvec
            sub-<label>_ses-<label>_dir-PA_epi.json  # Add IntendedFor field here

In this scenario, the short scan is organized as a field map, with the epi suffix. As of BIDS v1.10.0, EPI field maps can have bval and bvec files, so this organization is completely BIDS-compliant.

If you organize your short scan as a dMRI run, QSIPrep will denoise the short scan and concatenate it with the longer run, which is not optimal.

Moreover, if you have a short scan with a mix of b=0 and b>0 volumes, and you do not include the bval and bvec files, QSIPrep will assume that all of the volumes are b=0, which will almost certainly produce suboptimal results.

Complex-Valued Data

If you acquire complex-valued data, you should (1) split the data into magnitude and phase files (NOT real and imaginary!) and (2) retain a copy of the bval and bvec files with the part-mag entity included (i.e., do not use the inheritance principle on these files).

QSIPrep is not compatible with real and imaginary data.

Also, QSIPrep does not currently support using the inheritance principle for bval and bvec files. While this is not normally a problem, since these files should not be inherited, it would make sense from a BIDS readability perspective to inherit the bvals and bvecs across both the magnitude and phase files. For example, the following organization would be perfectly BIDS-compliant:

sub-<label>/
    ses-<label>/
        dwi/
            sub-<label>_ses-<label>_dwi.bval
            sub-<label>_ses-<label>_dwi.bvec
            sub-<label>_ses-<label>_part-mag_dwi.nii.gz
            sub-<label>_ses-<label>_part-mag_dwi.json
            sub-<label>_ses-<label>_part-phase_dwi.nii.gz
            sub-<label>_ses-<label>_part-phase_dwi.json

The inheritance principle ensures that the bvals and bvecs without the part entity apply to both the magnitude and phase files.

Unfortunately, if you do this, QSIPrep will not be able to find the bvec and bval files. Therefore, you should organize your data as below, to make sure QSIPrep will work:

sub-<label>/
    ses-<label>/
        dwi/
            sub-<label>_ses-<label>_part-mag_dwi.nii.gz
            sub-<label>_ses-<label>_part-mag_dwi.bval
            sub-<label>_ses-<label>_part-mag_dwi.bvec
            sub-<label>_ses-<label>_part-mag_dwi.json
            sub-<label>_ses-<label>_part-phase_dwi.nii.gz
            sub-<label>_ses-<label>_part-phase_dwi.bval
            sub-<label>_ses-<label>_part-phase_dwi.bvec
            sub-<label>_ses-<label>_part-phase_dwi.json

BIDS-URIs

BIDS-URIs are the recommended way to defined certain metadata fields, such as IntendedFor, in BIDS. However, QSIPrep does not currently support BIDS-URIs for the IntendedFor field. Therefore, you should use relative paths to the files, which is the older way to do things.

B0FieldIdentifier and B0FieldSource

B0FieldIdentifier and B0FieldSource are two metadata fields that are used to related images to field maps for distortion correction. They are the preferred alternative to the IntendedFor field in BIDS, but QSIPrep does not currently support them. Therefore, you should use the IntendedFor field with relative paths to the files, which is the older way to do things.

MultipartID

MultipartID is a metadata field that is used to identify a set of DWIs that should be considered as part of the same acquisition. If you want to group certain runs of dMRI data together, but not all runs (the default behavior), you should use the MultipartID field.

However, please note that MultipartID may interact in unexpected ways with the IntendedFor field and the QSIPrep parameters that impact grouping (e.g., --distortion-group-merge). Therefore, we recommend that, if you use MultipartID, you check your outputs to make sure the runs are being grouped in the manner you expect.

Note on using CUDA

The CUDA runtime version 11.1.1 is included in the QSIPrep docker image. The CUDA version of eddy is dramatically faster than the openmp version. Information on running Docker with CUDA enabled can be found on dockerhub. If running with Apptainer, the call to Apptainer should include --nv. To enable CUDA, see Configuring eddy.

Debugging

Logs and crashfiles are outputted into the <output dir>/qsiprep/sub-<participant_label>/log directory. Information on how to customize and understand these files can be found on the nipype debugging page.