Usage

Execution and the BIDS format

The dMRIPrep 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) one DWI series. We highly recommend that you validate your dataset with the free, online BIDS Validator.

The exact command to run dMRIPrep depends on the Installation method. The common parts of the command follow the BIDS-Apps definition. Example:

dmriprep data/bids_root/ out/ participant -w work/

Command-Line Arguments

dMRIPrep: dMRI PREProcessing workflows v25.0.0.dev152+gbf0475bd9.d20251027

usage: dmriprep [-h] [--skip-bids-validation]
                [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                [--session-label SESSION_LABEL [SESSION_LABEL ...]]
                [--subject-anatomical-reference {first-lex,unbiased,sessionwise}]
                [--bids-filter-file FILE] [-d PACKAGE=PATH [PACKAGE=PATH ...]]
                [--bids-database-dir PATH] [--num-workers NPROCS]
                [--omp-nthreads OMP_NTHREADS] [--mem MEMORY_MB] [--low-mem]
                [--use-plugin FILE] [--sloppy] [--anat-only]
                [--level {minimal,resampling,full}] [--boilerplate-only]
                [--reports-only]
                [--ignore {fieldmaps,sbref,eddy,t2w,flair,fmap-jacobian} [{fieldmaps,sbref,eddy,t2w,flair,fmap-jacobian} ...]]
                [--force {bbr,no-bbr,syn-sdc,fmap-jacobian} [{bbr,no-bbr,syn-sdc,fmap-jacobian} ...]]
                [--output-spaces [OUTPUT_SPACES ...]]
                [--dwi2anat-init {auto,t1w,t2w,header}]
                [--dwi2anat-dof {6,9,12}]
                [--fallback-total-readout-time FALLBACK_TOTAL_READOUT_TIME]
                [--random-seed _RANDOM_SEED] [--output-layout {bids,legacy}]
                [--aggregate-session-reports AGGR_SES_REPORTS]
                [--md-only-boilerplate] [--msm | --no-msm]
                [--skull-strip-template SKULL_STRIP_TEMPLATE]
                [--skull-strip-fixed-seed]
                [--skull-strip-t1w {auto,skip,force}] [--fmap-bspline]
                [--fmap-no-demean] [--use-syn-sdc [{warn,error}]]
                [--fs-license-file FILE] [--fs-subjects-dir PATH]
                [--submm-recon | --no-submm-recon] [--fs-no-reconall]
                [--fs-no-resume] [--version] [-v] [-w WORK_DIR]
                [--clean-workdir] [--resource-monitor] [--config-file FILE]
                [--write-graph] [--stop-on-first-crash] [--notrack]
                [--debug {fieldmaps,pdb,all} [{fieldmaps,pdb,all} ...]]
                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 dMRIPrep (see BIDS-Apps specification).

Options for filtering BIDS queries

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

--session-label

A space delimited list of session identifiers or a single identifier (the ses- prefix can be removed)

--subject-anatomical-reference

Possible choices: first-lex, unbiased, sessionwise

Method to produce the reference anatomical space:: “first-lex” will use the first image in lexicographical order “unbiased” will construct an unbiased template from all images (previously “–longitudinal”) “sessionwise” will independently process each session. If multiple runs are found, the behavior will be similar to “first-lex” for each session.

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

-d, --derivatives

Search PATH(s) for pre-computed derivatives. These may be provided as named folders (e.g., –derivatives smriprep=/path/to/smriprep).

--bids-database-dir

Path to a PyBIDS database folder, for faster indexing (especially useful for large datasets). Will be created if not present.

Options to handle performance

--num-workers, --nprocs, --n-procs, --num-procs, --n-workers: Total number of available workers (processes)
--omp-nthreads, --nthreads, --n_cpus, --n-cpus: maximum number of threads per-process
--mem, --mem_mb, --mem-mb: Upper bound memory limit for dMRIPrep processes in MB
--low-mem: Attempt to reduce memory usage (will increase disk usage in working directory)
--use-plugin, --nipype-plugin-file: Nipype plugin configuration file
--sloppy: Use low-quality tools for speed - TESTING ONLY
-v, --verbose: Increases log verbosity for each occurrence, debug level is -vvv

Options for performing only a subset of the workflow

--anat-only

run anatomical workflows only

--level

Possible choices: minimal, resampling, full

Processing level; may be ‘minimal’ (nothing that can be recomputed), ‘resampling’ (recomputable targets that aid in resampling) or ‘full’ (all target outputs).

--boilerplate-only, --boilerplate_only

Generate boilerplate only

--reports-only

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

Workflow configuration

--ignore

Possible choices: fieldmaps, sbref, eddy, t2w, flair, fmap-jacobian

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

--force

Possible choices: bbr, no-bbr, syn-sdc, fmap-jacobian

Force selected processing choices, overriding automatic selections (a space delimited list).

[no-]bbr: Use/disable boundary-based registration for DWI-to-T1w coregistration
(No goodness-of-fit checks)
syn-sdc: Calculate SyN-SDC correction in addition to other fieldmaps

--output-spaces

Standard and non-standard spaces to resample anatomical and diffusion images to. Standard spaces may be specified by the form <SPACE>[:cohort-<label>][:res-<resolution>][...], where <SPACE> is a keyword designating a spatial reference, and may be followed by optional, colon-separated parameters. Non-standard spaces imply specific orientations and sampling grids. The default value of this flag (meaning, if the argument is not include in the command line) is --output-spaces run - the original space and sampling grid of the original DWI run. Important to note, the res-* modifier does not define the resolution used for the spatial normalization. To generate no DWI outputs (if that is intended for some reason), use this option without specifying any spatial references. For further details, please check out https://www.nipreps.org/dmriprep/en/latest/spaces.html

--dwi2anat-init

Possible choices: auto, t1w, t2w, header

Method of initial DWI to anatomical coregistration. If auto, a T2w image is used if available, otherwise the T1w image. t1w forces use of the T1w, t2w forces use of the T2w, and header uses the DWI header information without an initial registration.

--dwi2anat-dof

Possible choices: 6, 9, 12

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

--fallback-total-readout-time

Fallback value for Total Readout Time (TRT) calculation. May be a number or “estimated”.

--random-seed

Initialize the random seed for the workflow

Options for modulating outputs

--output-layout

Possible choices: bids, legacy

Organization of outputs. “bids” (default) places dMRIPrep derivatives directly in the output directory, and defaults to placing FreeSurfer derivatives in <output-dir>/sourcedata/freesurfer. “legacy” creates derivative datasets as subdirectories of outputs.

--aggregate-session-reports

Maximum number of sessions aggregated in one subject’s visual report. If exceeded, visual reports are split by session.

--md-only-boilerplate

Skip generation of HTML and LaTeX formatted citation with pandoc

--msm, --no-msm

Enable or disable Multimodal Surface Matching surface registration.

Specific options for ANTs registrations

--skull-strip-template

Select a template for skull-stripping with antsBrainExtraction (OASIS30ANTs, by default)

--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 and matching –random-seed <int>

--skull-strip-t1w

Possible choices: auto, skip, force

Perform T1-weighted skull stripping (‘force’ ensures skull stripping, ‘skip’ ignores skull stripping, and ‘auto’ applies brain extraction based on the outcome of a heuristic to check whether the brain is already masked).

Specific options for handling fieldmaps

--fmap-bspline: Fit a B-Spline field using least-squares (experimental)
--fmap-no-demean: Do not remove median (within mask) from fieldmap

Specific options for SyN distortion correction

--use-syn-sdc

Possible choices: warn, error

Use fieldmap-less distortion correction based on anatomical image; if unable, error (default) or warn based on optional argument.

Specific options for FreeSurfer preprocessing

--fs-license-file: Path to FreeSurfer license key file. Get it (for free) by registering at https://surfer.nmr.mgh.harvard.edu/registration.html
--fs-subjects-dir: Path to existing FreeSurfer subjects directory to reuse. (default: OUTPUT_DIR/freesurfer)
--submm-recon, --no-submm-recon: Enable or disable sub-millimeter (hi-res) reconstruction.
--fs-no-reconall: Disable FreeSurfer surface preprocessing.
--fs-no-resume: EXPERT: Import pre-computed FreeSurfer reconstruction without resuming. The user is responsible for ensuring that all necessary files are present.

Other options

--version

show program’s version number and exit

-w, --work-dir

Path where intermediate results should be stored

--clean-workdir

Clears working directory of contents. Use of this flag is not recommended when running concurrent processes of fMRIPrep.

--resource-monitor

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

--config-file

Use pre-generated configuration file. Values in file will be overridden by command-line arguments.

--write-graph

Write workflow graph.

--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 dMRIPrep developers. This information helps to improve dMRIPrep and provides an indicator of real world usage crucial for obtaining funding.

--debug

Possible choices: fieldmaps, pdb, all

Debug mode(s) to enable. ‘all’ is alias for all available modes.

The FreeSurfer license

dMRIPrep uses FreeSurfer tools, which require a license to run.

To obtain a FreeSurfer license, simply register for free at https://surfer.nmr.mgh.harvard.edu/registration.html.

When using manually-prepared environments or Singularity, FreeSurfer will search for a license key file first using the $FS_LICENSE environment variable and then in the default path to the license key file ($FREESURFER_HOME/license.txt). If using the --cleanenv flag and $FS_LICENSE is set, use --fs-license-file $FS_LICENSE to pass the license file location to dMRIPrep.

It is possible to run the Docker container pointing the image to a local path where a valid license file is stored. For example, if the license is stored in the $HOME/.licenses/freesurfer/license.txt file on the host system:

$ docker run -ti --rm \
    -v $HOME/fullds005:/data:ro \
    -v $HOME/dockerout:/out \
    -v $HOME/.licenses/freesurfer/license.txt:/opt/freesurfer/license.txt \
    nipreps/dmriprep:latest \
    /data /out/out \
    participant \
    --ignore fieldmaps

Usage tracking with Google Analytics

To be able to assess usage of the software, we are recording each use of the CLI as an event in Google Analytics, using popylar. ``

For now, the only information that we are recording is the fact that the CLI was called and whether the call completed successfully. In addition, through Google Analytics, we will have access to very general information, such as the country and city in which the computer using the CLI was located and the time that it was used. At this time, we do not record any additional information, although in the future we may want to record statistics on the computational environment in which the CLI was called, such as the operating system.

Opting out of this usage tracking can be done by calling the CLI with the --notrack flag:

dmriprep data/bids_root/ out/ participant -w work/ --notrack