Beginner DWI tutorial


Some proficiency with the Unix command-line is required to make the best use of this software. There are many resources online to help you get started if you are not already familiar with it. We also recommend our own Introduction to the Unix command-line, which was written with a particular focus on the types of use that are common when using MRtrix3.


This tutorial is not intended to show the optimal or even recommended way of processing. It is merely a simplified example, intended to familiarise the user with the typical command line interface of certain basic processing steps.

This tutorial will hopefully provide enough information for a novice user to get from the raw DW image data to performing some streamlines tractography. It may also be useful for experienced MRtrix users in terms of identifying some of the new command names.

For all MRtrix3 scripts and commands, additional information on the command usage and available command-line options can be found by invoking the command with the -help option. Note that this tutorial includes commands and scripts for which there are relevant journal articles for citation; these are listed on the help pages also.

DWI geometric distortion correction

If the user has access to reversed phase-encode spin-echo image data, this can be used to correct the susceptibility-induced geometric distortions present in the diffusion images, as well as any eddy current-induced distortions and inter-volume subject motion. Procedures for this correct are not yet implemented in MRtrix3, though we do provide a script for interfacing with the relevant FSL tools:

dwifslpreproc <Input DWI series> <Output corrected DWI series> [options]

For more details, see the dwifslpreproc help file. In particular, it is necessary to manually specify what type of reversed phase-encoding acquisition has taken place (if any), and potentially provide additional relevant input images or provide details of the phase encoding scheme used in the acquisition.

DWI brain mask estimation

In previous versions of MRtrix3, a single command dwi2mask was provided for generating a brain mask from DWI data. There are now multiple algorithms offered through the dwi2mask``_ interface, with the behaviour prior to MRtrix version ``3.1.0 being provided via the “legacy” algorithm:

$ dwi2mask legacy <Input DWI> <Output mask>
$ mrview <Input DWI> -roi.load <Output mask>

Different dwi2mask algorithms may work better or worse on different types of DWI data, so you may wish to experiment with different options. The various algorithms available are described in more detail in the DWI masking page. Regardless of which algorithm you use, it is recommended that the output of this command should always be checked (and corrected if necessary) before proceeding with further processing.

Response function estimation

To perform spherical deconvolution, the DWI signal emanating from a single coherently-oriented fibre bundle must be estimated. We provide a script for doing this, which has a range of algorithms and parameters. This example will use fairly sensible defaults:

$ dwi2response tournier <Input DWI> <Output response text file>
$ shview <Output response text file>

Fibre Orientation Distribution estimation

This command performs Constrained Spherical Deconvolution (CSD) based on the response function estimated previously.

$ dwi2fod csd <Input DWI> <Input response text file> <Output FOD image> -mask <Input DWI mask>
$ mrview <Input DWI> -odf.load_sh <Output FOD image>

Whole-brain streamlines tractography

For the sake of this tutorial, we will perform whole-brain streamlines tractography, using default reconstruction parameters.

$ tckgen <Input FOD image> <Output track file> -seed_image <Input DWI mask> -mask <Input DWI mask> -select <Number of tracks>
$ mrview <Input DWI> -tractography.load <Output track file>

Note: Loading a very large number of tracks can inevitably make the mrview software run very slowly. When this occurs, it may be preferable to instead view only a subset of the generated tracks, e.g.:

$ tckedit <Track file> <Smaller track file> -number <Smaller number of tracks>
$ mrview <Input DWI> -tractography.load <Smaller track file>

Track Density Imaging (TDI)

TDI can be useful for visualising the results of tractography, particularly when a very large number of streamlines is generated.

$ tckmap <Input track file> <Output TDI> -vox <Voxel size in mm>
$ mrview <Output TDI>