dMRI-Lab 1.0
micro2shsqrtodf.m File Reference

Functions

function micro2shsqrtodf (in dwifile, in gifile, in bifile, in lambdaparfile, in lambdaperpfile, in ffile, in shfile, in nitfile, in mufile, in varargin)
 The SH coefficients of the ODF and the SH coefficients of its squared root are analytically related via Wigner's symbols, and the latter are estimated by solving a bi-quadratic problem with a unique quadratic restriction (if the ODF has unit mass, the coefficients vector of its squared root has norm 1).
 

Function Documentation

◆ micro2shsqrtodf()

function micro2shsqrtodf ( in dwifile,
in gifile,
in bifile,
in lambdaparfile,
in lambdaperpfile,
in ffile,
in shfile,
in nitfile,
in mufile,
in varargin )

The SH coefficients of the ODF and the SH coefficients of its squared root are analytically related via Wigner's symbols, and the latter are estimated by solving a bi-quadratic problem with a unique quadratic restriction (if the ODF has unit mass, the coefficients vector of its squared root has norm 1).

Computes the SH coefficients of the squared root of a unit mass, strictly non-negative ODF that best fits the multi-shell attenuation signal atti (with gradients table gi and b-values bi) according to the convolutional model:

           atti(u,b) = (1-f)*exp(-b*Diso) + f*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, f stands for the partial volume fraction of water confined in the neural axons, and Diso is the free-water (extra-cellular) diffusivity. Phi(v) is the ODF whose squared root we aim at estimating, so that Phi(v) will be non-negative at any possible point of its continuous domain. The coefficients of the ODF itself can be retrieved from the coefficients of its squared root (i.e. the output of this function) with a call to sh2squaredsh. NOTE: if the squared root of the ODF spands up to an even order L, then the ODF spans up to an order 2L.

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.
lambdaparfileA string specifying the file containing the elemental diffusivity along the parallel direction.
lambdaperpfileA string specifying the file contanining the elemental diffusivity along the perpendicular direction.
ffileA string specifying the file containing the partial volume fraction.
shfileA string specifying the file to save the SH coefficients of the squared root of the ODF at each imaged voxel.
nitfileA string specifying the file to save the number of iterations it took to converge or -1 if convergence failed.
mufileA string specifying the file to save the value of the Lagrange multiplier if Newton-Raphson's method is used.
vararginOptional arguments passed as -name value pairs.
Returns
- shfile: The SH coefficients of the ODF at each imaged voxel.
- nitfile: The number of iterations it took to converge or -1 if convergence failed.
- mufile: The value of the Lagrange multiplier if Newton-Raphson's method is used.

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.
  • lambdaparfile: A string specifying the file containing the parallel diffusvity modeling the impulse response (should fulfill 0<lpar<=Diso).
  • lambdaperpfile: A string specifying the file containing the perpendicular diffusvity modeling the impulse response (should fulfill 0<lerp<lpar).
  • ffile: A string specifying the file contanining 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 [].
  • shfile: A string specifying the file to save the SH coefficients of the squared root of the ODF at each imaged voxel.
  • nitfile: A string specifying the file to save the number of iterations it took to converge or -1 if convergence failed.
  • mufile: A string specifying the file to save the value of the Lagrange multiplier if Newton-Raphson's method is used.
  • varargin: Optional arguments passed as - name value pairs.

Optional Arguments:

  • General Optional Parameters:
    • L: an even integer with the maximum order of the SH to be used FOR THE SQUARED ROOT OF THE ODF (default: 6, meaning that the ODF itself will be expanded up to order 12).
    • lambda: the Laplace-Beltrami regularization parameter, which applies to the coefficients OF THE ODF itself (default 0.001).
    • tl, tu: the lower and upper thresholds, respectively, defining the range the dwi 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).
    • ADC0: estimated diffusivity of free water at body temperature (Diso). Should use the same as in atti2micro (default: 3.0e-3).

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).

Advanced parameters:

  • chunksz: if optimal == false, the LLS problem reduces to the product of the atti signal with a precomputed matrix. To improve the performance, cunksz voxels are processed together Note that decrasing this value can dramatically slow down processing in parallel (default: 1000).
  • recrop: wether (true) or not (false) cropping again the signal to the interval [tl,tu] after the free-water compartment has been substracted (default: false).
  • bth: 1x1, b-values that differ from each other less than this threshold are assumed to belong to the same shell (default: 1).

Examples:

micro2shsqrtodf dwifile.nii gifile.bvec bifile.bval lambdaparfile.nii lambdaperpfile.nii ffile.nii shfile.nii nitfile.nii mufile.nii -mask mask_file.nii
function micro2shsqrtodf(in dwifile, in gifile, in bifile, in lambdaparfile, in lambdaperpfile, in ffile, in shfile, in nitfile, in mufile, in varargin)
The SH coefficients of the ODF and the SH coefficients of its squared root are analytically related v...
Note
This is the simplest use case
See also
micro2shodf