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 v0.5.0+30.g510ed0ea

usage: dmriprep [-h] [--version] [--skip-bids-validation]
                [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                [--bids-filter-file PATH] [--anat-derivatives PATH]
                [--nprocs NPROCS] [--omp-nthreads OMP_NTHREADS]
                [--mem MEMORY_GB] [--low-mem] [--use-plugin USE_PLUGIN]
                [--anat-only] [--boilerplate_only] [--md-only-boilerplate]
                [-v]
                [--ignore {fieldmaps,sbref,eddy} [{fieldmaps,sbref,eddy} ...]]
                [--longitudinal]
                [--output-spaces [OUTPUT_SPACES [OUTPUT_SPACES ...]]]
                [--dwi2t1w-init {register,header}]
                [--skull-strip-template SKULL_STRIP_TEMPLATE]
                [--skull-strip-fixed-seed] [--use-syn-sdc] [--force-syn]
                [--fs-license-file PATH] [--fs-subjects-dir PATH]
                [--no-submm-recon | --fs-no-reconall] [-w WORK_DIR]
                [--clean-workdir] [--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 dMRIPrep (see BIDS-Apps specification).

Named Arguments

--version

show program’s version number and exit

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)

--bids-filter-file

a JSON file describing custom BIDS input filter using pybids {<suffix>:{<entity>:<filter>,…},…} (https://github.com/bids-standard/pybids/blob/master/bids/layout/config/bids.json)

--anat-derivatives

Reuse the anatomical derivatives from another fMRIPrep run or calculated with an alternative processing tool (NOT RECOMMENDED).

Options to handle performance

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

maximum number of threads across all processes

--omp-nthreads

maximum number of threads per-process

--mem, --mem_mb, --mem-mb

upper bound memory limit for dMRIPrep processes

--low-mem

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

--use-plugin

nipype plugin configuration file

--anat-only

run anatomical workflows only

--boilerplate_only

generate boilerplate only

--md-only-boilerplate

skip generation of HTML and LaTeX formatted citation with pandoc

-v, --verbose

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

Workflow configuration

--ignore

Possible choices: fieldmaps, sbref, eddy

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

--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/0.5.0/spaces.html

--dwi2t1w-init

Possible choices: register, header

Either “register” (the default) to initialize volumes at center or “header” to use the header information when co-registering DWI to T1w images.

Specific options for ANTs registrations

--skull-strip-template

select a template for skull-stripping with antsBrainExtraction

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

Specific options for SyN distortion correction

--use-syn-sdc

Attempt to set-up fieldmap-less estimation of fieldmaps via nonlinear registration with ANTs if no other fieldmap estimation method is available. Fieldmap-less estimation will not be used when sufficient fieldmap information (B0 mapping with SEI or GRE, or PEPOLAR estimation with EPIs) is retrieved from the BIDS structure for a given subject.

--force-syn

Force estimation of fieldmaps with the fieldmap-less approach. The use of this feature is discouraged.

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)

Surface preprocessing options

--no-submm-recon

disable sub-millimeter (hires) reconstruction

--fs-no-reconall

disable FreeSurfer surface preprocessing.

Other options

-w, --work-dir

path where intermediate results should be stored

--clean-workdir

Clears working directory of contents. Use of this flag is notrecommended when running concurrent processes of dMRIPrep.

--resource-monitor

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

--reports-only

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

--run-uuid

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

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

--sloppy

Use low-quality tools for speed - TESTING ONLY

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