Built-In Reconstruction Workflows

The Built-In recon workflows can be easily selected by specifying their name after the --recon-spec flag (e.g. --recon-spec amico_noddi). Many of these workflows were originally described in Cieslak et al.[1]. Not all workflows are suitable for all kinds of dMRI data. Be sure to check Which workflows are appropriate for your dMRI data?.

By specifying just a name for --recon_spec, you will be using all the default arguments for the various steps in that workflow. Workflows can be customized (see Custom Reconstruction Workflows).

Workflows

MRtrix3-based Workflows

The MRtrix workflows are identical up to the FOD estimation. In each case the fiber response function is estimated using dwi2response dhollander [2] with a mask based on the T1w. The main differences are in

  • the CSD algorithm used in dwi2fod (msmt_csd or ss3t_csd)

  • whether a T1w-based tissue segmentation is used during tractography

In the *_noACT versions of the pipelines, no T1w-based segmentation is used during tractography. Otherwise, cropping is performed at the GM/WM interface, along with backtracking.

In all pipelines, tractography is performed using tckgen, which uses the iFOD2 probabilistic tracking method to generate 1e7 streamlines with a maximum length of 250mm, minimum length of 30mm, FOD power of 0.33. Weights for each streamline were calculated using SIFT2 [3] and were included for while estimating the structural connectivity matrix.

Warning

We don’t recommend using ACT with FAST segmentations. The full benefits of ACT require very precise tissue boundaries and FAST just doesn’t do this reliably enough. We strongly recommend the hsvs segmentation if you’re going to use ACT. Note that this requires --freesurfer-input

MRtrix3 DWI Outputs

These files are located in the dwi/ directories.

File Name

Description

*_connectivity.mat

MATLAB format mat file containing connectivity matrices for all the selected atlases. This is an hdf5-format file and can be read using scipy.io.matlab.loadmat in Python.

*_exemplarbundles.zip

A zip archive containing the output directory from connectome2tck. Unzip this directory and view the exemplar connections using mrview to ensure that you’re seeing the expected shapes of connections.

*_streamlines.tck.gz

Streamlines produced by tckgen. NOTE: these are not saved to the output directory by default.

*model-mtnorm*param-inliermask*_dwimap.nii.gz

Inlier mask created by mtnormalize

*model-mtnorm*param-norm*_dwimap.nii.gz

Inlier mask created by mtnormalize

*model-sift2*_mu.txt

The $mu$ value that should be used to adjust SIFT2 weights to account for different response functions.

*model-sift2*_streamlineweights.csv

Per-streamline SIFT2 weight for each streamline in streamlines.tck.gz.

*param-fod*label-CSF*_dwimap.mif.gz

FOD for cerebrospinal fluid.

*param-fod*label-CSF*_dwimap.txt

SH response function for cerebrospinal fluid.

*param-fod*label-GM*_dwimap.mif.gz

FOD for gray matter.

*param-fod*label-GM*_dwimap.txt

SH response function for gray matter.

*param-fod*label-WM*_dwimap.mif.gz

FOD for white matter. These FODs are used as inputs to tckgen for tractograpy.

*param-fod*label-WM*_dwimap.txt

SH response function for white matter.

MRtrix3 Anatomical Outputs

These files are located anat/ directories.

File Name

Description

*space-T1w*atlas-hsvs*_dseg.nii.gz

Hybrid Surface/Voume Segmentation in MRtrix3 5tt format. Aligned in coordinate space to space-T1w.

*space-fsnative*atlas-hsvs*_dseg.nii.gz

Hybrid Surface/Voume Segmentation in MRtrix3 5tt format. Aligned to the FreeSurfer orig.mgz image.

mrtrix_multishell_msmt_ACT-hsvs

This workflow uses the msmt_csd algorithm [4] to estimate FODs for white matter, gray matter and cerebrospinal fluid using multi-shell acquisitions. The white matter FODs are used for tractography and the T1w segmentation is used for anatomical constraints [5]. The T1w segmentation uses the hybrid surface volume segmentation (hsvs) [6] and requires --freesurfer-input. This workflow produces MRtrix3 DWI Outputs and MRtrix3 Anatomical Outputs.

mrtrix_multishell_msmt_ACT-fast

Identical to mrtrix_multishell_msmt_ACT-hsvs except FSL’s FAST is used for tissue segmentation. This workflow is not recommended. This workflow produces MRtrix3 DWI Outputs.

mrtrix_multishell_msmt_noACT

This workflow uses the msmt_csd algorithm [4] to estimate FODs for white matter, gray matter and cerebrospinal fluid using multi-shell acquisitions. The white matter FODs are used for tractography with no T1w-based anatomical constraints. This workflow produces MRtrix3 DWI Outputs.

mrtrix_singleshell_ss3t_ACT-hsvs

This workflow uses the ss3t_csd_beta1 algorithm [7] to estimate FODs for white matter, and cerebrospinal fluid using single shell (DTI) acquisitions. The white matter FODs are used for tractography and the T1w segmentation is used for anatomical constraints [5]. The T1w segmentation uses the hybrid surface volume segmentation (hsvs) [6] and requires --freesurfer-input. This workflow produces MRtrix3 DWI Outputs and MRtrix3 Anatomical Outputs.

mrtrix_multishell_msmt_ACT-fast

Identical to mrtrix_singleshell_ss3t_ACT-hsvs except FSL’s FAST is used for tissue segmentation. This workflow is not recommended. This workflow produces MRtrix3 DWI Outputs.

mrtrix_singleshell_ss3t_noACT

This workflow uses the ss3t_csd_beta1 algorithm [7] to estimate FODs for white matter, and cerebrospinal fluid using single shell (DTI) acquisitions. The white matter FODs are used for tractography with no T1w-based anatomical constraints. This workflow produces MRtrix3 DWI Outputs.

pyafq_tractometry

This workflow uses the AFQ [8] implemented in Python [9] to recognize major white matter pathways within the tractography, and then extract tissue properties along those pathways. See the pyAFQ documentation .

PyAFQ Outputs

File Name

Description

sub-* (directory)

PyAFQ results direcrory for each subject

mrtrix_multishell_msmt_pyafq_tractometry

Identical to pyafq_tractometry except that tractography generated using IFOD2 from MRTrix3, instead of using pyAFQ’s default DIPY tractography. This can also be used as an example for how to import tractographies from other reconstruciton pipelines to pyAFQ. This workflow produces MRtrix3 DWI Outputs.

PyAFQ Outputs

File Name

Description

sub-* (directory)

PyAFQ results direcrory for each subject

amico_noddi

This workflow estimates the NODDI [10] model using the implementation from AMICO [11]. Images with intra-cellular volume fraction (ICVF), isotropic volume fraction (ISOVF), orientation dispersion (OD) are written to outputs. Additionally, a DSI Studio fib file is created using the peak directions and ICVF as a stand-in for QA to be used for tractography.

Scalar Maps

Model

Parameter

Description

noddi

direction

Peak directions from NODDI

noddi

icvf

Intracellular volume fraction from NODDI

noddi

isovf

Isotropic volume fraction from NODDI

noddi

od

Orientation dispersion index from NODDI

Other Outputs

File Name

Description

*model-noddi*_config.pickle.gz

A config file internally used by AMICO.

*model-noddi*param-direction*_dwimap.fib.gz

DSI Studio fib format file where the peak directions come from the NODDI fit. The “qa” variable is actually ICVF.

dsi_studio_gqi

Here the standard GQI plus deterministic tractography pipeline is used [12]. GQI works on almost any imaginable sampling scheme because DSI Studio will internally interpolate the q-space data so symmetry requirements are met. GQI models the water diffusion ODF, so ODF peaks are much smaller than you see with CSD. This results in a rather conservative peak detection, which greatly benefits from having more diffusion data than a typical DTI.

5 million streamlines are created with a maximum length of 250mm, minimum length of 30mm, random seeding, a step size of 1mm and an automatically calculated QA threshold.

Additionally, a number of anisotropy scalar images are produced such as QA, GFA and ISO.

Scalar Maps

Model

Parameter

Description

gqi

gfa

Generalized Fractional Anisotropy

gqi

iso

Isotropic Diffusion

gqi

qa

Fractional Anisotropy from a tensor fit

rdi

rd1

RD1

rdi

rd2

RD2

tensor

ad

AD

tensor

fa

Radial Diffusivity from a tensor fit

tensor

ha

HA

tensor

md

Mean Diffusivity

tensor

rd

Radial Diffusivity

tensor

txx

Tensor fit txx

tensor

txy

Tensor fit txy

tensor

txz

Tensor fit txz

tensor

tyy

Tensor fit tyy

tensor

tyz

Tensor fit tyz

tensor

tzz

Tensor fit tzz

Other Outputs

File Name

Description

*_connectivity.mat

MATLAB format mat file containing connectivity matrices for all the selected atlases. This is an hdf5-format file and can be read using scipy.io.matlab.loadmat in Python.

*space-T1w*_dwimap.fib.gz

DSI Studio fib format containing the GQI ODFs used for AutoTrack.

*space-T1w*_mapping.map.gz

Mapping file produced by DSI Studio.

dsi_studio_autotrack

This workflow implements DSI Studio’s q-space diffeomorphic reconstruction (QSDR), the MNI space (ICBM-152) version of GQI, followed by automatic fiber tracking (autotrack) [13][14] of 56 white matter pathways. Autotrack uses a population-averaged tractography atlas (based on HCP-Young Adult data) to identify tracts of interest in individual subject’s data. The autotrack procedure seeds deterministic fiber tracking with randomized parameter saturation within voxels that correspondto each tract in the tractography atlas and determines whether generated streamlines belong to the target tract based on the Hausdorff distance between subject and atlas streamlines.

Reconstructed subject-specific tracts are written out as .tck files that are aligned to the qsirecon-generated _dwiref.nii.gz and preproc_T1w.nii.gz volumes; .tck files can be visualized overlaid on these volumes in mrview or MI-brain. Note, .tck files will not appear in alignment with the dwiref/T1w volumes in DSI Studio due to how the .tck files are read in.

Diffusion metrics (e.g., dti_fa, gfa, iso,rdi, nrdi02) and shape statistics (e.g., mean_length, span, curl, volume, endpoint_radius) are calculated for subject-specific tracts and written out in an AutoTrackGQI.csv file.

Scalar Maps

Model

Parameter

Description

gqi

gfa

Generalized Fractional Anisotropy

gqi

iso

Isotropic Diffusion

gqi

qa

Fractional Anisotropy from a tensor fit

rdi

rd1

RD1

rdi

rd2

RD2

tensor

ad

AD

tensor

fa

Radial Diffusivity from a tensor fit

tensor

ha

HA

tensor

md

Mean Diffusivity

tensor

rd

Radial Diffusivity

tensor

txx

Tensor fit txx

tensor

txy

Tensor fit txy

tensor

txz

Tensor fit txz

tensor

tyy

Tensor fit tyy

tensor

tyz

Tensor fit tyz

tensor

tzz

Tensor fit tzz

Other Outputs

File Name

Description

*_streamlines.tck.gz

One tck.gz per bundle. The bundle represented by this file is specified in the bundle- tag.

*bundles-DSIStudio*_scalarstats.csv

Statistics on scalars produced by this workflow

*bundles-DSIStudio*_tdistats.tsv

Statistics on streamline density in voxels

*space-T1w*_dwimap.fib.gz

DSI Studio fib format containing the GQI ODFs used for AutoTrack.

*space-T1w*_mapping.map.gz

Mapping file produced by DSI Studio.

ss3t_autotrack

This workflow is identical to dsi_studio_autotrack, except it substitutes the GQI fit with the ss3t_csd_beta1 algorithm [7] to estimate FODs for white matter.

This is a good workflow for doing tractometry on low-quality single shell data.

Scalar Maps

Model

Parameter

Description

gqi

gfa

Generalized Fractional Anisotropy

gqi

iso

Isotropic Diffusion

gqi

qa

Fractional Anisotropy from a tensor fit

rdi

rd1

RD1

rdi

rd2

RD2

tensor

ad

AD

tensor

fa

Radial Diffusivity from a tensor fit

tensor

ha

HA

tensor

md

Mean Diffusivity

tensor

rd

Radial Diffusivity

tensor

txx

Tensor fit txx

tensor

txy

Tensor fit txy

tensor

txz

Tensor fit txz

tensor

tyy

Tensor fit tyy

tensor

tyz

Tensor fit tyz

tensor

tzz

Tensor fit tzz

Other Outputs

File Name

Description

*_streamlines.tck.gz

One tck.gz per bundle. The bundle represented by this file is specified in the bundle- tag.

*bundles-DSIStudio*_scalarstats.csv

Statistics on scalars produced by this workflow

*bundles-DSIStudio*_tdistats.tsv

Statistics on streamline density in voxels

*space-T1w*_dwimap.fib.gz

DSI Studio fib format containing the SS3T FODs used for AutoTrack.

*space-T1w*_mapping.map.gz

Mapping file produced by DSI Studio.

TORTOISE

The TORTOISE [15] software can calculate Tensor and MAPMRI fits, along with their many associated scalar maps. This workflow only produces scalar maps.

Scalar Maps

Model

Parameter

Description

mapmri

ng

Non-Gaussianity from MAPMRI

mapmri

ngpar

Non-Gaussianity parallel from MAPMRI

mapmri

ngperp

Non-Gaussianity perpendicular from MAPMRI

mapmri

pa

PA from MAPMRI

mapmri

path

PAth from MAPMRI

mapmri

rtap

Return to axis probability from MAPMRI

mapmri

rtop

Return to origin probability from MAPMRI

mapmri

rtpp

Return to plane probability from MAPMRI

tensor

ad

Apparent Diffusivity from a tensor fit

tensor

am

A0 from a tensor fit

tensor

fa

Fractional Anisotropy from a tensor fit

tensor

li

LI from a tensor fit

tensor

rd

Radial Diffusivity from a tensor fit

Other Outputs

File Name

Description

*_scalarstats.tsv

TORTOISE scalars (tensors and MAPMRI) summarized within WM bundles. The name of the method used to create the bundles is specified after bundles-.

dipy_mapmri

The MAPMRI method is used to estimate EAPs from which ODFs are calculated analytically. This method produces scalars like RTOP, RTAP, QIV, MSD, etc.

The ODFs are saved in DSI Studio format and tractography is run identically to that in dsi_studio_gqi.

Scalar Maps

Model

Parameter

Description

mapmri

lapnorm

Laplacian norm from regularized MAPMRI (MAPL)

mapmri

mapcoeffs

MAPMRI coefficients

mapmri

msd

mean square displacement from MAPMRI

mapmri

ng

Non-Gaussianity from MAPMRI

mapmri

ngpar

Non-Gaussianity parallel from MAPMRI

mapmri

ngperp

Non-Gaussianity perpendicular from MAPMRI

mapmri

qiv

q-space inverse variance from MAPMRI

mapmri

rtap

Return to axis probability from MAPMRI

mapmri

rtop

Return to origin probability from MAPMRI

mapmri

rtpp

Return to plane probability from MAPMRI

Other Outputs

File Name

Description

*_scalarstats.tsv

MAPMRI scalars summarized within WM bundles. The name of the method used to create the bundles is specified after bundles-.

dipy_dki

A DKI model is fit to the dMRI signal and multiple scalar maps are produced.

Scalar Maps

Model

Parameter

Description

dki

ad

DKI AD

dki

ak

DKI AK

dki

kfa

DKI KFA

dki

md

DKI MD

dki

mk

DKI MK

dki

mkt

DKI MKT

dki

rd

DKI RD

dki

rk

DKI RK

tensor

fa

DKI FA

Other Outputs

File Name

Description

*_scalarstats.tsv

DKI scalars summarized within WM bundles. The name of the method used to create the bundles is specified after bundles-.

dipy_3dshore

This uses the BrainSuite 3dSHORE basis in a Dipy reconstruction. Much like dipy_mapmri, a slew of anisotropy scalars are estimated. Here the dsi_studio_gqi fiber tracking is again run on the 3dSHORE-estimated ODFs.

Scalar Maps

Model

Parameter

Description

3dshore

CNR

Contrast to noise ratio for 3dshore fit

3dshore

alpha

alpha used when fitting in each voxel

3dshore

lapnorm

Laplacian norm from regularized MAPMRI (MAPL)

3dshore

mapcoeffs

MAPMRI coefficients

3dshore

msd

mean square displacement from MAPMRI

3dshore

ng

Non-Gaussianity from MAPMRI

3dshore

ngpar

Non-Gaussianity parallel from MAPMRI

3dshore

ngperp

Non-Gaussianity perpendicular from MAPMRI

3dshore

qiv

q-space inverse variance from MAPMRI

3dshore

r2

r^2 of the 3dshore fit

3dshore

regularization

regularization of the 3dshore fit

3dshore

rtap

Return to axis probability from MAPMRI

3dshore

rtop

Return to origin probability from MAPMRI

3dshore

rtpp

Return to plane probability from MAPMRI

reorient_fslstd

Reorients the qsirecon preprocessed DWI and bval/bvec to the standard FSL orientation. This can be useful if FSL tools will be applied outside of qsirecon.

csdsi_3dshore

[EXPERIMENTAL] This pipeline is for DSI or compressed-sensing DSI. The first step is a L2-regularized 3dSHORE reconstruction of the ensemble average propagator in each voxel. These EAPs are then used for two purposes

  1. To calculate ODFs, which are then sent to DSI Studio for tractography

  2. To estimate signal for a multishell (specifically HCP) sampling scheme, which is run through the pipeline

All outputs, including the imputed HCP sequence are saved in the outputs directory.

Scalar Maps

Model

Parameter

Description

3dshore

CNR

Contrast to noise ratio for 3dshore fit

3dshore

alpha

alpha used when fitting in each voxel

3dshore

lapnorm

Laplacian norm from regularized MAPMRI (MAPL)

3dshore

mapcoeffs

MAPMRI coefficients

3dshore

msd

mean square displacement from MAPMRI

3dshore

ng

Non-Gaussianity from MAPMRI

3dshore

ngpar

Non-Gaussianity parallel from MAPMRI

3dshore

ngperp

Non-Gaussianity perpendicular from MAPMRI

3dshore

qiv

q-space inverse variance from MAPMRI

3dshore

r2

r^2 of the 3dshore fit

3dshore

regularization

regularization of the 3dshore fit

3dshore

rtap

Return to axis probability from MAPMRI

3dshore

rtop

Return to origin probability from MAPMRI

3dshore

rtpp

Return to plane probability from MAPMRI

Other Outputs

File Name

Description

*_scalarstats.tsv

MAPMRI scalars summarized within WM bundles. The name of the method used to create the bundles is specified after bundles-.

hbcd_scalar_maps

Designed to run on [HBCD](https://hbcdstudy.org/) data, this is also a general-purpose way to get many multishell-supported fitting methods, including

Bundles are generated using dsi_studio_autotrack. All the scalars generated by these models are then mapped

  1. Into template space

  2. On to the bundles from dsi_studio_autotrack

In total, the scalars estimated by this workflow are:

Scalar Maps

Model

Parameter

Description

dki

ad

DKI AD

dki

ak

DKI AK

dki

kfa

DKI KFA

dki

md

DKI MD

dki

mk

DKI MK

dki

mkt

DKI MKT

dki

rd

DKI RD

dki

rk

DKI RK

gqi

gfa

Generalized Fractional Anisotropy

gqi

iso

Isotropic Diffusion

gqi

qa

Fractional Anisotropy from a tensor fit

mapmri

ng

Non-Gaussianity from MAPMRI

mapmri

ngpar

Non-Gaussianity parallel from MAPMRI

mapmri

ngperp

Non-Gaussianity perpendicular from MAPMRI

mapmri

pa

PA from MAPMRI

mapmri

path

PAth from MAPMRI

mapmri

rtap

Return to axis probability from MAPMRI

mapmri

rtop

Return to origin probability from MAPMRI

mapmri

rtpp

Return to plane probability from MAPMRI

noddi

direction

Peak directions from NODDI

noddi

icvf

Intracellular volume fraction from NODDI

noddi

isovf

Isotropic volume fraction from NODDI

noddi

od

Orientation dispersion index from NODDI

rdi

rd1

RD1

rdi

rd2

RD2

tensor

ad

AD

tensor

am

A0 from a tensor fit

tensor

fa

DKI FA

tensor

fa

Fractional Anisotropy from a tensor fit

tensor

fa

Radial Diffusivity from a tensor fit

tensor

ha

HA

tensor

li

LI from a tensor fit

tensor

md

Mean Diffusivity

tensor

rd

Radial Diffusivity

tensor

txx

Tensor fit txx

tensor

txy

Tensor fit txy

tensor

txz

Tensor fit txz

tensor

tyy

Tensor fit tyy

tensor

tyz

Tensor fit tyz

tensor

tzz

Tensor fit tzz

Other Outputs

File Name

Description

*_connectivity.mat

MATLAB format mat file containing connectivity matrices for all the selected atlases. This is an hdf5-format file and can be read using scipy.io.matlab.loadmat in Python.

*space-T1w*_dwimap.fib.gz

DSI Studio fib format containing the GQI ODFs used for AutoTrack.

*space-T1w*_mapping.map.gz

Mapping file produced by DSI Studio.

Which workflows are appropriate for your dMRI data?

Most reconstruction workflows will fit a model to the dMRI data. Listed below are the model-fitting workflows and which sampling schemes work with them.

Name

MultiShell

Cartesian

SingleShell

mrtrix_multishell_msmt_ACT-fast*

Yes

No

No

mrtrix_multishell_msmt_ACT-hsvs

Yes

No

No

mrtrix_multishell_msmt_noACT

Yes

No

No

mrtrix_singleshell_ss3t_noACT

No

No

Yes

mrtrix_singleshell_ss3t_ACT-hsvs

No

No

Yes

mrtrix_multishell_msmt_ACT-fast*

No

No

Yes

pyafq_tractometry

Yes

No

Yes

mrtrix_multishell_msmt_pyafq_tractometry

Yes

No

Yes

amico_noddi

Yes

No

No

TORTOISE

Yes

No

No

dsi_studio_gqi

Yes

Yes

Yes*

dsi_studio_autotrack

Yes

Yes

Yes

ss3t_autotrack

No

No

Yes

dipy_mapmri

Yes

Yes

No

dipy_dki

Yes

No

No

dipy_3dshore

Yes

Yes

No

csdsi_3dshore

Yes

Yes

No

hbcd_scalar_maps

Yes

No

No

* Not recommended

References