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, and it must include at least one T1w structural image and (unless disabled with a flag) a 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: q-Space Image PREProcessing workflows

usage: qsiprep [-h] [--version] [--skip_bids_validation]
               [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
               [--acquisition_type ACQUISITION_TYPE] [--recon-only]
               [--recon-spec RECON_SPEC] [--recon-input RECON_INPUT]
               [--nthreads NTHREADS] [--omp-nthreads OMP_NTHREADS]
               [--mem_mb MEM_MB] [--low-mem] [--use-plugin USE_PLUGIN]
               [--anat-only] [--boilerplate] [-v]
               [--ignore {fieldmaps,sbref} [{fieldmaps,sbref} ...]]
               [--longitudinal] [--b0-threshold B0_THRESHOLD]
               [--dwi_denoise_window DWI_DENOISE_WINDOW]
               [--unringing-method {none,mrdegibbs}] [--dwi-no-biascorr]
               [--no-b0-harmonization] [--denoise-before-combining]
               [--combine_all_dwis]
               [--distortion-group-merge {concat,average,none}]
               [--write-local-bvecs]
               [--output-space {T1w,template} [{T1w,template} ...]]
               [--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}]
               [--b0-motion-corr-to {iterative,first}]
               [--hmc-transform {Affine,Rigid}]
               [--hmc_model {none,3dSHORE,eddy}] [--eddy-config EDDY_CONFIG]
               [--shoreline_iters SHORELINE_ITERS]
               [--impute-slice-threshold IMPUTE_SLICE_THRESHOLD]
               [--skull-strip-template {OASIS,NKI}] [--skull-strip-fixed-seed]
               [--force-spatial-normalization] [--fs-license-file PATH]
               [--do-reconall] [--prefer_dedicated_fmaps] [--fmap-bspline]
               [--fmap-no-demean] [--use-syn-sdc] [--force-syn] [-w WORK_DIR]
               [--resource-monitor] [--reports-only] [--run-uuid RUN_UUID]
               [--write-graph] [--stop-on-first-crash] [--notrack] [--sloppy]
               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 (see BIDS-Apps specification).

Named Arguments

--version

show program’s version number and exit

Options for filtering BIDS queries

--skip_bids_validation, --skip-bids-validation

assume the input dataset is BIDS compliant and skip the validation

--participant_label, --participant-label

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

--acquisition_type, --acquisition_type

select a specific acquisition type to be processed

Options for reconstructing qsiprep outputs

--recon-only, --recon_only

run only reconstruction, assumes preprocessing has already completed.

--recon-spec, --recon_spec

json file specifying a reconstruction pipeline to be run after preprocessing

--recon-input, --recon_input

use this directory as inputs to qsirecon. This option skips qsiprep.

Options to handle performance

--nthreads, --n_cpus, --n-cpus

maximum number of threads across all processes

--omp-nthreads, --omp_nthreads

maximum number of threads per-process

--mem_mb, --mem-mb

upper bound memory limit for qsiprep processes

--low-mem, --low_mem

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

--use-plugin, --use_plugin

nipype plugin configuration file

--anat-only, --anat_only

run anatomical workflows only

--boilerplate

generate boilerplate only

-v, --verbose

increases log verbosity for each occurence, debug level is -vvv

Workflow configuration

--ignore

Possible choices: fieldmaps, sbref

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

--longitudinal

treat dataset as longitudinal - may increase runtime

--b0-threshold, --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, --dwi-denoise-window

window size in voxels for dwidenoise. Must be odd (default: 5). If 0, dwidwenoise will not be run

--unringing-method, --unringing_method

Possible choices: none, mrdegibbs

Method for Gibbs-ringing removal.
  • none: no action

  • mrdegibbs: use mrdegibbs from mrtrix3

--dwi-no-biascorr, --dwi_no_biascorr

skip b0-based dwi spatial bias correction

--no-b0-harmonization, --no_b0_harmonization

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

--denoise-before-combining, --denoise_before_combining

run dwidenoise before combining dwis. Requires --combine-all-dwis

--combine_all_dwis, --combine-all-dwis

combine dwis from across multiple runs for motion correction and reconstruction.

--distortion-group-merge, --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

--write-local-bvecs, --write_local_bvecs

write a series of voxelwise bvecs, relevant if writing preprocessed dwis to template space

--output-space, --output_space

Possible choices: T1w, template

volume and surface spaces to resample dwis into
  • T1w: subject anatomical volume

  • template: deprecated. Will be ignored

--template

Possible choices: MNI152NLin2009cAsym

volume template space (default: MNI152NLin2009cAsym)

--output-resolution, --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-T1w coregistration

--b0-to-t1w-transform, --b0_to_t1w_transform

Possible choices: Rigid, Affine

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

--intramodal-template-iters, --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, --intramodal_template_transform

Possible choices: Rigid, Affine, BSplineSyN, SyN

Transformation used for building the intramodal template.

Specific options for motion correction and coregistration

--b0-motion-corr-to, --bo_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, --hmc_transform

Possible choices: Affine, Rigid

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

--hmc_model, --hmc-model

Possible choices: none, 3dSHORE, eddy

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 “eddy_ingress”, the dwis are assumed to have been run through fsls eddy.

--eddy-config, --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/PennBBL/qsiprep/blob/master/qsiprep/data/eddy_params.json

--shoreline_iters, --shoreline-iters

number of SHORELine iterations. (default: 2)

--impute-slice-threshold, --impute_slice_threshold

impute data in slices that are this many SDs from expected. If 0 (default), no slices will be imputed

Specific options for ANTs registrations

--skull-strip-template, --skull_strip_template

Possible choices: OASIS, NKI

select ANTs skull-stripping template (default: OASIS)

--skull-strip-fixed-seed, --skull_strip_fixed_seed

do not use a random seed for skull-stripping - will ensure run-to-run replicability when used with –omp-nthreads 1

--force-spatial-normalization, --force_spatial_normalization

ensures that spatial normalization is run, even if template is not specified in –output-space. Useful if you plan to warp atlases into subject space.

Specific options for FreeSurfer preprocessing

--fs-license-file, --fs_license_file

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

--do-reconall, --do_reconall

Run the FreeSurfer recon-all pipeline

Specific options for handling fieldmaps

--prefer_dedicated_fmaps, --prefer-dedicated-fmaps

forces unwarping to use files from the fmap directory instead of using an RPEdir scan from the same session.

--fmap-bspline, --fmap_bspline

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

--fmap-no-demean, --fmap_no_demean

do not remove median (within mask) from fieldmap (default: True)

Specific options for SyN distortion correction

--use-syn-sdc, --use_syn_sdc

EXPERIMENTAL: Use fieldmap-free distortion correction. To use this option, “template” must be passed to –output-space

--force-syn, --force_syn

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

Other options

-w, --work-dir, --work_dir

path where intermediate results should be stored

--resource-monitor, --resource_monitor

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

--reports-only, --reports_only

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

--run-uuid, --run_uuid

Specify UUID of previous run, to include error logs in report. No effect without –reports-only.

--write-graph, --write_graph

Write workflow graph.

--stop-on-first-crash, --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.

--sloppy

Use low-quality tools for speed - TESTING ONLY

The docker wrapper CLI

The qsiprep on Docker wrapper

This is a lightweight Python wrapper to run qsiprep. Docker must be installed and running. This can be checked running

docker info

Please report any feedback to our GitHub repository (https://github.com/pennbbl/qsiprep) and do not forget to credit all the authors of software that qsiprep uses (https://qsiprep.readthedocs.io/en/latest/citing.html).

usage: qsiprep-docker [--recon-input RECON_INPUT] [--eddy-config EDDY_CONFIG]
                      [-h] [--version] [-i IMG] [-w WORK_DIR]
                      [--fs-license-file PATH] [--recon-spec RECON_SPEC]
                      [--gpus GPUS] [-f PATH] [-p PATH] [-a CUSTOM_ATLASES]
                      [--shell] [--config PATH] [-e ENV_VAR value] [-u USER]
                      [bids_dir] [output_dir] [{participant}]

Positional Arguments

bids_dir
output_dir
analysis_level

Possible choices: participant

Named Arguments

--recon-input, --recon_input
--eddy-config, --eddy_config
-h, --help

show this help message and exit

--version

show program’s version number and exit

-i, --image

image name

Wrapper options

Standard options that require mapping files into the container

-w, --work-dir

path where intermediate results should be stored

--fs-license-file

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

--recon-spec, --recon_spec
--gpus

gpus argument sent to docker

Developer options

Tools for testing and debugging qsiprep

-f, --patch-qsiprep

working qsiprep repository

-p, --patch-nipype

working nipype repository

-a, --custom_atlases

custom atlas directory

--shell

open shell in image instead of running qsiprep

--config

Use custom nipype.cfg file

-e, --env

Set custom environment variable within container

-u, --user

Run container as a given user/uid

The singularity wrapper CLI

Using qsiprep within a singularity container (qsiprep-<version>.simg)

To run qsiprep with singularity, a singularity image must be built (see Installation). This is the preferred method for HPCs. For example

singularity run --cleanenv -B /data/:/home/$user/data qsiprep-<version>.simg

Please report any feedback to our GitHub repository (https://github.com/pennbbl/qsiprep) and do not forget to credit all the authors of software that qsiprep uses (https://qsiprep.readthedocs.io/en/latest/citing.html).

usage: qsiprep-docker [--recon-input RECON_INPUT] [-h] [--version] [-i IMG]
                      [-w WORK_DIR] [--fs-license-file PATH]
                      [--recon-spec RECON_SPEC] [--eddy-config EDDY_CONFIG]
                      [-f PATH] [-p PATH] [-a CUSTOM_ATLASES] [--shell]
                      [--config PATH] [-e ENV_VAR value] [-u USER]
                      [bids_dir] [output_dir] [{participant}]

Positional Arguments

bids_dir
output_dir
analysis_level

Possible choices: participant

Named Arguments

--recon-input, --recon_input
-h, --help

show this help message and exit

--version

show program’s version number and exit

-i, --image

image name

Wrapper options

Standard options that require mapping files into the container

-w, --work-dir

path where intermediate results should be stored

--fs-license-file

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

--recon-spec, --recon_spec
--eddy-config, --eddy_config

Developer options

Tools for testing and debugging qsiprep

-f, --patch-qsiprep

working qsiprep repository

-p, --patch-nipype

working nipype repository

-a, --custom_atlases

custom atlas directory

--shell

open shell in image instead of running qsiprep

--config

Use custom nipype.cfg file

-e, --env

Set custom environment variable within container

-u, --user

Run container as a given user/uid

Note on using CUDA

The CUDA runtime version 9.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 singularity, the call to singularity 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.

CUDA Support

As of version 0.6.7 CUDA version 9.1 is supported in the QSIPrep container! To run locally using docker you will need the nvidia container runtime installed for Docker version 19.0.3 or higher. Singularity images will run with CUDA 9.1 with the -nv flag.

Support and communication

The documentation of this project is found here: http://qsiprep.readthedocs.org/en/latest/.

All bugs, concerns and enhancement requests for this software can be submitted here: https://github.com/pennbbl/qsiprep/issues.