def test_decompose_tensor_nan():
D_fine = np.array([1.7e-3, 0.0, 0.3e-3, 0.0, 0.0, 0.2e-3])
D_alter = np.array([1.6e-3, 0.0, 0.4e-3, 0.0, 0.0, 0.3e-3])
D_nan = np.nan * np.ones(6)
lref, vref = decompose_tensor(from_lower_triangular(D_fine))
lfine, vfine = _decompose_tensor_nan(from_lower_triangular(D_fine),
from_lower_triangular(D_alter))
assert_array_almost_equal(lfine, np.array([1.7e-3, 0.3e-3, 0.2e-3]))
assert_array_almost_equal(vfine, vref)
lref, vref = decompose_tensor(from_lower_triangular(D_alter))
lalter, valter = _decompose_tensor_nan(from_lower_triangular(D_nan),
from_lower_triangular(D_alter))
assert_array_almost_equal(lalter, np.array([1.6e-3, 0.4e-3, 0.3e-3]))
assert_array_almost_equal(valter, vref)
def test_decompose_tensor_nan():
D_fine = np.array([1.7e-3, 0.0, 0.3e-3, 0.0, 0.0, 0.2e-3])
D_alter = np.array([1.6e-3, 0.0, 0.4e-3, 0.0, 0.0, 0.3e-3])
D_nan = np.nan * np.ones(6)
lref, vref = decompose_tensor(from_lower_triangular(D_fine))
lfine, vfine = _decompose_tensor_nan(from_lower_triangular(D_fine),
from_lower_triangular(D_alter))
assert_array_almost_equal(lfine, np.array([1.7e-3, 0.3e-3, 0.2e-3]))
assert_array_almost_equal(vfine, vref)
lref, vref = decompose_tensor(from_lower_triangular(D_alter))
lalter, valter = _decompose_tensor_nan(from_lower_triangular(D_nan),
from_lower_triangular(D_alter))
assert_array_almost_equal(lalter, np.array([1.6e-3, 0.4e-3, 0.3e-3]))
assert_array_almost_equal(valter, vref)
def nls_iter(design_matrix,
sig,
S0,
Diso=3e-3,
mdreg=2.7e-3,
min_signal=1.0e-6,
cholesky=False,
f_transform=True,
jac=False,
weighting=None,
sigma=None):
""" Applies non linear least squares fit of the water free elimination
model to single voxel signals.
Parameters
----------
design_matrix : array (g, 7)
Design matrix holding the covariants used to solve for the regression
coefficients.
sig : array (g, )
Diffusion-weighted signal for a single voxel data.
S0 : float
Non diffusion weighted signal (i.e. signal for b-value=0).
Diso : float, optional
Value of the free water isotropic diffusion. Default is set to 3e-3
$mm^{2}.s^{-1}$. Please ajust this value if you are assuming different
units of diffusion.
mdreg : float, optimal
DTI's mean diffusivity regularization threshold. If standard DTI
diffusion tensor's mean diffusivity is almost near the free water
diffusion value, the diffusion signal is assumed to be only free water
diffusion (i.e. volume fraction will be set to 1 and tissue's diffusion
parameters are set to zero). Default md_reg is 2.7e-3 $mm^{2}.s^{-1}$
(corresponding to 90% of the free water diffusion value).
min_signal : float
The minimum signal value. Needs to be a strictly positive
number.
cholesky : bool, optional
If true it uses cholesky decomposition to insure that diffusion tensor
is positive define.
Default: False
f_transform : bool, optional
If true, the water volume fractions is converted during the convergence
procedure to ft = arcsin(2*f - 1) + pi/2, insuring f estimates between
0 and 1.
Default: True
jac : bool
Use the Jacobian? Default: False
weighting: str, optional
the weighting scheme to use in considering the
squared-error. Default behavior is to use uniform weighting. Other
options: 'sigma' 'gmm'
sigma: float, optional
If the 'sigma' weighting scheme is used, a value of sigma needs to be
provided here. According to [Chang2005]_, a good value to use is
1.5267 * std(background_noise), where background_noise is estimated
from some part of the image known to contain no signal (only noise).
Returns
-------
All parameters estimated from the free water tensor model.
Parameters are ordered as follows:
1) Three diffusion tensor's eigenvalues
2) Three lines of the eigenvector matrix each containing the
first, second and third coordinates of the eigenvector
3) The volume fraction of the free water compartment.
"""
# Initial guess
params = wls_iter(design_matrix,
sig,
S0,
min_signal=min_signal,
Diso=Diso,
mdreg=mdreg)
# Process voxel if it has significant signal from tissue
if params[12] < 0.99 and np.mean(sig) > min_signal and S0 > min_signal:
# converting evals and evecs to diffusion tensor elements
evals = params[:3]
evecs = params[3:12].reshape((3, 3))
dt = lower_triangular(vec_val_vect(evecs, evals))
# Cholesky decomposition if requested
if cholesky:
dt = lower_triangular_to_cholesky(dt)
# f transformation if requested
if f_transform:
f = np.arcsin(2 * params[12] - 1) + np.pi / 2
else:
f = params[12]
# Use the Levenberg-Marquardt algorithm wrapped in opt.leastsq
start_params = np.concatenate((dt, [-np.log(S0), f]), axis=0)
if jac:
this_tensor, status = opt.leastsq(_nls_err_func,
start_params[:8],
args=(design_matrix, sig, Diso,
weighting, sigma, cholesky,
f_transform),
Dfun=_nls_jacobian_func)
else:
this_tensor, status = opt.leastsq(_nls_err_func,
start_params[:8],
args=(design_matrix, sig, Diso,
weighting, sigma, cholesky,
f_transform))
# Process tissue diffusion tensor
if cholesky:
this_tensor[:6] = cholesky_to_lower_triangular(this_tensor[:6])
evals, evecs = _decompose_tensor_nan(
from_lower_triangular(this_tensor[:6]),
from_lower_triangular(start_params[:6]))
# Process water volume fraction f
f = this_tensor[7]
if f_transform:
f = 0.5 * (1 + np.sin(f - np.pi / 2))
params = np.concatenate(
(evals, evecs[0], evecs[1], evecs[2], np.array([f])), axis=0)
return params
def nls_iter(design_matrix, sig, S0, Diso=3e-3, mdreg=2.7e-3,
min_signal=1.0e-6, cholesky=False, f_transform=True, jac=False,
weighting=None, sigma=None):
""" Applies non linear least squares fit of the water free elimination
model to single voxel signals.
Parameters
----------
design_matrix : array (g, 7)
Design matrix holding the covariants used to solve for the regression
coefficients.
sig : array (g, )
Diffusion-weighted signal for a single voxel data.
S0 : float
Non diffusion weighted signal (i.e. signal for b-value=0).
Diso : float, optional
Value of the free water isotropic diffusion. Default is set to 3e-3
$mm^{2}.s^{-1}$. Please ajust this value if you are assuming different
units of diffusion.
mdreg : float, optimal
DTI's mean diffusivity regularization threshold. If standard DTI
diffusion tensor's mean diffusivity is almost near the free water
diffusion value, the diffusion signal is assumed to be only free water
diffusion (i.e. volume fraction will be set to 1 and tissue's diffusion
parameters are set to zero). Default md_reg is 2.7e-3 $mm^{2}.s^{-1}$
(corresponding to 90% of the free water diffusion value).
min_signal : float
The minimum signal value. Needs to be a strictly positive
number.
cholesky : bool, optional
If true it uses cholesky decomposition to insure that diffusion tensor
is positive define.
Default: False
f_transform : bool, optional
If true, the water volume fractions is converted during the convergence
procedure to ft = arcsin(2*f - 1) + pi/2, insuring f estimates between
0 and 1.
Default: True
jac : bool
Use the Jacobian? Default: False
weighting: str, optional
the weighting scheme to use in considering the
squared-error. Default behavior is to use uniform weighting. Other
options: 'sigma' 'gmm'
sigma: float, optional
If the 'sigma' weighting scheme is used, a value of sigma needs to be
provided here. According to [Chang2005]_, a good value to use is
1.5267 * std(background_noise), where background_noise is estimated
from some part of the image known to contain no signal (only noise).
Returns
-------
All parameters estimated from the free water tensor model.
Parameters are ordered as follows:
1) Three diffusion tensor's eigenvalues
2) Three lines of the eigenvector matrix each containing the
first, second and third coordinates of the eigenvector
3) The volume fraction of the free water compartment.
"""
# Initial guess
params = wls_iter(design_matrix, sig, S0,
min_signal=min_signal, Diso=Diso, mdreg=mdreg)
# Process voxel if it has significant signal from tissue
if params[12] < 0.99 and np.mean(sig) > min_signal and S0 > min_signal:
# converting evals and evecs to diffusion tensor elements
evals = params[:3]
evecs = params[3:12].reshape((3, 3))
dt = lower_triangular(vec_val_vect(evecs, evals))
# Cholesky decomposition if requested
if cholesky:
dt = lower_triangular_to_cholesky(dt)
# f transformation if requested
if f_transform:
f = np.arcsin(2*params[12] - 1) + np.pi/2
else:
f = params[12]
# Use the Levenberg-Marquardt algorithm wrapped in opt.leastsq
start_params = np.concatenate((dt, [-np.log(S0), f]), axis=0)
if jac:
this_tensor, status = opt.leastsq(_nls_err_func, start_params[:8],
args=(design_matrix, sig, Diso,
weighting, sigma, cholesky,
f_transform),
Dfun=_nls_jacobian_func)
else:
this_tensor, status = opt.leastsq(_nls_err_func, start_params[:8],
args=(design_matrix, sig, Diso,
weighting, sigma, cholesky,
f_transform))
# Process tissue diffusion tensor
if cholesky:
this_tensor[:6] = cholesky_to_lower_triangular(this_tensor[:6])
evals, evecs = _decompose_tensor_nan(
from_lower_triangular(this_tensor[:6]),
from_lower_triangular(start_params[:6]))
# Process water volume fraction f
f = this_tensor[7]
if f_transform:
f = 0.5 * (1 + np.sin(f - np.pi/2))
params = np.concatenate((evals, evecs[0], evecs[1], evecs[2],
np.array([f])), axis=0)
return params
