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.