dMRI-Lab 1.0
atti2mapl.m File Reference

Functions

function atti2mapl (in dwifile, in gifile, in bifile, in maplfile, in dtifile, in loptfile, in varargin)
 

Function Documentation

◆ atti2mapl()

function atti2mapl ( in dwifile,
in gifile,
in bifile,
in maplfile,
in dtifile,
in loptfile,
in varargin )

Computes the coefficients of the MAP-MRI signal model as described by Ozarslan et al:

     Ozarslan E, Koay CG, Shepherd TM, Komlosh ME, Irfanoglu MO, Pierpaoli C, Basser PJ. "Mean apparent propagator (MAP) MRI: a 
     novel diffusion imaging method for mapping tissue microstructure". Neuroimage. 2013 Sep; 78:16-32.

The attenuation signal is represented as a combination of Hermite functions (separable for each space direction) in a transformed "anatomical space" that comes from the rotation and stretching of the original space according to the tensor model previously computed. To fit the model, we use the MAPL (Laplacian-regularized) model described by Fick et al:

     Fick RHJ, Wassermann D, Caruyer E, Deriche R. "MAPL: Tissue microstructure estimation using Laplacian-regularized MAP-MRI and its application to HCP data". Neuroimage. 2016 Jul; 134:365-385.  
Parameters
dwifileA string specifying the file containing the diffusion-weighted images.
gifileA string specifying the file containing the gradient directions.
bifileA string specifying the file containing the b-values.
maplfileA string specifying the K MAPL coefficients computed at each voxel within the field of view.
dtifileA string specifying the file to save the estimated tensor model at each voxel.
loptfileA string specifying the file to save the regularization parameter used to weight the energy of the Laplacian at each voxel.
vararginOptional arguments passed as -name value pairs (e.g. -wlsit 5).
Returns
- maplfile: The K MAPL coefficients computed at each voxel within the field of view.
- dtifile: The file to save the estimated tensor model at each voxel.
- loptfile: The file to save the regularization parameter used to weight the energy of the Laplacian at each voxel.

Mandatory Inputs:

  • dwifile: A string specifying the file containing the diffusion-weighted images.
  • gifile: A string specifying the file containing the gradient directions.
  • bifile: A string specifying the file containing the b-values.
  • maplfile: A string specifying the K MAPL coefficients computed at each voxel within the field of view.
  • dtifile: A string specifying the file to save the estimated tensor model at each voxel.
  • loptfile: A string specifying the file to save the regularization parameter used to weight the energy of the Laplacian at each voxel.
  • varargin: Optional arguments passed as -name value pairs.

Optional Arguments General Optional Parameters:

  • Nmax: the maximum degree of the Hermite polynomials used in the expansion, must be an even integer >=0 (default: 4).
  • lambda: this is a regularization parameter that penalizes highly irregular solutions of the signal. In precise terms, the quadratic deviation from the linear model is added lambda times the energy of the Laplacian of the signal to compute the final cost function:
    • If lambda is a finite, positive number, then this fixed value is used for all voxels.
    • If lambda is empty, or is NaN, or is Inf, or is negative, then the appropriate value is estimated at each voxel using Generalized Cross Validatio. Note this will dramatically increase the processing time, since a large number of matrix inversions have to be performed at each voxel. (default: 0.2, i.e. NO GCV is used).
  • tl, tu: the lower and upper thresholds, respectively, defining the range the atti will lay within, so that tl should be close to 0 and tu should be close to 1 (default: 1.0e-7, 1-1.0e-7).
  • bcut: b-values over this value are ignored to estimate the diffusion tensor, which is used to transform the native space to the anatomical space (default: 2000 s/mm^2).
  • ADC0: estimated diffusivity of free water at body temperature. It is used to determine the lower and upper bounds of the eigenvalues of the dti and perform sanity checks (default: 3.0e-3).
  • tau: the effective diffusion time of the acquisition, in seconds, necessary to determine the regularization matrix (default: 35e-3).
  • const: whether (true) or not (false) constrain the estimated MAPL coefficients to fulfill two conditions:
    • E(q) = 1.0
    • P(R) >= 0 at a pre-defined set of values of R With these constraints, the estimation has a rigorous physical meaning but a quadratic problem must be solved at each voxel. Without it, we just need to solve an unconstrained least squares problem, which will be pretty faster (default: true, i.e. use constraints).
  • constRad: if const is set true, inequality constraints of the form P(x_i,y_i,z_i) >= 0, i=1..CI are enforced in the quadratic program. This option controls the value of CI. In brief: a 3-D meshgrid of (2*constRad+1)x(2*constRad+1)x(2*constRad+1) points is arranged in the normalized (anatomical) R-space. Then, half of these points are discarded due to antipodal symmetry, and the remaining points are used for the constraints. This way, CI = ( (2*constRad+1)^3 + 1 )/2 (default: 5, hence CI=666).

Other General Options:

  • maxthreads: the algorithm is run as a multi-threaded mex. This is the maximum allowed number of threads, which can indeed be reduced if it exceeds the number of logical cores (default: the number of logical cores in the machine).
  • mask: a MxNxP array of logicals. Only those voxels where mask is true are processed, the others are filled with zeros (default: all trues).

Example:

atti2mapl dwifile.nii gifile.bvec bifile.bval maplfile.nii dtifile.nii loptfile.nii -mask mask_file.nii
function atti2mapl(in dwifile, in gifile, in bifile, in maplfile, in dtifile, in loptfile, in varargin)
Note
This is the simplest use case
See also
atti2mapl