Command-line reference

The options are explained by decision on the Running QSIPrep page. This is the full qsiprep --help text. Options that take a list (--ignore, --force, --gpu, --participant-label, --session-label, --debug) take space-separated values. --config-file loads the settings of an earlier run, and any option given on the command line overrides it.

QSIPrep v26.2.0.dev12+gff4f8cdf9: q-Space Image Preprocessing workflows

usage: qsiprep --output-resolution MM [--participant-label LABEL [LABEL ...]]
               [--session-label LABEL [LABEL ...]] [--bids-filter-file FILE]
               [--bids-database-dir PATH] [--skip-bids-validation]
               [--boilerplate-only] [--reports-only]
               [--ignore {fieldmaps,pepolar-dwis,t2w,phase,sdc,shims,fov,gradwarp,jacobian} [{fieldmaps,pepolar-dwis,t2w,phase,sdc,shims,fov,gradwarp,jacobian} ...]]
               [--force {gradwarp1D,gradwarp3D,sdc-anat-reference,jacobian,gre-sdc-after-eddy,no-csf-synthstrip} [{gradwarp1D,gradwarp3D,sdc-anat-reference,jacobian,gre-sdc-after-eddy,no-csf-synthstrip} ...]]
               [--anat-modality {T1w,T2w,none}] [--infant]
               [--subject-anatomical-reference {first-lex,unbiased,sessionwise}]
               [--anat-biascorrect {n4,auto,none}]
               [--anatomical-template {MNI152NLin2009cAsym}]
               [--skip-anat-based-spatial-normalization] [--b0-threshold N]
               [--denoise-method {dwidenoise,dwidenoise2,patch2self,svht,none}]
               [--dwidenoise-window {auto,N}] [--denoise-config FILE]
               [--unringing-method {none,mrdegibbs,rpg,svht}]
               [--mrtrix-version {stable,dev}]
               [--dwi-biascorrect {n4,auto,none}] [--no-b0-harmonization]
               [--separate-all-dwis]
               [--distortion-group-merge {concat,average,none}]
               [--hmc-method {eddy,shoreline,tortoise}] [--eddy-config FILE]
               [--shoreline-config FILE] [--diffprep-config FILE]
               [--sdc-method {auto,topup,drbuddi,topup+drbuddi}]
               [--sdc-anat-reference {none,auto,synb0,t2w,invt1w}]
               [--gradient-file FILE]
               [--dwiref-definition {distortion-group,subject}]
               [--dwiref-construction-iters DWIREF_CONSTRUCTION_ITERS]
               [--dwiref-construction-transform {Rigid,Affine,BSplineSyN,SyN}]
               [--dwi2anat-dof {6,12}] [--nprocs N] [--omp-nthreads N]
               [--mem MEMORY_MB] [--low-mem] [--use-plugin FILE]
               [--gpu {diffprep,drbuddi,eddy,synthseg,synthstrip,all,none} [{diffprep,drbuddi,eddy,synthseg,synthstrip,all,none} ...]]
               [--tortoise-gpu-cpu-ratio N] [-w PATH]
               [--report-output-level {auto,root,subject,session}]
               [--config-file FILE] [--stop-on-first-crash]
               [--resource-monitor] [--notrack] [-v] [--sloppy]
               [--debug {fieldmaps,pdb,all} [{fieldmaps,pdb,all} ...]]
               [--write-graph] [-h] [--version]
               bids_dir output_dir {participant}

Required arguments

Every QSIPrep run needs these four. The three positional arguments follow the BIDS App convention; –output-resolution has no default and must be given explicitly.

bids_dir

The root folder of a valid BIDS dataset. The sub-<label> directories should be found at the top level of this folder.

output_dir

The output path for preprocessed derivatives and visual reports.

analysis_level

Possible choices: participant

Processing stage to run. Only “participant” is supported by QSIPrep.

--output-resolution

The isotropic voxel size in mm that the data will be resampled to after preprocessing. If this is smaller than the original voxel size, the data are upsampled using BSpline interpolation.

Input data and BIDS filtering

Select which subjects, sessions and files are read from the input dataset.

--participant-label

A space-delimited list of one or more participant identifiers. The “sub-” prefix may be omitted.

--session-label

A space-delimited list of one or more session identifiers. The “ses-” prefix may be omitted.

--bids-filter-file

A JSON file describing custom BIDS input filters using PyBIDS. For further details, see https://fmriprep.org/en/stable/faq.html#how-do-i-select-only-certain-files-to-be-input-to-fmriprep

--bids-database-dir

Path to a PyBIDS database directory, for faster indexing. This is especially useful for large datasets. The directory is created if it does not already exist.

--skip-bids-validation

Assume the input dataset is BIDS-compliant and skip validation.

Default: False

Workflow scope

Run only part of the workflow, or turn individual corrections on and off. –ignore disables processing that the input data would otherwise trigger; –force enables processing that the input metadata would otherwise skip.

--boilerplate-only, --boilerplate

Generate the boilerplate methods text and exit without running the workflow.

Default: False

--reports-only

Only generate reports; don’t run the workflows. This reruns report aggregation only, not reportlet generation for individual nodes.

Default: False

--ignore

Possible choices: fieldmaps, pepolar-dwis, t2w, phase, sdc, shims, fov, gradwarp, jacobian

Ignore selected aspects of the input dataset to disable the corresponding parts of the workflow (a space-delimited list). “fieldmaps” skips the fmap/ directory, but reverse phase-encoded DWI runs still drive susceptibility distortion correction. “pepolar-dwis” stops pairing DWI series with each other to estimate a PEPOLAR fieldmap (curated or inferred); those series are still processed, corrected by a fieldmap they are linked to, a fieldmap-less method, or not at all. “t2w” drops T2w images from the workflow entirely, including T2w-based susceptibility distortion correction. “phase” ignores phase images, so DWI series are denoised as magnitude-only data. “sdc” disables susceptibility distortion correction entirely (fieldmaps, reverse phase-encoded runs, and fieldmap-less methods are all switched off). “shims” treats all ShimSetting values as compatible when grouping series. “fov” concatenates series with differently-oriented fields of view anyway, in which case distortion corrections will be misapplied. “gradwarp” disables gradient nonlinearity correction entirely, including the voxelwise gradient deviation map. “jacobian” disables the Jacobian intensity modulation QSIPrep itself applies for gradient-nonlinearity, susceptibility and eddy-current distortion corrections. It does not affect FSL eddy’s internal modulation, which eddy applies whenever its resampling method is “jac” (the default; see –eddy-config).

Default: []

--force

Possible choices: gradwarp1D, gradwarp3D, sdc-anat-reference, jacobian, gre-sdc-after-eddy, no-csf-synthstrip

Force selected corrections on, overriding what the input metadata implies (a space-delimited list). “gradwarp3D” applies the full 3D gradient nonlinearity correction, and “gradwarp1D” the through-plane component of it only, to every DWI run regardless of the ImageType field, for data whose DIS2D/DIS3D tags are absent or untrustworthy. The two are mutually exclusive, and either requires –gradient-file. “sdc-anat-reference” escalates –sdc-anat-reference from a fallback to an override, so that the selected anatomical reference replaces fieldmap application for every DWI series. It requires an –sdc-anat-reference other than “none”. “jacobian” applies Jacobian intensity modulation to the fieldmap-less TORTOISE T2Wreg (EPIREG) correction as well. TORTOISE leaves that field unmodulated because its final registration stage is not restricted to the phase-encoding direction; forcing it uses the phase-encoding component of the field only. “gre-sdc-after-eddy” applies a GRE fieldmap after eddy, as QSIPrep used to, instead of handing it to eddy (–field), for comparing the two on real data. It requires –hmc-method eddy, is deprecated, and will be removed in a future release. “no-csf-synthstrip” restricts the nonlinear registration to the template with a SynthStrip –no-csf brain mask, which excludes CSF and dura at the brain border, for brains (e.g. with atrophy) where the default mask is looser than the template mask. Saved brain masks are unaffected.

Default: []

Anatomical processing

Processing of the T1w/T2w images that define the subject’s anatomical space.

--anat-modality

Possible choices: T1w, T2w, none

Modality to use as the anatomical reference. Images of this contrast are skull-stripped and segmented for use in the visual reports. T2w is forced when –infant is given.

Default: 'T1w'

--infant

Configure the pipelines to process infant brains. This changes the anatomical template to MNIInfant, and the appropriate MNIInfant cohort is selected from the participant’s age.

Default: False

--subject-anatomical-reference

Possible choices: first-lex, unbiased, sessionwise

How to define the subject-specific anatomical space. “sessionwise” produces one anatomical space per session. The others combine anatomical data across sessions to define a single anatomical space per subject.

Default: 'first-lex'

--anat-biascorrect

Possible choices: n4, auto, none

Whether to run N4 bias field correction on ANATOMICAL images. Note this is separate from –dwi-biascorrect, which only governs the DWIs. “n4” (default) always runs it; scanner-side intensity normalization (e.g. Siemens NORM) does not necessarily remove the need for it. “none” never runs it. “auto” skips it when the BIDS ImageType metadata contains “NORM”, which is how Siemens and others flag console-applied normalization.

Default: 'n4'

--anatomical-template

Possible choices: MNI152NLin2009cAsym

The standard-space template that anatomical images are normalized to. MNI152NLin2009cAsym is currently the only supported value. –infant overrides this with the appropriate MNIInfant cohort.

Default: 'MNI152NLin2009cAsym'

--skip-anat-based-spatial-normalization

Skip the anatomical-based normalization to template space. The normalization runs otherwise.

Default: False

DWI preprocessing

Per-series denoising, Gibbs-ringing removal and intensity correction, applied before head motion correction.

--b0-threshold

Any value in the .bval file below this threshold is treated as a b=0 image. Note that setting it too high degrades the preprocessing.

Default: 100

--denoise-method

Possible choices: dwidenoise, dwidenoise2, patch2self, svht, none

Image-based denoising method: “dwidenoise” (MRtrix3), “dwidenoise2”, “patch2self” (DIPY), “svht” (svht_denoise), or “none”. dwidenoise and dwidenoise2 are restricted to non-commercial use; svht is not. Settings for dwidenoise2 and svht are given with –denoise-config.

Default: 'dwidenoise'

--dwidenoise-window

Window size in voxels for image-based denoising: either an odd positive integer or “auto”. This applies to the “dwidenoise” method only, where “auto” calculates a window size from the number of volumes, following the method described in the dwidenoise documentation. It is unused by “patch2self”, “dwidenoise2” and “svht”; dwidenoise2 sizes its patches per iteration from its multi-resolution schedule, and svht takes its patch size from “extent”, both of which can be set with –denoise-config instead.

Default: auto

--denoise-config

Path to a JSON file with settings for the denoiser selected by –denoise-method, which must be dwidenoise2 or svht. Every key is optional, and unknown keys are an error. For dwidenoise2, keys other than “schedule” set the dwidenoise2 option of the same name (for example “demodulate”, “decomposition”, “estimator” or “noise_in”; “filter_method” sets -filter). “schedule” is a list of noise estimation iterations, each a JSON object whose keys are dwidenoise2 schedule columns (for example “spatial_subsample”, “kernel” and “update_noise”), or the name of a bundled schedule (“default”, “legacy” or “vlarge”). Without a schedule, dwidenoise2 uses its default schedule. For svht, the keys are “demean” (“none”, the default, or “shells”, which is recommended only for shelled schemes), “extent” (the patch size), “filter_method”, “aggregator”, “aggregator_fwhm”, “shape”, “stride”, “vst”, “noise_dof” and “preserve_noise_bias”. See the documentation for every key.

--unringing-method

Possible choices: none, mrdegibbs, rpg, svht

Method for Gibbs-ringing removal. “none” takes no action. “mrdegibbs” uses mrdegibbs from MRtrix3. “rpg” uses the TORTOISE method, which is suggested for partial Fourier acquisitions. “svht” uses svht_denoise, which matches mrdegibbs on full k-space data and also removes partial Fourier ringing for 7/8 and 6/8 acquisitions phase-encoded along j, read from the PartialFourier metadata field.

Default: 'none'

--mrtrix-version

Possible choices: stable, dev

Which MRtrix3 installation to use. “stable” is a released MRtrix3. “dev” is the MRtrix3 development branch, which is required for complex-valued unringing with –unringing-method mrdegibbs. The development branch has not been through a release cycle and may contain bugs.

Default: 'stable'

--dwi-biascorrect

Possible choices: n4, auto, none

Whether to run N4 bias field correction on the DWIs, after all data has been resampled to its final space. Note this is separate from –anat-biascorrect, which only governs the anatomicals. “n4” (default) always runs it. “none” never runs it; for prescan-normalized data we recommend this, as bias correction may introduce artifacts on normalized data. “auto” skips it when the BIDS ImageType metadata of every DWI contains “NORM”, which is how Siemens and others flag console-applied normalization.

Default: 'n4'

--no-b0-harmonization

Skip rescaling the DWI series so that their b=0 intensities match.

Default: False

Grouping and concatenation of DWI series

How DWI series are combined into outputs. QSIPrep groups series that share an acquisition geometry, corrects each group, and then merges the results.

--separate-all-dwis

Don’t attempt to combine DWI series from multiple runs. Each series is processed separately.

Default: False

--distortion-group-merge

Possible choices: concat, average, none

How to combine the corrected results of an output’s correction units. “concat” appends the images along the fourth dimension. “average” averages the corrected images at the same q-space coordinate, for the case where a whole sequence was duplicated in both phase-encoding directions. “none” keeps each correction unit as its own output.

Default: 'concat'

Head motion and eddy-current correction

Correction of subject motion and eddy-current distortion. Each method takes its settings from its own JSON configuration file.

--hmc-method

Possible choices: eddy, shoreline, tortoise

Which software corrects head motion and eddy currents. “eddy” (FSL) requires a shelled sampling scheme. “shoreline” is model-based, works on arbitrary q-space sampling, is configured with –shoreline-config, and is scheduled for removal in a future major release. “tortoise” (TORTOISE DIFFPREP) performs rigid head motion and 24-parameter quadratic eddy-current correction on arbitrary sampling; see –diffprep-config.

Default: 'eddy'

--eddy-config

Path to a JSON file with settings for the call to eddy. A default is used if none is given. The current default can be found at https://github.com/PennLINC/qsiprep/blob/main/qsiprep/data/eddy_params.json

--shoreline-config

Path to a JSON file with settings for SHORELine. This is valid only with –hmc-method shoreline. Every key is optional. “model” is the signal model used to predict motion-correction targets: “3dshore” (the default), “tensor”, or “none”, which warps each non-b=0 image with the transform of its nearest b=0 image. “iters” is the number of SHORELine iterations (default: 2). “transform” is the transformation optimized during head motion correction: “Affine” (the default) or “Rigid”. Unknown keys are an error. The current defaults can be found at https://github.com/PennLINC/qsiprep/blob/main/qsiprep/data/shoreline_params.json

--diffprep-config

Path to a JSON file with settings for the call to TORTOISE DIFFPREP, used only with –hmc-method tortoise. This is also where the correction mode is chosen: “correction_mode” may be “motion” (rigid only), “quadratic” (the default) or “cubic”. A default is used if none is given. The current default can be found at https://github.com/PennLINC/qsiprep/blob/main/qsiprep/data/diffprep_params.json

Susceptibility distortion correction

Correction of susceptibility-induced geometric distortion, from fieldmaps, reverse phase-encoded series, or an anatomical reference.

--sdc-method

Possible choices: auto, topup, drbuddi, topup+drbuddi

Which tool corrects susceptibility distortion for PEPOLAR (blip-up/blip-down) data. “topup” (FSL) requires –hmc-method eddy. “drbuddi” uses TORTOISE. “topup+drbuddi” runs TOPUP followed by DRBUDDI refinement, and requires –hmc-method eddy. “auto” selects TOPUP for eddy and DRBUDDI otherwise. Non-PEPOLAR corrections (GRE fieldmaps, SyN, T2w registration) are chosen by the input data and their own flags, not by this one.

Default: 'auto'

--sdc-anat-reference

Possible choices: none, auto, synb0, t2w, invt1w

Which anatomical-derived image serves as the reference for fieldmap-less susceptibility distortion correction, applied as a fallback to DWI series that no fieldmap reaches. “synb0” generates a synthetic distortion-free b=0 from the T1w with the SynB0-DISCO U-Net. “t2w” uses the real T2w (TORTOISE T2Wreg). “invt1w” uses the inverted-contrast T1w (nipreps-style SyN prior). “auto” picks synb0 when the subject has a T1w, else t2w when it has a T2w, else nothing; “invt1w” is never picked automatically. “none” disables anatomical SDC entirely. The engine consuming the reference is governed by –sdc-method and –hmc-method and validated by the plan compiler. With –hmc-method eddy, for example, a synthetic b=0 enters TOPUP as a zero-readout-time volume, while with –hmc-method tortoise it is the DIFFPREP registration target. synb0 and invt1w require a T1w image and a PhaseEncodingDirection on the DWI series.

Default: 'none'

Gradient nonlinearity correction

Correction of gradient nonlinearity, from a scanner coefficient file or a precomputed displacement field. See also –force gradwarp1D, –force gradwarp3D and –ignore gradwarp under Workflow scope.

--gradient-file

Path to a gradient nonlinearity information file, matching the input to TORTOISE’s –grad_nonlin: a scanner coefficient file (.grad for Siemens, .dat for GE, .gc for the TORTOISE binary format) or an ITK displacement field (.nii/.nii.gz). It applies to every DWI run in the dataset. Whether the spatial correction is applied to a given run, and in which dimensions, is decided from that run’s ImageType field unless –force gradwarp1D, –force gradwarp3D or –ignore gradwarp says otherwise. The voxelwise gradient deviation map is written whenever this is given.

Coregistration to the anatomical reference

Alignment of the DWI reference to the subject’s anatomical space.

--dwiref-definition

Possible choices: distortion-group, subject

Which reference image DWI-to-anatomical coregistration targets. “distortion-group” (default) registers each distortion group’s own b=0 reference to the anatomical. “subject” builds a single midpoint template from every group’s reference, registers that once, and has every group inherit the result, which makes preprocessed data directly comparable across groups. A subject with a single distortion group uses that group’s reference as the subject dwiref, with an identity transform. “subject” cannot be combined with –subject-anatomical-reference sessionwise.

Default: 'distortion-group'

--dwiref-construction-iters

Number of iterations for building the subject-level dwiref template from the b=0 references of all DWI groups. Must be at least 2 (default: 2). Only used when –dwiref-definition is “subject” and the subject has more than one DWI group.

Default: 2

--dwiref-construction-transform

Possible choices: Rigid, Affine, BSplineSyN, SyN

Transformation used for building the subject-level dwiref template. Only used when –dwiref-definition is “subject”.

Default: 'BSplineSyN'

--dwi2anat-dof

Possible choices: 6, 12

Degrees of freedom when registering the DWI reference to the anatomical images: 6 (rigid: rotation and translation) or 12 (affine). (default: 6)

Default: 6

Resource management

CPU, memory and scheduler limits. These change how long a run takes, not what it produces.

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

Maximum number of threads across all processes.

--omp-nthreads

Maximum number of threads per process.

--mem, --mem-mb

Upper bound on the memory available to QSIPrep processes, in MB.

--low-mem

Attempt to reduce memory usage. This increases disk usage in the working directory.

Default: False

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

Path to a Nipype plugin configuration file.

GPU acceleration

Run selected tasks on the GPU. GPU builds are not numerically identical to their CPU counterparts, so these options change results, not just runtime. The GPU must also be exposed to the container (docker run –gpus all or apptainer run –nv).

--gpu

Possible choices: diffprep, drbuddi, eddy, synthseg, synthstrip, all, none

Run selected tasks on the GPU (a space-delimited list). GPU memory is usually the binding constraint rather than the pipeline, so tasks are selected individually: an 8 GB card typically runs “eddy”, “diffprep” and “drbuddi” but not “synthstrip” or “synthseg”. “all” enables every task and “none” disables all of them. When given, this overrides “use_cuda” in –eddy-config and –diffprep-config; when omitted entirely, those keys still apply.

--tortoise-gpu-cpu-ratio

How many volumes DIFFPREP gives the GPU per pass, against one per CPU thread, during motion and eddy correction. TORTOISE does not move the series onto the GPU the way eddy_cuda does: it treats the GPU as one more worker, so the number of passes is ceil(nvolumes / (ngpus * ratio + omp-nthreads - ngpus)). It describes the machine, not the data, and is roughly how many volumes the GPU gets through while one CPU core does one. It is only worth setting when the GPU is fast relative to the core count, since its influence falls as –omp-nthreads rises: about 68% of volumes at 8 cores, and 19% at 64. It requires the patched TORTOISE. Left unset, TORTOISE uses its own default of 15.

Reports and execution

Where intermediate files and reports are written, and how the run reports on itself.

-w, --work-dir

Path where intermediate results should be stored.

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

--report-output-level

Possible choices: auto, root, subject, session

Where the HTML reports are written. “root” writes them to the output directory. “subject” writes them into each subject directory. “session” writes them into each session directory. “auto” resolves to “session” when –subject-anatomical-reference is “sessionwise”, and to “root” otherwise. Reports that cover more than one session, and data without a session level, are written to the subject level instead of the session level, with a warning.

Default: 'auto'

--config-file

Use a pre-generated configuration file. Values in the file are overridden by command-line arguments.

--stop-on-first-crash

Stop on the first crash, even if a work directory was specified.

Default: False

--resource-monitor

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

Default: False

--notrack

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

Default: False

-v, --verbose

Increase log verbosity by one level for each occurrence. Debug level is -vvv.

Default: 0

Debugging and developer options

For developing and debugging QSIPrep itself. –sloppy in particular produces results that are not fit for analysis.

--sloppy

Use low-quality, fast settings. FOR TESTING ONLY; the results are not fit for analysis.

Default: False

--debug

Possible choices: fieldmaps, pdb, all

Debug modes to enable (a space-delimited list). “fieldmaps” retains the intermediate fieldmap estimation files for inspection. “pdb” drops into the Python debugger when a node raises. “all” enables every mode.

--write-graph

Write out the workflow graph.

Default: False

Help and version

Print information and exit.

--version

show program’s version number and exit