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/

Command-Line Arguments

QSIPrep v1.0.2.dev2+g00c73c4: 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,sbref,t2w,flair,fmap-jacobian,phase} [{fieldmaps,sbref,t2w,flair,fmap-jacobian,phase} ...]]
               [--infant] [--longitudinal LONGITUDINAL]
               [--subject-anatomical-reference {first-alphabetically,unbiased,sessionwise}]
               [--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
--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/latest/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)
--use-plugin, --nipype-plugin-file: Nipype plugin configuration file
--sloppy: Use low-quality tools for speed - TESTING ONLY

Options for performing only a subset of the workflow

--anat-only: Run anatomical workflows only
--dwi-only: ignore anatomical (T1w/T2w) data and process DWIs only
--boilerplate-only, --boilerplate: Generate boilerplate only
--reports-only: Only generate reports, don’t run workflows. This will only rerun report aggregation, not reportlet generation for specific nodes.

Workflow configuration

--ignore

Possible choices: fieldmaps, sbref, t2w, flair, fmap-jacobian, phase

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

--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.

--longitudinal

Treat dataset as longitudinal - may increase runtime

--subject-anatomical-reference

Possible choices: first-alphabetically, unbiased, sessionwise

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.

--skip-anat-based-spatial-normalization

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

--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.

--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.

--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.

--denoise-method

Possible choices: dwidenoise, patch2self, none

Image-based denoising method. Either “dwidenoise” (MRtrix), “patch2self” (DIPY) or “none”. (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

--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.

--no-b0-harmonization

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

--denoise-after-combining

run dwidenoise after combining dwis, but before motion correction

--separate-all-dwis

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

--distortion-group-merge

Possible choices: concat, average, none

How to combine images across distorted groups.

concatenate: 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

--anatomical-template

Possible choices: MNI152NLin2009cAsym

volume template space (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.

--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.

--intramodal-template-transform

Possible choices: Rigid, Affine, BSplineSyN, SyN

Transformation used for building the intramodal template.

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)

--hmc-transform

Possible choices: Affine, Rigid

transformation to be optimized during head motion correction (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

--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/master/qsiprep/data/eddy_params.json

--shoreline-iters

number of SHORELine iterations. (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)

--fmap-bspline

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

--fmap-no-demean

Do not remove median (within mask) from fieldmap

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.

--force-syn

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

Other options

--version

show program’s version number and exit

-v, --verbose

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

-w, --work-dir

Path where intermediate results should be stored

--resource-monitor

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

--config-file

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

--write-graph

Write workflow graph.

--stop-on-first-crash

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

--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.

--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.

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.