There are many options for running
qsiprep but most have sensible defaults and
don’t need to be changed. This page describes the options most likely to be
needed to be adjusted for your specific data. Suppose the following data is available
in the BIDS input:
sub-1/ses-1/dwi/sub-1_ses-1_acq-multishell_run-01_dwi.nii.gz sub-1/ses-1/dwi/sub-1_ses-1_acq-multishell_run-01_dwi.nii.gz sub-1/ses-1/dwi/sub-1_ses-1_acq-multishell_run-03_dwi.nii.gz sub-1/ses-1/fmap/sub-1_ses-1_dir-PA_epi.nii.gz
One way to process these data would be to call
qsiprep like this:
qsiprep \ /path/to/inputs /path/to/outputs participant \ --output-resolution 1.2 \ --fs-license-file /path/to/license.txt
This section explains
sub-1/ses-1/fmap/sub-1_dir-PA_epi.nii.gz has a JSON sidecar containing the
IntendedFor field for fieldmap correction (see here):
"IntendedFor": [ "ses-1/dwi/sub-1_ses-1_acq-multishell_run-01_dwi.nii.gz", "ses-1/dwi/sub-1_ses-1_acq-multishell_run-02_dwi.nii.gz", "ses-1/dwi/sub-1_ses-1_acq-multishell_run-03_dwi.nii.gz" ]
qsiprep will infer that the dwi scans are in the same warped space - that their
susceptibility distortions are shared and they can be combined before head motion correction. Since
we didn’t specify
--separate-all-dwis the separate scans will be merged together before head motion
correction and the fully preprocessed outputs will be written to
there will be one output in the derivatives directory for each input image in the bids input
It is beneficial to have as much data as possible available for head motion correction. However, the denoising preprocessing step has important caveats that should be considered. For a discussion see Denoising and Merging Images.
This section covers
--output-resolution 1.2, and
Unlike with fMRI, which can be coregistered to a T1w image and warped to a
template using the T1w image’s spatial normalization, the T1w images do not
contain enough contrast to accurately align white matter structures to a
template. For this reason, spatial normalization is typically done after
models are fit. Therefore we omit the
--output-spaces argument from
preprocessing: i.e. no template warping takes place by default.
All outputs will be registered to the T1w image (or the
AC-PC aligned b=0 template if
--dwi-only was specified) but will have
an isotropic voxel size. Furthermore, all outputs are aligned according to the
AC-PC convention: the coordinates are changed from the native scanner
coordinates to a new system where $0, 0, 0$ is where the midline intersects
the anterior commissure (AC).
Cortex can be accurately spatially-normalized using the T1w image, so the T1w
image is still spatially normalized by default during preprocessing. The
transform from the T1w image to the
MNI152NLin2009cAsym template is
included in the derivatives. This can be used during reconstruction to map
cortical parcellations from the template into the DWI in order to estimate
brain graphs. If you want to save ~20 minutes of computation time, this
normalization can be disabled with the
--output-resolution argument determines the spatial resolution of the
preprocessed dwi series. You can specify the resolution of the original data
or choose to upsample the dwi to a higher spatial resolution. Some
post-processing pipelines such as fixel-based analysis recommend resampling
your output to at least 1.3mm resolution. By choosing this resolution here,
it means your data will only be interpolated once: head motion correction,
susceptibility distortion correction, coregistration and upsampling will be
done in a single step. If your are upsampling your data by more than 10%,
QSIPrep will use BSpline interpolation instead of Lanczos windowed sinc
Head motion correction model¶
eddy is technically model-free, it is an option for
--hmc-model along with
default) runs FSL’s
eddy for head motion correction and eddy current
correction. This will work for single-shell and multi-shell sampling schemes.
3dSHORE (aka “SHORELine”) option works for multi-shell, Cartesian
grid sampling (DSI) and random q-space sampling (CS-DSI).
none will register all the b=0 images to one another and the
b>0 images will have the transform from the nearest b=0 image applied. This
is not recommended. Between
3dSHORE, all sampling schemes
can be motion corrected.
Enabling and disabling preprocessing steps¶
The image processing operations performed by QSIPrep are configured by default to apply to most generic sequences. Depending on your sequence and sampling scheme, you can elect to enable, disable or alter the behavior of these steps to better match your data.
B1 Bias Field Correction
Reduce random noise in images.
Remove spatial ringing artifact from images.
Remove spatial non- uniformity of images.
Disabled by default
Change behavior with
Set the window to
Technically only supposed to be run on full Fourier acquisitions.
Uses N4BiasFieldCorrection on b=0 images, applies correction to the whole series
Not included in this table is the b=0 intensity harmonization step, which
applies simple scaling if there is more than one NIfTI file being processed.
It can be disabled with
Each of these steps can be applied at the same time, which by default is
before any images are concatenated. The user can instead run these steps
together after images are concatenated by specifying
--denoise-after-combining. See Denoising and Merging Images for more info.
What is happening??¶
While QSIPrep runs with -v -v, you will see lots of unintuitive output in the terminal like:
[Node] Setting-up "qsiprep_wf.single_subject_PNC_wf.dwi_finalize_acq_realistic_wf.transform_dwis_t1.final_b0_ref.b0ref_reportlet" in "/scratch/qsiprep_wf/single_subject_PNC_wf/dwi_finalize_acq_realistic_wf/transform_dwis_t1/final_b0_ref/b0ref_reportlet". 201229-21:33:46,213 nipype.workflow INFO: [Node] Running "b0ref_reportlet" ("qsiprep.niworkflows.interfaces.registration.SimpleBeforeAfterRPT") 201229-21:33:48,51 nipype.workflow INFO: [MultiProc] Running 2 tasks, and 3 jobs ready. Free memory (GB): 3.70/4.00, Free processors: 0/2. Currently running: * qsiprep_wf.single_subject_PNC_wf.dwi_finalize_acq_realistic_wf.transform_dwis_t1.final_b0_ref.b0ref_reportlet * qsiprep_wf.single_subject_PNC_wf.anat_preproc_wf.mni_mask
These print-outs describe what is currently running. In this case, we can see that
mni_mask are being run simultaneously. What exactly
are these steps and how do they fit into the overall workflow?
We can find the name of the node (aka “job”) being run in the quotation marks.
This task can be found in the workflow diagrams in Preprocessing pipeline details.
In the case of
mni_mask it is part of Handling Lesions and abnormalities, while
b0ref_reportlet is part of DWI reference image estimation. The relative place of these
jobs’ parent workflows in the overall workflow can be seen in the graph of
Also in this example you can see that QSIPrep was run with
Free processors: 0/2) and that both open slots are running a job.