dMRI-Lab 1.0
micro2moments.m File Reference

Functions

function micro2moments (in shfile, in lambdaparfile, in lambdaperpfile, in ffile, in mufile, in varargin)
 

Function Documentation

◆ micro2moments()

function micro2moments ( in shfile,
in lambdaparfile,
in lambdaperpfile,
in ffile,
in mufile,
in varargin )

This function computes moments (either full, axial, or planar) of arbitrary orders over either the attenuation signal E(q) or the diffusion propagator P(R) according to a linear convolutional model:

             atti(u,b) = Integral_{S}Phi(v)exp(-b*((lpar-lperp)(u*v)^2+lperp))dv,

where lpar and lperp parameterize the impulse response as an elemental rank-2 tensor and the ODF, Phi(v), is modeled through its SH expansion over the unit sphere. Either type of moments are defined as:

             mu_{full,E}^{nu}       = Integral_{R^3} ||q||^{nu} E(q) dq^3
             mu_{axial,E}^{nu}(u0)  = Integral_{R}   t^{nu} E(t*u0) dt
             mu_{planar,E}^{nu}(u0) = Integral_{v \perp u0} ||v||^{nu} E(v) dv^2
             mu_{full,P}^{nu}       = Integral_{R^3} ||R||^{nu} P(R) dR^3
             mu_{axial,P}^{nu}(r0)  = Integral_{R^3} t^{nu} P(t*r0) dt
             mu_{planar,P}^{ru}     = Integral_{s \perp r0} ||s||^{nu} P(s) ds^2

where nu>-3 for full moments, nu > -1 for axial moments, and nu > -2 for planar moments. In all cases, nu can be any real number, though the computation of integer moments is computationally more efficient and reliable. Most of the common diffusion measurements are described with this scheme:

             RTOP = mu_{full,E}^0, RTPP = mu_{axial,E}^0(u_max), RTAP = mu_{planar,E}^0(u_max), QMSD = mu_{full,E}^2, MSD = mu_{full,P}^2... 
Parameters
shfileA string specifying the file containing the SH coefficients of the ODF at each voxel up to order L. Should be computed with micro2shodf.
lambdaparfileA string specifying the file containing the parallel diffusivity modeling the impulse response (should fulfill 0<lpar<=Diso). This is obtained with atti2micro.
lambdaperpfileA string specifying the file containing the perpendicular diffusvity modeling the impulse response (should fulfill 0<lerp<lpar). This is obtained with atti2micro.
ffileA string specifying the file containing the partial volume fraction of intra-cellular water (should fulfill 0<=f<=1). If an empty array is passed, then f=1 for all voxels is assumed, so that ones(M,N,P) has the same effect as [].
mufileA string specifying the file to save the moment.
vararginOptional arguments passed as -name value pairs (e.g. -chunksz 256).
Returns
- mufile: The moment requested.

Mandatory Inputs:

  • shfile: A string specifying the file containing the SH coefficients of the ODF at each voxel up to order L. Should be computed with micro2shodf.
  • lambdaparfile: A string specifying the file to save the elemental diffusivity along the parallel direction.
  • lambdaperpfile: A string specifying the file to save the elemental diffusivity along the perpendicular direction.
  • ffile: A string specifying the file containing the partial volume fraction of intra-cellular water (should fulfill 0<=f<=1). If an empty array is passed, then f=1 for all voxels is assumed, so that ones(M,N,P) has the same effect as [].
  • mufile: A string specifying the file to save the moment.
  • varargin: Optional arguments passed as -name value pairs (e.g. -chunksz 256).

Optional Arguments - General Optional Parameters:

  • type: 1x2 string array, one of 'Ef', 'Ea', 'Ep', 'Pf', 'Pa', Pp', the first character indicating the signal the moment is computed over and the second one if it is either full, axial, or planar. Alternatively, you can specify either of 'rtop', 'rtpp', 'rtap', 'qmsd', or 'msd' (default: 'rtop').
  • nu: 1x1 double (or []) with the order of the moment to be computed. If you specified a particular measure in 'type' (e.g. 'rtop'), this is not used and may be left empty (default: not used).
  • mask: a MxNxP array of logicals. Only those voxels where mask is true are processed, the others are filled with zeros (default: all trues).
  • u0: only used for axial and planar moments; MxNxPx3 double array with the directions u0 for which axial and planar moments are computed. If left empty, [], the direction of maximum diffusivity will be internally computed and used (default: []).

Sanity Checks On The Micro-Structure Model:

  • chkmod: Whether (true) or not (false) perform sanity checks over lpar and lperp as provided by atti2micro. If true, three corrections are performed:
    • lpar is ensured to be in the range (ADC0/20,ADC0);
    • lperp is ensured to be greater than lpar*flperp (see below);
    • lperp is ensured to be less than lpar*Flperp (see below). (default: true)
  • flperp: If chkmod == true, this parameter provides a lower threshold for lperp as a function of lpar (default: 0.001).
  • Flperp: If chkmod == true, this parameter provides an upper threshold for lperp as a function of lpar (default: 0.999).
  • ADC0: Estimated diffusivity of free water at body temperature (Diso). Should use the same as in atti2micro (default: 3.0e-3).

Advanced Parameters:

  • tau: 1x1, the effective diffusion time of the dMRI sequence in miliseconds (default: 70.0e-3).
  • chunksz: The evaluation of SH at desired directions is done by repeatedly calling GenerateSHMatrix. This is done chunk-by-chunk for efficiency (default: 256).
  • clean: 1x1 double in the range [0,100]. This is a simple outlier rejection parameter to avoid out-of-range values: 0 means no outlier rejection is applied; >0 means outlier rejection is applied, the closer to 100 the more aggressive. You should use this flag just for visualization purposes, but not for actual quantitative analyses (default: 0).

Examples:

micro2moments shfile.nii lambdaparfile.nii lambdaperpfile.nii ffile.nii mufile.nii -mask mask_file.nii
function micro2moments(in shfile, in lambdaparfile, in lambdaperpfile, in ffile, in mufile, in varargin)
Note
This is the simplest use case
See also
micro2moments