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 formate 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: q-Space Image Preprocessing workflows

usage: qsiprep [-h] [--version] [--skip_bids_validation]
               [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
               [--bids-database-dir BIDS_DATABASE_DIR]
               [--bids-filter-file FILE] [--interactive-reports-only]
               [--recon-only] [--recon-spec RECON_SPEC]
               [--recon-input RECON_INPUT]
               [--freesurfer-input FREESURFER_INPUT] [--skip-odf-reports]
               [--nthreads NTHREADS] [--omp-nthreads OMP_NTHREADS]
               [--mem_mb MEM_MB] [--low-mem] [--use-plugin USE_PLUGIN]
               [--anat-only] [--dwi-only] [--infant] [--boilerplate] [-v]
               [--anat-modality {T1w,T2w,none}]
               [--ignore {fieldmaps} [{fieldmaps} ...]] [--longitudinal]
               [--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}]
               [--write-local-bvecs]
               [--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}]
               [--b0-motion-corr-to {iterative,first}]
               [--hmc-transform {Affine,Rigid}]
               [--hmc_model {none,3dSHORE,eddy,tensor}]
               [--eddy-config EDDY_CONFIG] [--shoreline_iters SHORELINE_ITERS]
               [--impute-slice-threshold IMPUTE_SLICE_THRESHOLD]
               [--skull-strip-template {OASIS,NKI}] [--skull-strip-fixed-seed]
               [--skip-anat-based-spatial-normalization]
               [--fs-license-file PATH] [--do-reconall]
               [--pepolar-method {TOPUP,DRBUDDI}] [--denoised_image_sdc]
               [--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)
--bids-database-dir, --bids_database_dir: path to a saved BIDS database directory
--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

Options for interactive report outputs¶

--interactive-reports-only, --interactive_reports_only: create interactive report json files on already preprocessed data.

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.
--freesurfer-input, --freesurfer_input: Directory containing freesurfer outputs to be integrated into recon.
--skip-odf-reports, --skip_odf_reports: run only reconstruction, assumes preprocessing has already completed.

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
--dwi-only, --dwi_only: ignore anatomical (T1w/T2w) data and process DWIs only
--infant: configure pipelines to process infant brains
--boilerplate: generate boilerplate only
-v, --verbose: increases log verbosity for each occurence, debug level is -vvv

Workflow configuration¶

--anat-modality, --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 and reconstruction. If –infant, T2w is forced.

--ignore

Possible choices: fieldmaps

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 image-based denoising, integer or “auto”.If “auto”, 5 will be used for dwidenoise and auto-configured for patch2self based on the number of b>0 images.

--denoise-method, --denoise_method

Possible choices: dwidenoise, patch2self, none

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

--unringing-method, --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, --dwi_no_biascorr

DEPRECATED: see –b1-biascorr-stage

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

--no-b0-harmonization, --no_b0_harmonization

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

--denoise-after-combining, --denoise_after_combining

run dwidenoise after combining dwis, but before motion correction. Requires --combine-all-dwis

--separate_all_dwis, --separate-all-dwis

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

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

--anatomical-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-Anatomical coregistration¶

--b0-to-t1w-transform, --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, --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, 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, --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

--skip-anat-based-spatial-normalization, --skip_anat_based_spatial_normalization

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

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 (IGNORED)

Specific options for handling fieldmaps and distortion correction¶

--pepolar-method, --pepolar_method

Possible choices: TOPUP, DRBUDDI

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

--denoised_image_sdc, --denoised_image_sdc

use denoised b=0 images if available instead of raw (from BIDS) images in SDC

--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]
                      [--bids-filter-file BIDS_FILTER_FILE]
                      [--freesurfer-input FREESURFER_INPUT] [-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
--bids-filter-file, --bids_filter_file
--freesurfer-input, --freesurfer_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
--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]
                      [--bids-filter-file BIDS_FILTER_FILE] [-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
--bids-filter-file, --bids_filter_file
-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.