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 |
*_exemplarbundles.zip |
A zip archive containing the output directory from |
*_streamlines.tck.gz |
Streamlines produced by |
*model-mtnorm*param-inliermask*_dwimap.nii.gz |
Inlier mask created by |
*model-mtnorm*param-norm*_dwimap.nii.gz |
Inlier mask created by |
*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 |
*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 |
*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-fsnative*atlas-hsvs*_dseg.nii.gz |
Hybrid Surface/Voume Segmentation in MRtrix3 5tt format. Aligned to the FreeSurfer |
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 |
*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 |
*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 |
*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 |
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 |
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 |
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
To calculate ODFs, which are then sent to DSI Studio for tractography
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 |
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
Into template space
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 |
*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 |
|---|---|---|---|
Yes |
No |
No |
|
Yes |
No |
No |
|
Yes |
No |
No |
|
No |
No |
Yes |
|
No |
No |
Yes |
|
No |
No |
Yes |
|
Yes |
No |
Yes |
|
Yes |
No |
Yes |
|
Yes |
No |
No |
|
Yes |
No |
No |
|
Yes |
Yes |
Yes* |
|
Yes |
Yes |
Yes |
|
No |
No |
Yes |
|
Yes |
Yes |
No |
|
Yes |
No |
No |
|
Yes |
Yes |
No |
|
Yes |
Yes |
No |
|
Yes |
No |
No |
* Not recommended