Tensor Distribution Function code


Diffusion magnetic resonance imaging (dMRI) is a powerful tool for studying white matter microstructure features such as white matter connectivity and integrity in the human brain. Diffusion Tensor Imaging (DTI) has been the gold standard for measuring white matter microstructure, but DTI is not sufficient to resolve fiber crossings and intermixing of tracts.

Since the tensor distribution function (TDF) represents the diffusion profile as a probabilistic mixture of tensors, it can be used to reconstruct multiple underlying fibers.


1. Step1 instructions :
Step1 <4D_DWI> [l_low l_low_val] [l_step l_step_val] [l_high l_high_val]
Paramteres explained:

  • bval, bvec, 4D_DWI, mask – same parameters that you would feed to dtifit or any other diffusion reconstruction program
  • output_folder – folder where .mat files will be put (they will be used at Steps 2 and 3)
  • [l_low l_low_val] – lower limit for lambda sampling. Standard is l_low 0.2
  • [l_step l_step_val] – step for lambda sampling. Standard is l_step 0.2
  • [l_high l_high_val] – upper limit for lambda sampling. Standard is l_high 2.0

2. Step2 instructions :
Step2_v2 [s s_val] [postfix postfix_val] [p p_thr_val] [qp qp_val] [qp_solver {qpip/quadprog}] [output_predicted output_predicted_val] [alpha alpha_val] [crossval_subj crossval_subj_dir]
Parameters explained:

  • <input_dir> – direction with subj.mat, samp1.mat, samp2.mat, brain_mask.nii – output of Step1
  • <segment_ID> – id of the segment processed (used for parallelization)
  • <segments_total> – total number of segment. amount of qsub processes with segment id from 1 to N should be equal to segments_total=N
  • [s s_val] – type of sampling. Use s 1 for sampling 1 (10 lower level – 40 upper level directions). Use s 2 for sampling 2 (40 lower level – 160 upper level directions). Please mind that s 2 DOES NOT MAKE SENSE, as the problem is way underdetermined.
  • [postfix postfix_val] – postfix for resulting files. Useful for testing fitting with different parameters
  • [p p_thr_val] – threshold value for upsampling for Tensor Orientation Distribution. For instance p 0.1 will upsample all directions where TOD>0.1
  • [qp qp_val] – if you are planning to use Quadratic Programming. Your only option is qp 1, as gradient descent does not make sense in current setting.
  • [qp_solver {qpip/quadprog}] – which solver you are going to use for QP. qp_solver qpip – this one: quadprog – standard MATLAB solver.
  • [output_predicted output_predicted_val] – whether you want to output predicted signal. output_predicted 1 will write to resulting mat files the predicted signal from the model
  • [alpha alpha_val] – alpha is the over-relaxation parameter 0.2
  • [crossval_subj crossval_subj_dir] – directory where subjects for cross-prediction (see rRMSE idea) resides. if you set this paramter, the algorithm will predict signal from b0 and bvecs of crossval_subject.

3. Step3 instructions :
Step3 Step3 gathers together all outputs from Step2 and results in nifti files for TDF_FA, TDF_DWI_predicted, TDF_DWI_crossval_predicted, etc. Parameters explained:

Step3 <input_dir> <segments_total> <thr_series> <postfix>

Step3 gathers together all outputs from Step2 and results in nifti files for TDF_FA, TDF_DWI_predicted, TDF_DWI_crossval_predicted, etc. Parameters explained:

<input_dir> – folder with subject data (with results of Step1 and Step2_v2) <segments_total> – total amount of segments processed on Step2_v2. It must match the amount of files with results from Step2. It also must match <segments_total> which was an input to Step2_v2 <thr_series> – it is obsolete, just use any number – postfix you used on Step2


  • Leow, A. D., Zhu, S., Zhan, L., McMahon, K., de Zubicaray, G. I., Meredith, M., … & Thompson, P. M. (2009). The tensor distribution function. Magnetic Resonance in Medicine: An Official Journal of the International Society for Magnetic Resonance in Medicine, 61(1), 205-214.
  • Zhan, L., Leow, A. D., Jahanshad, N., Chiang, M. C., Barysheva, M., Lee, A. D., … & Thompson, P. M. (2010). How does angular resolution affect diffusion imaging measures?. Neuroimage, 49(2), 1357-1371.
  • Zhan, L., Leow, A. D., Zhu, S., Barysheva, M., Toga, A. W., McMahon, K. L., … & Thompson, P. M. (2009, September). A novel measure of fractional anisotropy based on the tensor distribution function. In International Conference on Medical Image Computing and Computer-Assisted Intervention (pp. 845-852). Springer, Berlin, Heidelberg.
  • Isaev, D. Y., Nir, T. M., Jahanshad, N., Villalon-Reina, J. E., Zhan, L., Leow, A. D., & Thompson, P. M. (2017, January). Improved clinical diffusion MRI reliability using a tensor distribution function compared to a single tensor. In 12th International Symposium on Medical Information Processing and Analysis (Vol. 10160, p. 101601K). International Society for Optics and Photonics.