dMRI-Lab 1.0
micro2shodf.m File Reference

Functions

function micro2shodf (in dwifile, in gifile, in bifile, in lambdaparfile, in lambdaperpfile, in ffile, in shfile, in varargin)
 

Function Documentation

◆ micro2shodf()

function micro2shodf ( in dwifile,
in gifile,
in bifile,
in lambdaparfile,
in lambdaperpfile,
in ffile,
in shfile,
in varargin )

Computes the SH coefficients of the 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 we aim at estimating.

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.
vararginOptional arguments passed as -name value pairs (e.g. -flperp 0.001).
Returns
- shfile: The SH coefficients of the ODF at each imaged 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.
  • 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 [].
  • varargin: Optional arguments passed as - name value pairs (e.g. -flperp 0.001).

Optional Arguments - General Optional Parameters:

  • L: An even integer with the maximum order of the SH to be used (default: 8).
  • lambda: The Laplace-Beltrami regularization parameter for the linear least squares problem (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: The estimated diffusivity of free water at body temperature (Diso). Should use the same as in atti2micro (default: 3.0e-3).
  • mask: A MxNxP array of logicals. Only those voxels where mask is true are processed, the others are filled with isotropic ODFs (default: all trues).

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:

  • optimal: wether (true) or not (false) use a globally optimal
    • (slower) LLS fitting of the ODF for all shells or a subotimal
    • (faster) LLS fitting shell-by-shell (default: true).
  • 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:

micro2shodf dwifile.nii gifile.bvec bifile.bval lambdaparfile.nii lambdaperpfile.nii ffile.nii shfile.nii -mask mask_file.nii
function micro2shodf(in dwifile, in gifile, in bifile, in lambdaparfile, in lambdaperpfile, in ffile, in shfile, in varargin)
Note
This is the simplest use case
See also
micro2shodf