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