Options and Usage for TMI

This page describes each optional argument to TMI. For specific use-case examples of TMI calls, please see the examples page.

Main usage: tmi <input> <output>

input

Input to tmi can be any diffusion MRI image file that is compatible with mrtrix3 as an input. Ideally the input to tmi is the output from the deisgner preprocessing pipeline.

output

Name of the folder which will contain parameter images.

By default, if none of the below options are used, TMI will not estimate parameters for the input data. TMI uses mrconvert from mrtrix3 as its image conversion workhorse and can therefore handle any input image data type that mrtrix3 can, including .nii, .nii.gz, .mgh, .mgz, .mif, .mif.gz, .img/.hdr, or dicom inputs (when the inputs are folder names that contain dicom data).

Table of contents

  1. input
  2. output
  3. Options for tensor estimation
    1. -DTI
    2. -DKI
    3. -WDKI
    4. -fit_constraints <0,0,0>
  4. Options for outlier replacement
    1. -akc_outliers
    2. -fit_smoothing <percentile>
  5. Options for model estimation
    1. -SMI
    2. -WMTI
    3. -compartments <IAS,EAS,FW>
    4. -sigma <noisemap>
    5. -lmax <lmax (0,2,4,6)>
    6. -bshape <beta1,beta2,...>
    7. -echo_time <TE1,TE2,...>
    8. -maxb <b-value>
  6. Other options for TMI
    1. -mask <mask>
    2. -datatype <dtype>
    3. -fslbvec <bvecs>
    4. -fslbval <bvals>
    5. -bids <bids>
    6. -n_cores <ncpus>
    7. -nocleanup
    8. -scratch </path/to/scratch>
  7. Standard options for Mrtrix3 executables
    1. -info
    2. -quiet
    3. -debug
    4. -force
    5. -nthreads
    6. -config key value
    7. -help

Options for tensor estimation

-DTI

  • Perform DTI fitting using weighted linear least squares.
  • Include diffusion tensor parameters in output folder.
  • Parameters extracted from the kurtosis tensor are labelled as *_dti.nii (e.g. ad_dti.nii, fa_dti.nii).
  • When the DTI option is used, b-shells greater than 1000 are automatically excluded from tensor estimation.

-DKI

  • Perform DKI fitting using weighted linear least squares.
  • Include diffusion kurtosis parameters in output folder.
  • Parameters extracted from the diffusion tensor are labelled as *_dki.nii (e.g. ad_dki.nii, fa_dki.nii, mk_dki.nii).
  • When DKI option is used, b-shells greater than 3000 are automatically excluded from tensor estimation.

-WDKI

  • Output folder will also contain kurtosis parameters that are computed using definitions with the kurtosis tensor, unlike the conventional definitions which compute them using averages of the directional kurtosis. For example, for mean kurtosis mk_wdki is simply the angular average of the dimensionless cumulant tensor $\overline{W({\bf \hat{n}})} = \tfrac{1}{4 \pi} \int_{\mathbb{S}^2} d\hat{\mathbf{n}}\, W(\hat{\mathbf{n}})$ while the more standard definition (mk_dki) is the angular average of the directional kurtosis $\overline{K({\bf \hat{n}})} = \tfrac{1}{4 \pi} \int_{\mathbb{S}^2} d\hat{\mathbf{n}}\, K(\hat{\mathbf{n}})= \tfrac{1}{4 \pi} \int_{\mathbb{S}^2} d\hat{\mathbf{n}}\, \frac{\bar{D}^2 W(\hat{\mathbf{n}})}{ {D(\hat{\mathbf{n}})}^2}$.
  • Parameters extracted from the W tensor are labelled as *_wdki.nii (e.g. ad_wdki.nii, fa_wdki.nii, mk_wdki.nii).
  • Note that the estimated tensors (D and W) are identical but how we combine the tensor elements to make kurtosis scalar maps differs (DTI maps with _wdki are identical to those with _dki since there is no conflict with DTI-derived metrics).

-fit_constraints <0,0,0>

  • For use with -DKI or -WDKI
  • A comma separated list of either 0 or 1. Each index corresponds to a hard bound on the kurtosis tensor. Index 1 corresponds to diffusion tensor > 0, index 2 corresponds to kurtosis tensor > 0, index 3 corresponds to kurtosis tensor < 10. An input of 1,1,1 will perform a fully constrained DKI fit, and 0,0,0 will perform an unconstrained fit.
  • Default 0,0,0

Options for outlier replacement

-akc_outliers

  • Brute force K tensor outlier detection and filtering. The kurtosis tensor is projected onto a sphere with 10,000 directions. Voxels where mean kurtosis is less than -1 or greater than 10 are labelled as outliers.
  • Outliers are replaced by the median value of neighboring (26 adjacent) non-outlier voxels in all diffusion weighted images and the DKI fit is done again.

-fit_smoothing <percentile>

  • Windowed adaptive nonlocal means filter on the dwi.
  • Diffusion weighted images undergo an NLM filter over the most similar neighboring pixels and directions prior to fitting.
  • For each voxel we take a cubic patch in 4d and take the mean over the $n$ most similar voxels in xyz and q-space. n is decided by the input argument to tmi, where with n=10 (default) we are smoothing over the 10% most similar voxels, and so on.
  • If used in conjunctions with -akc_outliers outliers are detected and ignored during the smoothing process.
  • The <percentile> Defines the degree of similar voxels in a sliding window patch to average. A percentile of 10 will average the 10% most similar voxels and directions in the sliding window. We recommend a percentile of 10 as a starting point for tuning this option.

Options for model estimation

-SMI

  • Perform estimation of the Standard Model of WHite Matter.
  • Use in conjunction with -compartments, -sigma, -bshape, and -echo_time options.
  • We recommend prior estimation of the noise level sigma using designer along with the -denoise option.

-WMTI

  • Include WMTI parameters in output folder (awf,ias_params,eas_params).
  • WMTI estimation is performed using the dipy package.

-compartments <IAS,EAS,FW>

  • SMI compartments (IAS, EAS, and FW) expressed as a comma separated string.
  • default: IAS,EAS

-sigma <noisemap>

  • Path to noise map for SMI parameter estimation. Not required but recommended.
  • We recommend computing sigma prior to running tmi using designer.

-lmax <lmax (0,2,4,6)>

  • Value of L-max to use for SMI parameter estimation.
  • Reasonable values of L-max will be computed automatically if this option is not used.
  • L-max should be 0, 2, 4, or 6.

-bshape <beta1,beta2,...>

  • Specify the b-shape used in the acquisition (comma separated list the same length as number of inputs).

-echo_time <TE1,TE2,...>

  • Specify the echo time used in the acquisition (comma separated list the same length as number of inputs).

-maxb <b-value>

  • Specify the maxmimum b-value to use during DKI estimation.
  • Units should be in ms/µm^2.
  • default maximum b-value for DKI estimation is 3.0 ms/µm^2

Other options for TMI

-mask <mask>

  • Perform parameter estimation within the specified brain mask.

-datatype <dtype>

  • Specify the output datatype. Valid options are float32, float32le, float32be, float64, float64le, float64be, int64, uint64, int64le, uint64le, int64be, uint64be, int32, uint32, int32le, uint32le, int32be, uint32be, int16, uint16, int16le, uint16le, int16be, uint16be, cfloat32, cfloat32le, cfloat32be, cfloat64, cfloat64le, cfloat64be, int8, uint8, bit.

-fslbvec <bvecs>

  • Specify bvec path if path is different from the path to the dwi(s) or the file has an unusual extension.

-fslbval <bvals>

  • Specify bval path if path is different from the path to the dwi(s) or the file has an unusual extension.

-bids <bids>

  • Specify BIDS .json path(s) if different from the path to the dwi or the file has an unusual extension.

-n_cores <ncpus>

  • Specify the number of cores to use in parallel tasks, by default TMI will use total available cores - 2.
  • Parallel tasks include -denoise, -degibbs, and -eddy (when eddy_openmp is the eddy backend).

-nocleanup

  • Do not delete intermediate files during script execution, and do not delete scratch directory at script completion.

-scratch </path/to/scratch>

  • Manually specify the path in which to generate the scratch directory.

Standard options for Mrtrix3 executables

-info

  • Display information messages.

-quiet

  • Do not display information messages or progress status. Alternatively, this can be achieved by setting the MRTRIX_QUIET environment variable to a non-empty string.

-debug

  • Display debugging messages.

-force

  • Force overwrite of output files.

-nthreads

  • Use this number of threads in multi-threaded applications (set to 0 to disable multi-threading).
  • Not used in Designer, use -n_cores instead.

-config key value

  • Temporarily set the value of an MRtrix config file entry.
  • Not used in Designer.

-help

  • Display information page and exit.