reconst

Module: reconst.base

Base-classes for reconstruction models and reconstruction fits.

All the models in the reconst module follow the same template: a Model object is used to represent the abstract properties of the model, that are independent of the specifics of the data . These properties are reused whenever fitting a particular set of data (different voxels, for example).

ReconstModel(gtab)	Abstract class for signal reconstruction models
ReconstFit(model, data)	Abstract class which holds the fit result of ReconstModel

Module: reconst.cache

Cache()

Cache values based on a key object (such as a sphere or gradient table).

Module: reconst.cross_validation

Cross-validation analysis of diffusion models.

coeff_of_determination(data, model[, axis])	Calculate the coefficient of determination for a model prediction,
kfold_xval(model, data, folds, *model_args, ...)	Perform k-fold cross-validation.

Module: reconst.csdeconv

AxSymShResponse(S0, dwi_response[, bvalue])	A simple wrapper for response functions represented using only axially symmetric, even spherical harmonic functions (ie, m == 0 and l is even).
ConstrainedSphericalDeconvModel(gtab, response)
ConstrainedSDTModel(gtab, ratio[, ...])
auto_response(gtab, data[, roi_center, ...])	Automatic estimation of ssst response function using FA.
response_from_mask(gtab, data, mask)	Computation of single-shell single-tissue (ssst) response
estimate_response(gtab, evals, S0)	Estimate single fiber response function
forward_sdt_deconv_mat(ratio, l_values[, ...])	Build forward sharpening deconvolution transform (SDT) matrix Parameters ---------- ratio : float ratio = \(\frac{\lambda_2}{\lambda_1}\) of the single fiber response function l_values : ndarray (N,) The order (l) of spherical harmonic function associated with each row of the deconvolution matrix.
csdeconv(dwsignal, X, B_reg[, tau, ...])	Constrained-regularized spherical deconvolution (CSD) [1]_ Deconvolves the axially symmetric single fiber response function r_rh in rotational harmonics coefficients from the diffusion weighted signal in dwsignal.
odf_deconv(odf_sh, R, B_reg[, lambda_, tau, ...])	ODF constrained-regularized spherical deconvolution using the Sharpening Deconvolution Transform (SDT) [1]_, [2]_. Parameters ---------- odf_sh : ndarray ((sh_order_max + 1)*(sh_order_max + 2)/2,) ndarray of SH coefficients for the ODF spherical function to be deconvolved R : ndarray ((sh_order_max + 1)(sh_order_max + 2)/2, (sh_order_max + 1)(sh_order_max + 2)/2) SDT matrix in SH basis B_reg : ndarray ((sh_order_max + 1)(sh_order_max + 2)/2, (sh_order_max + 1)(sh_order_max + 2)/2) SH basis matrix used for deconvolution lambda_ : float lambda parameter in minimization equation (default 1.0) tau : float threshold (tau *max(fODF)) controlling the amplitude below which the corresponding fODF is assumed to be zero. r2_term : bool True if ODF is computed from model that uses the \(r^2\) term in the integral. Recall that Tuch's ODF (used in Q-ball Imaging [1]_) and the true normalized ODF definition differ from a \(r^2\) term in the ODF integral. The original Sharpening Deconvolution Transform (SDT) technique [2]_ is expecting Tuch's ODF without the \(r^2\) (see [3]_ for the mathematical details). Now, this function supports ODF that have been computed using the \(r^2\) term because the proper analytical response function has be derived. For example, models such as DSI, GQI, SHORE, CSA, Tensor, Multi-tensor ODFs, should now be deconvolved with the r2_term=True. Returns ------- fodf_sh : ndarray ((sh_order_max + 1)(sh_order_max + 2)/2,) Spherical harmonics coefficients of the constrained-regularized fiber ODF num_it : int Number of iterations in the constrained-regularization used for convergence References ---------- .. [1] Tuch, D. MRM 2004. Q-Ball Imaging. .. [2] Descoteaux, M., et al. IEEE TMI 2009. Deterministic and Probabilistic Tractography Based on Complex Fibre Orientation Distributions .. [3] Descoteaux, M, PhD thesis, INRIA Sophia-Antipolis, 2008. .
odf_sh_to_sharp(odfs_sh, sphere[, basis, ...])	Sharpen odfs using the sharpening deconvolution transform [2]_ This function can be used to sharpen any smooth ODF spherical function.
mask_for_response_ssst(gtab, data[, ...])	Computation of mask for single-shell single-tissue (ssst) response
response_from_mask_ssst(gtab, data, mask)	Computation of single-shell single-tissue (ssst) response
auto_response_ssst(gtab, data[, roi_center, ...])	Automatic estimation of single-shell single-tissue (ssst) response
recursive_response(gtab, data[, mask, ...])	Recursive calibration of response function using peak threshold
fa_trace_to_lambdas([fa, trace])

Module: reconst.cti

Classes and functions for fitting the correlation tensor model

CorrelationTensorModel(gtab1, gtab2[, ...])	Class for the Correlation Tensor Model
CorrelationTensorFit(model, model_params)	Class for fitting the Correlation Tensor Model
from_qte_to_cti(C)	Rescales the qte C elements to the C elements used in CTI.
multi_gaussian_k_from_c(ccti, MD)	Computes the multiple Gaussian diffusion kurtosis tensor from the covariance tensor.
split_cti_params(cti_params)	Splits CTI params into DTI, DKI, CTI portions.
cti_prediction(cti_params, gtab1, gtab2[, S0])	Predict a signal given correlation tensor imaging parameters.
params_to_cti_params(result[, min_diffusivity])
ls_fit_cti(design_matrix, data, ...[, ...])	Compute the diffusion kurtosis and covariance tensors using an ordinary or weighted linear least squares approach

Module: reconst.dki

Classes and functions for fitting the diffusion kurtosis model

DiffusionKurtosisModel(gtab[, fit_method, ...])	Class for the Diffusion Kurtosis Model
DiffusionKurtosisFit(model, model_params[, ...])	Class for fitting the Diffusion Kurtosis Model
carlson_rf(x, y, z[, errtol])	Compute the Carlson's incomplete elliptic integral of the first kind
carlson_rd(x, y, z[, errtol])	Compute the Carlson's incomplete elliptic integral of the second kind
directional_diffusion(dt, V[, min_diffusivity])	Calculate the apparent diffusion coefficient (adc) in each direction of a sphere for a single voxel [1]_
directional_diffusion_variance(kt, V[, ...])	Calculate the apparent diffusion variance (adv) in each direction of a sphere for a single voxel [1]_
directional_kurtosis(dt, md, kt, V[, ...])	Calculate the apparent kurtosis coefficient (akc) in each direction of a sphere for a single voxel [1]_
apparent_kurtosis_coef(dki_params, sphere[, ...])	Calculate the apparent kurtosis coefficient (AKC) in each direction of a sphere [1]_ Parameters ---------- dki_params : ndarray (x, y, z, 27) or (n, 27) All parameters estimated from the diffusion kurtosis model.
mean_kurtosis(dki_params[, min_kurtosis, ...])	Compute mean kurtosis (MK) from the kurtosis tensor Parameters ---------- dki_params : ndarray (x, y, z, 27) or (n, 27) All parameters estimated from the diffusion kurtosis model.
radial_kurtosis(dki_params[, min_kurtosis, ...])	Compute radial kurtosis (RK) of a diffusion kurtosis tensor [1]_, [2]_
axial_kurtosis(dki_params[, min_kurtosis, ...])	Compute axial kurtosis (AK) from the kurtosis tensor [1]_, [2]_
kurtosis_maximum(dki_params[, sphere, gtol, ...])	Compute kurtosis maximum value
mean_kurtosis_tensor(dki_params[, ...])	Compute mean of the kurtosis tensor (MKT) [1]_
kurtosis_fractional_anisotropy(dki_params)	Compute the anisotropy of the kurtosis tensor (KFA) [1]_ Parameters ---------- dki_params : ndarray (x, y, z, 27) or (n, 27) All parameters estimated from the diffusion kurtosis model.
dki_prediction(dki_params, gtab[, S0])	Predict a signal given diffusion kurtosis imaging parameters
params_to_dki_params(result[, min_diffusivity])
ls_fit_dki(design_matrix, data, ...[, ...])	Compute the diffusion and kurtosis tensors using an ordinary or weighted linear least squares approach [1]_
cls_fit_dki(design_matrix, data, ...[, ...])	Compute the diffusion and kurtosis tensors using a constrained ordinary or weighted linear least squares approach [1]_
Wrotate(kt, Basis)	Rotate a kurtosis tensor from the standard Cartesian coordinate system to another coordinate system basis
Wrotate_element(kt, indi, indj, indk, indl, B)	Compute the the specified index element of a kurtosis tensor rotated to the coordinate system basis B
Wcons(k_elements)	Construct the full 4D kurtosis tensors from its 15 independent elements
split_dki_param(dki_params)	Extract the diffusion tensor eigenvalues, the diffusion tensor eigenvector matrix, and the 15 independent elements of the kurtosis tensor from the model parameters estimated from the DKI model

Module: reconst.dki_micro

Classes and functions for fitting the DKI-based microstructural model

KurtosisMicrostructureModel(gtab[, fit_method])	Class for the Diffusion Kurtosis Microstructural Model
KurtosisMicrostructuralFit(model, model_params)	Class for fitting the Diffusion Kurtosis Microstructural Model
axonal_water_fraction(dki_params[, sphere, ...])	Computes the axonal water fraction from DKI [1]_.
diffusion_components(dki_params[, sphere, ...])	Extracts the restricted and hindered diffusion tensors of well aligned fibers from diffusion kurtosis imaging parameters [1]_.
dkimicro_prediction(params, gtab[, S0])	Signal prediction given the DKI microstructure model parameters. Parameters ---------- params : ndarray (x, y, z, 40) or (n, 40) All parameters estimated from the diffusion kurtosis microstructure 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) Fifteen elements of the kurtosis tensor 4) Six elements of the hindered diffusion tensor 5) Six elements of the restricted diffusion tensor 6) Axonal water fraction gtab : a GradientTable class instance The gradient table for this prediction S0 : float or ndarray The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1 Returns ------- S : (..., N) ndarray Simulated signal based on the DKI microstructure model Notes ----- 1) The predicted signal is given by: \(S(\theta, b) = S_0 * [f * e^{-b ADC_{r}} + (1-f) * e^{-b ADC_{h}]\), where :math:` ADC_{r} and ADC_{h} are the apparent diffusion coefficients of the diffusion hindered and restricted compartment for a given direction theta:math:, b:math: is the b value provided in the GradientTable input for that direction, `f$ is the volume fraction of the restricted diffusion compartment (also known as the axonal water fraction). 2) In the original article of DKI microstructural model [1]_, the hindered and restricted tensors were defined as the intra-cellular and extra-cellular diffusion compartments respectively. .
tortuosity(hindered_ad, hindered_rd)	Computes the tortuosity of the hindered diffusion compartment given its axial and radial diffusivities

Module: reconst.dsi

DiffusionSpectrumModel(gtab[, qgrid_size, ...])
DiffusionSpectrumFit(model, data)
DiffusionSpectrumDeconvModel(gtab[, ...])
DiffusionSpectrumDeconvFit(model, data)
create_qspace(gtab, origin)	create the 3D grid which holds the signal values (q-space)
create_qtable(gtab, origin)	create a normalized version of gradients
hanning_filter(gtab, filter_width, origin)	create a hanning window
pdf_interp_coords(sphere, rradius, origin)	Precompute coordinates for ODF calculation from the PDF
pdf_odf(Pr, rradius, interp_coords)	Calculates the real ODF from the diffusion propagator(PDF) Pr
half_to_full_qspace(data, gtab)	Half to full Cartesian grid mapping
project_hemisph_bvecs(gtab)	Project any near identical bvecs to the other hemisphere
threshold_propagator(P[, estimated_snr])	Applies hard threshold on the propagator to remove background noise for the deconvolution.
gen_PSF(qgrid_sampling, siz_x, siz_y, siz_z)	Generate a PSF for DSI Deconvolution by taking the ifft of the binary q-space sampling mask and truncating it to keep only the center.
LR_deconv(prop, psf[, numit, acc_factor])	Perform Lucy-Richardson deconvolution algorithm on a 3D array.

Module: reconst.dti

Classes and functions for fitting tensors

TensorModel(gtab[, fit_method, return_S0_hat])	Diffusion Tensor
TensorFit(model, model_params[, model_S0])
fractional_anisotropy(evals[, axis])	Return Fractional anisotropy (FA) of a diffusion tensor.
geodesic_anisotropy(evals[, axis])	Geodesic anisotropy (GA) of a diffusion tensor.
mean_diffusivity(evals[, axis])	Mean Diffusivity (MD) of a diffusion tensor.
axial_diffusivity(evals[, axis])	Axial Diffusivity (AD) of a diffusion tensor.
radial_diffusivity(evals[, axis])	Radial Diffusivity (RD) of a diffusion tensor.
trace(evals[, axis])	Trace of a diffusion tensor.
color_fa(fa, evecs)	Color fractional anisotropy of diffusion tensor
determinant(q_form)	The determinant of a tensor, given in quadratic form
isotropic(q_form)	Calculate the isotropic part of the tensor [1]_.
deviatoric(q_form)	Calculate the deviatoric (anisotropic) part of the tensor [1]_.
norm(q_form)	Calculate the Frobenius norm of a tensor quadratic form
mode(q_form)	Mode (MO) of a diffusion tensor [1]_.
linearity(evals[, axis])	The linearity of the tensor [1]_
planarity(evals[, axis])	The planarity of the tensor [1]_
sphericity(evals[, axis])	The sphericity of the tensor [1]_
apparent_diffusion_coef(q_form, sphere)	Calculate the apparent diffusion coefficient (ADC) in each direction of a sphere.
tensor_prediction(dti_params, gtab, S0)	Predict a signal given tensor parameters.
iter_fit_tensor([step])	Wrap a fit_tensor func and iterate over chunks of data with given length
wls_fit_tensor(design_matrix, data[, ...])	Computes weighted least squares (WLS) fit to calculate self-diffusion tensor using a linear regression model [1]_.
ols_fit_tensor(design_matrix, data[, ...])	Computes ordinary least squares (OLS) fit to calculate self-diffusion tensor using a linear regression model [1]_.
nlls_fit_tensor(design_matrix, data[, ...])	Fit the cumulant expansion params (e.g. DTI, DKI) using non-linear least-squares.
restore_fit_tensor(design_matrix, data[, ...])	Use the RESTORE algorithm [1]_ to calculate a robust tensor fit
_lt_indices	ndarray(shape, dtype=float, buffer=None, offset=0,
from_lower_triangular(D)	Returns a tensor given the six unique tensor elements
_lt_rows	ndarray(shape, dtype=float, buffer=None, offset=0,
_lt_cols	ndarray(shape, dtype=float, buffer=None, offset=0,
lower_triangular(tensor[, b0])	Returns the six lower triangular values of the tensor ordered as (Dxx, Dxy, Dyy, Dxz, Dyz, Dzz) and a dummy variable if b0 is not None.
decompose_tensor(tensor[, min_diffusivity])	Returns eigenvalues and eigenvectors given a diffusion tensor
design_matrix(gtab[, dtype])	Constructs design matrix for DTI weighted least squares or least squares fitting.
quantize_evecs(evecs[, odf_vertices])	Find the closest orientation of an evenly distributed sphere
eig_from_lo_tri(data[, min_diffusivity])	Calculates tensor eigenvalues/eigenvectors from an array containing the lower diagonal form of the six unique tensor elements.

Module: reconst.eudx_direction_getter

EuDXDirectionGetter

Deterministic Direction Getter based on peak directions.

Module: reconst.forecast

ForecastModel(gtab[, sh_order_max, ...])	Fiber ORientation Estimated using Continuous Axially Symmetric Tensors (FORECAST) [1,2,3]_.
ForecastFit(model, data, sh_coef, d_par, d_perp)
find_signal_means(b_unique, data_norm, ...)	Calculate the mean signal for each shell.
forecast_error_func(x, b_unique, E)	Calculates the difference between the mean signal calculated using the parameter vector x and the average signal E using FORECAST and SMT
psi_l(l, b)
forecast_matrix(sh_order_max, d_par, d_perp, ...)	Compute the FORECAST radial matrix
rho_matrix(sh_order_max, vecs)	Compute the SH matrix \(\rho\)
lb_forecast(sh_order_max)	Returns the Laplace-Beltrami regularization matrix for FORECAST

Module: reconst.fwdti

Classes and functions for fitting tensors without free water contamination

FreeWaterTensorModel(gtab[, fit_method])	Class for the Free Water Elimination Diffusion Tensor Model
FreeWaterTensorFit(model, model_params)	Class for fitting the Free Water Tensor Model
fwdti_prediction(params, gtab[, S0, Diso])	Signal prediction given the free water DTI model parameters.
wls_iter(design_matrix, sig, S0[, Diso, ...])	Applies weighted linear least squares fit of the water free elimination model to single voxel signals.
wls_fit_tensor(gtab, data[, Diso, mask, ...])	Computes weighted least squares (WLS) fit to calculate self-diffusion tensor using a linear regression model [1]_.
nls_iter(design_matrix, sig, S0[, Diso, ...])	Applies non linear least squares fit of the water free elimination model to single voxel signals.
nls_fit_tensor(gtab, data[, mask, Diso, ...])	Fit the water elimination tensor model using the non-linear least-squares.
lower_triangular_to_cholesky(tensor_elements)	Performs Cholesky decomposition of the diffusion tensor
cholesky_to_lower_triangular(R)	Convert Cholesky decomposition elements to the diffusion tensor elements

Module: reconst.gqi

Classes and functions for generalized q-sampling

GeneralizedQSamplingModel(gtab[, method, ...])
GeneralizedQSamplingFit(model, data)
normalize_qa(qa[, max_qa])	Normalize quantitative anisotropy.
squared_radial_component(x[, tol])	Part of the GQI2 integral
npa(self, odf[, width])	non-parametric anisotropy
equatorial_zone_vertices(vertices, pole[, width])	finds the 'vertices' in the equatorial zone conjugate to 'pole' with width half 'width' degrees
polar_zone_vertices(vertices, pole[, width])	finds the 'vertices' in the equatorial band around the 'pole' of radius 'width' degrees
upper_hemi_map(v)	maps a 3-vector into the z-upper hemisphere
equatorial_maximum(vertices, odf, pole, width)
patch_vertices(vertices, pole, width)	find 'vertices' within the cone of 'width' degrees around 'pole'
patch_maximum(vertices, odf, pole, width)
odf_sum(odf)
patch_sum(vertices, odf, pole, width)
triple_odf_maxima(vertices, odf, width)

Module: reconst.ivim

Classes and functions for fitting ivim model

IvimModelTRR(gtab[, split_b_D, split_b_S0, ...])	Ivim model
IvimModelVP(gtab[, bounds, maxiter, xtol])
IvimFit(model, model_params)
ivim_prediction(params, gtab)	The Intravoxel incoherent motion (IVIM) model function.
f_D_star_prediction(params, gtab, S0, D)	Function used to predict IVIM signal when S0 and D are known by considering f and D_star as the unknown parameters.
f_D_star_error(params, gtab, signal, S0, D)	Error function used to fit f and D_star keeping S0 and D fixed
ivim_model_selector(gtab[, fit_method])	Selector function to switch between the 2-stage Trust-Region Reflective based NLLS fitting method (also containing the linear fit): trr and the Variable Projections based fitting method: varpro.

Module: reconst.mapmri

MapmriModel(gtab[, radial_order, ...])	Mean Apparent Propagator MRI (MAPMRI) [1]_ of the diffusion signal.
MapmriFit(model, mapmri_coef, mu, R, lopt[, ...])
isotropic_scale_factor(mu_squared)	Estimated isotropic scaling factor _[1] Eq.
mapmri_index_matrix(radial_order)	Calculates the indices for the MAPMRI [1]_ basis in x, y and z.
b_mat(index_matrix)	Calculates the B coefficients from [1]_ Eq.
b_mat_isotropic(index_matrix)	Calculates the isotropic B coefficients from [1]_ Fig 8.
mapmri_phi_1d(n, q, mu)	One dimensional MAPMRI basis function from [1]_ Eq.
mapmri_phi_matrix(radial_order, mu, q_gradients)	Compute the MAPMRI phi matrix for the signal [1]_ eq.
mapmri_psi_1d(n, x, mu)	One dimensional MAPMRI propagator basis function from [1]_ Eq.
mapmri_psi_matrix(radial_order, mu, rgrad)	Compute the MAPMRI psi matrix for the propagator [1]_ eq.
mapmri_odf_matrix(radial_order, mu, s, vertices)	Compute the MAPMRI ODF matrix [1]_ Eq.
mapmri_isotropic_phi_matrix(radial_order, mu, q)	Three dimensional isotropic MAPMRI signal basis function from [1]_ Eq.
mapmri_isotropic_radial_signal_basis(j, ...)	Radial part of the isotropic 1D-SHORE signal basis [1]_ eq.
mapmri_isotropic_M_mu_independent(...)	Computed the mu independent part of the signal design matrix.
mapmri_isotropic_M_mu_dependent(...)	Computed the mu dependent part of the signal design matrix.
mapmri_isotropic_psi_matrix(radial_order, ...)	Three dimensional isotropic MAPMRI propagator basis function from [1]_ Eq.
mapmri_isotropic_radial_pdf_basis(j, ...)	Radial part of the isotropic 1D-SHORE propagator basis [1]_ eq.
mapmri_isotropic_K_mu_independent(...)	Computes mu independent part of K.
mapmri_isotropic_K_mu_dependent(...)	Computes mu dependent part of M.
binomialfloat(n, k)	Custom Binomial function
mapmri_isotropic_odf_matrix(radial_order, ...)	Compute the isotropic MAPMRI ODF matrix [1]_ Eq.
mapmri_isotropic_odf_sh_matrix(radial_order, ...)	Compute the isotropic MAPMRI ODF matrix [1]_ Eq.
mapmri_isotropic_laplacian_reg_matrix(...)	Computes the Laplacian regularization matrix for MAP-MRI's isotropic implementation [1]_ eq.
mapmri_isotropic_laplacian_reg_matrix_from_index_matrix(...)	Computes the Laplacian regularization matrix for MAP-MRI's isotropic implementation [1]_ eq.
mapmri_isotropic_index_matrix(radial_order)	Calculates the indices for the isotropic MAPMRI basis [1]_ Fig 8.
create_rspace(gridsize, radius_max)	Create the real space table, that contains the points in which to compute the pdf.
delta(n, m)
map_laplace_u(n, m)	S(n, m) static matrix for Laplacian regularization [1]_ eq.
map_laplace_t(n, m)	L(m, n) static matrix for Laplacian regularization [1]_ eq.
map_laplace_s(n, m)	R(m,n) static matrix for Laplacian regularization [1]_ eq.
mapmri_STU_reg_matrices(radial_order)	Generate the static portions of the Laplacian regularization matrix according to [1]_ eq.
mapmri_laplacian_reg_matrix(ind_mat, mu, ...)	Put the Laplacian regularization matrix together [1]_ eq.
generalized_crossvalidation_array(data, M, LR)	Generalized Cross Validation Function [1]_ eq.
generalized_crossvalidation(data, M, LR[, ...])	Generalized Cross Validation Function [1]_ eq.
gcv_cost_function(weight, args)	The GCV cost function that is iterated [4].

Module: reconst.mcsd

MultiShellResponse(response, sh_order_max, ...)
MultiShellDeconvModel(gtab, response[, ...])
MSDeconvFit(model, coeff, mask)
QpFitter(X, reg)
multi_tissue_basis(gtab, sh_order_max, iso_comp)	Builds a basis for multi-shell multi-tissue CSD model.
solve_qp(P, Q, G, H)	Helper function to set up and solve the Quadratic Program (QP) in CVXPY.
multi_shell_fiber_response(sh_order_max, ...)	Fiber response function estimation for multi-shell data.
mask_for_response_msmt(gtab, data[, ...])	Computation of masks for multi-shell multi-tissue (msmt) response
response_from_mask_msmt(gtab, data, mask_wm, ...)	Computation of multi-shell multi-tissue (msmt) response
auto_response_msmt(gtab, data[, tol, ...])	Automatic estimation of multi-shell multi-tissue (msmt) response

Module: reconst.msdki

Classes and functions for fitting the mean signal diffusion kurtosis model

MeanDiffusionKurtosisModel(gtab[, bmag, ...])	Mean signal Diffusion Kurtosis Model
MeanDiffusionKurtosisFit(model, model_params)
mean_signal_bvalue(data, gtab[, bmag])	Computes the average signal across different diffusion directions for each unique b-value Parameters ---------- data : ndarray ([X, Y, Z, ...], g) ndarray containing the data signals in its last dimension.
msk_from_awf(f)	Computes mean signal kurtosis from axonal water fraction estimates of the SMT2 model
awf_from_msk(msk[, mask])	Computes the axonal water fraction from the mean signal kurtosis assuming the 2-compartmental spherical mean technique model [1]_, [2]_
msdki_prediction(msdki_params, gtab[, S0])	Predict the mean signal given the parameters of the mean signal DKI, an GradientTable object and S0 signal.
wls_fit_msdki(design_matrix, msignal, ng[, ...])	Fits the mean signal diffusion kurtosis imaging based on a weighted least square solution [1]_.
design_matrix(ubvals)	Constructs design matrix for the mean signal diffusion kurtosis model

Module: reconst.multi_voxel

Tools to easily make multi voxel models

MultiVoxelFit(model, fit_array, mask)	Holds an array of fits and allows access to their attributes and methods
CallableArray	An array which can be called like a function
multi_voxel_fit(single_voxel_fit)	Method decorator to turn a single voxel model fit definition into a multi voxel model fit definition

Module: reconst.odf

OdfModel(gtab)	An abstract class to be sub-classed by specific odf models
OdfFit(model, data)
gfa(samples)	The general fractional anisotropy of a function evaluated on the unit sphere Parameters ---------- samples : ndarray Values of data on the unit sphere.
minmax_normalize(samples[, out])	Min-max normalization of a function evaluated on the unit sphere

Module: reconst.qtdmri

QtdmriModel(gtab[, radial_order, ...])	The q:math:tau-dMRI model [1] to analytically and continuously represent the q:math:tau diffusion signal attenuation over diffusion sensitization q and diffusion time \(\tau\).
QtdmriFit(model, qtdmri_coef, us, ut, ...)
qtdmri_to_mapmri_matrix(radial_order, ...)	Generate the matrix that maps the qtdmri coefficients to MAP-MRI coefficients for the anisotropic case.
qtdmri_isotropic_to_mapmri_matrix(...)	Generate the matrix that maps the spherical qtdmri coefficients to MAP-MRI coefficients for the isotropic case.
qtdmri_temporal_normalization(ut)	Normalization factor for the temporal basis
qtdmri_mapmri_normalization(mu)	Normalization factor for Cartesian MAP-MRI basis.
qtdmri_mapmri_isotropic_normalization(j, l, u0)	Normalization factor for Spherical MAP-MRI basis.
qtdmri_signal_matrix_(radial_order, ...[, ...])	Function to generate the qtdmri signal basis.
qtdmri_signal_matrix(radial_order, ...)	Constructs the design matrix as a product of 3 separated radial, angular and temporal design matrices.
qtdmri_eap_matrix(radial_order, time_order, ...)	Constructs the design matrix as a product of 3 separated radial, angular and temporal design matrices.
qtdmri_isotropic_signal_matrix_(...[, ...])
qtdmri_isotropic_signal_matrix(radial_order, ...)
qtdmri_eap_matrix_(radial_order, time_order, ...)
qtdmri_isotropic_eap_matrix_(radial_order, ...)
qtdmri_isotropic_eap_matrix(radial_order, ...)	Constructs the design matrix as a product of 3 separated radial, angular and temporal design matrices.
radial_basis_opt(j, l, us, q)	Spatial basis dependent on spatial scaling factor us
angular_basis_opt(l, m, q, theta, phi)	Angular basis independent of spatial scaling factor us.
radial_basis_EAP_opt(j, l, us, r)
angular_basis_EAP_opt(j, l, m, r, theta, phi)
temporal_basis(o, ut, tau)	Temporal basis dependent on temporal scaling factor ut
qtdmri_index_matrix(radial_order, time_order)	Computes the SHORE basis order indices according to [1].
qtdmri_isotropic_index_matrix(radial_order, ...)	Computes the SHORE basis order indices according to [1].
qtdmri_laplacian_reg_matrix(ind_mat, us, ut)	Computes the cartesian qt-dMRI Laplacian regularization matrix.
qtdmri_isotropic_laplacian_reg_matrix(...[, ...])	Computes the spherical qt-dMRI Laplacian regularization matrix.
part23_reg_matrix_q(ind_mat, U_mat, T_mat, us)	Partial cartesian spatial Laplacian regularization matrix following second line of Eq.
part23_iso_reg_matrix_q(ind_mat, us)	Partial spherical spatial Laplacian regularization matrix following the equation below Eq.
part4_reg_matrix_q(ind_mat, U_mat, us)	Partial cartesian spatial Laplacian regularization matrix following equation Eq.
part4_iso_reg_matrix_q(ind_mat, us)	Partial spherical spatial Laplacian regularization matrix following the equation below Eq.
part1_reg_matrix_tau(ind_mat, ut)	Partial temporal Laplacian regularization matrix following Appendix B in [1].
part23_reg_matrix_tau(ind_mat, ut)	Partial temporal Laplacian regularization matrix following Appendix B in [1].
part4_reg_matrix_tau(ind_mat, ut)	Partial temporal Laplacian regularization matrix following Appendix B in [1].
H(value)	Step function of H(x)=1 if x>=0 and zero otherwise.
generalized_crossvalidation(data, M, LR[, ...])	Generalized Cross Validation Function [1].
GCV_cost_function(weight, arguments)	Generalized Cross Validation Function that is iterated [1].
qtdmri_isotropic_scaling(data, q, tau)	Constructs design matrix for fitting an exponential to the diffusion time points.
qtdmri_anisotropic_scaling(data, q, bvecs, tau)	Constructs design matrix for fitting an exponential to the diffusion time points.
design_matrix_spatial(bvecs, qvals)	Constructs design matrix for DTI weighted least squares or least squares fitting.
create_rt_space_grid(grid_size_r, ...)	Generates EAP grid (for potential positivity constraint).
qtdmri_number_of_coefficients(radial_order, ...)	Computes the total number of coefficients of the qtdmri basis given a radial and temporal order.
l1_crossvalidation(b0s_mask, E, M[, ...])	cross-validation function to find the optimal weight of alpha for sparsity regularization
elastic_crossvalidation(b0s_mask, E, M, L, lopt)	cross-validation function to find the optimal weight of alpha for sparsity regularization when also Laplacian regularization is used.
visualise_gradient_table_G_Delta_rainbow(gtab)	This function visualizes a q-tau acquisition scheme as a function of gradient strength and pulse separation (big_delta).

Module: reconst.qti

Classes and functions for fitting the covariance tensor model of q-space trajectory imaging (QTI) by Westin et al. as presented in “Q-space trajectory imaging for multidimensional diffusion MRI of the human brain” NeuroImage vol. 135 (2016): 345-62. https://doi.org/10.1016/j.neuroimage.2016.02.039

QtiModel(gtab[, fit_method, cvxpy_solver])
QtiFit(params)
from_3x3_to_6x1(T)	Convert symmetric 3 x 3 matrices into 6 x 1 vectors.
from_6x1_to_3x3(V)	Convert 6 x 1 vectors into symmetric 3 x 3 matrices.
from_6x6_to_21x1(T)	Convert symmetric 6 x 6 matrices into 21 x 1 vectors.
from_21x1_to_6x6(V)	Convert 21 x 1 vectors into symmetric 6 x 6 matrices.
cvxpy_1x6_to_3x3(V)	Convert a 1 x 6 vector into a symmetric 3 x 3 matrix.
cvxpy_1x21_to_6x6(V)	Convert 1 x 21 vector into a symmetric 6 x 6 matrix.
dtd_covariance(DTD)	Calculate covariance of a diffusion tensor distribution (DTD).
qti_signal(gtab, D, C[, S0])	Generate signals using the covariance tensor signal representation.
design_matrix(btens)	Calculate the design matrix from the b-tensors.

Module: reconst.quick_squash

Detect common dtype across object array

quick_squash(obj_arr[, mask, fill])	Try and make a standard array from an object array
reduce(function, iterable[, initial])	Apply a function of two arguments cumulatively to the items of a sequence or iterable, from left to right, so as to reduce the iterable to a single value.

Module: reconst.recspeed

Optimized routines for creating voxel diffusion models

adj_to_countarrs(adj_inds)	Convert adjacency sequence to counts and flattened indices
argmax_from_adj(vals, vertex_inds, adj_inds)	Indices of local maxima from vals given adjacent points
argmax_from_countarrs(vals, vertinds, ...)	Indices of local maxima from vals from count, array neighbors
le_to_odf(odf, LEs, radius, odfn, radiusn, ...)	odf for interpolated Laplacian normalized signal
local_maxima(odf, edges)	Local maxima of a function evaluated on a discrete set of points.
proc_reco_args(vals, vertinds)
remove_similar_vertices(vertices, theta[, ...])	Remove vertices that are less than theta degrees from any other Returns vertices that are at least theta degrees from any other vertex.
search_descending(a, relative_threshold)	i in descending array a so a[i] < a[0] * relative_threshold
sum_on_blocks_1d(arr, blocks, out, outn)	Summations on blocks of 1d array

Module: reconst.rumba

Robust and Unbiased Model-BAsed Spherical Deconvolution (RUMBA-SD)

RumbaSDModel(gtab[, wm_response, ...])
RumbaFit(model, model_params)
logger	Instances of the Logger class represent a single logging channel.
rumba_deconv(data, kernel[, n_iter, ...])	Fit fODF and GM/CSF volume fractions for a voxel using RUMBA-SD [1]_.
mbessel_ratio(n, x)	Fast computation of modified Bessel function ratio (first kind).
generate_kernel(gtab, sphere, wm_response, ...)	Generate deconvolution kernel
rumba_deconv_global(data, kernel, mask[, ...])	Fit fODF for all voxels simultaneously using RUMBA-SD.

Module: reconst.sfm

The Sparse Fascicle Model.

This is an implementation of the sparse fascicle model described in [Rokem2015]. The multi b-value version of this model is described in [Rokem2014].

[Rokem2015]

Ariel Rokem, Jason D. Yeatman, Franco Pestilli, Kendrick N. Kay, Aviv Mezer, Stefan van der Walt, Brian A. Wandell (2015). Evaluating the accuracy of diffusion MRI models in white matter. PLoS ONE 10(4): e0123272. doi:10.1371/journal.pone.0123272

[Rokem2014]

Ariel Rokem, Kimberly L. Chan, Jason D. Yeatman, Franco Pestilli, Brian A. Wandell (2014). Evaluating the accuracy of diffusion models at multiple b-values with cross-validation. ISMRM 2014.

IsotropicModel(gtab)	A base-class for the representation of isotropic signals.
IsotropicFit(model, params)	A fit object for representing the isotropic signal as the mean of the diffusion-weighted signal.
ExponentialIsotropicModel(gtab)	Representing the isotropic signal as a fit to an exponential decay function with b-values
ExponentialIsotropicFit(model, params)	A fit to the ExponentialIsotropicModel object, based on data.
SparseFascicleModel(gtab[, sphere, ...])
SparseFascicleFit(model, beta, S0, iso)
sfm_design_matrix(gtab, sphere, response[, mode])	Construct the SFM design matrix

Module: reconst.shm

Tools for using spherical harmonic models to fit diffusion data.

References

[1]

Aganj, I., et al. 2009. ODF Reconstruction in Q-Ball Imaging With Solid Angle Consideration.

[2]

Descoteaux, M., et al. 2007. Regularized, fast, and robust analytical Q-ball imaging.

[3]

Tristan-Vega, A., et al. 2010. A new methodology for estimation of fiber populations in white matter of the brain with Funk-Radon transform.

[4]

Tristan-Vega, A., et al. 2009. Estimation of fiber orientation probability density functions in high angular resolution diffusion imaging.

Note about the Transpose: In the literature the matrix representation of these methods is often written as Y = Bx where B is some design matrix and Y and x are column vectors. In our case the input data, a dwi stored as a nifti file for example, is stored as row vectors (ndarrays) of the form (x, y, z, n), where n is the number of diffusion directions. We could transpose and reshape the data to be (n, x*y*z), so that we could directly plug it into the above equation. However, I have chosen to keep the data as is and implement the relevant equations rewritten in the following form: Y.T = x.T B.T, or in python syntax data = np.dot(sh_coef, B.T) where data is Y.T and sh_coef is x.T.

SphHarmModel(gtab)	To be subclassed by all models that return a SphHarmFit when fit.
QballBaseModel(gtab, sh_order_max[, smooth, ...])	To be subclassed by Qball type models.
SphHarmFit(model, shm_coef, mask)	Diffusion data fit to a spherical harmonic model
CsaOdfModel(gtab, sh_order_max[, smooth, ...])	Implementation of Constant Solid Angle reconstruction method.
OpdtModel(gtab, sh_order_max[, smooth, ...])	Implementation of Orientation Probability Density Transform reconstruction method.
QballModel(gtab, sh_order_max[, smooth, ...])	Implementation of regularized Qball reconstruction method.
ResidualBootstrapWrapper(signal_object, B, ...)	Returns a residual bootstrap sample of the signal_object when indexed
forward_sdeconv_mat(r_rh, l_values)	Build forward spherical deconvolution matrix
sh_to_rh(r_sh, m_values, l_values)	Spherical harmonics (SH) to rotational harmonics (RH)
gen_dirac(m_values, l_values, theta, phi[, ...])	Generate Dirac delta function orientated in (theta, phi) on the sphere
spherical_harmonics(m_values, l_values, ...)	Compute spherical harmonics.
real_sph_harm(m_values, l_values, theta, phi)	Compute real spherical harmonics.
real_sh_tournier_from_index(m_values, ...[, ...])	Compute real spherical harmonics as initially defined in Tournier 2007 [1]_ then updated in MRtrix3 [2]_, where the real harmonic \(Y^m_l\) is defined to be: Real(\(Y^m_l\)) * sqrt(2) if m > 0 \(Y^0_l\) if m = 0 Imag(\(Y^|m|_l\)) * sqrt(2) if m < 0 This may take scalar or array arguments.
real_sh_descoteaux_from_index(m_values, ...)	Compute real spherical harmonics as in Descoteaux et al. 2007 [1]_, where the real harmonic \(Y^m_l\) is defined to be: Imag(\(Y^m_l\)) * sqrt(2) if m > 0 \(Y^0_l\) if m = 0 Real(\(Y^m_l\)) * sqrt(2) if m < 0 This may take scalar or array arguments.
real_sh_tournier(sh_order_max, theta, phi[, ...])	Compute real spherical harmonics as initially defined in Tournier 2007 [1]_ then updated in MRtrix3 [2]_, where the real harmonic \(Y^m_l\) is defined to be: Real(\(Y^m_l\)) * sqrt(2) if m > 0 \(Y^0_l\) if m = 0 Imag(\(Y^|m|_l\)) * sqrt(2) if m < 0 This may take scalar or array arguments.
real_sh_descoteaux(sh_order_max, theta, phi)	Compute real spherical harmonics as in Descoteaux et al. 2007 [1]_, where the real harmonic \(Y^m_l\) is defined to be: Imag(\(Y^m_l\)) * sqrt(2) if m > 0 \(Y^0_l\) if m = 0 Real(\(Y^m_l\)) * sqrt(2) if m < 0 This may take scalar or array arguments.
real_sym_sh_mrtrix(sh_order_max, theta, phi)	dipy.reconst.shm.real_sym_sh_mrtrix is deprecated, Please use dipy.reconst.shm.real_sh_tournier instead * deprecated from version: 1.3 * Will raise <class 'dipy.utils.deprecator.ExpiredDeprecationError'> as of version: 2.0 Compute real symmetric spherical harmonics as in Tournier 2007 [2]_, where the real harmonic \(Y^m_l\) is defined to be:: Real(\(Y^m_l\)) if m > 0 \(Y^0_l\) if m = 0 Imag(\(Y^|m|_l\)) if m < 0 This may take scalar or array arguments.
real_sym_sh_basis(sh_order_max, theta, phi)	Samples a real symmetric spherical harmonic basis at point on the sphere dipy.reconst.shm.real_sym_sh_basis is deprecated, Please use dipy.reconst.shm.real_sh_descoteaux instead * deprecated from version: 1.3 * Will raise <class 'dipy.utils.deprecator.ExpiredDeprecationError'> as of version: 2.0 Samples the basis functions up to order sh_order_max at points on the sphere given by theta and phi.
sph_harm_ind_list(sh_order_max[, full_basis])	Returns the order (l) and phase_factor (m) of all the symmetric spherical harmonics of order less then or equal to sh_order_max.
order_from_ncoef(ncoef[, full_basis])	Given a number n of coefficients, calculate back the sh_order_max
smooth_pinv(B, L)	Regularized pseudo-inverse Computes a regularized least square inverse of B Parameters ---------- B : array_like (n, m) Matrix to be inverted L : array_like (m,) Returns ------- inv : ndarray (m, n) regularized least square inverse of B Notes ----- In the literature this inverse is often written \((B^{T}B+L^{2})^{-1}B^{T}\).
lazy_index(index)	Produces a lazy index
normalize_data(data, where_b0[, min_signal, out])	Normalizes the data with respect to the mean b0
hat(B)	Returns the hat matrix for the design matrix B
lcr_matrix(H)	Returns a matrix for computing leveraged, centered residuals from data
bootstrap_data_array(data, H, R[, permute])	Applies the Residual Bootstraps to the data given H and R
bootstrap_data_voxel(data, H, R[, permute])	Like bootstrap_data_array but faster when for a single voxel
sf_to_sh(sf, sphere[, sh_order_max, ...])	Spherical function to spherical harmonics (SH).
sh_to_sf(sh, sphere[, sh_order_max, ...])	Spherical harmonics (SH) to spherical function (SF).
sh_to_sf_matrix(sphere[, sh_order_max, ...])	Matrix that transforms Spherical harmonics (SH) to spherical function (SF).
calculate_max_order(n_coeffs[, full_basis])	Calculate the maximal harmonic order (l), given that you know the number of parameters that were estimated.
anisotropic_power(sh_coeffs[, norm_factor, ...])	Calculate anisotropic power map with a given SH coefficient matrix. Parameters ---------- sh_coeffs : ndarray A ndarray where the last dimension is the SH coefficients estimates for that voxel. norm_factor: float, optional The value to normalize the ap values. power : int, optional The degree to which power maps are calculated. non_negative: bool, optional Whether to rectify the resulting map to be non-negative. Returns ------- log_ap : ndarray The log of the resulting power image. Notes ----- Calculate AP image based on a IxJxKxC SH coefficient matrix based on the equation: .. math:: AP = sum_{l=2,4,6,...}{frac{1}{2l+1} sum_{m=-l}^l{|a_{l,m}|^n}} Where the last dimension, C, is made of a flattened array of \(l`x:math:`m\) coefficients, where \(l\) are the SH orders, and \(m = 2l+1\), So l=1 has 1 coefficient, l=2 has 5, ... l=8 has 17 and so on. A l=2 SH coefficient matrix will then be composed of a IxJxKx6 volume. The power, \(n\) is usually set to \(n=2\). The final AP image is then shifted by -log(norm_factor), to be strictly non-negative. Remaining values < 0 are discarded (set to 0), per default, and this option is controlled through the non_negative keyword argument. References ---------- .. [1] Dell'Acqua, F., Lacerda, L., Catani, M., Simmons, A., 2014. Anisotropic Power Maps: A diffusion contrast to reveal low anisotropy tissues from HARDI data, in: Proceedings of International Society for Magnetic Resonance in Medicine. Milan, Italy. .
convert_sh_to_full_basis(sh_coeffs)	Given an array of SH coeffs from a symmetric basis, returns the coefficients for the full SH basis by filling odd order SH coefficients with zeros
convert_sh_from_legacy(sh_coeffs, sh_basis)	Convert SH coefficients in legacy SH basis to SH coefficients of the new SH basis for descoteaux07 [1]_ or tournier07 [2]_[3]_ bases.
convert_sh_to_legacy(sh_coeffs, sh_basis[, ...])	Convert SH coefficients in new SH basis to SH coefficients for the legacy SH basis for descoteaux07 [1]_ or tournier07 [2]_[3]_ bases.
convert_sh_descoteaux_tournier(sh_coeffs)	Convert SH coefficients between legacy-descoteaux07 and tournier07.

Module: reconst.shore

ShoreModel(gtab[, radial_order, zeta, ...])	Simple Harmonic Oscillator based Reconstruction and Estimation (SHORE) [1]_ of the diffusion signal.
ShoreFit(model, shore_coef)
shore_matrix(radial_order, zeta, gtab[, tau])	Compute the SHORE matrix for modified Merlet's 3D-SHORE [1]_ ..math:: :nowrap: begin{equation} textbf{E}(qtextbf{u})=sum_{l=0, even}^{N_{max}} sum_{n=l}^{(N_{max}+l)/2} sum_{m=-l}^l c_{nlm} phi_{nlm}(qtextbf{u}) end{equation} where \(\phi_{nlm}\) is ..math:: :nowrap: begin{equation} phi_{nlm}^{SHORE}(qtextbf{u})=Biggl[dfrac{2(n-l)!} {zeta^{3/2} Gamma(n+3/2)} Biggr]^{1/2} Biggl(dfrac{q^2}{zeta}Biggr)^{l/2} expBiggl(dfrac{-q^2}{2zeta}Biggr) L^{l+1/2}_{n-l} Biggl(dfrac{q^2}{zeta}Biggr) Y_l^m(textbf{u}).
shore_matrix_pdf(radial_order, zeta, rtab)	Compute the SHORE propagator matrix [1]_"
shore_matrix_odf(radial_order, zeta, ...)	Compute the SHORE ODF matrix [1]_"
l_shore(radial_order)	Returns the angular regularisation matrix for SHORE basis
n_shore(radial_order)	Returns the angular regularisation matrix for SHORE basis
create_rspace(gridsize, radius_max)	Create the real space table, that contains the points in which
shore_indices(radial_order, index)	Given the basis order and the index, return the shore indices n, l, m for modified Merlet's 3D-SHORE ..math:: :nowrap: begin{equation} textbf{E}(qtextbf{u})=sum_{l=0, even}^{N_{max}} sum_{n=l}^{(N_{max}+l)/2} sum_{m=-l}^l c_{nlm} phi_{nlm}(qtextbf{u}) end{equation} where \(\phi_{nlm}\) is ..math:: :nowrap: begin{equation} phi_{nlm}^{SHORE}(qtextbf{u})=Biggl[dfrac{2(n-l)!} {zeta^{3/2} Gamma(n+3/2)} Biggr]^{1/2} Biggl(dfrac{q^2}{zeta}Biggr)^{l/2} expBiggl(dfrac{-q^2}{2zeta}Biggr) L^{l+1/2}_{n-l} Biggl(dfrac{q^2}{zeta}Biggr) Y_l^m(textbf{u}).
shore_order(n, l, m)	Given the indices (n,l,m) of the basis, return the minimum order for those indices and their index for modified Merlet's 3D-SHORE.

Module: reconst.utils

dki_design_matrix(gtab)	Construct B design matrix for DKI.
cti_design_matrix(gtab1, gtab2)	Construct B design matrix for CTI.
convert_tensors(tensor, from_format, to_format)	Convert tensors from one format to another.

Module: reconst.vec_val_sum

vec_val_vect(vecs, vals)

Vectorize vecs.diag(vals).`vecs`.T for last 2 dimensions of vecs

ReconstModel

class dipy.reconst.base.ReconstModel(gtab)

Bases: object

Abstract class for signal reconstruction models

__init__(gtab)

Initialization of the abstract class for signal reconstruction models

Parameters

gtab : GradientTable class instance

fit(data, mask=None, **kwargs)

ReconstFit

class dipy.reconst.base.ReconstFit(model, data)

Bases: object

Abstract class which holds the fit result of ReconstModel

For example that could be holding FA or GFA etc.

__init__(model, data)

Cache

class dipy.reconst.cache.Cache

Bases: object

Cache values based on a key object (such as a sphere or gradient table).

Notes

This class is meant to be used as a mix-in:

class MyModel(Model, Cache):
    pass

class MyModelFit(Fit):
    pass

Inside a method on the fit, typical usage would be:

def odf(sphere):
    M = self.model.cache_get('odf_basis_matrix', key=sphere)

    if M is None:
        M = self._compute_basis_matrix(sphere)
        self.model.cache_set('odf_basis_matrix', key=sphere, value=M)

__init__()

cache_clear()

Clear the cache.

cache_get(tag, key, default=None)

Retrieve a value from the cache.

Parameters

tagstr

Description of the cached value.

keyobject

Key object used to look up the cached value.

defaultobject

Value to be returned if no cached entry is found.

Returns

vobject

Value from the cache associated with (tag, key). Returns default if no cached entry is found.

cache_set(tag, key, value)

Store a value in the cache.

Parameters

tagstr

Description of the cached value.

keyobject

Key object used to look up the cached value.

valueobject

Value stored in the cache for each unique combination of (tag, key).

Examples

>>> def compute_expensive_matrix(parameters):
...     # Imagine the following computation is very expensive
...     return (p**2 for p in parameters)

>>> c = Cache()

>>> parameters = (1, 2, 3)
>>> X1 = compute_expensive_matrix(parameters)

>>> c.cache_set('expensive_matrix', parameters, X1)
>>> X2 = c.cache_get('expensive_matrix', parameters)

>>> X1 is X2
True

coeff_of_determination

dipy.reconst.cross_validation.coeff_of_determination(data, model, axis=-1)

Calculate the coefficient of determination for a model prediction,

relative to data.

datandarray

The data

modelndarray

The predictions of a model for this data. Same shape as the data.

axis: int, optional

The axis along which different samples are laid out (default: -1).

CODndarray

The coefficient of determination. This has shape data.shape[:-1]

See: https://en.wikipedia.org/wiki/Coefficient_of_determination

The coefficient of determination is calculated as:

\[R^2 = 100 * (1 - \]

rac{SSE}{SSD})

where SSE is the sum of the squared error between the model and the data (sum of the squared residuals) and SSD is the sum of the squares of the deviations of the data from the mean of the data (variance * N).

kfold_xval

dipy.reconst.cross_validation.kfold_xval(model, data, folds, *model_args, **model_kwargs)

Perform k-fold cross-validation.

It generate out-of-sample predictions for each measurement.

Parameters

modelModel class instance

The type of the model to use for prediction. The corresponding Fit object must have a predict function implemented One of the following: reconst.dti.TensorModel or reconst.csdeconv.ConstrainedSphericalDeconvModel.

datandarray

Diffusion MRI data acquired with the GradientTable of the model. Shape will typically be (x, y, z, b) where xyz are spatial dimensions and b is the number of bvals/bvecs in the GradientTable.

foldsint

The number of divisions to apply to the data

model_argslist

Additional arguments to the model initialization

model_kwargsdict

Additional key-word arguments to the model initialization. If contains the kwarg mask, this will be used as a key-word argument to the fit method of the model object, rather than being used in the initialization of the model object

Notes

This function assumes that a prediction API is implemented in the Model class for which prediction is conducted. That is, the Fit object that gets generated upon fitting the model needs to have a predict method, which receives a GradientTable class instance as input and produces a predicted signal as output.

It also assumes that the model object has bval and bvec attributes holding b-values and corresponding unit vectors.

References

[1]

Rokem, A., Chan, K.L. Yeatman, J.D., Pestilli, F., Mezer, A., Wandell, B.A., 2014. Evaluating the accuracy of diffusion models at multiple b-values with cross-validation. ISMRM 2014.

AxSymShResponse

class dipy.reconst.csdeconv.AxSymShResponse(S0, dwi_response, bvalue=None)

Bases: object

A simple wrapper for response functions represented using only axially symmetric, even spherical harmonic functions (ie, m == 0 and l is even).

Parameters

S0float

Signal with no diffusion weighting.

dwi_responsearray

Response function signal as coefficients to axially symmetric, even spherical harmonic.

__init__(S0, dwi_response, bvalue=None)

basis(sphere)

A basis that maps the response coefficients onto a sphere.

on_sphere(sphere)

Evaluates the response function on sphere.

ConstrainedSphericalDeconvModel

class dipy.reconst.csdeconv.ConstrainedSphericalDeconvModel(gtab, response, reg_sphere=None, sh_order_max=8, lambda_=1, tau=0.1, convergence=50)

Bases: SphHarmModel

__init__(gtab, response, reg_sphere=None, sh_order_max=8, lambda_=1, tau=0.1, convergence=50)

Constrained Spherical Deconvolution (CSD) [1]_.

Spherical deconvolution computes a fiber orientation distribution (FOD), also called fiber ODF (fODF) [2]_, as opposed to a diffusion ODF as the QballModel or the CsaOdfModel. This results in a sharper angular profile with better angular resolution that is the best object to be used for later deterministic and probabilistic tractography [3]_.

A sharp fODF is obtained because a single fiber response function is injected as a priori knowledge. The response function is often data-driven and is thus provided as input to the ConstrainedSphericalDeconvModel. It will be used as deconvolution kernel, as described in [1]_.

Parameters

gtab : GradientTable response : tuple or AxSymShResponse object

A tuple with two elements. The first is the eigen-values as an (3,) ndarray and the second is the signal value for the response function without diffusion weighting (i.e. S0). This is to be able to generate a single fiber synthetic signal. The response function will be used as deconvolution kernel ([1]_).

reg_sphereSphere (optional)

sphere used to build the regularization B matrix. Default: ‘symmetric362’.

sh_order_maxint (optional)

maximal spherical harmonics order (l). Default: 8

lambda_float (optional)

weight given to the constrained-positivity regularization part of the deconvolution equation (see [1]_). Default: 1

taufloat (optional)

threshold controlling the amplitude below which the corresponding fODF is assumed to be zero. Ideally, tau should be set to zero. However, to improve the stability of the algorithm, tau is set to tau*100 % of the mean fODF amplitude (here, 10% by default) (see [1]_). Default: 0.1

convergenceint

Maximum number of iterations to allow the deconvolution to converge.

References

[1]

Tournier, J.D., et al. NeuroImage 2007. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution

[2]

Descoteaux, M., et al. IEEE TMI 2009. Deterministic and Probabilistic Tractography Based on Complex Fibre Orientation Distributions

[3]

Côté, M-A., et al. Medical Image Analysis 2013. Tractometer: Towards validation of tractography pipelines

[4]

Tournier, J.D, et al. Imaging Systems and Technology 2012. MRtrix: Diffusion Tractography in Crossing Fiber Regions

fit(data, mask=None)

Fit method for every voxel in data

predict(sh_coeff, gtab=None, S0=1.0)

Compute a signal prediction given spherical harmonic coefficients for the provided GradientTable class instance.

Parameters

sh_coeffndarray

The spherical harmonic representation of the FOD from which to make the signal prediction.

gtabGradientTable

The gradients for which the signal will be predicted. Uses the model’s gradient table by default.

S0ndarray or float

The non diffusion-weighted signal value.

Returns

pred_signdarray

The predicted signal.

ConstrainedSDTModel

class dipy.reconst.csdeconv.ConstrainedSDTModel(gtab, ratio, reg_sphere=None, sh_order_max=8, lambda_=1.0, tau=0.1)

Bases: SphHarmModel

__init__(gtab, ratio, reg_sphere=None, sh_order_max=8, lambda_=1.0, tau=0.1)

Spherical Deconvolution Transform (SDT) [1]_.

The SDT computes a fiber orientation distribution (FOD) as opposed to a diffusion ODF as the QballModel or the CsaOdfModel. This results in a sharper angular profile with better angular resolution. The Constrained SDTModel is similar to the Constrained CSDModel but mathematically it deconvolves the q-ball ODF as oppposed to the HARDI signal (see [1]_ for a comparison and a through discussion).

A sharp fODF is obtained because a single fiber response function is injected as a priori knowledge. In the SDTModel, this response is a single fiber q-ball ODF as opposed to a single fiber signal function for the CSDModel. The response function will be used as deconvolution kernel.

Parameters

gtab : GradientTable ratio : float

ratio of the smallest vs the largest eigenvalue of the single prolate tensor response function

reg_sphereSphere

sphere used to build the regularization B matrix

sh_order_maxint

maximal spherical harmonics order (l)

lambda_float

weight given to the constrained-positivity regularization part of the deconvolution equation

taufloat

threshold (tau *mean(fODF)) controlling the amplitude below which the corresponding fODF is assumed to be zero.

References

[1]

Descoteaux, M., et al. IEEE TMI 2009. Deterministic and Probabilistic Tractography Based on Complex Fibre Orientation Distributions.

fit(data, mask=None)

Fit method for every voxel in data

auto_response

dipy.reconst.csdeconv.auto_response(gtab, data, roi_center=None, roi_radius=10, fa_thr=0.7, fa_callable=None, return_number_of_voxels=None)

Automatic estimation of ssst response function using FA.

dipy.reconst.csdeconv.auto_response is deprecated, Please use dipy.reconst.csdeconv.auto_response_ssst instead

• deprecated from version: 1.2

• Raises <class ‘dipy.utils.deprecator.ExpiredDeprecationError’> as of version: 1.4

Parameters

gtab : GradientTable data : ndarray

diffusion data

roi_centerarray-like, (3,)

Center of ROI in data. If center is None, it is assumed that it is the center of the volume with shape data.shape[:3].

roi_radiusint

radius of cubic ROI

fa_thrfloat

FA threshold

fa_callablecallable

A callable that defines an operation that compares FA with the fa_thr. The operator should have two positional arguments (e.g., fa_operator(FA, fa_thr)) and it should return a bool array.

return_number_of_voxelsbool

If True, returns the number of voxels used for estimating the response function

Returns

responsetuple, (2,)

(evals, S0)

ratiofloat

The ratio between smallest versus largest eigenvalue of the response.

Notes

In CSD there is an important pre-processing step: the estimation of the fiber response function. In order to do this, we look for voxels with very anisotropic configurations. We get this information from csdeconv.mask_for_response_ssst(), which returns a mask of selected voxels (more details are available in the description of the function).

With the mask, we compute the response function by using csdeconv.response_from_mask_ssst(), which returns the response and the ratio (more details are available in the description of the function).

response_from_mask

dipy.reconst.csdeconv.response_from_mask(gtab, data, mask)

Computation of single-shell single-tissue (ssst) response

function from a given mask.

dipy.reconst.csdeconv.response_from_mask is deprecated, Please use dipy.reconst.csdeconv.response_from_mask_ssst instead

• deprecated from version: 1.2

• Raises <class ‘dipy.utils.deprecator.ExpiredDeprecationError’> as of version: 1.4

Parameters

gtab : GradientTable data : ndarray

diffusion data

maskndarray

mask from where to compute the response function

Returns

responsetuple, (2,)

(evals, S0)

ratiofloat

The ratio between smallest versus largest eigenvalue of the response.

Notes

In CSD there is an important pre-processing step: the estimation of the fiber response function. In order to do this, we look for voxels with very anisotropic configurations. This information can be obtained by using csdeconv.mask_for_response_ssst() through a mask of selected voxels (see[1]_). The present function uses such a mask to compute the ssst response function.

For the response we also need to find the average S0 in the ROI. This is possible using gtab.b0s_mask() we can find all the S0 volumes (which correspond to b-values equal 0) in the dataset.

The response consists always of a prolate tensor created by averaging the highest and second highest eigenvalues in the ROI with FA higher than threshold. We also include the average S0s.

We also return the ratio which is used for the SDT models.

References

[1]

Tournier, J.D., et al. NeuroImage 2004. Direct estimation of the

fiber orientation density function from diffusion-weighted MRI data using spherical deconvolution

estimate_response

dipy.reconst.csdeconv.estimate_response(gtab, evals, S0)

Estimate single fiber response function

Parameters

gtab : GradientTable evals : ndarray S0 : float

non diffusion weighted

Returns

S : estimated signal

forward_sdt_deconv_mat

dipy.reconst.csdeconv.forward_sdt_deconv_mat(ratio, l_values, r2_term=False)

Build forward sharpening deconvolution transform (SDT) matrix Parameters ———- ratio : float ratio = \(\frac{\lambda_2}{\lambda_1}\) of the single fiber response function l_values : ndarray (N,) The order (l) of spherical harmonic function associated with each row of the deconvolution matrix. Only even orders are allowed. r2_term : bool True if ODF comes from an ODF computed from a model using the \(r^2\) term in the integral. For example, DSI, GQI, SHORE, CSA, Tensor, Multi-tensor ODFs. This results in using the proper analytical response function solution solving from the single-fiber ODF with the r^2 term. This derivation is not published anywhere but is very similar to [1]_. Returns ——- R : ndarray (N, N) SDT deconvolution matrix P : ndarray (N, N) Funk-Radon Transform (FRT) matrix References ———- .. [1] Descoteaux, M. PhD Thesis. INRIA Sophia-Antipolis. 2008.

csdeconv

dipy.reconst.csdeconv.csdeconv(dwsignal, X, B_reg, tau=0.1, convergence=50, P=None)

Constrained-regularized spherical deconvolution (CSD) [1]_ Deconvolves the axially symmetric single fiber response function r_rh in rotational harmonics coefficients from the diffusion weighted signal in dwsignal. Parameters ———- dwsignal : array Diffusion weighted signals to be deconvolved. X : array Prediction matrix which estimates diffusion weighted signals from FOD coefficients. B_reg : array (N, B) SH basis matrix which maps FOD coefficients to FOD values on the surface of the sphere. B_reg should be scaled to account for lambda. tau : float Threshold controlling the amplitude below which the corresponding fODF is assumed to be zero. Ideally, tau should be set to zero. However, to improve the stability of the algorithm, tau is set to tau*100 % of the max fODF amplitude (here, 10% by default). This is similar to peak detection where peaks below 0.1 amplitude are usually considered noise peaks. Because SDT is based on a q-ball ODF deconvolution, and not signal deconvolution, using the max instead of mean (as in CSD), is more stable. convergence : int Maximum number of iterations to allow the deconvolution to converge. P : ndarray This is an optimization to avoid computing dot(X.T, X) many times. If the same X is used many times, P can be precomputed and passed to this function. Returns ——- fodf_sh : ndarray ((sh_order_max + 1)*(sh_order_max + 2)/2,) Spherical harmonics coefficients of the constrained-regularized fiber ODF. num_it : int Number of iterations in the constrained-regularization used for convergence. Notes —– This section describes how the fitting of the SH coefficients is done. Problem is to minimise per iteration: \(F(f_n) = ||Xf_n - S||^2 + \lambda^2 ||H_{n-1} f_n||^2\) Where \(X\) maps current FOD SH coefficients \(f_n\) to DW signals \(s\) and \(H_{n-1}\) maps FOD SH coefficients \(f_n\) to amplitudes along set of negative directions identified in previous iteration, i.e. the matrix formed by the rows of \(B_{reg}\) for which \(Hf_{n-1}<0\) where \(B_{reg}\) maps \(f_n\) to FOD amplitude on a sphere. Solve by differentiating and setting to zero: \(\Rightarrow \frac{\delta F}{\delta f_n} = 2X^T(Xf_n - S) + 2 \lambda^2 H_{n-1}^TH_{n-1}f_n=0\) Or: \((X^TX + \lambda^2 H_{n-1}^TH_{n-1})f_n = X^Ts\) Define \(Q = X^TX + \lambda^2 H_{n-1}^TH_{n-1}\) , which by construction is a square positive definite symmetric matrix of size \(n_{SH} by n_{SH}\). If needed, positive definiteness can be enforced with a small minimum norm regulariser (helps a lot with poorly conditioned direction sets and/or superresolution): \(Q = X^TX + (\lambda H_{n-1}^T) (\lambda H_{n-1}) + \mu I\) Solve \(Qf_n = X^Ts\) using Cholesky decomposition: \(Q = LL^T\) where \(L\) is lower triangular. Then problem can be solved by back-substitution: \(L_y = X^Ts\) \(L^Tf_n = y\) To speeds things up further, form \(P = X^TX + \mu I\), and update to form \(Q\) by rankn update with \(H_{n-1}\). The dipy implementation looks like: form initially \(P = X^T X + \mu I\) and \(\lambda B_{reg}\) for each voxel: form \(z = X^Ts\) estimate \(f_0\) by solving \(Pf_0=z\). We use a simplified \(l_{max}=4\) solution here, but it might not make a big difference. Then iterate until no change in rows of \(H\) used in \(H_n\) form \(H_{n}\) given \(f_{n-1}\) form \(Q = P + (\lambda H_{n-1}^T) (\lambda H_{n-1}\)) (this can be done by rankn update, but we currently do not use rankn update). solve \(Qf_n = z\) using Cholesky decomposition We’d like to thanks Donald Tournier for his help with describing and implementing this algorithm. References ———- .. [1] Tournier, J.D., et al. NeuroImage 2007. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution.

odf_deconv

dipy.reconst.csdeconv.odf_deconv(odf_sh, R, B_reg, lambda_=1.0, tau=0.1, r2_term=False)

ODF constrained-regularized spherical deconvolution using the Sharpening Deconvolution Transform (SDT) [1]_, [2]_. Parameters ———- odf_sh : ndarray ((sh_order_max + 1)*(sh_order_max + 2)/2,) ndarray of SH coefficients for the ODF spherical function to be deconvolved R : ndarray ((sh_order_max + 1)(sh_order_max + 2)/2, (sh_order_max + 1)(sh_order_max + 2)/2) SDT matrix in SH basis B_reg : ndarray ((sh_order_max + 1)(sh_order_max + 2)/2, (sh_order_max + 1)(sh_order_max + 2)/2) SH basis matrix used for deconvolution lambda_ : float lambda parameter in minimization equation (default 1.0) tau : float threshold (tau *max(fODF)) controlling the amplitude below which the corresponding fODF is assumed to be zero. r2_term : bool True if ODF is computed from model that uses the \(r^2\) term in the integral. Recall that Tuch’s ODF (used in Q-ball Imaging [1]_) and the true normalized ODF definition differ from a \(r^2\) term in the ODF integral. The original Sharpening Deconvolution Transform (SDT) technique [2]_ is expecting Tuch’s ODF without the \(r^2\) (see [3]_ for the mathematical details). Now, this function supports ODF that have been computed using the \(r^2\) term because the proper analytical response function has be derived. For example, models such as DSI, GQI, SHORE, CSA, Tensor, Multi-tensor ODFs, should now be deconvolved with the r2_term=True. Returns ——- fodf_sh : ndarray ((sh_order_max + 1)(sh_order_max + 2)/2,) Spherical harmonics coefficients of the constrained-regularized fiber ODF num_it : int Number of iterations in the constrained-regularization used for convergence References ———- .. [1] Tuch, D. MRM 2004. Q-Ball Imaging. .. [2] Descoteaux, M., et al. IEEE TMI 2009. Deterministic and Probabilistic Tractography Based on Complex Fibre Orientation Distributions .. [3] Descoteaux, M, PhD thesis, INRIA Sophia-Antipolis, 2008.

odf_sh_to_sharp

dipy.reconst.csdeconv.odf_sh_to_sharp(odfs_sh, sphere, basis=None, ratio=0.2, sh_order_max=8, lambda_=1.0, tau=0.1, r2_term=False)

Sharpen odfs using the sharpening deconvolution transform [2]_ This function can be used to sharpen any smooth ODF spherical function. In theory, this should only be used to sharpen QballModel ODFs, but in practice, one can play with the deconvolution ratio and sharpen almost any ODF-like spherical function. The constrained-regularization is stable and will not only sharpen the ODF peaks but also regularize the noisy peaks. Parameters ———- odfs_sh : ndarray ((sh_order_max + 1)*(sh_order_max + 2)/2, ) array of odfs expressed as spherical harmonics coefficients sphere : Sphere sphere used to build the regularization matrix basis : {None, ‘tournier07’, ‘descoteaux07’} different spherical harmonic basis: None for the default DIPY basis, tournier07 for the Tournier 2007 [4]_ basis, and descoteaux07 for the Descoteaux 2007 [3]_ basis (None defaults to descoteaux07). ratio : float, ratio of the smallest vs the largest eigenvalue of the single prolate tensor response function (\(\frac{\lambda_2}{\lambda_1}\)) sh_order_max : int maximal SH order (l) of the SH representation lambda_ : float lambda parameter (see odfdeconv) (default 1.0) tau : float tau parameter in the L matrix construction (see odfdeconv) (default 0.1) r2_term : bool True if ODF is computed from model that uses the \(r^2\) term in the integral. Recall that Tuch’s ODF (used in Q-ball Imaging [1]_) and the true normalized ODF definition differ from a \(r^2\) term in the ODF integral. The original Sharpening Deconvolution Transform (SDT) technique [2]_ is expecting Tuch’s ODF without the \(r^2\) (see [3]_ for the mathematical details). Now, this function supports ODF that have been computed using the \(r^2\) term because the proper analytical response function has be derived. For example, models such as DSI, GQI, SHORE, CSA, Tensor, Multi-tensor ODFs, should now be deconvolved with the r2_term=True. Returns ——- fodf_sh : ndarray sharpened odf expressed as spherical harmonics coefficients References ———- .. [1] Tuch, D. MRM 2004. Q-Ball Imaging. .. [2] Descoteaux, M., et al. IEEE TMI 2009. Deterministic and Probabilistic Tractography Based on Complex Fibre Orientation Distributions .. [3] Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510. .. [4] Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution. NeuroImage. 2007;35(4):1459-1472.

mask_for_response_ssst

dipy.reconst.csdeconv.mask_for_response_ssst(gtab, data, roi_center=None, roi_radii=10, fa_thr=0.7)

Computation of mask for single-shell single-tissue (ssst) response

function using FA.

Parameters

gtab : GradientTable data : ndarray

diffusion data (4D)

roi_centerarray-like, (3,)

Center of ROI in data. If center is None, it is assumed that it is the center of the volume with shape data.shape[:3].

roi_radiiint or array-like, (3,)

radii of cuboid ROI

fa_thrfloat

FA threshold

Returns

maskndarray

Mask of voxels within the ROI and with FA above the FA threshold.

Notes

In CSD there is an important pre-processing step: the estimation of the fiber response function. In order to do this, we look for voxels with very anisotropic configurations. This function aims to accomplish that by returning a mask of voxels within a ROI, that have a FA value above a given threshold. For example we can use a ROI (20x20x20) at the center of the volume and store the signal values for the voxels with FA values higher than 0.7 (see [1]_).

References

[1]

Tournier, J.D., et al. NeuroImage 2004. Direct estimation of the

fiber orientation density function from diffusion-weighted MRI data using spherical deconvolution

response_from_mask_ssst

dipy.reconst.csdeconv.response_from_mask_ssst(gtab, data, mask)

Computation of single-shell single-tissue (ssst) response

function from a given mask.

Parameters

gtab : GradientTable data : ndarray

diffusion data

maskndarray

mask from where to compute the response function

Returns

responsetuple, (2,)

(evals, S0)

ratiofloat

The ratio between smallest versus largest eigenvalue of the response.

Notes

In CSD there is an important pre-processing step: the estimation of the fiber response function. In order to do this, we look for voxels with very anisotropic configurations. This information can be obtained by using csdeconv.mask_for_response_ssst() through a mask of selected voxels (see[1]_). The present function uses such a mask to compute the ssst response function.

For the response we also need to find the average S0 in the ROI. This is possible using gtab.b0s_mask() we can find all the S0 volumes (which correspond to b-values equal 0) in the dataset.

The response consists always of a prolate tensor created by averaging the highest and second highest eigenvalues in the ROI with FA higher than threshold. We also include the average S0s.

We also return the ratio which is used for the SDT models.

References

[1]

Tournier, J.D., et al. NeuroImage 2004. Direct estimation of the

fiber orientation density function from diffusion-weighted MRI data using spherical deconvolution

auto_response_ssst

dipy.reconst.csdeconv.auto_response_ssst(gtab, data, roi_center=None, roi_radii=10, fa_thr=0.7)

Automatic estimation of single-shell single-tissue (ssst) response

function using FA.

Parameters

gtab : GradientTable data : ndarray

diffusion data

roi_centerarray-like, (3,)

Center of ROI in data. If center is None, it is assumed that it is the center of the volume with shape data.shape[:3].

roi_radiiint or array-like, (3,)

radii of cuboid ROI

fa_thrfloat

FA threshold

Returns

responsetuple, (2,)

(evals, S0)

ratiofloat

The ratio between smallest versus largest eigenvalue of the response.

Notes

In CSD there is an important pre-processing step: the estimation of the fiber response function. In order to do this, we look for voxels with very anisotropic configurations. We get this information from csdeconv.mask_for_response_ssst(), which returns a mask of selected voxels (more details are available in the description of the function).

With the mask, we compute the response function by using csdeconv.response_from_mask_ssst(), which returns the response and the ratio (more details are available in the description of the function).

recursive_response

dipy.reconst.csdeconv.recursive_response(gtab, data, mask=None, sh_order_max=8, peak_thr=0.01, init_fa=0.08, init_trace=0.0021, iter=8, convergence=0.001, parallel=False, num_processes=None, sphere=<dipy.core.sphere.HemiSphere object>)

Recursive calibration of response function using peak threshold

Parameters

gtab : GradientTable data : ndarray

diffusion data

maskndarray, optional

mask for recursive calibration, for example a white matter mask. It has shape data.shape[0:3] and dtype=bool. Default: use the entire data array.

sh_order_maxint, optional

maximal spherical harmonics order (l). Default: 8

peak_thrfloat, optional

peak threshold, how large the second peak can be relative to the first peak in order to call it a single fiber population [1]. Default: 0.01

init_fafloat, optional

FA of the initial ‘fat’ response function (tensor). Default: 0.08

init_tracefloat, optional

trace of the initial ‘fat’ response function (tensor). Default: 0.0021

iterint, optional

maximum number of iterations for calibration. Default: 8.

convergencefloat, optional

convergence criterion, maximum relative change of SH coefficients. Default: 0.001.

parallelbool, optional

Whether to use parallelization in peak-finding during the calibration procedure. Default: True

num_processesint, optional

If parallel is True, the number of subprocesses to use (default multiprocessing.cpu_count()). If < 0 the maximal number of cores minus num_processes + 1 is used (enter -1 to use as many cores as possible). 0 raises an error.

sphereSphere, optional.

The sphere used for peak finding. Default: default_sphere.

Returns

responsendarray

response function in SH coefficients

Notes

In CSD there is an important pre-processing step: the estimation of the fiber response function. Using an FA threshold is not a very robust method. It is dependent on the dataset (non-informed used subjectivity), and still depends on the diffusion tensor (FA and first eigenvector), which has low accuracy at high b-value. This function recursively calibrates the response function, for more information see [1].

References

[1]

Tax, C.M.W., et al. NeuroImage 2014. Recursive calibration of the fiber response function for spherical deconvolution of diffusion MRI data.

fa_trace_to_lambdas

dipy.reconst.csdeconv.fa_trace_to_lambdas(fa=0.08, trace=0.0021)

CorrelationTensorModel

class dipy.reconst.cti.CorrelationTensorModel(gtab1, gtab2, fit_method='WLS', *args, **kwargs)

Bases: ReconstModel

Class for the Correlation Tensor Model

__init__(gtab1, gtab2, fit_method='WLS', *args, **kwargs)

Correlation Tensor Imaging Model [1]

Parameters

gtab1: dipy.core.gradients.GradientTable

A GradientTable class instance for first DDE diffusion epoch

gtab2: dipy.core.gradients.GradientTable

A GradientTable class instance for second DDE diffusion epoch

fit_method : str or callable, optional args, kwargs :

arguments and key-word arguments passed to the fit_method.

fit(data, mask=None)

Fit method for every voxel in data

predict(cti_params, S0=1)

Predict a signal for the CTI model class instance given parameters

Parameters

cti_params: numpy.ndarray (…, 48) All parameters estimated from the correlation 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. Fifteen elements of the kurtosis tensor 4. Twenty-One elements of the covariance tensor

gtab1: dipy.core.gradients.GradientTable

A GradientTable class instance for first DDE diffusion epoch

gtab2: dipy.core.gradients.GradientTable

A GradientTable class instance for second DDE diffusion epoch

S0float or ndarray (optional)

The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1

Returns

Snumpy.ndarray

Predicted signal based on the CTI model

CorrelationTensorFit

class dipy.reconst.cti.CorrelationTensorFit(model, model_params)

Bases: DiffusionKurtosisFit

Class for fitting the Correlation Tensor Model

__init__(model, model_params)

Initialize a CorrelationTensorFit class instance.

Parameters

modelCorrelationTensorModel Class instance

Class instance containing the Correlation Tensor Model for the fit

model_paramsndarray (x, y, z, 48) or (n, 48)

All parameters estimated from the diffusion kurtosis 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. Fifteen elements of the kurtosis tensor

4. Twenty One elements of the covariance tensor

property K_aniso

Returns the anisotropic Source of Kurtosis (K_aniso) Notes —– The K_aniso is defined as[1]_: :math:: [K_{aniso} = frac{6}{5} cdot frac{langle V_{lambda}(D_c) rangle}{overline{D}^2}] where: \(K_{aniso}\) is the anisotropic kurtosis, \(\langle V_{\lambda}(D_c) \rangle\) represents the mean of the variance of eigenvalues of the diffusion tensor, \(\overline{D}\) is the mean of the diffusion tensor. References ———- .. [1] [NetoHe2020] Henriques, R.N., Jespersen, S.N., Shemesh, N., 2020. Correlation tensor magnetic resonance imaging. Neuroimage 211. doi: 10.1016/j.neuroimage.2020.116605

property K_iso

Returns the isotropic Source of Kurtosis (K_iso) Notes —– The K_iso is defined as : :math:: $$ K_{text{iso}} = 3 cdot frac{V(overline{D}^c)}{overline{D}^2} $$ where: :math:` K_{text{iso}} ` is the isotropic kurtosis, (V({overline{D}^c})) represents the variance of the diffusion tensor raised to the power c, (overline{D}) is the mean of the diffusion tensor.

property K_micro

Returns Microscopic Source of Kurtosis.

K_total()

Returns the total excess kurtosis. Notes —– \(K_total\) is defined as : :math:: [Psi = frac{2}{5} cdot frac{D_{11}^2 + D_{22}^2 + D_{33}^2 + 2D_{12}^2 + 2D_{13}^2 + 2D_{23}^2{overline{D}^2} - frac{6}{5} ] [{overline{W}} = frac{1}{5} cdot (W_{1111} + W_{2222} + W_{3333} + 2W_{1122} + 2W_{1133} + 2W_{2233}) ] where (Psi) is a variable representing a part of the total excess kurtosis, (D_{ij}) are elements of the diffusion tensor, (overline{D}) is the mean of the diffusion tensor. {overline{W}} is the mean kurtosis, (W_{ijkl}) are elements of the kurtosis tensor.

property ct

Returns the 21 independent elements of the covariance tensor as an array

predict(gtab1, gtab2, S0=1)

Given a CTI model fit, predict the signal on the vertices of a gradient table

Parameters:

params: numpy.ndarray (…,43)

All parameters estimated from the correlation 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. Fifteen elements of the kurtosis tensor 4. Twenty-One elements of the covariance tensor

gtab1: dipy.core.gradients.GradientTable

A GradientTable class instance for first DDE diffusion epoch

gtab2: dipy.core.gradients.GradientTable

A GradientTable class instance for second DDE diffusion epoch

S0float or ndarray (optional)

The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1

Returns

Snumpy.ndarray

Predicted signal based on the CTI model

from_qte_to_cti

dipy.reconst.cti.from_qte_to_cti(C)

Rescales the qte C elements to the C elements used in CTI.

Parameters

C: array(…, 21)

Twenty-one elements of the covariance tensor in voigt notation plus some extra scaling factors.

Returns

ccti: array(…, 21)

Covariance Tensor Elements with no hidden factors.

multi_gaussian_k_from_c

dipy.reconst.cti.multi_gaussian_k_from_c(ccti, MD)

Computes the multiple Gaussian diffusion kurtosis tensor from the covariance tensor.

Parameters

ccti: array(…, 21)

Covariance Tensor Elements with no hidden factors.

MD: Mean Diffusivity (MD) of a diffusion tensor.

Returns

K: array (…, 15)

Fifteen elements of the kurtosis tensor

split_cti_params

dipy.reconst.cti.split_cti_params(cti_params)

Splits CTI params into DTI, DKI, CTI portions.

Extract the diffusion tensor eigenvalues, the diffusion tensor eigenvector matrix, and the 21 independent elements of the covariance tensor, and the 15 independent elements of the kurtosis tensor from the model parameters estimated from the CTI model

Parameters

params: numpy.ndarray (…, 48) All parameters estimated from the correlation 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. Fifteen elements of the kurtosis tensor 4. Twenty-One elements of the covariance tensor

Returns

evalsarray (…, 3)

Eigenvalues from eigen decomposition of the tensor.

evecsarray (…, 3)

Associated eigenvectors from eigen decomposition of the tensor. Eigenvectors are columnar (e.g. evecs[:,j] is associated with evals[j])

ktarray (…, 15)

Fifteen elements of the kurtosis tensor

ct: array(…, 21)

Twenty-one elements of the covariance tensor

cti_prediction

dipy.reconst.cti.cti_prediction(cti_params, gtab1, gtab2, S0=1)

Predict a signal given correlation tensor imaging parameters.

Parameters

cti_params: numpy.ndarray (…, 48) All parameters estimated from the correlation 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. Fifteen elements of the kurtosis tensor 4. Twenty-One elements of the covariance tensor

gtab1: dipy.core.gradients.GradientTable

A GradientTable class instance for first DDE diffusion epoch

gtab2: dipy.core.gradients.GradientTable

A GradientTable class instance for second DDE diffusion epoch

S0float or ndarray (optional)

The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1

Returns

Sndarray

Simulated signal based on the CTI model

params_to_cti_params

dipy.reconst.cti.params_to_cti_params(result, min_diffusivity=0)

ls_fit_cti

dipy.reconst.cti.ls_fit_cti(design_matrix, data, inverse_design_matrix, weights=True, min_diffusivity=0)

Compute the diffusion kurtosis and covariance tensors using an ordinary or weighted linear least squares approach

Parameters

design_matrixarray (g, 43)

Design matrix holding the covariants used to solve for the regression coefficients.

dataarray (g)

Data or response variables holding the data.

inverse_design_matrixarray (43, g)

Inverse of the design matrix.

weightsbool, optional

Parameter indicating whether weights are used. Default: True.

min_diffusivityfloat, optional

Because negative eigenvalues are not physical and small eigenvalues, much smaller than the diffusion weighting, cause quite a lot of noise in metrics such as fa, diffusivity values smaller than min_diffusivity are replaced with min_diffusivity.

Returns

cti_params : array (48) All parameters estimated from the diffusion kurtosis model for all N voxels. Parameters are ordered as follows:

1. Three diffusion tensor eigenvalues.

2. Three blocks of three elements, containing the first second and

   third coordinates of the diffusion tensor eigenvectors.

3. Fifteen elements of the kurtosis tensor.

4. Twenty One elements of the covariance tensor.

DiffusionKurtosisModel

class dipy.reconst.dki.DiffusionKurtosisModel(gtab, fit_method='WLS', return_S0_hat=False, *args, **kwargs)

Bases: ReconstModel

Class for the Diffusion Kurtosis Model

__init__(gtab, fit_method='WLS', return_S0_hat=False, *args, **kwargs)

Diffusion Kurtosis Tensor Model [1]

Parameters

gtabGradientTable instance

The gradient table for the data set.

fit_methodstr or callable, optional

str be one of the following:

‘OLS’ or ‘ULLS’ for ordinary least squares. ‘WLS’, ‘WLLS’ or ‘UWLLS’ for weighted ordinary least squares.

See dki.ls_fit_dki.

‘CLS’ for LMI constrained ordinary least squares [2]. ‘CWLS’ for LMI constrained weighted least squares [2].

See dki.cls_fit_dki.

callable has to have the signature:

fit_method(design_matrix, data, *args, **kwargs).

Default: “WLS”

return_S0_hatbool

Boolean to return (True) or not (False) the S0 values for the fit.

args, kwargs :

arguments and key-word arguments passed to the fit_method.

References

[1]

Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. Estimation of tensors and tensor-derived measures in diffusional kurtosis imaging. Magn Reson Med. 65(3), 823-836

[2]

Dela Haije et al. “Enforcing necessary non-negativity constraints for common diffusion MRI models using sum of squares programming”. NeuroImage 209, 2020, 116405.

fit(data, mask=None)

Fit method of the DKI model.

Parameters

dataarray

The measured signal from one voxel.

maskarray

A boolean array used to mark the coordinates in the data that should be analyzed that has the shape data.shape[-1]

multi_fit(data, mask=None)

Fit method for every voxel in data

predict(dki_params, S0=1.0)

Predict a signal for this DKI model class instance given parameters

Parameters

dki_params : ndarray (x, y, z, 27) or (n, 27) All parameters estimated from the diffusion kurtosis 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. Fifteen elements of the kurtosis tensor

S0float or ndarray (optional)

The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1

DiffusionKurtosisFit

class dipy.reconst.dki.DiffusionKurtosisFit(model, model_params, model_S0=None)

Bases: TensorFit

Class for fitting the Diffusion Kurtosis Model

__init__(model, model_params, model_S0=None)

Initialize a DiffusionKurtosisFit class instance

Since DKI is an extension of DTI, class instance is defined as subclass of the TensorFit from dti.py

Parameters

modelDiffusionKurtosisModel Class instance

Class instance containing the Diffusion Kurtosis Model for the fit

model_paramsndarray (x, y, z, 27) or (n, 27)

All parameters estimated from the diffusion kurtosis model, not including S0. 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. Fifteen elements of the kurtosis tensor

model_S0ndarray (x, y, z, 1) or (n, 1), optional

S0 estimated from the diffusion kurtosis model.

ak(min_kurtosis=-0.42857142857142855, max_kurtosis=10, analytical=True)

Compute axial kurtosis (AK) of a diffusion kurtosis tensor [1]_

Parameters

min_kurtosisfloat (optional)

To keep kurtosis values within a plausible biophysical range, axial kurtosis values that are smaller than min_kurtosis are replaced with -3./7 (theoretical kurtosis limit for regions that consist of water confined to spherical pores [2]_)

max_kurtosisfloat (optional)

To keep kurtosis values within a plausible biophysical range, axial kurtosis values that are larger than max_kurtosis are replaced with max_kurtosis. Default = 10

analyticalbool (optional)

If True, AK is calculated from rotated diffusion kurtosis tensor, otherwise it will be computed from the apparent diffusion kurtosis values along the principal axis of the diffusion tensor (see notes). Default is set to True.

Returns

akarray

Calculated AK.

Notes

AK is defined as the directional kurtosis parallel to the fiber’s main direction e1 [1]_, [2]_. You can compute AK using to approaches:

1. AK is calculated from rotated diffusion kurtosis tensor [2]_, i.e.:

\[AK = \hat{W}_{1111} \frac{(\lambda_{1}+\lambda_{2}+\lambda_{3})^2}{(9 \lambda_{1}^2)}\]

2. AK can be sampled from the principal axis of the diffusion tensor:

\[AK = K(\mathbf{\mathbf{e}_1)\]

Although both approaches leads to an exact calculation of AK, the first approach will be referred to as the analytical method while the second approach will be referred to as the numerical method based on their analogy to the estimation strategies for MK and RK.

References

[1]

Jensen, J.H., Helpern, J.A., 2010. MRI quantification of non-Gaussian water diffusion by kurtosis analysis. NMR in Biomedicine 23(7): 698-710

[2]

Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. Estimation of tensors and tensor-derived measures in diffusional kurtosis imaging. Magn Reson Med. 65(3), 823-836

[3]

Barmpoutis, A., & Zhuo, J., 2011. Diffusion kurtosis imaging: Robust estimation from DW-MRI using homogeneous polynomials. Proceedings of the 8th {IEEE} International Symposium on Biomedical Imaging: From Nano to Macro, ISBI 2011, 262-265. doi: 10.1109/ISBI.2011.5872402

akc(sphere)

Calculate the apparent kurtosis coefficient (AKC) in each direction on the sphere for each voxel in the data Parameters ———- sphere : Sphere class instance Returns ——- akc : ndarray The estimates of the apparent kurtosis coefficient in every direction on the input sphere Notes —– For each sphere direction with coordinates \((n_{1}, n_{2}, n_{3})\), the calculation of AKC is done using formula: .. math :: AKC(n)=frac{MD^{2}}{ADC(n)^{2}}sum_{i=1}^{3}sum_{j=1}^{3} sum_{k=1}^{3}sum_{l=1}^{3}n_{i}n_{j}n_{k}n_{l}W_{ijkl} where \(W_{ijkl}\) are the elements of the kurtosis tensor, MD the mean diffusivity and ADC the apparent diffusion coefficient computed as: .. math :: ADC(n)=sum_{i=1}^{3}sum_{j=1}^{3}n_{i}n_{j}D_{ij} where \(D_{ij}\) are the elements of the diffusion tensor.

property kfa

Return the kurtosis tensor (KFA) [1]_ Notes —– The KFA is defined as [1]_: .. math:: KFA equiv frac{||mathbf{W} - MKT mathbf{I}^{(4)}||_F}{||mathbf{W}||_F} where \(W\) is the kurtosis tensor, MKT the kurtosis tensor mean, \(I^(4)\) is the fully symmetric rank 2 isotropic tensor and \(||...||_F\) is the tensor’s Frobenius norm [1]_. References ———- .. [1] Glenn, G. R., Helpern, J. A., Tabesh, A., and Jensen, J. H. (2015). Quantitative assessment of diffusional kurtosis anisotropy. NMR in Biomedicine 28, 448–459. doi:10.1002/nbm.3271

kmax(sphere='repulsion100', gtol=1e-05, mask=None)

Compute the maximum value of a single voxel kurtosis tensor

Parameters

sphereSphere class instance, optional

The sphere providing sample directions for the initial search of the maximum value of kurtosis.

gtolfloat, optional

This input is to refine kurtosis maximum under the precision of the directions sampled on the sphere class instance. The gradient of the convergence procedure must be less than gtol before successful termination. If gtol is None, fiber direction is directly taken from the initial sampled directions of the given sphere object

Returns

max_valuefloat

kurtosis tensor maximum value

property kt

Return the 15 independent elements of the kurtosis tensor as an array

mk(min_kurtosis=-0.42857142857142855, max_kurtosis=10, analytical=True)

Compute mean kurtosis (MK) from the kurtosis tensor Parameters ———- min_kurtosis : float (optional) To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are smaller than min_kurtosis are replaced with min_kurtosis. Default = -3./7 (theoretical kurtosis limit for regions that consist of water confined to spherical pores [4]_) max_kurtosis : float (optional) To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are larger than max_kurtosis are replaced with max_kurtosis. Default = 10 analytical : bool (optional) If True, MK is calculated using its analytical solution, otherwise an exact numerical estimator is used (see Notes). Default is set to True. Returns ——- mk : array Calculated MK. Notes —– The MK is defined as the average of directional kurtosis coefficients across all spatial directions, which can be formulated by the following surface integral[1]_: .. math:: MK equiv frac{1}{4pi} int dOmega_mathbf{n} K(mathbf{n}) This integral can be numerically solved by averaging directional kurtosis values sampled for directions of a spherical t-design [2]_. Alternatively, MK can be solved from the analytical solution derived by Tabesh et al. [3]_. This solution is given by: .. math:: MK=F_1(lambda_1,lambda_2,lambda_3)hat{W}_{1111}+ F_1(lambda_2,lambda_1,lambda_3)hat{W}_{2222}+ F_1(lambda_3,lambda_2,lambda_1)hat{W}_{3333}+ \ F_2(lambda_1,lambda_2,lambda_3)hat{W}_{2233}+ F_2(lambda_2,lambda_1,lambda_3)hat{W}_{1133}+ F_2(lambda_3,lambda_2,lambda_1)hat{W}_{1122} where \(\hat{W}_{ijkl}\) are the components of the \(W\) tensor in the coordinates system defined by the eigenvectors of the diffusion tensor \(\mathbf{D}\) and .. math:: F_1(lambda_1,lambda_2,lambda_3)= frac{(lambda_1+lambda_2+lambda_3)^2} {18(lambda_1-lambda_2)(lambda_1-lambda_3)} [frac{sqrt{lambda_2lambda_3}}{lambda_1} R_F(frac{lambda_1}{lambda_2},frac{lambda_1}{lambda_3},1)+\ frac{3lambda_1^2-lambda_1lambda_2-lambda_2lambda_3- lambda_1lambda_3} {3lambda_1 sqrt{lambda_2 lambda_3}} R_D(frac{lambda_1}{lambda_2},frac{lambda_1}{lambda_3},1)-1 ] F_2(lambda_1,lambda_2,lambda_3)= frac{(lambda_1+lambda_2+lambda_3)^2} {3(lambda_2-lambda_3)^2} [frac{lambda_2+lambda_3}{sqrt{lambda_2lambda_3}} R_F(frac{lambda_1}{lambda_2},frac{lambda_1}{lambda_3},1)+\ frac{2lambda_1-lambda_2-lambda_3}{3sqrt{lambda_2 lambda_3}} R_D(frac{lambda_1}{lambda_2},frac{lambda_1}{lambda_3},1)-2] where \(R_f\) and \(R_d\) are the Carlson’s elliptic integrals. References ———- .. [1] Jensen, J.H., Helpern, J.A., 2010. MRI quantification of non-Gaussian water diffusion by kurtosis analysis. NMR in Biomedicine 23(7): 698-710 .. [2] Hardin, R.H., Sloane, N.J.A., 1996. McLaren’s Improved Snub Cube and Other New Spherical Designs in Three Dimensions. Discrete and Computational Geometry 15, 429-441. .. [3] Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. Estimation of tensors and tensor-derived measures in diffusional kurtosis imaging. Magn Reson Med. 65(3), 823-836 .. [4] Barmpoutis, A., & Zhuo, J., 2011. Diffusion kurtosis imaging: Robust estimation from DW-MRI using homogeneous polynomials. Proceedings of the 8th {IEEE} International Symposium on Biomedical Imaging: From Nano to Macro, ISBI 2011, 262-265. doi: 10.1109/ISBI.2011.5872402

mkt(min_kurtosis=-0.42857142857142855, max_kurtosis=10)

Compute mean of the kurtosis tensor (MKT) [1]_

Parameters

min_kurtosisfloat (optional)

To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are smaller than min_kurtosis are replaced with min_kurtosis. Default = -3./7 (theoretical kurtosis limit for regions that consist of water confined to spherical pores [2]_)

max_kurtosisfloat (optional)

To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are larger than max_kurtosis are replaced with max_kurtosis. Default = 10

Returns

mktarray

Calculated mean kurtosis tensor.

Notes

The MKT is defined as [1]_:

\[MKT \equiv \frac{1}{4\pi} \int d \Omega_{\mathnbf{n}} n_i n_j n_k n_l W_{ijkl}\]

which can be directly computed from the trace of the kurtosis tensor:

\[\]

MKT = frac{1}{5} Tr(mathbf{W}) = frac{1}{5} (W_{1111} + W_{2222} + W_{3333} + 2W_{1122} + 2W_{1133} + 2W_{2233})

References

[1]

Hansen, B., Lund, T. E., Sangill, R., and Jespersen, S. N. 2013. Experimentally and computationally fast method for estimation of a mean kurtosis. Magnetic Resonance in Medicine69, 1754–1760. 388. doi:10.1002/mrm.24743

[2]

Barmpoutis, A., & Zhuo, J., 2011. Diffusion kurtosis imaging: Robust estimation from DW-MRI using homogeneous polynomials. Proceedings of the 8th {IEEE} International Symposium on Biomedical Imaging: From Nano to Macro, ISBI 2011, 262-265. doi: 10.1109/ISBI.2011.5872402

predict(gtab, S0=1.0)

Given a DKI model fit, predict the signal on the vertices of a gradient table Parameters ———- gtab : a GradientTable class instance The gradient table for this prediction S0 : float or ndarray (optional) The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1 Notes —– The predicted signal is given by: .. math:: S(n,b)=S_{0}e^{-bD(n)+frac{1}{6}b^{2}D(n)^{2}K(n)} \(\mathbf{D(n)}\) and \(\mathbf{K(n)}\) can be computed from the DT and KT using the following equations: .. math:: D(n)=sum_{i=1}^{3}sum_{j=1}^{3}n_{i}n_{j}D_{ij} and .. math:: K(n)=frac{MD^{2}}{D(n)^{2}}sum_{i=1}^{3}sum_{j=1}^{3} sum_{k=1}^{3}sum_{l=1}^{3}n_{i}n_{j}n_{k}n_{l}W_{ijkl} where \(D_{ij}\) and \(W_{ijkl}\) are the elements of the second-order DT and the fourth-order KT tensors, respectively, and \(MD\) is the mean diffusivity.

rk(min_kurtosis=-0.42857142857142855, max_kurtosis=10, analytical=True)

Compute radial kurtosis (RK) of a diffusion kurtosis tensor [1]_

Parameters

min_kurtosisfloat (optional)

To keep kurtosis values within a plausible biophysical range, radial kurtosis values that are smaller than min_kurtosis are replaced with min_kurtosis. Default = -3./7 (theoretical kurtosis limit for regions that consist of water confined to spherical pores [3]_)

max_kurtosisfloat (optional)

To keep kurtosis values within a plausible biophysical range, radial kurtosis values that are larger than max_kurtosis are replaced with max_kurtosis. Default = 10

analyticalbool (optional)

If True, RK is calculated using its analytical solution, otherwise an exact numerical estimator is used (see Notes). Default is set to True

Returns

rkarray

Calculated RK.

Notes

RK is defined as the average of the directional kurtosis perpendicular to the fiber’s main direction e1 [1]_, [2]_:

\[\]

RK equiv frac{1}{2pi} int dOmega _mathbf{theta}

K(mathbf{theta}) delta (mathbf{theta}cdot mathbf{e}_1)

This equation can be numerically computed by averaging apparent directional kurtosis samples for directions perpendicular to e1.

Otherwise, RK can be calculated from its analytical solution [2]_:

\[K_{\bot} = G_1(\lambda_1,\lambda_2,\lambda_3)\hat{W}_{2222} + G_1(\lambda_1,\lambda_3,\lambda_2)\hat{W}_{3333} + G_2(\lambda_1,\lambda_2,\lambda_3)\hat{W}_{2233}\]

where:

\[G_1(\lambda_1,\lambda_2,\lambda_3)= \frac{(\lambda_1+\lambda_2+\lambda_3)^2}{18\lambda_2(\lambda_2- \lambda_3)} \left (2\lambda_2 + \frac{\lambda_3^2-3\lambda_2\lambda_3}{\sqrt{\lambda_2\lambda_3}} \right)\]

and

\[ G_2(\lambda_1,\lambda_2,\lambda_3)= \frac{(\lambda_1+\lambda_2+\lambda_3)^2}{(\lambda_2-\lambda_3)^2} \left ( \frac{\lambda_2+\lambda_3}{\sqrt{\lambda_2\lambda_3}}- 2\right )\]

References

[1]

Jensen, J.H., Helpern, J.A., 2010. MRI quantification of non-Gaussian water diffusion by kurtosis analysis. NMR in Biomedicine 23(7): 698-710

[2]

Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. Estimation of tensors and tensor-derived measures in diffusional kurtosis imaging. Magn Reson Med. 65(3), 823-836

[3]

Barmpoutis, A., & Zhuo, J., 2011. Diffusion kurtosis imaging: Robust estimation from DW-MRI using homogeneous polynomials. Proceedings of the 8th {IEEE} International Symposium on Biomedical Imaging: From Nano to Macro, ISBI 2011, 262-265. doi: 10.1109/ISBI.2011.5872402

carlson_rf

dipy.reconst.dki.carlson_rf(x, y, z, errtol=0.0003)

Compute the Carlson’s incomplete elliptic integral of the first kind

Carlson’s incomplete elliptic integral of the first kind is defined as:

\[R_F = \frac{1}{2} \int_{0}^{\infty} \left [(t+x)(t+y)(t+z) \right ] ^{-\frac{1}{2}}dt\]

Parameters

xndarray

First independent variable of the integral.

yndarray

Second independent variable of the integral.

zndarray

Third independent variable of the integral.

errtolfloat

Error tolerance. Integral is computed with relative error less in magnitude than the defined value

Returns

RFndarray

Value of the incomplete first order elliptic integral

Notes

x, y, and z have to be nonnegative and at most one of them is zero.

References

[1]

Carlson, B.C., 1994. Numerical computation of real or complex elliptic integrals. arXiv:math/9409227 [math.CA]

carlson_rd

dipy.reconst.dki.carlson_rd(x, y, z, errtol=0.0001)

Compute the Carlson’s incomplete elliptic integral of the second kind

Carlson’s incomplete elliptic integral of the second kind is defined as:

\[R_D = \frac{3}{2} \int_{0}^{\infty} (t+x)^{-\frac{1}{2}} (t+y)^{-\frac{1}{2}}(t+z) ^{-\frac{3}{2}}\]

Parameters

xndarray

First independent variable of the integral.

yndarray

Second independent variable of the integral.

zndarray

Third independent variable of the integral.

errtolfloat

Error tolerance. Integral is computed with relative error less in magnitude than the defined value

Returns

RDndarray

Value of the incomplete second order elliptic integral

Notes

x, y, and z have to be nonnegative and at most x or y is zero.

directional_diffusion

dipy.reconst.dki.directional_diffusion(dt, V, min_diffusivity=0)

Calculate the apparent diffusion coefficient (adc) in each direction of a sphere for a single voxel [1]_

Parameters

dtarray (6,)

elements of the diffusion tensor of the voxel.

Varray (g, 3)

g directions of a Sphere in Cartesian coordinates

min_diffusivityfloat (optional)

Because negative eigenvalues are not physical and small eigenvalues cause quite a lot of noise in diffusion-based metrics, diffusivity values smaller than min_diffusivity are replaced with min_diffusivity. Default = 0

Returns

adcndarray (g,)

Apparent diffusion coefficient (adc) in all g directions of a sphere for a single voxel.

References

[1]

Neto Henriques R, Correia MM, Nunes RG, Ferreira HA (2015). Exploring the 3D geometry of the diffusion kurtosis tensor - Impact on the development of robust tractography procedures and novel biomarkers, NeuroImage 111: 85-99

directional_diffusion_variance

dipy.reconst.dki.directional_diffusion_variance(kt, V, min_kurtosis=-0.42857142857142855)

Calculate the apparent diffusion variance (adv) in each direction of a sphere for a single voxel [1]_

Parameters

dtarray (6,)

elements of the diffusion tensor of the voxel.

ktarray (15,)

elements of the kurtosis tensor of the voxel.

Varray (g, 3)

g directions of a Sphere in Cartesian coordinates

min_kurtosisfloat (optional)

Because high-amplitude negative values of kurtosis are not physically and biologicaly pluasible, and these cause artefacts in kurtosis-based measures, directional kurtosis values smaller than min_kurtosis are replaced with min_kurtosis. Default = -3./7 (theoretical kurtosis limit for regions that consist of water confined to spherical pores [2]_)

adcndarray(g,) (optional)

Apparent diffusion coefficient (adc) in all g directions of a sphere for a single voxel.

advndarray(g,) (optional)

Apparent diffusion variance coefficient (advc) in all g directions of a sphere for a single voxel.

Returns

advndarray (g,)

Apparent diffusion variance (adv) in all g directions of a sphere for a single voxel.

References

[1]

Neto Henriques R, Correia MM, Nunes RG, Ferreira HA (2015). Exploring the 3D geometry of the diffusion kurtosis tensor - Impact on the development of robust tractography procedures and novel biomarkers, NeuroImage 111: 85-99

directional_kurtosis

dipy.reconst.dki.directional_kurtosis(dt, md, kt, V, min_diffusivity=0, min_kurtosis=-0.42857142857142855, adc=None, adv=None)

Calculate the apparent kurtosis coefficient (akc) in each direction of a sphere for a single voxel [1]_

Parameters

dtarray (6,)

elements of the diffusion tensor of the voxel.

mdfloat

mean diffusivity of the voxel

ktarray (15,)

elements of the kurtosis tensor of the voxel.

Varray (g, 3)

g directions of a Sphere in Cartesian coordinates

min_diffusivityfloat (optional)

Because negative eigenvalues are not physical and small eigenvalues cause quite a lot of noise in diffusion-based metrics, diffusivity values smaller than min_diffusivity are replaced with min_diffusivity. Default = 0

min_kurtosisfloat (optional)

Because high-amplitude negative values of kurtosis are not physically and biologicaly pluasible, and these cause artefacts in kurtosis-based measures, directional kurtosis values smaller than min_kurtosis are replaced with min_kurtosis. Default = -3./7 (theoretical kurtosis limit for regions that consist of water confined to spherical pores [2]_)

adcndarray(g,) (optional)

Apparent diffusion coefficient (adc) in all g directions of a sphere for a single voxel.

advndarray(g,) (optional)

Apparent diffusion variance (advc) in all g directions of a sphere for a single voxel.

Returns

akcndarray (g,)

Apparent kurtosis coefficient (AKC) in all g directions of a sphere for a single voxel.

References

[1]

Neto Henriques R, Correia MM, Nunes RG, Ferreira HA (2015). Exploring the 3D geometry of the diffusion kurtosis tensor - Impact on the development of robust tractography procedures and novel biomarkers, NeuroImage 111: 85-99

[2]

Barmpoutis, A., & Zhuo, J., 2011. Diffusion kurtosis imaging: Robust estimation from DW-MRI using homogeneous polynomials. Proceedings of the 8th {IEEE} International Symposium on Biomedical Imaging: From Nano to Macro, ISBI 2011, 262-265. doi: 10.1109/ISBI.2011.5872402

apparent_kurtosis_coef

dipy.reconst.dki.apparent_kurtosis_coef(dki_params, sphere, min_diffusivity=0, min_kurtosis=-0.42857142857142855)

Calculate the apparent kurtosis coefficient (AKC) in each direction of a sphere [1]_ Parameters ———- dki_params : ndarray (x, y, z, 27) or (n, 27) All parameters estimated from the diffusion kurtosis 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 eigenvectors respectively 3) Fifteen elements of the kurtosis tensor sphere : a Sphere class instance The AKC will be calculated for each of the vertices in the sphere min_diffusivity : float (optional) Because negative eigenvalues are not physical and small eigenvalues cause quite a lot of noise in diffusion-based metrics, diffusivity values smaller than min_diffusivity are replaced with min_diffusivity. Default = 0 min_kurtosis : float (optional) Because high-amplitude negative values of kurtosis are not physically and biologicaly pluasible, and these cause artefacts in kurtosis-based measures, directional kurtosis values smaller than min_kurtosis are replaced with min_kurtosis. Default = -3./7 (theoretical kurtosis limit for regions that consist of water confined to spherical pores [2]_) Returns ——- akc : ndarray (x, y, z, g) or (n, g) Apparent kurtosis coefficient (AKC) for all g directions of a sphere. Notes —– For each sphere direction with coordinates \((n_{1}, n_{2}, n_{3})\), the calculation of AKC is done using formula [1]_: .. math :: AKC(n)=frac{MD^{2}}{ADC(n)^{2}}sum_{i=1}^{3}sum_{j=1}^{3} sum_{k=1}^{3}sum_{l=1}^{3}n_{i}n_{j}n_{k}n_{l}W_{ijkl} where \(W_{ijkl}\) are the elements of the kurtosis tensor, MD the mean diffusivity and ADC the apparent diffusion coefficient computed as: .. math :: ADC(n)=sum_{i=1}^{3}sum_{j=1}^{3}n_{i}n_{j}D_{ij} where \(D_{ij}\) are the elements of the diffusion tensor. References ———- .. [1] Neto Henriques R, Correia MM, Nunes RG, Ferreira HA (2015). Exploring the 3D geometry of the diffusion kurtosis tensor - Impact on the development of robust tractography procedures and novel biomarkers, NeuroImage 111: 85-99 .. [2] Barmpoutis, A., & Zhuo, J., 2011. Diffusion kurtosis imaging: Robust estimation from DW-MRI using homogeneous polynomials. Proceedings of the 8th {IEEE} International Symposium on Biomedical Imaging: From Nano to Macro, ISBI 2011, 262-265. doi: 10.1109/ISBI.2011.5872402

mean_kurtosis

dipy.reconst.dki.mean_kurtosis(dki_params, min_kurtosis=-0.42857142857142855, max_kurtosis=3, analytical=True)

Compute mean kurtosis (MK) from the kurtosis tensor Parameters ———- dki_params : ndarray (x, y, z, 27) or (n, 27) All parameters estimated from the diffusion kurtosis 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) Fifteen elements of the kurtosis tensor min_kurtosis : float (optional) To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are smaller than min_kurtosis are replaced with min_kurtosis. Default = -3./7 (theoretical kurtosis limit for regions that consist of water confined to spherical pores [4]_) max_kurtosis : float (optional) To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are larger than max_kurtosis are replaced with max_kurtosis. Default = 10 analytical : bool (optional) If True, MK is calculated using its analytical solution, otherwise an exact numerical estimator is used (see Notes). Default is set to True Returns ——- mk : array Calculated MK. Notes —– The MK is defined as the average of directional kurtosis coefficients across all spatial directions, which can be formulated by the following surface integral[1]_: .. math:: MK equiv frac{1}{4pi} int dOmega_mathbf{n} K(mathbf{n}) This integral can be numerically solved by averaging directional kurtosis values sampled for directions of a spherical t-design [2]_. Alternatively, MK can be solved from the analytical solution derived by Tabesh et al. [3]_. This solution is given by: .. math:: MK=F_1(lambda_1,lambda_2,lambda_3)hat{W}_{1111}+ F_1(lambda_2,lambda_1,lambda_3)hat{W}_{2222}+ F_1(lambda_3,lambda_2,lambda_1)hat{W}_{3333}+ \ F_2(lambda_1,lambda_2,lambda_3)hat{W}_{2233}+ F_2(lambda_2,lambda_1,lambda_3)hat{W}_{1133}+ F_2(lambda_3,lambda_2,lambda_1)hat{W}_{1122} where \(\hat{W}_{ijkl}\) are the components of the \(W\) tensor in the coordinates system defined by the eigenvectors of the diffusion tensor \(\mathbf{D}\) and .. math:: F_1(lambda_1,lambda_2,lambda_3)= frac{(lambda_1+lambda_2+lambda_3)^2} {18(lambda_1-lambda_2)(lambda_1-lambda_3)} [frac{sqrt{lambda_2lambda_3}}{lambda_1} R_F(frac{lambda_1}{lambda_2},frac{lambda_1}{lambda_3},1)+\ frac{3lambda_1^2-lambda_1lambda_2-lambda_2lambda_3- lambda_1lambda_3} {3lambda_1 sqrt{lambda_2 lambda_3}} R_D(frac{lambda_1}{lambda_2},frac{lambda_1}{lambda_3},1)-1 ] F_2(lambda_1,lambda_2,lambda_3)= frac{(lambda_1+lambda_2+lambda_3)^2} {3(lambda_2-lambda_3)^2} [frac{lambda_2+lambda_3}{sqrt{lambda_2lambda_3}} R_F(frac{lambda_1}{lambda_2},frac{lambda_1}{lambda_3},1)+\ frac{2lambda_1-lambda_2-lambda_3}{3sqrt{lambda_2 lambda_3}} R_D(frac{lambda_1}{lambda_2},frac{lambda_1}{lambda_3},1)-2] where \(R_f\) and \(R_d\) are the Carlson’s elliptic integrals. References ———- .. [1] Jensen, J.H., Helpern, J.A., 2010. MRI quantification of non-Gaussian water diffusion by kurtosis analysis. NMR in Biomedicine 23(7): 698-710 .. [2] Hardin, R.H., Sloane, N.J.A., 1996. McLaren’s Improved Snub Cube and Other New Spherical Designs in Three Dimensions. Discrete and Computational Geometry 15, 429-441. .. [3] Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. Estimation of tensors and tensor-derived measures in diffusional kurtosis imaging. Magn Reson Med. 65(3), 823-836 .. [4] Barmpoutis, A., & Zhuo, J., 2011. Diffusion kurtosis imaging: Robust estimation from DW-MRI using homogeneous polynomials. Proceedings of the 8th {IEEE} International Symposium on Biomedical Imaging: From Nano to Macro, ISBI 2011, 262-265. doi: 10.1109/ISBI.2011.5872402

radial_kurtosis

dipy.reconst.dki.radial_kurtosis(dki_params, min_kurtosis=-0.42857142857142855, max_kurtosis=10, analytical=True)

Compute radial kurtosis (RK) of a diffusion kurtosis tensor [1]_, [2]_

Parameters

dki_params : ndarray (x, y, z, 27) or (n, 27) All parameters estimated from the diffusion kurtosis 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. Fifteen elements of the kurtosis tensor

min_kurtosisfloat (optional)

To keep kurtosis values within a plausible biophysical range, radial kurtosis values that are smaller than min_kurtosis are replaced with min_kurtosis. Default = -3./7 (theoretical kurtosis limit for regions that consist of water confined to spherical pores [3]_)

max_kurtosisfloat (optional)

To keep kurtosis values within a plausible biophysical range, radial kurtosis values that are larger than max_kurtosis are replaced with max_kurtosis. Default = 10

analyticalbool (optional)

If True, RK is calculated using its analytical solution, otherwise an exact numerical estimator is used (see Notes). Default is set to True.

Returns

rkarray

Calculated RK.

Notes

RK is defined as the average of the directional kurtosis perpendicular to the fiber’s main direction e1 [1]_, [2]_:

\[\]

RK equiv frac{1}{2pi} int dOmega _mathbf{theta} K(mathbf{theta})

delta (mathbf{theta}cdot mathbf{e}_1)

This equation can be numerically computed by averaging apparent directional kurtosis samples for directions perpendicular to e1.

Otherwise, RK can be calculated from its analytical solution [2]_:

\[K_{\bot} = G_1(\lambda_1,\lambda_2,\lambda_3)\hat{W}_{2222} + G_1(\lambda_1,\lambda_3,\lambda_2)\hat{W}_{3333} + G_2(\lambda_1,\lambda_2,\lambda_3)\hat{W}_{2233}\]

where:

\[G_1(\lambda_1,\lambda_2,\lambda_3)= \frac{(\lambda_1+\lambda_2+\lambda_3)^2}{18\lambda_2(\lambda_2- \lambda_3)} \left (2\lambda_2 + \frac{\lambda_3^2-3\lambda_2\lambda_3}{\sqrt{\lambda_2\lambda_3}} \right)\]

and

\[G_2(\lambda_1,\lambda_2,\lambda_3)= \frac{(\lambda_1+\lambda_2+\lambda_3)^2}{(\lambda_2-\lambda_3)^2} \left ( \frac{\lambda_2+\lambda_3}{\sqrt{\lambda_2\lambda_3}}-2\right )\]

References

[1]

Jensen, J.H., Helpern, J.A., 2010. MRI quantification of non-Gaussian water diffusion by kurtosis analysis. NMR in Biomedicine 23(7): 698-710

[2]

Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. Estimation of tensors and tensor-derived measures in diffusional kurtosis imaging. Magn Reson Med. 65(3), 823-836

[3]

Barmpoutis, A., & Zhuo, J., 2011. Diffusion kurtosis imaging: Robust estimation from DW-MRI using homogeneous polynomials. Proceedings of the 8th {IEEE} International Symposium on Biomedical Imaging: From Nano to Macro, ISBI 2011, 262-265. doi: 10.1109/ISBI.2011.5872402

axial_kurtosis

dipy.reconst.dki.axial_kurtosis(dki_params, min_kurtosis=-0.42857142857142855, max_kurtosis=10, analytical=True)

Compute axial kurtosis (AK) from the kurtosis tensor [1]_, [2]_

Parameters

dki_params : ndarray (x, y, z, 27) or (n, 27) All parameters estimated from the diffusion kurtosis 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. Fifteen elements of the kurtosis tensor

min_kurtosisfloat (optional)

To keep kurtosis values within a plausible biophysical range, axial kurtosis values that are smaller than min_kurtosis are replaced with min_kurtosis. Default = -3./7 (theoretical kurtosis limit for regions that consist of water confined to spherical pores [3]_)

max_kurtosisfloat (optional)

To keep kurtosis values within a plausible biophysical range, axial kurtosis values that are larger than max_kurtosis are replaced with max_kurtosis. Default = 10

analyticalbool (optional)

If True, AK is calculated from rotated diffusion kurtosis tensor, otherwise it will be computed from the apparent diffusion kurtosis values along the principal axis of the diffusion tensor (see notes). Default is set to True.

Returns

akarray

Calculated AK.

Notes

AK is defined as the directional kurtosis parallel to the fiber’s main direction e1 [1]_, [2]_. You can compute AK using to approaches:

1. AK is calculated from rotated diffusion kurtosis tensor [2]_, i.e.:

\[AK = \hat{W}_{1111} \frac{(\lambda_{1}+\lambda_{2}+\lambda_{3})^2}{(9 \lambda_{1}^2)}\]

2. AK can be sampled from the principal axis of the diffusion tensor:

\[AK = K(\mathbf{\mathbf{e}_1)\]

Although both approaches leads to an exact calculation of AK, the first approach will be referred to as the analytical method while the second approach will be referred to as the numerical method based on their analogy to the estimation strategies for MK and RK.

References

[1]

Jensen, J.H., Helpern, J.A., 2010. MRI quantification of non-Gaussian water diffusion by kurtosis analysis. NMR in Biomedicine 23(7): 698-710

[2]

Tabesh, A., Jensen, J.H., Ardekani, B.A., Helpern, J.A., 2011. Estimation of tensors and tensor-derived measures in diffusional kurtosis imaging. Magn Reson Med. 65(3), 823-836

[3]

Barmpoutis, A., & Zhuo, J., 2011. Diffusion kurtosis imaging: Robust estimation from DW-MRI using homogeneous polynomials. Proceedings of the 8th {IEEE} International Symposium on Biomedical Imaging: From Nano to Macro, ISBI 2011, 262-265. doi: 10.1109/ISBI.2011.5872402

kurtosis_maximum

dipy.reconst.dki.kurtosis_maximum(dki_params, sphere='repulsion100', gtol=0.01, mask=None)

Compute kurtosis maximum value

Parameters

dki_params : ndarray (x, y, z, 27) or (n, 27) All parameters estimated from the diffusion kurtosis model. Parameters are ordered as follows:

1. Three diffusion tensor’s eingenvalues

2. Three lines of the eigenvector matrix each containing the first,

   second and third coordinates of the eigenvector

3. Fifteen elements of the kurtosis tensor

sphereSphere class instance, optional

The sphere providing sample directions for the initial search of the maximal value of kurtosis.

gtolfloat, optional

This input is to refine kurtosis maximum under the precision of the directions sampled on the sphere class instance. The gradient of the convergence procedure must be less than gtol before successful termination. If gtol is None, fiber direction is directly taken from the initial sampled directions of the given sphere object

maskndarray

A boolean array used to mark the coordinates in the data that should be analyzed that has the shape dki_params.shape[:-1]

Returns

max_valuefloat

kurtosis tensor maximum value

max_dirarray (3,)

Cartesian coordinates of the direction of the maximal kurtosis value

mean_kurtosis_tensor

dipy.reconst.dki.mean_kurtosis_tensor(dki_params, min_kurtosis=-0.42857142857142855, max_kurtosis=10)

Compute mean of the kurtosis tensor (MKT) [1]_

Parameters

dki_params : ndarray (x, y, z, 27) or (n, 27) All parameters estimated from the diffusion kurtosis 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. Fifteen elements of the kurtosis tensor

min_kurtosisfloat (optional)

To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are smaller than min_kurtosis are replaced with min_kurtosis. Default = -3./7 (theoretical kurtosis limit for regions that consist of water confined to spherical pores [2]_)

max_kurtosisfloat (optional)

To keep kurtosis values within a plausible biophysical range, mean kurtosis values that are larger than max_kurtosis are replaced with max_kurtosis. Default = 10

Returns

mktarray

Calculated mean kurtosis tensor.

Notes

The MKT is defined as [1]_:

\[MKT \equiv \frac{1}{4\pi} \int d \Omega_{\mathnbf{n}} n_i n_j n_k n_l W_{ijkl}\]

which can be directly computed from the trace of the kurtosis tensor:

\[\]

MKT = frac{1}{5} Tr(mathbf{W}) = frac{1}{5} (W_{1111} + W_{2222} + W_{3333} + 2W_{1122} + 2W_{1133} + 2W_{2233})

References

[1]

Hansen, B., Lund, T. E., Sangill, R., and Jespersen, S. N. (2013). Experimentally and computationally fast method for estimation of a mean kurtosis.Magnetic Resonance in Medicine69, 1754–1760.388 doi:10.1002/mrm.24743

[2]

Barmpoutis, A., & Zhuo, J., 2011. Diffusion kurtosis imaging: Robust estimation from DW-MRI using homogeneous polynomials. Proceedings of the 8th {IEEE} International Symposium on Biomedical Imaging: From Nano to Macro, ISBI 2011, 262-265. doi: 10.1109/ISBI.2011.5872402

kurtosis_fractional_anisotropy

dipy.reconst.dki.kurtosis_fractional_anisotropy(dki_params)

Compute the anisotropy of the kurtosis tensor (KFA) [1]_ Parameters ———- dki_params : ndarray (x, y, z, 27) or (n, 27) All parameters estimated from the diffusion kurtosis 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) Fifteen elements of the kurtosis tensor Returns ——- kfa : array Calculated mean kurtosis tensor. Notes —– The KFA is defined as [1]_: .. math:: KFA equiv frac{||mathbf{W} - MKT mathbf{I}^{(4)}||_F}{||mathbf{W}||_F} where \(W\) is the kurtosis tensor, MKT the kurtosis tensor mean, \(I^(4)\) is the fully symmetric rank 2 isotropic tensor and \(||...||_F\) is the tensor’s Frobenius norm [1]_. References ———- .. [1] Glenn, G. R., Helpern, J. A., Tabesh, A., and Jensen, J. H. (2015). Quantitative assessment of diffusional kurtosis anisotropy. NMR in Biomedicine 28, 448–459. doi:10.1002/nbm.3271

dki_prediction

dipy.reconst.dki.dki_prediction(dki_params, gtab, S0=1.0)

Predict a signal given diffusion kurtosis imaging parameters

dki_params : ndarray (x, y, z, 27) or (n, 27) All parameters estimated from the diffusion kurtosis 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. Fifteen elements of the kurtosis tensor

gtaba GradientTable class instance

The gradient table for this prediction

S0float or ndarray (optional)

The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1

S(…, N) ndarray

Simulated signal based on the DKI model:

\[S=S_{0}e^{-bD+\]

rac{1}{6}b^{2}D^{2}K}

params_to_dki_params

dipy.reconst.dki.params_to_dki_params(result, min_diffusivity=0)

ls_fit_dki

dipy.reconst.dki.ls_fit_dki(design_matrix, data, inverse_design_matrix, return_S0_hat=False, weights=True, min_diffusivity=0)

Compute the diffusion and kurtosis tensors using an ordinary or weighted linear least squares approach [1]_

Parameters

design_matrixarray (g, 22)

Design matrix holding the covariants used to solve for the regression coefficients.

dataarray (g)

Data or response variables holding the data.

inverse_design_matrixarray (22, g)

Inverse of the design matrix.

return_S0_hatbool, optional

Boolean to return (True) or not (False) the S0 values for the fit.

weightsbool, optional

Parameter indicating whether weights are used. Default: True.

min_diffusivityfloat, optional

Because negative eigenvalues are not physical and small eigenvalues, much smaller than the diffusion weighting, cause quite a lot of noise in metrics such as fa, diffusivity values smaller than min_diffusivity are replaced with min_diffusivity.

Returns

dki_params : array (27) All parameters estimated from the diffusion kurtosis model for all N voxels. Parameters are ordered as follows:

1. Three diffusion tensor eigenvalues.

2. Three blocks of three elements, containing the first second and

   third coordinates of the diffusion tensor eigenvectors.

3. Fifteen elements of the kurtosis tensor.

References

[1] Veraart, J., Sijbers, J., Sunaert, S., Leemans, A., Jeurissen, B.,

2013. Weighted linear least squares estimation of diffusion MRI parameters: Strengths, limitations, and pitfalls. Magn Reson Med 81, 335-346.

cls_fit_dki

dipy.reconst.dki.cls_fit_dki(design_matrix, data, inverse_design_matrix, sdp, return_S0_hat=False, weights=True, min_diffusivity=0, cvxpy_solver=None)

Compute the diffusion and kurtosis tensors using a constrained ordinary or weighted linear least squares approach [1]_

Parameters

design_matrixarray (g, 22)

Design matrix holding the covariants used to solve for the regression coefficients.

dataarray (g)

Data or response variables holding the data.

inverse_design_matrixarray (22, g)

Inverse of the design matrix.

sdpPositiveDefiniteLeastSquares instance

A CVXPY representation of a regularized least squares optimization problem.

return_S0_hatbool, optional

Boolean to return (True) or not (False) the S0 values for the fit.

weightsbool, optional

Parameter indicating whether weights are used. Default: True.

min_diffusivityfloat, optional

Because negative eigenvalues are not physical and small eigenvalues, much smaller than the diffusion weighting, cause quite a lot of noise in metrics such as fa, diffusivity values smaller than min_diffusivity are replaced with min_diffusivity.

cvxpy_solverstr, optional

cvxpy solver name. Optionally optimize the positivity constraint with a particular cvxpy solver. See https://www.cvxpy.org/ for details. Default: None (cvxpy chooses its own solver).

Returns

dki_params : array (27) All parameters estimated from the diffusion kurtosis model for all N voxels. Parameters are ordered as follows:

1. Three diffusion tensor eigenvalues.

2. Three blocks of three elements, containing the first second and

   third coordinates of the diffusion tensor eigenvectors.

3. Fifteen elements of the kurtosis tensor.

References

[1]

Dela Haije et al. “Enforcing necessary non-negativity constraints for common diffusion MRI models using sum of squares programming”. NeuroImage 209, 2020, 116405.

Wrotate

dipy.reconst.dki.Wrotate(kt, Basis)

Rotate a kurtosis tensor from the standard Cartesian coordinate system to another coordinate system basis

Parameters

kt(15,)

Vector with the 15 independent elements of the kurtosis tensor

Basisarray (3, 3)

Vectors of the basis column-wise oriented

indsarray(m, 4) (optional)

Array of vectors containing the four indexes of m specific elements of the rotated kurtosis tensor. If not specified all 15 elements of the rotated kurtosis tensor are computed.

Returns

Wrotarray (m,) or (15,)

Vector with the m independent elements of the rotated kurtosis tensor. If ‘indices’ is not specified all 15 elements of the rotated kurtosis tensor are computed.

Notes

KT elements are assumed to be ordered as follows:

\[\]

begin{matrix} ( & W_{xxxx} & W_{yyyy} & W_{zzzz} & W_{xxxy} & W_{xxxz}

& … \ & W_{xyyy} & W_{yyyz} & W_{xzzz} & W_{yzzz} & W_{xxyy} & … \ & W_{xxzz} & W_{yyzz} & W_{xxyz} & W_{xyyz} & W_{xyzz} & & )end{matrix}

References

[1] Hui ES, Cheung MM, Qi L, Wu EX, 2008. Towards better MR characterization of neural tissues using directional diffusion kurtosis analysis. Neuroimage 42(1): 122-34

Wrotate_element

dipy.reconst.dki.Wrotate_element(kt, indi, indj, indk, indl, B)

Compute the the specified index element of a kurtosis tensor rotated to the coordinate system basis B

Parameters

ktndarray (x, y, z, 15) or (n, 15)

Array containing the 15 independent elements of the kurtosis tensor

indiint

Rotated kurtosis tensor element index i (0 for x, 1 for y, 2 for z)

indjint

Rotated kurtosis tensor element index j (0 for x, 1 for y, 2 for z)

indkint

Rotated kurtosis tensor element index k (0 for x, 1 for y, 2 for z)

indl: int

Rotated kurtosis tensor element index l (0 for x, 1 for y, 2 for z)

B: array (x, y, z, 3, 3) or (n, 15)

Vectors of the basis column-wise oriented

Returns

Wrefloat

rotated kurtosis tensor element of index ind_i, ind_j, ind_k, ind_l

Notes

It is assumed that initial kurtosis tensor elementes are defined on the Cartesian coordinate system.

References

[1] Hui ES, Cheung MM, Qi L, Wu EX, 2008. Towards better MR characterization of neural tissues using directional diffusion kurtosis analysis. Neuroimage 42(1): 122-34

Wcons

dipy.reconst.dki.Wcons(k_elements)

Construct the full 4D kurtosis tensors from its 15 independent elements

Parameters

k_elements(15,)

elements of the kurtosis tensor in the following order:

\[\]

begin{matrix} ( & W_{xxxx} & W_{yyyy} & W_{zzzz} & W_{xxxy} & W_{xxxz}

& … \ & W_{xyyy} & W_{yyyz} & W_{xzzz} & W_{yzzz} & W_{xxyy} & … \ & W_{xxzz} & W_{yyzz} & W_{xxyz} & W_{xyyz} & W_{xyzz} & & )end{matrix}

Returns

Warray(3, 3, 3, 3)

Full 4D kurtosis tensor

split_dki_param

dipy.reconst.dki.split_dki_param(dki_params)

Extract the diffusion tensor eigenvalues, the diffusion tensor eigenvector matrix, and the 15 independent elements of the kurtosis tensor from the model parameters estimated from the DKI model

Parameters

dki_params : ndarray (x, y, z, 27) or (n, 27) All parameters estimated from the diffusion kurtosis 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. Fifteen elements of the kurtosis tensor

Returns

eigvalsarray (x, y, z, 3) or (n, 3)

Eigenvalues from eigen decomposition of the tensor.

eigvecsarray (x, y, z, 3, 3) or (n, 3, 3)

Associated eigenvectors from eigen decomposition of the tensor. Eigenvectors are columnar (e.g. eigvecs[:,j] is associated with eigvals[j])

ktarray (x, y, z, 15) or (n, 15)

Fifteen elements of the kurtosis tensor

KurtosisMicrostructureModel

class dipy.reconst.dki_micro.KurtosisMicrostructureModel(gtab, fit_method='WLS', *args, **kwargs)

Bases: DiffusionKurtosisModel

Class for the Diffusion Kurtosis Microstructural Model

__init__(gtab, fit_method='WLS', *args, **kwargs)

Initialize a KurtosisMicrostrutureModel class instance [1]_.

Parameters

gtab : GradientTable class instance

fit_methodstr or callable

str can be one of the following: ‘OLS’ or ‘ULLS’ to fit the diffusion tensor and kurtosis tensor using the ordinary linear least squares solution

dki.ols_fit_dki

‘WLS’ or ‘UWLLS’ to fit the diffusion tensor and kurtosis tensor using the ordinary linear least squares solution

dki.wls_fit_dki

callable has to have the signature:

fit_method(design_matrix, data, *args, **kwargs)

args, kwargsarguments and key-word arguments passed to the

fit_method. See dki.ols_fit_dki, dki.wls_fit_dki for details

References

[1]

Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter Characterization with Diffusion Kurtosis Imaging. Neuroimage 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006

fit(data, mask=None, sphere='repulsion100', gtol=0.01, awf_only=False)

Fit method of the Diffusion Kurtosis Microstructural Model

Parameters

dataarray

An 4D matrix containing the diffusion-weighted data.

maskarray

A boolean array used to mark the coordinates in the data that should be analyzed that has the shape data.shape[-1]

sphereSphere class instance, optional

The sphere providing sample directions for the initial search of the maximal value of kurtosis.

gtolfloat, optional

This input is to refine kurtosis maxima under the precision of the directions sampled on the sphere class instance. The gradient of the convergence procedure must be less than gtol before successful termination. If gtol is None, fiber direction is directly taken from the initial sampled directions of the given sphere object

awf_onlybool, optiomal

If set to true only the axonal volume fraction is computed from the kurtosis tensor. Default = False

predict(params, S0=1.0)

Predict a signal for the DKI microstructural model class instance given parameters.

Parameters

paramsndarray (x, y, z, 40) or (n, 40)

All parameters estimated from the diffusion kurtosis microstructural 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. Fifteen elements of the kurtosis tensor

4. Six elements of the hindered diffusion tensor

5. Six elements of the restricted diffusion tensor

6. Axonal water fraction

S0float or ndarray (optional)

The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1

Notes

In the original article of DKI microstructural model [1]_, the hindered and restricted tensors were defined as the intra-cellular and extra-cellular diffusion compartments respectively.

References

[1]

Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter Characterization with Diffusion Kurtosis Imaging. Neuroimage 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006

KurtosisMicrostructuralFit

class dipy.reconst.dki_micro.KurtosisMicrostructuralFit(model, model_params)

Bases: DiffusionKurtosisFit

Class for fitting the Diffusion Kurtosis Microstructural Model

__init__(model, model_params)

Initialize a KurtosisMicrostructural Fit class instance.

Parameters

modelDiffusionKurtosisModel Class instance

Class instance containing the Diffusion Kurtosis Model for the fit

model_paramsndarray (x, y, z, 40) or (n, 40)

All parameters estimated from the diffusion kurtosis microstructural 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. Fifteen elements of the kurtosis tensor

4. Six elements of the hindered diffusion tensor

5. Six elements of the restricted diffusion tensor

6. Axonal water fraction

Notes

In the original article of DKI microstructural model [1]_, the hindered and restricted tensors were defined as the intra-cellular and extra-cellular diffusion compartments respectively.

References

[1]

Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter Characterization with Diffusion Kurtosis Imaging. Neuroimage 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006

property awf

Returns the volume fraction of the restricted diffusion compartment also known as axonal water fraction.

Notes

The volume fraction of the restricted diffusion compartment can be seem as the volume fraction of the intra-cellular compartment [1]_.

References

[1]

Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter Characterization with Diffusion Kurtosis Imaging. Neuroimage 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006

property axonal_diffusivity

Returns the axonal diffusivity defined as the restricted diffusion tensor trace [1]_.

References

[1]

Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter Characterization with Diffusion Kurtosis Imaging. Neuroimage 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006

property hindered_ad

Returns the axial diffusivity of the hindered compartment.

Notes

The hindered diffusion tensor can be seem as the tissue’s extra-cellular diffusion compartment [1]_.

References

[1]

Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter Characterization with Diffusion Kurtosis Imaging. Neuroimage 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006

property hindered_evals

Returns the eigenvalues of the hindered diffusion compartment.

Notes

The hindered diffusion tensor can be seem as the tissue’s extra-cellular diffusion compartment [1]_.

References

[1]

Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter Characterization with Diffusion Kurtosis Imaging. Neuroimage 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006

property hindered_rd

Returns the radial diffusivity of the hindered compartment.

Notes

The hindered diffusion tensor can be seem as the tissue’s extra-cellular diffusion compartment [1]_.

References

[1]

Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter Characterization with Diffusion Kurtosis Imaging. Neuroimage 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006

predict(gtab, S0=1.0)

Given a DKI microstructural model fit, predict the signal on the vertices of a gradient table gtab : a GradientTable class instance The gradient table for this prediction S0 : float or ndarray (optional) The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1 Notes —– The predicted signal is given by: \(S(\theta, b) = S_0 * [f * e^{-b ADC_{r}} + (1-f) * e^{-b ADC_{h}]\), where \(ADC_{r}\) and \(ADC_{h}\) are the apparent diffusion coefficients of the diffusion hindered and restricted compartment for a given direction \(\theta\), \(b\) is the b value provided in the GradientTable input for that direction, \(f\) is the volume fraction of the restricted diffusion compartment (also known as the axonal water fraction).

property restricted_evals

Returns the eigenvalues of the restricted diffusion compartment.

Notes

The restricted diffusion tensor can be seem as the tissue’s intra-cellular diffusion compartment [1]_.

References

[1]

Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter Characterization with Diffusion Kurtosis Imaging. Neuroimage 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006

property tortuosity

Returns the tortuosity of the hindered diffusion which is defined by ADe / RDe, where ADe and RDe are the axial and radial diffusivities of the hindered compartment [1]_.

Notes

The hindered diffusion tensor can be seem as the tissue’s extra-cellular diffusion compartment [1]_.

References

[1]

Fieremans, E., Jensen, J.H., Helpern, J.A., 2011. White Matter Characterization with Diffusion Kurtosis Imaging. Neuroimage 58(1): 177-188. doi:10.1016/j.neuroimage.2011.06.006

axonal_water_fraction

dipy.reconst.dki_micro.axonal_water_fraction(dki_params, sphere='repulsion100', gtol=0.01, mask=None)

Computes the axonal water fraction from DKI [1]_.

Parameters

dki_paramsndarray (x, y, z, 27) or (n, 27)

All parameters estimated from the diffusion kurtosis 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. Fifteen elements of the kurtosis tensor

sphereSphere class instance, optional

The sphere providing sample directions for the initial search of the maximal value of kurtosis.

gtolfloat, optional

This input is to refine kurtosis maxima under the precision of the directions sampled on the sphere class instance. The gradient of the convergence procedure must be less than gtol before successful termination. If gtol is None, fiber direction is directly taken from the initial sampled directions of the given sphere object

maskndarray

A boolean array used to mark the coordinates in the data that should be analyzed that has the shape dki_params.shape[:-1]

Returns

awfndarray (x, y, z) or (n)

Axonal Water Fraction

References

[1]

Fieremans E, Jensen JH, Helpern JA, 2011. White matter characterization with diffusional kurtosis imaging. Neuroimage 58(1):177-88. doi: 10.1016/j.neuroimage.2011.06.006

diffusion_components

dipy.reconst.dki_micro.diffusion_components(dki_params, sphere='repulsion100', awf=None, mask=None)

Extracts the restricted and hindered diffusion tensors of well aligned fibers from diffusion kurtosis imaging parameters [1]_.

Parameters

dki_paramsndarray (x, y, z, 27) or (n, 27)

All parameters estimated from the diffusion kurtosis 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. Fifteen elements of the kurtosis tensor

sphereSphere class instance, optional

The sphere providing sample directions to sample the restricted and hindered cellular diffusion tensors. For more details see Fieremans et al., 2011.

awfndarray (optional)

Array containing values of the axonal water fraction that has the shape dki_params.shape[:-1]. If not given this will be automatically computed using axonal_water_fraction()” with function’s default precision.

maskndarray (optional)

A boolean array used to mark the coordinates in the data that should be analyzed that has the shape dki_params.shape[:-1]

Returns

edtndarray (x, y, z, 6) or (n, 6)

Parameters of the hindered diffusion tensor.

idtndarray (x, y, z, 6) or (n, 6)

Parameters of the restricted diffusion tensor.

Notes

In the original article of DKI microstructural model [1]_, the hindered and restricted tensors were defined as the intra-cellular and extra-cellular diffusion compartments respectively.

References

[1]

Fieremans E, Jensen JH, Helpern JA, 2011. White matter characterization with diffusional kurtosis imaging. Neuroimage 58(1):177-88. doi: 10.1016/j.neuroimage.2011.06.006

dkimicro_prediction

dipy.reconst.dki_micro.dkimicro_prediction(params, gtab, S0=1)

Signal prediction given the DKI microstructure model parameters. Parameters ———- params : ndarray (x, y, z, 40) or (n, 40) All parameters estimated from the diffusion kurtosis microstructure 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) Fifteen elements of the kurtosis tensor 4) Six elements of the hindered diffusion tensor 5) Six elements of the restricted diffusion tensor 6) Axonal water fraction gtab : a GradientTable class instance The gradient table for this prediction S0 : float or ndarray The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1 Returns ——- S : (…, N) ndarray Simulated signal based on the DKI microstructure model Notes —– 1) The predicted signal is given by: \(S(\theta, b) = S_0 * [f * e^{-b ADC_{r}} + (1-f) * e^{-b ADC_{h}]\), where :math:` ADC_{r} and ADC_{h} are the apparent diffusion coefficients of the diffusion hindered and restricted compartment for a given direction theta:math:, b:math: is the b value provided in the GradientTable input for that direction, `f$ is the volume fraction of the restricted diffusion compartment (also known as the axonal water fraction). 2) In the original article of DKI microstructural model [1]_, the hindered and restricted tensors were defined as the intra-cellular and extra-cellular diffusion compartments respectively.

tortuosity

dipy.reconst.dki_micro.tortuosity(hindered_ad, hindered_rd)

Computes the tortuosity of the hindered diffusion compartment given its axial and radial diffusivities

Parameters

hindered_ad: ndarray

Array containing the values of the hindered axial diffusivity.

hindered_rd: ndarray

Array containing the values of the hindered radial diffusivity.

Returns

Tortuosity of the hindered diffusion compartment

DiffusionSpectrumModel

class dipy.reconst.dsi.DiffusionSpectrumModel(gtab, qgrid_size=17, r_start=2.1, r_end=6.0, r_step=0.2, filter_width=32, normalize_peaks=False)

Bases: OdfModel, Cache

__init__(gtab, qgrid_size=17, r_start=2.1, r_end=6.0, r_step=0.2, filter_width=32, normalize_peaks=False)

Diffusion Spectrum Imaging The theoretical idea underlying this method is that the diffusion propagator \(P(\mathbf{r})\) (probability density function of the average spin displacements) can be estimated by applying 3D FFT to the signal values \(S(\mathbf{q})\) ..math:: :nowrap: begin{eqnarray} P(mathbf{r}) & = & S_{0}^{-1}int S(mathbf{q})exp(-i2pimathbf{q}cdotmathbf{r})dmathbf{r} end{eqnarray} where \(\mathbf{r}\) is the displacement vector and \(\mathbf{q}\) is the wave vector which corresponds to different gradient directions. Method used to calculate the ODFs. Here we implement the method proposed by Wedeen et al. [1]_. The main assumption for this model is fast gradient switching and that the acquisition gradients will sit on a keyhole Cartesian grid in q_space [3]_. Parameters ———- gtab : GradientTable, Gradient directions and bvalues container class qgrid_size : int, has to be an odd number. Sets the size of the q_space grid. For example if qgrid_size is 17 then the shape of the grid will be (17, 17, 17). r_start : float, ODF is sampled radially in the PDF. This parameters shows where the sampling should start. r_end : float, Radial endpoint of ODF sampling r_step : float, Step size of the ODf sampling from r_start to r_end filter_width : float, Strength of the hanning filter References ———- .. [1] Wedeen V.J et al., “Mapping Complex Tissue Architecture With Diffusion Spectrum Magnetic Resonance Imaging”, MRM 2005. .. [2] Canales-Rodriguez E.J et al., “Deconvolution in Diffusion Spectrum Imaging”, Neuroimage, 2010. .. [3] Garyfallidis E, “Towards an accurate brain tractography”, PhD thesis, University of Cambridge, 2012. Examples ——– In this example where we provide the data, a gradient table and a reconstruction sphere, we calculate generalized FA for the first voxel in the data with the reconstruction performed using DSI. >>> import warnings >>> from dipy.data import dsi_voxels, default_sphere >>> data, gtab = dsi_voxels() >>> from dipy.reconst.dsi import DiffusionSpectrumModel >>> ds = DiffusionSpectrumModel(gtab) >>> dsfit = ds.fit(data) >>> from dipy.reconst.odf import gfa >>> np.round(gfa(dsfit.odf(default_sphere))[0, 0, 0], 2) 0.11 Notes —– A. Have in mind that DSI expects gradients on both hemispheres. If your gradients span only one hemisphere you need to duplicate the data and project them to the other hemisphere before calling this class. The function dipy.reconst.dsi.half_to_full_qspace can be used for this purpose. B. If you increase the size of the grid (parameter qgrid_size) you will most likely also need to update the r_* parameters. This is because the added zero padding from the increase of gqrid_size also introduces a scaling of the PDF. C. We assume that data only one b0 volume is provided. See Also ——– dipy.reconst.gqi.GeneralizedQSampling

fit(data, mask=None)

Fit method for every voxel in data

DiffusionSpectrumFit

class dipy.reconst.dsi.DiffusionSpectrumFit(model, data)

Bases: OdfFit

__init__(model, data)

Calculates PDF and ODF and other properties for a single voxel

Parameters

modelobject,

DiffusionSpectrumModel

data1d ndarray,

signal values

msd_discrete(normalized=True)

Calculates the mean squared displacement on the discrete propagator ..math:: :nowrap: begin{equation} MSD:{DSI}=int_{-infty}^{infty}int_{-infty}^{infty}int_{-infty}^{infty} P(hat{mathbf{r}}) cdot hat{mathbf{r}}^{2} dr_x dr_y dr_z end{equation} where \(\hat{\mathbf{r}}\) is a point in the 3D Propagator space (see Wu et al. [1]_). Parameters ———- normalized : boolean, optional Whether to normalize the propagator by its sum in order to obtain a pdf. Default: True Returns ——- msd : float the mean square displacement References ———- .. [1] Wu Y. et al., “Hybrid diffusion imaging”, NeuroImage, vol 36, p. 617-629, 2007.

odf(sphere)

Calculates the real discrete odf for a given discrete sphere ..math:: :nowrap: begin{equation} psi_{DSI}(hat{mathbf{u}})=int_{0}^{infty}P(rhat{mathbf{u}})r^{2}dr end{equation} where \(\hat{\mathbf{u}}\) is the unit vector which corresponds to a sphere point.

pdf(normalized=True)

Applies the 3D FFT in the q-space grid to generate the diffusion propagator

rtop_pdf(normalized=True)

Calculates the return to origin probability from the propagator, which is the propagator evaluated at zero (see Descoteaux et Al. [1]_, Tuch [2]_, Wu et al. [3]_) rtop = P(0)

Parameters

normalizedboolean, optional

Whether to normalize the propagator by its sum in order to obtain a pdf. Default: True.

Returns

rtopfloat

the return to origin probability

References

[1]

Descoteaux M. et al., “Multiple q-shell diffusion propagator

imaging”, Medical Image Analysis, vol 15, No. 4, p. 603-621, 2011.

[2]

Tuch D.S., “Diffusion MRI of Complex Tissue Structure”, PhD Thesis, 2002.

[3]

Wu Y. et al., “Computation of Diffusion Function Measures

in q -Space Using Magnetic Resonance Hybrid Diffusion Imaging”, IEEE TRANSACTIONS ON MEDICAL IMAGING, vol. 27, No. 6, p. 858-865, 2008

rtop_signal(filtering=True)

Calculates the return to origin probability (rtop) from the signal rtop equals to the sum of all signal values

Parameters

filteringboolean, optional

Whether to perform Hanning filtering. Default: True

Returns

rtopfloat

the return to origin probability

DiffusionSpectrumDeconvModel

class dipy.reconst.dsi.DiffusionSpectrumDeconvModel(gtab, qgrid_size=35, r_start=4.1, r_end=13.0, r_step=0.4, filter_width=inf, normalize_peaks=False)

Bases: DiffusionSpectrumModel

__init__(gtab, qgrid_size=35, r_start=4.1, r_end=13.0, r_step=0.4, filter_width=inf, normalize_peaks=False)

Diffusion Spectrum Deconvolution The idea is to remove the convolution on the DSI propagator that is caused by the truncation of the q-space in the DSI sampling. ..math:: :nowrap: begin{eqnarray*} P_{dsi}(mathbf{r}) & = & S_{0}^{-1}iiintlimits_{| mathbf{q} | le mathbf{q_{max}}} S(mathbf{q})exp(-i2pimathbf{q}cdotmathbf{r})dmathbf{q} \ & = & S_{0}^{-1}iiintlimits_{mathbf{q}} left( S(mathbf{q}) cdot M(mathbf{q}) right) exp(-i2pimathbf{q}cdotmathbf{r})dmathbf{q} \ & = & P(mathbf{r}) otimes left( S_{0}^{-1}iiintlimits_{mathbf{q}} M(mathbf{q}) exp(-i2pimathbf{q}cdotmathbf{r})dmathbf{q} right) \ end{eqnarray*} where \(\mathbf{r}\) is the displacement vector and \(\mathbf{q}\) is the wave vector which corresponds to different gradient directions, \(M(\mathbf{q})\) is a mask corresponding to your q-space sampling and \(\otimes\) is the convolution operator [1]_. Parameters ———- gtab : GradientTable, Gradient directions and bvalues container class qgrid_size : int, has to be an odd number. Sets the size of the q_space grid. For example if qgrid_size is 35 then the shape of the grid will be (35, 35, 35). r_start : float, ODF is sampled radially in the PDF. This parameters shows where the sampling should start. r_end : float, Radial endpoint of ODF sampling r_step : float, Step size of the ODf sampling from r_start to r_end filter_width : float, Strength of the hanning filter References ———- .. [1] Canales-Rodriguez E.J et al., “Deconvolution in Diffusion Spectrum Imaging”, Neuroimage, 2010. .. [2] Biggs David S.C. et al., “Acceleration of Iterative Image Restoration Algorithms”, Applied Optics, vol. 36, No. 8, p. 1766-1775, 1997.

fit(data, mask=None)

Fit method for every voxel in data

DiffusionSpectrumDeconvFit

class dipy.reconst.dsi.DiffusionSpectrumDeconvFit(model, data)

Bases: DiffusionSpectrumFit

__init__(model, data)

Calculates PDF and ODF and other properties for a single voxel

Parameters

modelobject,

DiffusionSpectrumModel

data1d ndarray,

signal values

pdf()

Applies the 3D FFT in the q-space grid to generate the DSI diffusion propagator, remove the background noise with a hard threshold and then deconvolve the propagator with the Lucy-Richardson deconvolution algorithm

create_qspace

dipy.reconst.dsi.create_qspace(gtab, origin)

create the 3D grid which holds the signal values (q-space)

Parameters

gtab : GradientTable origin : (3,) ndarray

center of qspace

Returns

qgridndarray

qspace coordinates

create_qtable

dipy.reconst.dsi.create_qtable(gtab, origin)

create a normalized version of gradients

Parameters

gtab : GradientTable origin : (3,) ndarray

center of qspace

Returns

qtable : ndarray

hanning_filter

dipy.reconst.dsi.hanning_filter(gtab, filter_width, origin)

create a hanning window

The signal is premultiplied by a Hanning window before Fourier transform in order to ensure a smooth attenuation of the signal at high q values.

Parameters

gtab : GradientTable filter_width : int origin : (3,) ndarray

center of qspace

Returns

filter(N,) ndarray

where N is the number of non-b0 gradient directions

pdf_interp_coords

dipy.reconst.dsi.pdf_interp_coords(sphere, rradius, origin)

Precompute coordinates for ODF calculation from the PDF

Parameters

sphereobject,

Sphere

rradiusarray, shape (N,)

line interpolation points

originarray, shape (3,)

center of the grid

pdf_odf

dipy.reconst.dsi.pdf_odf(Pr, rradius, interp_coords)

Calculates the real ODF from the diffusion propagator(PDF) Pr

Parameters

Prarray, shape (X, X, X)

probability density function

rradiusarray, shape (N,)

interpolation range on the radius

interp_coordsarray, shape (3, M, N)

coordinates in the pdf for interpolating the odf

half_to_full_qspace

dipy.reconst.dsi.half_to_full_qspace(data, gtab)

Half to full Cartesian grid mapping

Useful when dMRI data are provided in one qspace hemisphere as DiffusionSpectrum expects data to be in full qspace.

Parameters

dataarray, shape (X, Y, Z, W)

where (X, Y, Z) volume size and W number of gradient directions

gtabGradientTable

container for b-values and b-vectors (gradient directions)

Returns

new_data : array, shape (X, Y, Z, 2 * W -1) new_gtab : GradientTable

Notes

We assume here that only on b0 is provided with the initial data. If that is not the case then you will need to write your own preparation function before providing the gradients and the data to the DiffusionSpectrumModel class.

project_hemisph_bvecs

dipy.reconst.dsi.project_hemisph_bvecs(gtab)

Project any near identical bvecs to the other hemisphere

Parameters

gtabobject,

GradientTable

Notes

Useful only when working with some types of dsi data.

threshold_propagator

dipy.reconst.dsi.threshold_propagator(P, estimated_snr=15.0)

Applies hard threshold on the propagator to remove background noise for the deconvolution.

gen_PSF

dipy.reconst.dsi.gen_PSF(qgrid_sampling, siz_x, siz_y, siz_z)

Generate a PSF for DSI Deconvolution by taking the ifft of the binary q-space sampling mask and truncating it to keep only the center.

LR_deconv

dipy.reconst.dsi.LR_deconv(prop, psf, numit=5, acc_factor=1)

Perform Lucy-Richardson deconvolution algorithm on a 3D array.

Parameters

prop3-D ndarray of dtype float

The 3D volume to be deconvolve

psf3-D ndarray of dtype float

The filter that will be used for the deconvolution.

numitint

Number of Lucy-Richardson iteration to perform.

acc_factorfloat

Exponential acceleration factor as in [1]_.

References

[1]

Biggs David S.C. et al., “Acceleration of Iterative Image Restoration Algorithms”, Applied Optics, vol. 36, No. 8, p. 1766-1775, 1997.

TensorModel

class dipy.reconst.dti.TensorModel(gtab, fit_method='WLS', return_S0_hat=False, *args, **kwargs)

Bases: ReconstModel

Diffusion Tensor

__init__(gtab, fit_method='WLS', return_S0_hat=False, *args, **kwargs)

A Diffusion Tensor Model [1]_, [2]_.

Parameters

gtab : GradientTable class instance

fit_methodstr or callable

str can be one of the following:

‘WLS’ for weighted least squares

dti.wls_fit_tensor()

‘LS’ or ‘OLS’ for ordinary least squares

dti.ols_fit_tensor()

‘NLLS’ for non-linear least-squares

dti.nlls_fit_tensor()

‘RT’ or ‘restore’ or ‘RESTORE’ for RESTORE robust tensor

fitting [3]_ dti.restore_fit_tensor()

callable has to have the signature:

fit_method(design_matrix, data, *args, **kwargs)

return_S0_hatbool

Boolean to return (True) or not (False) the S0 values for the fit.

args, kwargsarguments and key-word arguments passed to the

fit_method. See dti.wls_fit_tensor, dti.ols_fit_tensor for details

min_signalfloat

The minimum signal value. Needs to be a strictly positive number. Default: minimal signal in the data provided to fit.

Notes

In order to increase speed of processing, tensor fitting is done simultaneously over many voxels. Many fit_methods use the ‘step’ parameter to set the number of voxels that will be fit at once in each iteration. This is the chunk size as a number of voxels. A larger step value should speed things up, but it will also take up more memory. It is advisable to keep an eye on memory consumption as this value is increased.

E.g., in iter_fit_tensor() we have a default step value of 1e4

References

[1]

Basser, P.J., Mattiello, J., LeBihan, D., 1994. Estimation of the effective self-diffusion tensor from the NMR spin echo. J Magn Reson B 103, 247-254.

[2]

Basser, P., Pierpaoli, C., 1996. Microstructural and physiological features of tissues elucidated by quantitative diffusion-tensor MRI. Journal of Magnetic Resonance 111, 209-219.

[3]

Lin-Ching C., Jones D.K., Pierpaoli, C. 2005. RESTORE: Robust estimation of tensors by outlier rejection. MRM 53: 1088-1095

fit(data, mask=None, adjacency=False)

Fit method of the DTI model class

Parameters

dataarray

The measured signal from one voxel.

maskarray

A boolean array used to mark the coordinates in the data that should be analyzed that has the shape data.shape[:-1]

adjacencyfloat, optional

Calculate voxel adjacency accounting for mask, using this value as cutoff distance (measured in voxel coordinates)

predict(dti_params, S0=1.0)

Predict a signal for this TensorModel class instance given parameters.

Parameters

dti_paramsndarray

The last dimension should have 12 tensor parameters: 3 eigenvalues, followed by the 3 eigenvectors

S0float or ndarray

The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1

TensorFit

class dipy.reconst.dti.TensorFit(model, model_params, model_S0=None)

Bases: object

__init__(model, model_params, model_S0=None)

Initialize a TensorFit class instance.

property S0_hat

ad()

Axial diffusivity (AD) calculated from cached eigenvalues.

Returns

adarray (V, 1)

Calculated AD.

Notes

RD is calculated with the following equation:

\[AD = \lambda_1\]

adc(sphere)

Calculate the apparent diffusion coefficient (ADC) in each direction on the sphere for each voxel in the data

sphere : Sphere class instance

adcndarray

The estimates of the apparent diffusion coefficient in every direction on the input sphere

The calculation of ADC, relies on the following relationship:

\[ADC = \]

ec{b} Q ec{b}^T

Where Q is the quadratic form of the tensor.

color_fa()

Color fractional anisotropy of diffusion tensor

property directions

For tracking - return the primary direction in each voxel

property evals

Returns the eigenvalues of the tensor as an array

property evecs

Returns the eigenvectors of the tensor as an array, columnwise

fa()

Fractional anisotropy (FA) calculated from cached eigenvalues.

ga()

Geodesic anisotropy (GA) calculated from cached eigenvalues.

linearity()

Returns

linearityarray

Calculated linearity of the diffusion tensor [1]_.

Notes

Linearity is calculated with the following equation:

\[Linearity = \frac{\lambda_1-\lambda_2}{\lambda_1+\lambda_2+\lambda_3}\]

References

[1]

Westin C.-F., Peled S., Gubjartsson H., Kikinis R., Jolesz F., “Geometrical diffusion measures for MRI from tensor basis analysis” in Proc. 5th Annual ISMRM, 1997.

lower_triangular(b0=None)

md()

Mean diffusivity (MD) calculated from cached eigenvalues.

Returns

mdarray (V, 1)

Calculated MD.

Notes

MD is calculated with the following equation:

\[MD = \frac{\lambda_1+\lambda_2+\lambda_3}{3}\]

mode()

Tensor mode calculated from cached eigenvalues.

odf(sphere)

The diffusion orientation distribution function (dODF). This is an estimate of the diffusion distance in each direction Parameters ———- sphere : Sphere class instance. The dODF is calculated in the vertices of this input. Returns ——- odf : ndarray The diffusion distance in every direction of the sphere in every voxel in the input data. Notes —– This is based on equation 3 in [1]_. To re-derive it from scratch, follow steps in [2]_, Section 7.9 Equation 7.24 but with an \(r^2\) term in the integral. References ———- .. [1] Aganj, I., Lenglet, C., Sapiro, G., Yacoub, E., Ugurbil, K., & Harel, N. (2010). Reconstruction of the orientation distribution function in single- and multiple-shell q-ball imaging within constant solid angle. Magnetic Resonance in Medicine, 64(2), 554-566. doi:DOI: 10.1002/mrm.22365 .. [2] Descoteaux, M. (2008). PhD Thesis: High Angular Resolution Diffusion MRI: from Local Estimation to Segmentation and Tractography. ftp://ftp-sop.inria.fr/athena/Publications/PhDs/descoteaux_thesis.pdf

planarity()

Returns

sphericityarray

Calculated sphericity of the diffusion tensor [1]_.

Notes

Sphericity is calculated with the following equation:

\[Sphericity = \frac{2 (\lambda_2 - \lambda_3)}{\lambda_1+\lambda_2+\lambda_3}\]

References

[1]

Westin C.-F., Peled S., Gubjartsson H., Kikinis R., Jolesz F., “Geometrical diffusion measures for MRI from tensor basis analysis” in Proc. 5th Annual ISMRM, 1997.

predict(gtab, S0=None, step=None)

Given a model fit, predict the signal on the vertices of a sphere Parameters ———- gtab : a GradientTable class instance This encodes the directions for which a prediction is made S0 : float array The mean non-diffusion weighted signal in each voxel. Default: The fitted S0 value in all voxels if it was fitted. Otherwise 1 in all voxels. step : int The chunk size as a number of voxels. Optional parameter with default value 10,000. In order to increase speed of processing, tensor fitting is done simultaneously over many voxels. This parameter sets the number of voxels that will be fit at once in each iteration. A larger step value should speed things up, but it will also take up more memory. It is advisable to keep an eye on memory consumption as this value is increased. Notes —– The predicted signal is given by: .. math :: S( heta, b) = S_0 * e^{-b ADC} Where: .. math :: ADC = heta Q heta^T :math:` heta` is a unit vector pointing at any direction on the sphere for which a signal is to be predicted and \(b\) is the b value provided in the GradientTable input for that direction

property quadratic_form

Calculates the 3x3 diffusion tensor for each voxel

rd()

Radial diffusivity (RD) calculated from cached eigenvalues.

Returns

rdarray (V, 1)

Calculated RD.

Notes

RD is calculated with the following equation:

\[RD = \frac{\lambda_2 + \lambda_3}{2}\]

property shape

sphericity()

Returns

sphericityarray

Calculated sphericity of the diffusion tensor [1]_.

Notes

Sphericity is calculated with the following equation:

\[Sphericity = \frac{3 \lambda_3}{\lambda_1+\lambda_2+\lambda_3}\]

References

[1]

Westin C.-F., Peled S., Gubjartsson H., Kikinis R., Jolesz F., “Geometrical diffusion measures for MRI from tensor basis analysis” in Proc. 5th Annual ISMRM, 1997.

trace()

Trace of the tensor calculated from cached eigenvalues.

Returns

tracearray (V, 1)

Calculated trace.

Notes

The trace is calculated with the following equation:

\[trace = \lambda_1 + \lambda_2 + \lambda_3\]

fractional_anisotropy

dipy.reconst.dti.fractional_anisotropy(evals, axis=-1)

Return Fractional anisotropy (FA) of a diffusion tensor.

Parameters

evalsarray-like

Eigenvalues of a diffusion tensor.

axisint

Axis of evals which contains 3 eigenvalues.

Returns

faarray

Calculated FA. Range is 0 <= FA <= 1.

Notes

FA is calculated using the following equation:

\[FA = \sqrt{\frac{1}{2}\frac{(\lambda_1-\lambda_2)^2+(\lambda_1- \lambda_3)^2+(\lambda_2-\lambda_3)^2}{\lambda_1^2+ \lambda_2^2+\lambda_3^2}}\]

geodesic_anisotropy

dipy.reconst.dti.geodesic_anisotropy(evals, axis=-1)

Geodesic anisotropy (GA) of a diffusion tensor. Parameters ———- evals : array-like Eigenvalues of a diffusion tensor. axis : int Axis of evals which contains 3 eigenvalues. Returns ——- ga : array Calculated GA. In the range 0 to +infinity Notes —– GA is calculated using the following equation given in [1]_: .. math:: GA = sqrt{sum_{i=1}^3 log^2{left ( lambda_i/<mathbf{D}> right )}}, quad textrm{where} quad <mathbf{D}> = (lambda_1lambda_2lambda_3)^{1/3} Note that the notation, \(<D>\), is often used as the mean diffusivity (MD) of the diffusion tensor and can lead to confusions in the literature (see [1]_ versus [2]_ versus [3]_ for example). Reference [2]_ defines geodesic anisotropy (GA) with \(<D>\) as the MD in the denominator of the sum. This is wrong. The original paper [1]_ defines GA with \(<D> = det(D)^{1/3}\), as the isotropic part of the distance. This might be an explanation for the confusion. The isotropic part of the diffusion tensor in Euclidean space is the MD whereas the isotropic part of the tensor in log-Euclidean space is \(det(D)^{1/3}\). The Appendix of [1]_ and log-Euclidean derivations from [3]_ are clear on this. Hence, all that to say that \(<D> = det(D)^{1/3}\) here for the GA definition and not MD. References ———- .. [1] P. G. Batchelor, M. Moakher, D. Atkinson, F. Calamante, A. Connelly, “A rigorous framework for diffusion tensor calculus”, Magnetic Resonance in Medicine, vol. 53, pp. 221-225, 2005. .. [2] M. M. Correia, V. F. Newcombe, G.B. Williams. “Contrast-to-noise ratios for indices of anisotropy obtained from diffusion MRI: a study with standard clinical b-values at 3T”. NeuroImage, vol. 57, pp. 1103-1115, 2011. .. [3] A. D. Lee, etal, P. M. Thompson. “Comparison of fractional and geodesic anisotropy in diffusion tensor images of 90 monozygotic and dizygotic twins”. 5th IEEE International Symposium on Biomedical Imaging (ISBI), pp. 943-946, May 2008. .. [4] V. Arsigny, P. Fillard, X. Pennec, N. Ayache. “Log-Euclidean metrics for fast and simple calculus on diffusion tensors.” Magnetic Resonance in Medecine, vol 56, pp. 411-421, 2006.

mean_diffusivity

dipy.reconst.dti.mean_diffusivity(evals, axis=-1)

Mean Diffusivity (MD) of a diffusion tensor.

Parameters

evalsarray-like

Eigenvalues of a diffusion tensor.

axisint

Axis of evals which contains 3 eigenvalues.

Returns

mdarray

Calculated MD.

Notes

MD is calculated with the following equation:

\[MD = \frac{\lambda_1 + \lambda_2 + \lambda_3}{3}\]

axial_diffusivity

dipy.reconst.dti.axial_diffusivity(evals, axis=-1)

Axial Diffusivity (AD) of a diffusion tensor. Also called parallel diffusivity.

Parameters

evalsarray-like

Eigenvalues of a diffusion tensor, must be sorted in descending order along axis.

axisint

Axis of evals which contains 3 eigenvalues.

Returns

adarray

Calculated AD.

Notes

AD is calculated with the following equation:

\[AD = \lambda_1\]

radial_diffusivity

dipy.reconst.dti.radial_diffusivity(evals, axis=-1)

Radial Diffusivity (RD) of a diffusion tensor. Also called perpendicular diffusivity.

Parameters

evalsarray-like

Eigenvalues of a diffusion tensor, must be sorted in descending order along axis.

axisint

Axis of evals which contains 3 eigenvalues.

Returns

rdarray

Calculated RD.

Notes

RD is calculated with the following equation:

\[RD = \frac{\lambda_2 + \lambda_3}{2}\]

trace

dipy.reconst.dti.trace(evals, axis=-1)

Trace of a diffusion tensor.

Parameters

evalsarray-like

Eigenvalues of a diffusion tensor.

axisint

Axis of evals which contains 3 eigenvalues.

Returns

tracearray

Calculated trace of the diffusion tensor.

Notes

Trace is calculated with the following equation:

\[Trace = \lambda_1 + \lambda_2 + \lambda_3\]

color_fa

dipy.reconst.dti.color_fa(fa, evecs)

Color fractional anisotropy of diffusion tensor

Parameters

faarray-like

Array of the fractional anisotropy (can be 1D, 2D or 3D)

evecsarray-like

eigen vectors from the tensor model

Returns

rgbArray with 3 channels for each color as the last dimension.

Colormap of the FA with red for the x value, y for the green value and z for the blue value.

Notes

It is computed from the clipped FA between 0 and 1 using the following formula

\[rgb = abs(max(\vec{e})) \times fa\]

determinant

dipy.reconst.dti.determinant(q_form)

The determinant of a tensor, given in quadratic form

Parameters

q_formndarray

The quadratic form of a tensor, or an array with quadratic forms of tensors. Should be of shape (x, y, z, 3, 3) or (n, 3, 3) or (3, 3).

Returns

detarray

The determinant of the tensor in each spatial coordinate

isotropic

dipy.reconst.dti.isotropic(q_form)

Calculate the isotropic part of the tensor [1]_.

Parameters

q_formndarray

The quadratic form of a tensor, or an array with quadratic forms of tensors. Should be of shape (x,y,z,3,3) or (n, 3, 3) or (3,3).

Returns

A_hat: ndarray

The isotropic part of the tensor in each spatial coordinate

Notes

The isotropic part of a tensor is defined as (equations 3-5 of [1]_):

\[\bar{A} = \frac{1}{2} tr(A) I\]

References

[1]

Daniel B. Ennis and G. Kindlmann, “Orthogonal Tensor Invariants and the Analysis of Diffusion Tensor Magnetic Resonance Images”, Magnetic Resonance in Medicine, vol. 55, no. 1, pp. 136-146, 2006.

deviatoric

dipy.reconst.dti.deviatoric(q_form)

Calculate the deviatoric (anisotropic) part of the tensor [1]_. Parameters ———- q_form : ndarray The quadratic form of a tensor, or an array with quadratic forms of tensors. Should be of shape (x,y,z,3,3) or (n, 3, 3) or (3,3). Returns ——- A_squiggle : ndarray The deviatoric part of the tensor in each spatial coordinate. Notes —– The deviatoric part of the tensor is defined as (equations 3-5 in [1]_): .. math :: widetilde{A} = A - bar{A} Where \(A\) is the tensor quadratic form and \(\bar{A}\) is the anisotropic part of the tensor. References ———- .. [1] Daniel B. Ennis and G. Kindlmann, “Orthogonal Tensor Invariants and the Analysis of Diffusion Tensor Magnetic Resonance Images”, Magnetic Resonance in Medicine, vol. 55, no. 1, pp. 136-146, 2006.

norm

dipy.reconst.dti.norm(q_form)

Calculate the Frobenius norm of a tensor quadratic form

Parameters

q_form: ndarray

The quadratic form of a tensor, or an array with quadratic forms of tensors. Should be of shape (x,y,z,3,3) or (n, 3, 3) or (3,3).

Returns

normndarray

The Frobenius norm of the 3,3 tensor q_form in each spatial coordinate.

Notes

The Frobenius norm is defined as:

math:

||A||_F = [sum_{i,j} abs(a_{i,j})^2]^{1/2}

See Also

np.linalg.norm

mode

dipy.reconst.dti.mode(q_form)

Mode (MO) of a diffusion tensor [1]_. Parameters ———- q_form : ndarray The quadratic form of a tensor, or an array with quadratic forms of tensors. Should be of shape (x, y, z, 3, 3) or (n, 3, 3) or (3, 3). Returns ——- mode : array Calculated tensor mode in each spatial coordinate. Notes —– Mode ranges between -1 (planar anisotropy) and +1 (linear anisotropy) with 0 representing orthotropy. Mode is calculated with the following equation (equation 9 in [1]_): .. math:: Mode = 3*sqrt{6}*det(widetilde{A}/norm(widetilde{A})) Where \(\widetilde{A}\) is the deviatoric part of the tensor quadratic form. References ———- .. [1] Daniel B. Ennis and G. Kindlmann, “Orthogonal Tensor Invariants and the Analysis of Diffusion Tensor Magnetic Resonance Images”, Magnetic Resonance in Medicine, vol. 55, no. 1, pp. 136-146, 2006.

linearity

dipy.reconst.dti.linearity(evals, axis=-1)

The linearity of the tensor [1]_

Parameters

evalsarray-like

Eigenvalues of a diffusion tensor.

axisint

Axis of evals which contains 3 eigenvalues.

Returns

linearityarray

Calculated linearity of the diffusion tensor.

Notes

Linearity is calculated with the following equation:

\[Linearity = \frac{\lambda_1-\lambda_2}{\lambda_1+\lambda_2+\lambda_3}\]

References

[1]

Westin C.-F., Peled S., Gubjartsson H., Kikinis R., Jolesz F., “Geometrical diffusion measures for MRI from tensor basis analysis” in Proc. 5th Annual ISMRM, 1997.

planarity

dipy.reconst.dti.planarity(evals, axis=-1)

The planarity of the tensor [1]_

Parameters

evalsarray-like

Eigenvalues of a diffusion tensor.

axisint

Axis of evals which contains 3 eigenvalues.

Returns

linearityarray

Calculated linearity of the diffusion tensor.

Notes

Planarity is calculated with the following equation:

\[Planarity = \frac{2 (\lambda_2-\lambda_3)}{\lambda_1+\lambda_2+\lambda_3}\]

References

[1]

Westin C.-F., Peled S., Gubjartsson H., Kikinis R., Jolesz F., “Geometrical diffusion measures for MRI from tensor basis analysis” in Proc. 5th Annual ISMRM, 1997.

sphericity

dipy.reconst.dti.sphericity(evals, axis=-1)

The sphericity of the tensor [1]_

Parameters

evalsarray-like

Eigenvalues of a diffusion tensor.

axisint

Axis of evals which contains 3 eigenvalues.

Returns

sphericityarray

Calculated sphericity of the diffusion tensor.

Notes

Sphericity is calculated with the following equation:

\[Sphericity = \frac{3 \lambda_3)}{\lambda_1+\lambda_2+\lambda_3}\]

References

[1]

Westin C.-F., Peled S., Gubjartsson H., Kikinis R., Jolesz F., “Geometrical diffusion measures for MRI from tensor basis analysis” in Proc. 5th Annual ISMRM, 1997.

apparent_diffusion_coef

dipy.reconst.dti.apparent_diffusion_coef(q_form, sphere)

Calculate the apparent diffusion coefficient (ADC) in each direction of a sphere.

Parameters

q_formndarray

The quadratic form of a tensor, or an array with quadratic forms of tensors. Should be of shape (…, 3, 3)

spherea Sphere class instance

The ADC will be calculated for each of the vertices in the sphere

Notes

The calculation of ADC, relies on the following relationship:

\[ADC = \vec{b} Q \vec{b}^T\]

Where Q is the quadratic form of the tensor.

tensor_prediction

dipy.reconst.dti.tensor_prediction(dti_params, gtab, S0)

Predict a signal given tensor parameters. Parameters ———- dti_params : ndarray Tensor parameters. The last dimension should have 12 tensor parameters: 3 eigenvalues, followed by the 3 corresponding eigenvectors. gtab : a GradientTable class instance The gradient table for this prediction S0 : float or ndarray The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1 Notes —– The predicted signal is given by: \(S( heta, b) = S_0 * e^{-b ADC}\), where \(ADC = heta Q heta^T\), :math:` heta` is a unit vector pointing at any direction on the sphere for which a signal is to be predicted, \(b\) is the b value provided in the GradientTable input for that direction, \(Q\) is the quadratic form of the tensor determined by the input parameters.

iter_fit_tensor

dipy.reconst.dti.iter_fit_tensor(step=10000.0)

Wrap a fit_tensor func and iterate over chunks of data with given length

Splits data into a number of chunks of specified size and iterates the decorated fit_tensor function over them. This is useful to counteract the temporary but significant memory usage increase in fit_tensor functions that use vectorized operations and need to store large temporary arrays for their vectorized operations.

Parameters

stepint

The chunk size as a number of voxels. Optional parameter with default value 10,000.

In order to increase speed of processing, tensor fitting is done simultaneously over many voxels. This parameter sets the number of voxels that will be fit at once in each iteration. A larger step value should speed things up, but it will also take up more memory. It is advisable to keep an eye on memory consumption as this value is increased.

wls_fit_tensor

dipy.reconst.dti.wls_fit_tensor(design_matrix, data, return_S0_hat=False)

Computes weighted least squares (WLS) fit to calculate self-diffusion tensor using a linear regression model [1]_.

Parameters

design_matrixarray (g, 7)

Design matrix holding the covariants used to solve for the regression coefficients.

dataarray ([X, Y, Z, …], g)

Data or response variables holding the data. Note that the last dimension should contain the data. It makes no copies of data.

return_S0_hatbool

Boolean to return (True) or not (False) the S0 values for the fit.

Returns

eigvalsarray (…, 3)

Eigenvalues from eigen decomposition of the tensor.

eigvecsarray (…, 3, 3)

Associated eigenvectors from eigen decomposition of the tensor. Eigenvectors are columnar (e.g. eigvecs[:,j] is associated with eigvals[j])

See Also

decompose_tensor

Notes

In Chung, et al. 2006, the regression of the WLS fit needed an unbiased preliminary estimate of the weights and therefore the ordinary least squares (OLS) estimates were used. A “two pass” method was implemented:

1. calculate OLS estimates of the data

2. apply the OLS estimates as weights to the WLS fit of the data

This ensured heteroscedasticity could be properly modeled for various types of bootstrap resampling (namely residual bootstrap).

\[\begin{split}y = \mathrm{data} \\ X = \mathrm{design matrix} \\ \hat{\beta}_\mathrm{WLS} = \mathrm{desired regression coefficients (e.g. tensor)}\\ \\ \hat{\beta}_\mathrm{WLS} = (X^T W X)^{-1} X^T W y \\ \\ W = \mathrm{diag}((X \hat{\beta}_\mathrm{OLS})^2), \mathrm{where} \hat{\beta}_\mathrm{OLS} = (X^T X)^{-1} X^T y\end{split}\]

References

[1]

Chung, SW., Lu, Y., Henry, R.G., 2006. Comparison of bootstrap approaches for estimation of uncertainties of DTI parameters. NeuroImage 33, 531-541.

ols_fit_tensor

dipy.reconst.dti.ols_fit_tensor(design_matrix, data, return_S0_hat=False, return_lower_triangular=False)

Computes ordinary least squares (OLS) fit to calculate self-diffusion tensor using a linear regression model [1]_.

Parameters

design_matrixarray (g, 7)

Design matrix holding the covariants used to solve for the regression coefficients.

dataarray ([X, Y, Z, …], g)

Data or response variables holding the data. Note that the last dimension should contain the data. It makes no copies of data.

return_S0_hatbool

Boolean to return (True) or not (False) the S0 values for the fit.

return_lower_triangularbool

Boolean to return (True) or not (False) the coefficients of the fit.

Returns

eigvalsarray (…, 3)

Eigenvalues from eigen decomposition of the tensor.

eigvecsarray (…, 3, 3)

Associated eigenvectors from eigen decomposition of the tensor. Eigenvectors are columnar (e.g. eigvecs[:,j] is associated with eigvals[j])

See Also

WLS_fit_tensor, decompose_tensor, design_matrix

Notes

\[ \begin{align}\begin{aligned}\begin{split}y = \mathrm{data} \\ X = \mathrm{design matrix} \\\end{split}\\\hat{\beta}_\mathrm{OLS} = (X^T X)^{-1} X^T y\end{aligned}\end{align} \]

References

[1]

Chung, SW., Lu, Y., Henry, R.G., 2006. Comparison of bootstrap approaches for estimation of uncertainties of DTI parameters. NeuroImage 33, 531-541.

nlls_fit_tensor

dipy.reconst.dti.nlls_fit_tensor(design_matrix, data, weighting=None, sigma=None, jac=True, return_S0_hat=False, fail_is_nan=False)

Fit the cumulant expansion params (e.g. DTI, DKI) using non-linear least-squares.

Parameters

design_matrixarray (g, Npar)

Design matrix holding the covariants used to solve for the regression coefficients. First six parameters of design matrix should correspond to the six unique diffusion tensor elements in the lower triangular order (Dxx, Dxy, Dyy, Dxz, Dyz, Dzz), while last parameter to -log(S0)

dataarray ([X, Y, Z, …], g)

Data or response variables holding the data. Note that the last dimension should contain the data. It makes no copies of data.

weighting: str

the weighting scheme to use in considering the squared-error. Default behavior is to use uniform weighting. Other options: ‘sigma’ ‘gmm’

sigmaarray (optional)

If ‘sigma’ weighting is used, we will weight the error function according to 1/sigma^2. If ‘gmm’, the Geman-Mclure M-estimator is used for weighting (see below).

jacbool

Use the Jacobian? Default: True

return_S0_hatbool

Boolean to return (True) or not (False) the S0 values for the fit.

fail_is_nanbool

Boolean to set failed NL fitting to NaN (True) or LS (False, default).

Returns

nlls_params: the eigen-values and eigen-vectors of the tensor in each

voxel.

restore_fit_tensor

dipy.reconst.dti.restore_fit_tensor(design_matrix, data, sigma=None, jac=True, return_S0_hat=False, fail_is_nan=False)

Use the RESTORE algorithm [1]_ to calculate a robust tensor fit

Parameters

design_matrixarray of shape (g, 7)

Design matrix holding the covariants used to solve for the regression coefficients.

dataarray of shape ([X, Y, Z, n_directions], g)

Data or response variables holding the data. Note that the last dimension should contain the data. It makes no copies of data.

sigmafloat, array of shape [n_directions], array of shape [X, Y, Z]

An estimate of the variance. [1]_ recommend to use 1.5267 * std(background_noise), where background_noise is estimated from some part of the image known to contain no signal (only noise). Array with ndim > 1 corresponds to spatially varying sigma, so if providing spatially-flattened data and spatially-varying sigma, provide array with shape [num_vox, 1].

jacbool, optional

Whether to use the Jacobian of the tensor to speed the non-linear optimization procedure used to fit the tensor parameters (see also nlls_fit_tensor()). Default: True

return_S0_hatbool

Boolean to return (True) or not (False) the S0 values for the fit.

fail_is_nanbool

Boolean to set failed NL fitting to NaN (True) or LS (False, default).

Returns

restore_params : an estimate of the tensor parameters in each voxel.

References

[1]

Chang, L-C, Jones, DK and Pierpaoli, C (2005). RESTORE: robust

estimation of tensors by outlier rejection. MRM, 53: 1088-95.

_lt_indices

dipy.reconst.dti._lt_indices()

ndarray(shape, dtype=float, buffer=None, offset=0,

strides=None, order=None)

An array object represents a multidimensional, homogeneous array of fixed-size items. An associated data-type object describes the format of each element in the array (its byte-order, how many bytes it occupies in memory, whether it is an integer, a floating point number, or something else, etc.)

Arrays should be constructed using array, zeros or empty (refer to the See Also section below). The parameters given here refer to a low-level method (ndarray(…)) for instantiating an array.

For more information, refer to the numpy module and examine the methods and attributes of an array.

Parameters

(for the __new__ method; see Notes below)

shapetuple of ints

Shape of created array.

dtypedata-type, optional

Any object that can be interpreted as a numpy data type.

bufferobject exposing buffer interface, optional

Used to fill the array with data.

offsetint, optional

Offset of array data in buffer.

stridestuple of ints, optional

Strides of data in memory.

order{‘C’, ‘F’}, optional

Row-major (C-style) or column-major (Fortran-style) order.

Attributes

Tndarray

Transpose of the array.

databuffer

The array’s elements, in memory.

dtypedtype object

Describes the format of the elements in the array.

flagsdict

Dictionary containing information related to memory use, e.g., ‘C_CONTIGUOUS’, ‘OWNDATA’, ‘WRITEABLE’, etc.

flatnumpy.flatiter object

Flattened version of the array as an iterator. The iterator allows assignments, e.g., x.flat = 3 (See ndarray.flat for assignment examples; TODO).

imagndarray

Imaginary part of the array.

realndarray

Real part of the array.

sizeint

Number of elements in the array.

itemsizeint

The memory use of each array element in bytes.

nbytesint

The total number of bytes required to store the array data, i.e., itemsize * size.

ndimint

The array’s number of dimensions.

shapetuple of ints

Shape of the array.

stridestuple of ints

The step-size required to move from one element to the next in memory. For example, a contiguous (3, 4) array of type int16 in C-order has strides (8, 2). This implies that to move from element to element in memory requires jumps of 2 bytes. To move from row-to-row, one needs to jump 8 bytes at a time (2 * 4).

ctypesctypes object

Class containing properties of the array needed for interaction with ctypes.

basendarray

If the array is a view into another array, that array is its base (unless that array is also a view). The base array is where the array data is actually stored.

See Also

array : Construct an array. zeros : Create an array, each element of which is zero. empty : Create an array, but leave its allocated memory unchanged (i.e.,

it contains “garbage”).

dtype : Create a data-type. numpy.typing.NDArray : An ndarray alias generic

w.r.t. its dtype.type <numpy.dtype.type>.

Notes

There are two modes of creating an array using __new__:

1. If buffer is None, then only shape, dtype, and order are used.

2. If buffer is an object exposing the buffer interface, then all keywords are interpreted.

No __init__ method is needed because the array is fully initialized after the __new__ method.

Examples

These examples illustrate the low-level ndarray constructor. Refer to the See Also section above for easier ways of constructing an ndarray.

First mode, buffer is None:

>>> np.ndarray(shape=(2,2), dtype=float, order='F')
array([[0.0e+000, 0.0e+000], # random
       [     nan, 2.5e-323]])

Second mode:

>>> np.ndarray((2,), buffer=np.array([1,2,3]),
...            offset=np.int_().itemsize,
...            dtype=int) # offset = 1*itemsize, i.e. skip first element
array([2, 3])

from_lower_triangular

dipy.reconst.dti.from_lower_triangular(D)

Returns a tensor given the six unique tensor elements

Given the six unique tensor elements (in the order: Dxx, Dxy, Dyy, Dxz, Dyz, Dzz) returns a 3 by 3 tensor. All elements after the sixth are ignored.

Parameters

Darray_like, (…, >6)

Unique elements of the tensors

Returns

tensorndarray (…, 3, 3)

3 by 3 tensors

_lt_rows

dipy.reconst.dti._lt_rows()

ndarray(shape, dtype=float, buffer=None, offset=0,

strides=None, order=None)

An array object represents a multidimensional, homogeneous array of fixed-size items. An associated data-type object describes the format of each element in the array (its byte-order, how many bytes it occupies in memory, whether it is an integer, a floating point number, or something else, etc.)

Arrays should be constructed using array, zeros or empty (refer to the See Also section below). The parameters given here refer to a low-level method (ndarray(…)) for instantiating an array.

For more information, refer to the numpy module and examine the methods and attributes of an array.

Parameters

(for the __new__ method; see Notes below)

shapetuple of ints

Shape of created array.

dtypedata-type, optional

Any object that can be interpreted as a numpy data type.

bufferobject exposing buffer interface, optional

Used to fill the array with data.

offsetint, optional

Offset of array data in buffer.

stridestuple of ints, optional

Strides of data in memory.

order{‘C’, ‘F’}, optional

Row-major (C-style) or column-major (Fortran-style) order.

Attributes

Tndarray

Transpose of the array.

databuffer

The array’s elements, in memory.

dtypedtype object

Describes the format of the elements in the array.

flagsdict

Dictionary containing information related to memory use, e.g., ‘C_CONTIGUOUS’, ‘OWNDATA’, ‘WRITEABLE’, etc.

flatnumpy.flatiter object

Flattened version of the array as an iterator. The iterator allows assignments, e.g., x.flat = 3 (See ndarray.flat for assignment examples; TODO).

imagndarray

Imaginary part of the array.

realndarray

Real part of the array.

sizeint

Number of elements in the array.

itemsizeint

The memory use of each array element in bytes.

nbytesint

The total number of bytes required to store the array data, i.e., itemsize * size.

ndimint

The array’s number of dimensions.

shapetuple of ints

Shape of the array.

stridestuple of ints

The step-size required to move from one element to the next in memory. For example, a contiguous (3, 4) array of type int16 in C-order has strides (8, 2). This implies that to move from element to element in memory requires jumps of 2 bytes. To move from row-to-row, one needs to jump 8 bytes at a time (2 * 4).

ctypesctypes object

Class containing properties of the array needed for interaction with ctypes.

basendarray

If the array is a view into another array, that array is its base (unless that array is also a view). The base array is where the array data is actually stored.

See Also

array : Construct an array. zeros : Create an array, each element of which is zero. empty : Create an array, but leave its allocated memory unchanged (i.e.,

it contains “garbage”).

dtype : Create a data-type. numpy.typing.NDArray : An ndarray alias generic

w.r.t. its dtype.type <numpy.dtype.type>.

Notes

There are two modes of creating an array using __new__:

1. If buffer is None, then only shape, dtype, and order are used.

2. If buffer is an object exposing the buffer interface, then all keywords are interpreted.

No __init__ method is needed because the array is fully initialized after the __new__ method.

Examples

These examples illustrate the low-level ndarray constructor. Refer to the See Also section above for easier ways of constructing an ndarray.

First mode, buffer is None:

>>> np.ndarray(shape=(2,2), dtype=float, order='F')
array([[0.0e+000, 0.0e+000], # random
       [     nan, 2.5e-323]])

Second mode:

>>> np.ndarray((2,), buffer=np.array([1,2,3]),
...            offset=np.int_().itemsize,
...            dtype=int) # offset = 1*itemsize, i.e. skip first element
array([2, 3])

_lt_cols

dipy.reconst.dti._lt_cols()

ndarray(shape, dtype=float, buffer=None, offset=0,

strides=None, order=None)

An array object represents a multidimensional, homogeneous array of fixed-size items. An associated data-type object describes the format of each element in the array (its byte-order, how many bytes it occupies in memory, whether it is an integer, a floating point number, or something else, etc.)

Arrays should be constructed using array, zeros or empty (refer to the See Also section below). The parameters given here refer to a low-level method (ndarray(…)) for instantiating an array.

For more information, refer to the numpy module and examine the methods and attributes of an array.

Parameters

(for the __new__ method; see Notes below)

shapetuple of ints

Shape of created array.

dtypedata-type, optional

Any object that can be interpreted as a numpy data type.

bufferobject exposing buffer interface, optional

Used to fill the array with data.

offsetint, optional

Offset of array data in buffer.

stridestuple of ints, optional

Strides of data in memory.

order{‘C’, ‘F’}, optional

Row-major (C-style) or column-major (Fortran-style) order.

Attributes

Tndarray

Transpose of the array.

databuffer

The array’s elements, in memory.

dtypedtype object

Describes the format of the elements in the array.

flagsdict

Dictionary containing information related to memory use, e.g., ‘C_CONTIGUOUS’, ‘OWNDATA’, ‘WRITEABLE’, etc.

flatnumpy.flatiter object

Flattened version of the array as an iterator. The iterator allows assignments, e.g., x.flat = 3 (See ndarray.flat for assignment examples; TODO).

imagndarray

Imaginary part of the array.

realndarray

Real part of the array.

sizeint

Number of elements in the array.

itemsizeint

The memory use of each array element in bytes.

nbytesint

The total number of bytes required to store the array data, i.e., itemsize * size.

ndimint

The array’s number of dimensions.

shapetuple of ints

Shape of the array.

stridestuple of ints

The step-size required to move from one element to the next in memory. For example, a contiguous (3, 4) array of type int16 in C-order has strides (8, 2). This implies that to move from element to element in memory requires jumps of 2 bytes. To move from row-to-row, one needs to jump 8 bytes at a time (2 * 4).

ctypesctypes object

Class containing properties of the array needed for interaction with ctypes.

basendarray

If the array is a view into another array, that array is its base (unless that array is also a view). The base array is where the array data is actually stored.

See Also

array : Construct an array. zeros : Create an array, each element of which is zero. empty : Create an array, but leave its allocated memory unchanged (i.e.,

it contains “garbage”).

dtype : Create a data-type. numpy.typing.NDArray : An ndarray alias generic

w.r.t. its dtype.type <numpy.dtype.type>.

Notes

There are two modes of creating an array using __new__:

1. If buffer is None, then only shape, dtype, and order are used.

2. If buffer is an object exposing the buffer interface, then all keywords are interpreted.

No __init__ method is needed because the array is fully initialized after the __new__ method.

Examples

These examples illustrate the low-level ndarray constructor. Refer to the See Also section above for easier ways of constructing an ndarray.

First mode, buffer is None:

>>> np.ndarray(shape=(2,2), dtype=float, order='F')
array([[0.0e+000, 0.0e+000], # random
       [     nan, 2.5e-323]])

Second mode:

>>> np.ndarray((2,), buffer=np.array([1,2,3]),
...            offset=np.int_().itemsize,
...            dtype=int) # offset = 1*itemsize, i.e. skip first element
array([2, 3])

lower_triangular

dipy.reconst.dti.lower_triangular(tensor, b0=None)

Returns the six lower triangular values of the tensor ordered as (Dxx, Dxy, Dyy, Dxz, Dyz, Dzz) and a dummy variable if b0 is not None.

Parameters

tensorarray_like (…, 3, 3)

a collection of 3, 3 diffusion tensors

b0float

if b0 is not none log(b0) is returned as the dummy variable

Returns

Dndarray

If b0 is none, then the shape will be (…, 6) otherwise (…, 7)

decompose_tensor

dipy.reconst.dti.decompose_tensor(tensor, min_diffusivity=0)

Returns eigenvalues and eigenvectors given a diffusion tensor

Computes tensor eigen decomposition to calculate eigenvalues and eigenvectors (Basser et al., 1994a).

Parameters

tensorarray (…, 3, 3)

Hermitian matrix representing a diffusion tensor.

min_diffusivityfloat

Because negative eigenvalues are not physical and small eigenvalues, much smaller than the diffusion weighting, cause quite a lot of noise in metrics such as fa, diffusivity values smaller than min_diffusivity are replaced with min_diffusivity.

Returns

eigvalsarray (…, 3)

Eigenvalues from eigen decomposition of the tensor. Negative eigenvalues are replaced by zero. Sorted from largest to smallest.

eigvecsarray (…, 3, 3)

Associated eigenvectors from eigen decomposition of the tensor. Eigenvectors are columnar (e.g. eigvecs[…, :, j] is associated with eigvals[…, j])

design_matrix

dipy.reconst.dti.design_matrix(gtab, dtype=None)

Constructs design matrix for DTI weighted least squares or least squares fitting. (Basser et al., 1994a)

Parameters

gtab : A GradientTable class instance

dtypestring

Parameter to control the dtype of returned designed matrix

Returns

design_matrixarray (g,7)

Design matrix or B matrix assuming Gaussian distributed tensor model design_matrix[j, :] = (Bxx, Byy, Bzz, Bxy, Bxz, Byz, dummy)

quantize_evecs

dipy.reconst.dti.quantize_evecs(evecs, odf_vertices=None)

Find the closest orientation of an evenly distributed sphere

Parameters

evecs : ndarray odf_vertices : None or ndarray

If None, then set vertices from symmetric362 sphere. Otherwise use passed ndarray as vertices

Returns

IN : ndarray

eig_from_lo_tri

dipy.reconst.dti.eig_from_lo_tri(data, min_diffusivity=0)

Calculates tensor eigenvalues/eigenvectors from an array containing the lower diagonal form of the six unique tensor elements.

Parameters

dataarray_like (…, 6)

diffusion tensors elements stored in lower triangular order

min_diffusivityfloat

See decompose_tensor()

Returns

dti_paramsarray (…, 12)

Eigen-values and eigen-vectors of the same array.

EuDXDirectionGetter

class dipy.reconst.eudx_direction_getter.EuDXDirectionGetter

Bases: DirectionGetter

Deterministic Direction Getter based on peak directions.

This class contains the cython portion of the code for PeaksAndMetrics and is not meant to be used on its own.

__init__()

ang_thr

initial_direction(point)

The best starting directions for fiber tracking from point

All the valid peaks in the voxel closest to point are returned as initial directions.

qa_thr

total_weight

ForecastModel

class dipy.reconst.forecast.ForecastModel(gtab, sh_order_max=8, lambda_lb=0.001, dec_alg='CSD', sphere=None, lambda_csd=1.0)

Bases: OdfModel, Cache

Fiber ORientation Estimated using Continuous Axially Symmetric Tensors (FORECAST) [1,2,3]_. FORECAST is a Spherical Deconvolution reconstruction model for multi-shell diffusion data which enables the calculation of a voxel adaptive response function using the Spherical Mean Technique (SMT) [2,3]_.

With FORECAST it is possible to calculate crossing invariant parallel diffusivity, perpendicular diffusivity, mean diffusivity, and fractional anisotropy [2]_

References

[1]

Anderson A. W., “Measurement of Fiber Orientation Distributions Using High Angular Resolution Diffusion Imaging”, Magnetic Resonance in Medicine, 2005.

[2]

Kaden E. et al., “Quantitative Mapping of the Per-Axon Diffusion Coefficients in Brain White Matter”, Magnetic Resonance in Medicine, 2016.

[3]

Zucchelli E. et al., “A generalized SMT-based framework for Diffusion MRI microstructural model estimation”, MICCAI Workshop on Computational DIFFUSION MRI (CDMRI), 2017.

Notes

The implementation of FORECAST may require CVXPY (https://www.cvxpy.org/).

__init__(gtab, sh_order_max=8, lambda_lb=0.001, dec_alg='CSD', sphere=None, lambda_csd=1.0)

Analytical and continuous modeling of the diffusion signal with respect to the FORECAST basis [1,2,3]_. This implementation is a modification of the original FORECAST model presented in [1]_ adapted for multi-shell data as in [2,3]_ . The main idea is to model the diffusion signal as the combination of a single fiber response function \(F(\mathbf{b})\) times the fODF \(\rho(\mathbf{v})\) ..math:: :nowrap: begin{equation} E(mathbf{b}) = int_{mathbf{v} in mathcal{S}^2} rho(mathbf{v}) F({mathbf{b}} | mathbf{v}) d mathbf{v} end{equation} where \(\mathbf{b}\) is the b-vector (b-value times gradient direction) and \(\mathbf{v}\) is an unit vector representing a fiber direction. In FORECAST \(\rho\) is modeled using real symmetric Spherical Harmonics (SH) and \(F(\mathbf(b))\) is an axially symmetric tensor. Parameters ———- gtab : GradientTable, gradient directions and bvalues container class. sh_order_max : unsigned int, an even integer that represent the maximal SH order (l) of the basis (max 12) lambda_lb: float, Laplace-Beltrami regularization weight. dec_alg : str, Spherical deconvolution algorithm. The possible values are Weighted Least Squares (‘WLS’), Positivity Constraints using CVXPY (‘POS’) and the Constraint Spherical Deconvolution algorithm (‘CSD’). Default is ‘CSD’. sphere : array, shape (N,3), sphere points where to enforce positivity when ‘POS’ or ‘CSD’ dec_alg are selected. lambda_csd : float, CSD regularization weight. References ———- .. [1] Anderson A. W., “Measurement of Fiber Orientation Distributions Using High Angular Resolution Diffusion Imaging”, Magnetic Resonance in Medicine, 2005. .. [2] Kaden E. et al., “Quantitative Mapping of the Per-Axon Diffusion Coefficients in Brain White Matter”, Magnetic Resonance in Medicine, 2016. .. [3] Zucchelli M. et al., “A generalized SMT-based framework for Diffusion MRI microstructural model estimation”, MICCAI Workshop on Computational DIFFUSION MRI (CDMRI), 2017. Examples ——– In this example, where the data, gradient table and sphere tessellation used for reconstruction are provided, we model the diffusion signal with respect to the FORECAST and compute the fODF, parallel and perpendicular diffusivity. >>> import warnings >>> from dipy.data import default_sphere, get_3shell_gtab >>> gtab = get_3shell_gtab() >>> from dipy.sims.voxel import multi_tensor >>> mevals = np.array(([0.0017, 0.0003, 0.0003], … [0.0017, 0.0003, 0.0003])) >>> angl = [(0, 0), (60, 0)] >>> data, sticks = multi_tensor(gtab, … mevals, … S0=100.0, … angles=angl, … fractions=[50, 50], … snr=None) >>> from dipy.reconst.forecast import ForecastModel >>> from dipy.reconst.shm import descoteaux07_legacy_msg >>> with warnings.catch_warnings(): … warnings.filterwarnings( … “ignore”, message=descoteaux07_legacy_msg, … category=PendingDeprecationWarning) … fm = ForecastModel(gtab, sh_order_max=6) >>> f_fit = fm.fit(data) >>> d_par = f_fit.dpar >>> d_perp = f_fit.dperp >>> with warnings.catch_warnings(): … warnings.filterwarnings( … “ignore”, message=descoteaux07_legacy_msg, … category=PendingDeprecationWarning) … fodf = f_fit.odf(default_sphere)

fit(data, mask=None)

Fit method for every voxel in data

ForecastFit

class dipy.reconst.forecast.ForecastFit(model, data, sh_coef, d_par, d_perp)

Bases: OdfFit

__init__(model, data, sh_coef, d_par, d_perp)

Calculates diffusion properties for a single voxel

Parameters

modelobject,

AnalyticalModel

data1d ndarray,

fitted data

sh_coef1d ndarray,

forecast sh coefficients

d_parfloat,

parallel diffusivity

d_perpfloat,

perpendicular diffusivity

property dpar

The parallel diffusivity

property dperp

The perpendicular diffusivity

fractional_anisotropy()

Calculates the fractional anisotropy.

mean_diffusivity()

Calculates the mean diffusivity.

odf(sphere, clip_negative=True)

Calculates the fODF for a given discrete sphere.

Parameters

sphereSphere,

the odf sphere

clip_negativeboolean, optional

if True clip the negative odf values to 0, default True

predict(gtab=None, S0=1.0)

Calculates the fODF for a given discrete sphere.

Parameters

gtabGradientTable, optional

gradient directions and bvalues container class.

S0float, optional

the signal at b-value=0

property sh_coeff

The FORECAST SH coefficients

find_signal_means

dipy.reconst.forecast.find_signal_means(b_unique, data_norm, bvals, rho, lb_matrix, w=0.001)

Calculate the mean signal for each shell.

Parameters

b_unique1d ndarray,

unique b-values in a vector excluding zero

data_norm1d ndarray,

normalized diffusion signal

bvals1d ndarray,

the b-values

rho2d ndarray,

SH basis matrix for fitting the signal on each shell

lb_matrix2d ndarray,

Laplace-Beltrami regularization matrix

wfloat,

weight for the Laplace-Beltrami regularization

Returns

means1d ndarray

the average of the signal for each b-values

forecast_error_func

dipy.reconst.forecast.forecast_error_func(x, b_unique, E)

Calculates the difference between the mean signal calculated using the parameter vector x and the average signal E using FORECAST and SMT

psi_l

dipy.reconst.forecast.psi_l(l, b)

forecast_matrix

dipy.reconst.forecast.forecast_matrix(sh_order_max, d_par, d_perp, bvals)

Compute the FORECAST radial matrix

rho_matrix

dipy.reconst.forecast.rho_matrix(sh_order_max, vecs)

Compute the SH matrix \(\rho\)

lb_forecast

dipy.reconst.forecast.lb_forecast(sh_order_max)

Returns the Laplace-Beltrami regularization matrix for FORECAST

FreeWaterTensorModel

class dipy.reconst.fwdti.FreeWaterTensorModel(gtab, fit_method='NLS', *args, **kwargs)

Bases: ReconstModel

Class for the Free Water Elimination Diffusion Tensor Model

__init__(gtab, fit_method='NLS', *args, **kwargs)

Free Water Diffusion Tensor Model [1]_.

Parameters

gtab : GradientTable class instance fit_method : str or callable

str can be one of the following:

‘WLS’ for weighted linear least square fit according to [1]_

fwdti.wls_iter()

‘NLS’ for non-linear least square fit according to [1]_

fwdti.nls_iter()

callable has to have the signature:

fit_method(design_matrix, data, *args, **kwargs)

args, kwargsarguments and key-word arguments passed to the

fit_method. See fwdti.wls_iter, fwdti.nls_iter for details

References

[1]

Henriques, R.N., Rokem, A., Garyfallidis, E., St-Jean, S., Peterson E.T., Correia, M.M., 2017. [Re] Optimization of a free water elimination two-compartment model for diffusion tensor imaging. ReScience volume 3, issue 1, article number 2

fit(data, mask=None)

Fit method for every voxel in data

predict(fwdti_params, S0=1)

Predict a signal for this TensorModel class instance given parameters.

Parameters

fwdti_params(…, 13) ndarray

The last dimension should have 13 parameters: the 12 tensor parameters (3 eigenvalues, followed by the 3 corresponding eigenvectors) and the free water volume fraction.

S0float or ndarray

The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1

Returns

S(…, N) ndarray

Simulated signal based on the free water DTI model

FreeWaterTensorFit

class dipy.reconst.fwdti.FreeWaterTensorFit(model, model_params)

Bases: TensorFit

Class for fitting the Free Water Tensor Model

__init__(model, model_params)

Initialize a FreeWaterTensorFit class instance. Since the free water tensor model is an extension of DTI, class instance is defined as subclass of the TensorFit from dti.py

Parameters

modelFreeWaterTensorModel Class instance

Class instance containing the free water tensor model for the fit

model_paramsndarray (x, y, z, 13) or (n, 13)

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

References

[1]

Henriques, R.N., Rokem, A., Garyfallidis, E., St-Jean, S., Peterson E.T., Correia, M.M., 2017. [Re] Optimization of a free water elimination two-compartment model for diffusion tensor imaging. ReScience volume 3, issue 1, article number 2

property f

Returns the free water diffusion volume fraction f

predict(gtab, S0=1)

Given a free water tensor model fit, predict the signal on the vertices of a gradient table

Parameters

gtaba GradientTable class instance

The gradient table for this prediction

S0float array

The mean non-diffusion weighted signal in each voxel. Default: 1 in all voxels.

Returns

S(…, N) ndarray

Simulated signal based on the free water DTI model

fwdti_prediction

dipy.reconst.fwdti.fwdti_prediction(params, gtab, S0=1, Diso=0.003)

Signal prediction given the free water DTI model parameters. Parameters ———- params : (…, 13) ndarray Model parameters. The last dimension should have the 12 tensor parameters (3 eigenvalues, followed by the 3 corresponding eigenvectors) and the volume fraction of the free water compartment. gtab : a GradientTable class instance The gradient table for this prediction S0 : float or ndarray The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1 Diso : float, optional Value of the free water isotropic diffusion. Default is set to 3e-3 \(mm^{2}.s^{-1}\). Please adjust this value if you are assuming different units of diffusion. Returns ——- S : (…, N) ndarray Simulated signal based on the free water DTI model Notes —– The predicted signal is given by: \(S(\theta, b) = S_0 * [(1-f) * e^{-b ADC} + f * e^{-b D_{iso}]\), where \(ADC = \theta Q \theta^T\), \(\theta\) is a unit vector pointing at any direction on the sphere for which a signal is to be predicted, \(b\) is the b value provided in the GradientTable input for that direction, \(Q\) is the quadratic form of the tensor determined by the input parameters, \(f\) is the free water diffusion compartment, \(D_{iso}\) is the free water diffusivity which is equal to $3 * 10^{-3} mm^{2}s^{-1} [1]_. References ———- .. [1] Henriques, R.N., Rokem, A., Garyfallidis, E., St-Jean, S., Peterson E.T., Correia, M.M., 2017. [Re] Optimization of a free water elimination two-compartment model for diffusion tensor imaging. ReScience volume 3, issue 1, article number 2

wls_iter

dipy.reconst.fwdti.wls_iter(design_matrix, sig, S0, Diso=0.003, mdreg=0.0027, min_signal=1e-06, piterations=3)

Applies weighted 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 adjust 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. Default: minimal signal in the data provided to fit. piterations : inter, optional Number of iterations used to refine the precision of f. Default is set to 3 corresponding to a precision of 0.01. 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

wls_fit_tensor

dipy.reconst.fwdti.wls_fit_tensor(gtab, data, Diso=0.003, mask=None, min_signal=1e-06, piterations=3, mdreg=0.0027)

Computes weighted least squares (WLS) fit to calculate self-diffusion tensor using a linear regression model [1]_. Parameters ———- gtab : a GradientTable class instance The gradient table containing diffusion acquisition parameters. data : ndarray ([X, Y, Z, …], g) Data or response variables holding the data. Note that the last dimension should contain the data. It makes no copies of data. Diso : float, optional Value of the free water isotropic diffusion. Default is set to 3e-3 \(mm^{2}.s^{-1}\). Please adjust this value if you are assuming different units of diffusion. mask : array, optional A boolean array used to mark the coordinates in the data that should be analyzed that has the shape data.shape[:-1] min_signal : float The minimum signal value. Needs to be a strictly positive number. Default: 1.0e-6. piterations : inter, optional Number of iterations used to refine the precision of f. Default is set to 3 corresponding to a precision of 0.01. 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). Returns ——- fw_params : ndarray (x, y, z, 13) Matrix containing in the last dimension the free water model parameters in the following order: 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. References ———- .. [1] Henriques, R.N., Rokem, A., Garyfallidis, E., St-Jean, S., Peterson E.T., Correia, M.M., 2017. [Re] Optimization of a free water elimination two-compartment model for diffusion tensor imaging. ReScience volume 3, issue 1, article number 2

nls_iter

dipy.reconst.fwdti.nls_iter(design_matrix, sig, S0, Diso=0.003, mdreg=0.0027, min_signal=1e-06, 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 adjust 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.

nls_fit_tensor

dipy.reconst.fwdti.nls_fit_tensor(gtab, data, mask=None, Diso=0.003, mdreg=0.0027, min_signal=1e-06, f_transform=True, cholesky=False, jac=False, weighting=None, sigma=None)

Fit the water elimination tensor model using the non-linear least-squares. Parameters ———- gtab : a GradientTable class instance The gradient table containing diffusion acquisition parameters. data : ndarray ([X, Y, Z, …], g) Data or response variables holding the data. Note that the last dimension should contain the data. It makes no copies of data. mask : array, optional A boolean array used to mark the coordinates in the data that should be analyzed that has the shape data.shape[:-1] Diso : float, optional Value of the free water isotropic diffusion. Default is set to 3e-3 \(mm^{2}.s^{-1}\). Please adjust 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. Default: 1.0e-6. 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 cholesky : bool, optional If true it uses Cholesky decomposition to insure that diffusion tensor is positive define. Default: False 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 ——- fw_params : ndarray (x, y, z, 13) Matrix containing in the dimension the free water model parameters in the following order: 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

lower_triangular_to_cholesky

dipy.reconst.fwdti.lower_triangular_to_cholesky(tensor_elements)

Performs Cholesky decomposition of the diffusion tensor

Parameters

tensor_elementsarray (6,)

Array containing the six elements of diffusion tensor’s lower triangular.

Returns

cholesky_elementsarray (6,)

Array containing the six Cholesky’s decomposition elements (R0, R1, R2, R3, R4, R5) [1]_.

References

[1]

Koay, C.G., Carew, J.D., Alexander, A.L., Basser, P.J., Meyerand, M.E., 2006. Investigation of anomalous estimates of tensor-derived quantities in diffusion tensor imaging. Magnetic Resonance in Medicine, 55(4), 930-936. doi:10.1002/mrm.20832

cholesky_to_lower_triangular

dipy.reconst.fwdti.cholesky_to_lower_triangular(R)

Convert Cholesky decomposition elements to the diffusion tensor elements

Parameters

Rarray (6,)

Array containing the six Cholesky’s decomposition elements (R0, R1, R2, R3, R4, R5) [1]_.

Returns

tensor_elementsarray (6,)

Array containing the six elements of diffusion tensor’s lower triangular.

References

[1]

Koay, C.G., Carew, J.D., Alexander, A.L., Basser, P.J., Meyerand, M.E., 2006. Investigation of anomalous estimates of tensor-derived quantities in diffusion tensor imaging. Magnetic Resonance in Medicine, 55(4), 930-936. doi:10.1002/mrm.20832

GeneralizedQSamplingModel

class dipy.reconst.gqi.GeneralizedQSamplingModel(gtab, method='gqi2', sampling_length=1.2, normalize_peaks=False)

Bases: OdfModel, Cache

__init__(gtab, method='gqi2', sampling_length=1.2, normalize_peaks=False)

Generalized Q-Sampling Imaging [1]_

This model has the same assumptions as the DSI method i.e. Cartesian grid sampling in q-space and fast gradient switching.

Implements equations 2.14 from [2]_ for standard GQI and equation 2.16 from [2]_ for GQI2. You can think of GQI2 as an analytical solution of the DSI ODF.

Parameters

gtabobject,

GradientTable

methodstr,

‘standard’ or ‘gqi2’

sampling_lengthfloat,

diffusion sampling length (lambda in eq. 2.14 and 2.16)

References

[1]

Yeh F-C et al., “Generalized Q-Sampling Imaging”, IEEE TMI, 2010

[2]

Garyfallidis E, “Towards an accurate brain tractography”, PhD

thesis, University of Cambridge, 2012.

Notes

As of version 0.9, range of the sampling length in GQI2 has changed to match the same scale used in the ‘standard’ method [1]_. This means that the value of sampling_length should be approximately 1 - 1.3 (see [1]_, pg. 1628).

Examples

Here we create an example where we provide the data, a gradient table and a reconstruction sphere and calculate the ODF for the first voxel in the data.

>>> from dipy.data import dsi_voxels
>>> data, gtab = dsi_voxels()
>>> from dipy.core.subdivide_octahedron import create_unit_sphere
>>> sphere = create_unit_sphere(5)
>>> from dipy.reconst.gqi import GeneralizedQSamplingModel
>>> gq = GeneralizedQSamplingModel(gtab, 'gqi2', 1.1)
>>> voxel_signal = data[0, 0, 0]
>>> odf = gq.fit(voxel_signal).odf(sphere)

See Also

dipy.reconst.dsi.DiffusionSpectrumModel

fit(data, mask=None)

Fit method for every voxel in data

GeneralizedQSamplingFit

class dipy.reconst.gqi.GeneralizedQSamplingFit(model, data)

Bases: OdfFit

__init__(model, data)

Calculates PDF and ODF for a single voxel

Parameters

modelobject,

DiffusionSpectrumModel

data1d ndarray,

signal values

odf(sphere)

Calculates the discrete ODF for a given discrete sphere.

normalize_qa

dipy.reconst.gqi.normalize_qa(qa, max_qa=None)

Normalize quantitative anisotropy.

Used mostly with GQI rather than GQI2.

Parameters

qaarray, shape (X, Y, Z, N)

where N is the maximum number of peaks stored

max_qafloat,

maximum qa value. Usually found in the CSF (corticospinal fluid).

Returns

nqaarray, shape (x, Y, Z, N)

normalized quantitative anisotropy

Notes

Normalized quantitative anisotropy has the very useful property to be very small near gray matter and background areas. Therefore, it can be used to mask out white matter areas.

squared_radial_component

dipy.reconst.gqi.squared_radial_component(x, tol=0.01)

Part of the GQI2 integral

Eq.8 in the referenced paper by Yeh et al. 2010

npa

dipy.reconst.gqi.npa(self, odf, width=5)

non-parametric anisotropy

Nimmo-Smith et al. ISMRM 2011

equatorial_zone_vertices

dipy.reconst.gqi.equatorial_zone_vertices(vertices, pole, width=5)

finds the ‘vertices’ in the equatorial zone conjugate to ‘pole’ with width half ‘width’ degrees

polar_zone_vertices

dipy.reconst.gqi.polar_zone_vertices(vertices, pole, width=5)

finds the ‘vertices’ in the equatorial band around the ‘pole’ of radius ‘width’ degrees

upper_hemi_map

dipy.reconst.gqi.upper_hemi_map(v)

maps a 3-vector into the z-upper hemisphere

equatorial_maximum

dipy.reconst.gqi.equatorial_maximum(vertices, odf, pole, width)

patch_vertices

dipy.reconst.gqi.patch_vertices(vertices, pole, width)

find ‘vertices’ within the cone of ‘width’ degrees around ‘pole’

patch_maximum

dipy.reconst.gqi.patch_maximum(vertices, odf, pole, width)

odf_sum

dipy.reconst.gqi.odf_sum(odf)

patch_sum

dipy.reconst.gqi.patch_sum(vertices, odf, pole, width)

triple_odf_maxima

dipy.reconst.gqi.triple_odf_maxima(vertices, odf, width)

IvimModelTRR

class dipy.reconst.ivim.IvimModelTRR(gtab, split_b_D=400.0, split_b_S0=200.0, bounds=None, two_stage=True, tol=1e-15, x_scale=(1000.0, 0.1, 0.001, 0.0001), gtol=1e-15, ftol=1e-15, eps=1e-15, maxiter=1000)

Bases: ReconstModel

Ivim model

__init__(gtab, split_b_D=400.0, split_b_S0=200.0, bounds=None, two_stage=True, tol=1e-15, x_scale=(1000.0, 0.1, 0.001, 0.0001), gtol=1e-15, ftol=1e-15, eps=1e-15, maxiter=1000)

Initialize an IVIM model.

The IVIM model assumes that biological tissue includes a volume fraction ‘f’ of water flowing with a pseudo-diffusion coefficient D* and a fraction (1-f) of static (diffusion only), intra and extracellular water, with a diffusion coefficient D. In this model the echo attenuation of a signal in a single voxel can be written as

\[\]

S(b) = S_0[f*e^{(-b*D*)} + (1-f)e^{(-b*D)}]

Where: .. math:

S_0, f, D* and D are the IVIM parameters.

Parameters

gtabGradientTable class instance

Gradient directions and bvalues

split_b_Dfloat, optional

The b-value to split the data on for two-stage fit. This will be used while estimating the value of D. The assumption is that at higher b values the effects of perfusion is less and hence the signal can be approximated as a mono-exponential decay. default : 400.

split_b_S0float, optional

The b-value to split the data on for two-stage fit for estimation of S0 and initial guess for D_star. The assumption here is that at low bvalues the effects of perfusion are more. default : 200.

boundstuple of arrays with 4 elements, optional

Bounds to constrain the fitted model parameters. This is only supported for Scipy version > 0.17. When using a older Scipy version, this function will raise an error if bounds are different from None. This parameter is also used to fill nan values for out of bounds parameters in the IvimFit class using the method fill_na. default : ([0., 0., 0., 0.], [np.inf, .3, 1., 1.])

two_stagebool

Argument to specify whether to perform a non-linear fitting of all parameters after the linear fitting by splitting the data based on bvalues. This gives more accurate parameters but takes more time. The linear fit can be used to get a quick estimation of the parameters. default : False

tolfloat, optional

Tolerance for convergence of minimization. default : 1e-15

x_scalearray-like, optional

Scaling for the parameters. This is passed to least_squares which is only available for Scipy version > 0.17. default: [1000, 0.01, 0.001, 0.0001]

gtolfloat, optional

Tolerance for termination by the norm of the gradient. default : 1e-15

ftolfloat, optional

Tolerance for termination by the change of the cost function. default : 1e-15

epsfloat, optional

Step size used for numerical approximation of the jacobian. default : 1e-15

maxiterint, optional

Maximum number of iterations to perform. default : 1000

References

[1]

Le Bihan, Denis, et al. “Separation of diffusion and perfusion in intravoxel incoherent motion MR imaging.” Radiology 168.2 (1988): 497-505.

[2]

Federau, Christian, et al. “Quantitative measurement of brain perfusion with intravoxel incoherent motion MR imaging.” Radiology 265.3 (2012): 874-881.

estimate_f_D_star(params_f_D_star, data, S0, D)

Estimate f and D_star using the values of all the other parameters obtained from a linear fit.

Parameters

params_f_D_star: array

An array containing the value of f and D_star.

dataarray

Array containing the actual signal values.

S0float

The parameters S0 obtained from a linear fit.

Dfloat

The parameters D obtained from a linear fit.

Returns

ffloat

Perfusion fraction estimated from the fit.

D_star :

The value of D_star estimated from the fit.

estimate_linear_fit(data, split_b, less_than=True)

Estimate a linear fit by taking log of data.

Parameters

dataarray

An array containing the data to be fit

split_bfloat

The b value to split the data

less_thanbool

If True, splitting occurs for bvalues less than split_b

Returns

S0float

The estimated S0 value. (intercept)

Dfloat

The estimated value of D.

fit(data, mask=None)

Fit method for every voxel in data

predict(ivim_params, gtab, S0=1.0)

Predict a signal for this IvimModel class instance given parameters.

Parameters

ivim_paramsarray

The ivim parameters as an array [S0, f, D_star and D]

gtabGradientTable class instance

Gradient directions and bvalues.

S0float, optional

This has been added just for consistency with the existing API. Unlike other models, IVIM predicts S0 and this is over written by the S0 value in params.

Returns

ivim_signalarray

The predicted IVIM signal using given parameters.

IvimModelVP

class dipy.reconst.ivim.IvimModelVP(gtab, bounds=None, maxiter=10, xtol=1e-08)

Bases: ReconstModel

__init__(gtab, bounds=None, maxiter=10, xtol=1e-08)

Initialize an IvimModelVP class.

The IVIM model assumes that biological tissue includes a volume fraction ‘f’ of water flowing with a pseudo-diffusion coefficient D* and a fraction (1-f: treated as a separate fraction in the variable projection method) of static (diffusion only), intra and extracellular water, with a diffusion coefficient D. In this model the echo attenuation of a signal in a single voxel can be written as

\[\]

S(b) = S_0*[f*e^{(-b*D*)} + (1-f)e^{(-b*D)}]

Where: .. math:

S_0, f, D* and D are the IVIM parameters.

maxiter: int, optional

Maximum number of iterations for the Differential Evolution in SciPy. default : 10

xtolfloat, optional

Tolerance for convergence of minimization. default : 1e-8

References

[1]

Le Bihan, Denis, et al. “Separation of diffusion and perfusion in intravoxel incoherent motion MR imaging.” Radiology 168.2 (1988): 497-505.

[2]

Federau, Christian, et al. “Quantitative measurement of brain perfusion with intravoxel incoherent motion MR imaging.” Radiology 265.3 (2012): 874-881.

[3]

Fadnavis, Shreyas et.al. “MicroLearn: Framework for machine learning, reconstruction, optimization and microstructure modeling, Proceedings of: International Society of Magnetic Resonance in Medicine (ISMRM), Montreal, Canada, 2019.

cvx_fit(signal, phi)

Performs the constrained search for the linear parameters f after the estimation of x is done. Estimation of the linear parameters f is a constrained linear least-squares optimization problem solved by using a convex optimizer from cvxpy. The IVIM equation contains two parameters that depend on the same volume fraction. Both are estimated as separately in the convex optimizer.

Parameters

phiarray

Returns an array calculated from :func: phi.

signalarray

The signal values measured for this model.

Returns

f1, f2 (volume fractions)

Notes

cost function for differential evolution algorithm:

\[minimize(norm((signal)- (phi*f)))\]

fit(data, mask=None)

Fit method for every voxel in data

ivim_mix_cost_one(phi, signal)

Constructs the objective for the :func: stoc_search_cost.

First calculates the Moore-Penrose inverse of the input phi and takes a dot product with the measured signal. The result obtained is again multiplied with phi to complete the projection of the variable into a transformed space. (see [1]_ and [2]_ for thorough discussion on Variable Projections and relevant cost functions).

Parameters

phiarray

Returns an array calculated from :func: Phi.

signalarray

The signal values measured for this model.

Returns

(signal - S)^T(signal - S)

Notes

to make cost function for Differential Evolution algorithm: .. math:

(signal -  S)^T(signal -  S)

References

[1]

Fadnavis, Shreyas et.al. “MicroLearn: Framework for machine learning, reconstruction, optimization and microstructure modeling, Proceedings of: International Society of Magnetic Resonance in Medicine (ISMRM), Montreal, Canada, 2019.

[2]

Farooq, Hamza, et al. “Microstructure Imaging of Crossing (MIX) White Matter Fibers from diffusion MRI.” Scientific reports 6 (2016).

nlls_cost(x_f, signal)

Cost function for the least square problem. The cost function is used in the Least Squares function of SciPy in :func: fit. It guarantees that stopping point of the algorithm is at least a stationary point with reduction in the the number of iterations required by the differential evolution optimizer.

Parameters

x_farray

Contains the parameters ‘x’ and ‘f’ combines in the same array.

signalarray

The signal values measured for this model.

Returns

sum{(signal - phi*f)^2}

Notes

cost function for the least square problem.

\[sum{(signal - phi*f)^2}\]

phi(x)

Creates a structure for the combining the diffusion and pseudo- diffusion by multiplying with the bvals and then exponentiating each of the two components for fitting as per the IVIM- two compartment model.

Parameters

xarray

input from the Differential Evolution optimizer.

Returns

exp_phi1array

Combined array of parameters perfusion/pseudo-diffusion and diffusion parameters.

stoc_search_cost(x, signal)

Cost function for differential evolution algorithm. Performs a stochastic search for the non-linear parameters ‘x’. The objective function is calculated in the :func: ivim_mix_cost_one. The function constructs the parameters using :func: phi.

Parameters

xarray

input from the Differential Evolution optimizer.

signalarray

The signal values measured for this model.

Returns

func:

ivim_mix_cost_one

x_and_f_to_x_f(x, f)

Combines the array of parameters ‘x’ and ‘f’ into x_f for performing NLLS on the final stage of optimization.

Parameters

x, farray

Split parameters into two separate arrays

Returns

x_farray

Combined array of parameters ‘x’ and ‘f’ parameters.

x_f_to_x_and_f(x_f)

Splits the array of parameters in x_f to ‘x’ and ‘f’ for performing a search on the both of them independently using the Trust Region Method.

Parameters

x_farray

Combined array of parameters ‘x’ and ‘f’ parameters.

Returns

x, farray

Split parameters into two separate arrays

IvimFit

class dipy.reconst.ivim.IvimFit(model, model_params)

Bases: object

__init__(model, model_params)

Initialize a IvimFit class instance.

Parameters

model : Model class

model_paramsarray

The parameters of the model. In this case it is an array of ivim parameters. If the fitting is done for multi_voxel data, the multi_voxel decorator will run the fitting on all the voxels and model_params will be an array of the dimensions (data[:-1], 4), i.e., there will be 4 parameters for each of the voxels.

property D

property D_star

property S0_predicted

property perfusion_fraction

predict(gtab, S0=1.0)

Given a model fit, predict the signal.

Parameters

gtabGradientTable class instance

Gradient directions and bvalues

S0float

S0 value here is not necessary and will not be used to predict the signal. It has been added to conform to the structure of the predict method in multi_voxel which requires a keyword argument S0.

Returns

signalarray

The signal values predicted for this model using its parameters.

property shape

ivim_prediction

dipy.reconst.ivim.ivim_prediction(params, gtab)

The Intravoxel incoherent motion (IVIM) model function.

Parameters

paramsarray

An array of IVIM parameters - [S0, f, D_star, D].

gtabGradientTable class instance

Gradient directions and bvalues.

S0float, optional

This has been added just for consistency with the existing API. Unlike other models, IVIM predicts S0 and this is over written by the S0 value in params.

Returns

Sarray

An array containing the IVIM signal estimated using given parameters.

f_D_star_prediction

dipy.reconst.ivim.f_D_star_prediction(params, gtab, S0, D)

Function used to predict IVIM signal when S0 and D are known by considering f and D_star as the unknown parameters.

Parameters

paramsarray

The value of f and D_star.

gtabGradientTable class instance

Gradient directions and bvalues.

S0float

The parameters S0 obtained from a linear fit.

Dfloat

The parameters D obtained from a linear fit.

Returns

Sarray

An array containing the IVIM signal estimated using given parameters.

f_D_star_error

dipy.reconst.ivim.f_D_star_error(params, gtab, signal, S0, D)

Error function used to fit f and D_star keeping S0 and D fixed

Parameters

paramsarray

The value of f and D_star.

gtabGradientTable class instance

Gradient directions and bvalues.

signalarray

Array containing the actual signal values.

S0float

The parameters S0 obtained from a linear fit.

Dfloat

The parameters D obtained from a linear fit.

Returns

residualarray

An array containing the difference of actual and estimated signal.

ivim_model_selector

dipy.reconst.ivim.ivim_model_selector(gtab, fit_method='trr', **kwargs)

Selector function to switch between the 2-stage Trust-Region Reflective based NLLS fitting method (also containing the linear fit): trr and the Variable Projections based fitting method: varpro.

Parameters

fit_methodstring, optional

The value fit_method can either be ‘trr’ or ‘varpro’. default : trr

MapmriModel

class dipy.reconst.mapmri.MapmriModel(gtab, radial_order=6, laplacian_regularization=True, laplacian_weighting=0.2, positivity_constraint=False, global_constraints=False, pos_grid=15, pos_radius='adaptive', anisotropic_scaling=True, eigenvalue_threshold=0.0001, bval_threshold=inf, dti_scale_estimation=True, static_diffusivity=0.0007, cvxpy_solver=None)

Bases: ReconstModel, Cache

Mean Apparent Propagator MRI (MAPMRI) [1]_ of the diffusion signal.

The main idea is to model the diffusion signal as a linear combination of the continuous functions presented in [2]_ but extending it in three dimensions. The main difference with the SHORE proposed in [3]_ is that MAPMRI 3D extension is provided using a set of three basis functions for the radial part, one for the signal along x, one for y and one for z, while [3]_ uses one basis function to model the radial part and real Spherical Harmonics to model the angular part. From the MAPMRI coefficients is possible to use the analytical formulae to estimate the ODF.

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[2]

Ozarslan E. et al., “Simple harmonic oscillator based reconstruction and estimation for one-dimensional q-space magnetic resonance 1D-SHORE)”, eapoc Intl Soc Mag Reson Med, vol. 16, p. 35., 2008.

[3]

Merlet S. et al., “Continuous diffusion signal, EAP and ODF estimation via Compressive Sensing in diffusion MRI”, Medical Image Analysis, 2013.

[4]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

[5]

Cheng, J., 2014. Estimation and Processing of Ensemble Average Propagator and Its Features in Diffusion MRI. Ph.D. Thesis.

[6]

Hosseinbor et al. “Bessel fourier orientation reconstruction (bfor): An analytical diffusion propagator reconstruction for hybrid diffusion imaging and computation of q-space indices”. NeuroImage 64, 2013, 650-670.

[7]

Craven et al. “Smoothing Noisy Data with Spline Functions.” NUMER MATH 31.4 (1978): 377-403.

[8]

Avram et al. “Clinical feasibility of using mean apparent propagator (MAP) MRI to characterize brain tissue microstructure”. NeuroImage 2015, in press.

[9]

Dela Haije et al. “Enforcing necessary non-negativity constraints for common diffusion MRI models using sum of squares programming”. NeuroImage 209, 2020, 116405.

__init__(gtab, radial_order=6, laplacian_regularization=True, laplacian_weighting=0.2, positivity_constraint=False, global_constraints=False, pos_grid=15, pos_radius='adaptive', anisotropic_scaling=True, eigenvalue_threshold=0.0001, bval_threshold=inf, dti_scale_estimation=True, static_diffusivity=0.0007, cvxpy_solver=None)

Analytical and continuous modeling of the diffusion signal with respect to the MAPMRI basis [1]_.

The main idea is to model the diffusion signal as a linear combination of the continuous functions presented in [2]_ but extending it in three dimensions.

The main difference with the SHORE proposed in [3]_ is that MAPMRI 3D extension is provided using a set of three basis functions for the radial part, one for the signal along x, one for y and one for z, while [3]_ uses one basis function to model the radial part and real Spherical Harmonics to model the angular part.

From the MAPMRI coefficients it is possible to estimate various q-space indices, the PDF and the ODF.

The fitting procedure can be constrained using the positivity constraint proposed in [1]_ or [4]_ and/or the laplacian regularization proposed in [5]_.

For the estimation of q-space indices we recommend using the ‘regular’ anisotropic implementation of MAPMRI. However, it has been shown that the ODF estimation in this implementation has a bias which ‘squeezes together’ the ODF peaks when there is a crossing at an angle smaller than 90 degrees [5]_. When you want to estimate ODFs for tractography we therefore recommend using the isotropic implementation (which is equivalent to [3]_).

The switch between isotropic and anisotropic can be easily made through the anisotropic_scaling option.

Parameters

gtabGradientTable,

gradient directions and bvalues container class. the gradient table has to include b0-images.

radial_orderunsigned int,

an even integer that represent the order of the basis

laplacian_regularization: bool,

Regularize using the Laplacian of the MAP-MRI basis.

laplacian_weighting: string or scalar,

The string ‘GCV’ makes it use generalized cross-validation to find the regularization weight [4]. A scalar sets the regularization weight to that value and an array will make it selected the optimal weight from the values in the array.

positivity_constraintbool,

Constrain the propagator to be positive.

global_constraintsbool, optional

If set to False, positivity is enforced on a grid determined by pos_grid and pos_radius. If set to True, positivity is enforced everywhere using the constraints of [6]_. Global constraints are currently supported for anisotropic_scaling=True and for radial_order <= 10. Default: False.

pos_gridinteger,

The number of points in the grid that is used in the local positivity constraint.

pos_radiusfloat or string,

If set to a float, the maximum distance the local positivity constraint constrains to posivity is that value. If set to ‘adaptive’, the maximum distance is dependent on the estimated tissue diffusivity.

anisotropic_scalingbool,

If True, uses the standard anisotropic MAP-MRI basis. If False, uses the isotropic MAP-MRI basis (equal to 3D-SHORE).

eigenvalue_thresholdfloat,

Sets the minimum of the tensor eigenvalues in order to avoid stability problem.

bval_thresholdfloat,

Sets the b-value threshold to be used in the scale factor estimation. In order for the estimated non-Gaussianity to have meaning this value should set to a lower value (b<2000 s/mm^2) such that the scale factors are estimated on signal points that reasonably represent the spins at Gaussian diffusion.

dti_scale_estimationbool,

Whether or not DTI fitting is used to estimate the isotropic scale factor for isotropic MAP-MRI. When set to False the algorithm presets the isotropic tissue diffusivity to static_diffusivity. This vastly increases fitting speed but at the cost of slightly reduced fitting quality. Can still be used in combination with regularization and constraints.

static_diffusivityfloat,

the tissue diffusivity that is used when dti_scale_estimation is set to False. The default is that of typical white matter D=0.7e-3 _[5].

cvxpy_solverstr, optional

cvxpy solver name. Optionally optimize the positivity constraint with a particular cvxpy solver. See https://www.cvxpy.org/ for details. Default: None (cvxpy chooses its own solver)

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[2]

Ozarslan E. et al., “Simple harmonic oscillator based reconstruction and estimation for one-dimensional q-space magnetic resonance 1D-SHORE)”, Proc Intl Soc Mag Reson Med, vol. 16, p. 35., 2008.

[3]

Ozarslan E. et al., “Simple harmonic oscillator based reconstruction and estimation for three-dimensional q-space mri”, ISMRM 2009.

[4]

Dela Haije et al. “Enforcing necessary non-negativity constraints for common diffusion MRI models using sum of squares programming”. NeuroImage 209, 2020, 116405.

[5]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

[6]

Merlet S. et al., “Continuous diffusion signal, EAP and ODF estimation via Compressive Sensing in diffusion MRI”, Medical Image Analysis, 2013.

Examples

In this example, where the data, gradient table and sphere tessellation used for reconstruction are provided, we model the diffusion signal with respect to the SHORE basis and compute the real and analytical ODF.

>>> from dipy.data import dsi_voxels, default_sphere
>>> from dipy.core.gradients import gradient_table
>>> _, gtab_ = dsi_voxels()
>>> gtab = gradient_table(gtab_.bvals, gtab_.bvecs,
...                       b0_threshold=gtab_.bvals.min())
>>> from dipy.sims.voxel import sticks_and_ball
>>> data, golden_directions = sticks_and_ball(gtab, d=0.0015, S0=1,
...                                           angles=[(0, 0),
...                                                   (90, 0)],
...                                           fractions=[50, 50],
...                                           snr=None)
>>> from dipy.reconst.mapmri import MapmriModel
>>> radial_order = 4
>>> map_model = MapmriModel(gtab, radial_order=radial_order)
>>> mapfit = map_model.fit(data)
>>> odf = mapfit.odf(default_sphere)

fit(data, mask=None)

Fit method for every voxel in data

MapmriFit

class dipy.reconst.mapmri.MapmriFit(model, mapmri_coef, mu, R, lopt, errorcode=0)

Bases: ReconstFit

__init__(model, mapmri_coef, mu, R, lopt, errorcode=0)

Calculates diffusion properties for a single voxel

Parameters

modelobject,

AnalyticalModel

mapmri_coef1d ndarray,

mapmri coefficients

muarray, shape (3,)

scale parameters vector for x, y and z

Rarray, shape (3,3)

rotation matrix

loptfloat,

regularization weight used for laplacian regularization

errorcodeint

provides information on whether errors occurred in the fitting of each voxel. 0 means no problem, 1 means a LinAlgError occurred when trying to invert the design matrix. 2 means the positivity constraint was unable to solve the problem. 3 means that after positivity constraint failed, also matrix inversion failed.

fitted_signal(gtab=None)

Recovers the fitted signal for the given gradient table. If no gradient table is given it recovers the signal for the gtab of the model object.

property mapmri_R

The MAPMRI rotation matrix

property mapmri_coeff

The MAPMRI coefficients

property mapmri_mu

The MAPMRI scale factors

msd()

Calculates the analytical Mean Squared Displacement (MSD). It is defined as the Laplacian of the origin of the estimated signal [1]_. The analytical formula for the MAP-MRI basis was derived in [2]_ eq. (C13, D1).

References

[1]

Cheng, J., 2014. Estimation and Processing of Ensemble Average

Propagator and Its Features in Diffusion MRI. Ph.D. Thesis.

[2]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

ng()

Calculates the analytical non-Gaussiannity (NG) [1]_. For the NG to be meaningful the mapmri scale factors must be estimated only on data representing Gaussian diffusion of spins, i.e., bvals smaller than about 2000 s/mm^2 [2]_.

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[2]

Avram et al. “Clinical feasibility of using mean apparent

propagator (MAP) MRI to characterize brain tissue microstructure”. NeuroImage 2015, in press.

ng_parallel()

Calculates the analytical parallel non-Gaussiannity (NG) [1]_. For the NG to be meaningful the mapmri scale factors must be estimated only on data representing Gaussian diffusion of spins, i.e., bvals smaller than about 2000 s/mm^2 [2]_.

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[2]

Avram et al. “Clinical feasibility of using mean apparent

propagator (MAP) MRI to characterize brain tissue microstructure”. NeuroImage 2015, in press.

ng_perpendicular()

Calculates the analytical perpendicular non-Gaussiannity (NG) [1]_. For the NG to be meaningful the mapmri scale factors must be estimated only on data representing Gaussian diffusion of spins, i.e., bvals smaller than about 2000 s/mm^2 [2]_.

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[2]

Avram et al. “Clinical feasibility of using mean apparent

propagator (MAP) MRI to characterize brain tissue microstructure”. NeuroImage 2015, in press.

norm_of_laplacian_signal()

Calculates the norm of the laplacian of the fitted signal [1]_. This information could be useful to assess if the extrapolation of the fitted signal contains spurious oscillations. A high laplacian may indicate that these are present, and any q-space indices that use integrals of the signal may be corrupted (e.g. RTOP, RTAP, RTPP, QIV).

References

[1]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

odf(sphere, s=2)

Calculates the analytical Orientation Distribution Function (ODF) from the signal [1]_ Eq. (32).

Parameters

sphereSphere

A Sphere instance with vertices, edges and faces attributes.

sunsigned int

radial moment of the ODF

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

odf_sh(s=2)

Calculates the real analytical odf for a given discrete sphere. Computes the design matrix of the ODF for the given sphere vertices and radial moment [1]_ eq. (32). The radial moment s acts as a sharpening method. The analytical equation for the spherical ODF basis is given in [2]_ eq. (C8).

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[2]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

pdf(r_points)

Diffusion propagator on a given set of real points. if the array r_points is non writeable, then intermediate results are cached for faster recalculation

predict(qvals_or_gtab, S0=100.0)

Recovers the reconstructed signal for any qvalue array or gradient table.

qiv()

Calculates the analytical Q-space Inverse Variance (QIV). It is defined as the inverse of the Laplacian of the origin of the estimated propagator [1]_ eq. (22). The analytical formula for the MAP-MRI basis was derived in [2]_ eq. (C14, D2).

References

[1]

Hosseinbor et al. “Bessel fourier orientation reconstruction

(bfor): An analytical diffusion propagator reconstruction for hybrid diffusion imaging and computation of q-space indices. NeuroImage 64, 2013, 650-670.

[2]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

rtap()

Calculates the analytical return to the axis probability (RTAP) [1]_ eq. (40, 44a). The analytical formula for the isotropic MAP-MRI basis was derived in [2]_ eq. (C11).

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[2]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

rtop()

Calculates the analytical return to the origin probability (RTOP) [1]_ eq. (36, 43). The analytical formula for the isotropic MAP-MRI basis was derived in [2]_ eq. (C11).

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[2]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

rtpp()

Calculates the analytical return to the plane probability (RTPP) [1]_ eq. (42). The analytical formula for the isotropic MAP-MRI basis was derived in [2]_ eq. (C11).

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[2]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

isotropic_scale_factor

dipy.reconst.mapmri.isotropic_scale_factor(mu_squared)

Estimated isotropic scaling factor _[1] Eq. (49).

Parameters

mu_squaredarray, shape (N,3)

squared scale factors of mapmri basis in x, y, z

Returns

u0float

closest isotropic scale factor for the isotropic basis

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

mapmri_index_matrix

dipy.reconst.mapmri.mapmri_index_matrix(radial_order)

Calculates the indices for the MAPMRI [1]_ basis in x, y and z.

Parameters

radial_orderunsigned int

radial order of MAPMRI basis

Returns

index_matrixarray, shape (N,3)

ordering of the basis in x, y, z

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

b_mat

dipy.reconst.mapmri.b_mat(index_matrix)

Calculates the B coefficients from [1]_ Eq. (27).

Parameters

index_matrixarray, shape (N,3)

ordering of the basis in x, y, z

Returns

Barray, shape (N,)

B coefficients for the basis

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

b_mat_isotropic

dipy.reconst.mapmri.b_mat_isotropic(index_matrix)

Calculates the isotropic B coefficients from [1]_ Fig 8.

Parameters

index_matrixarray, shape (N,3)

ordering of the isotropic basis in j, l, m

Returns

Barray, shape (N,)

B coefficients for the isotropic basis

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

mapmri_phi_1d

dipy.reconst.mapmri.mapmri_phi_1d(n, q, mu)

One dimensional MAPMRI basis function from [1]_ Eq. (4).

Parameters

nunsigned int

order of the basis

qarray, shape (N,)

points in the q-space in which evaluate the basis

mufloat

scale factor of the basis

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

mapmri_phi_matrix

dipy.reconst.mapmri.mapmri_phi_matrix(radial_order, mu, q_gradients)

Compute the MAPMRI phi matrix for the signal [1]_ eq. (23).

Parameters

radial_orderunsigned int,

an even integer that represent the order of the basis

muarray, shape (3,)

scale factors of the basis for x, y, z

q_gradientsarray, shape (N,3)

points in the q-space in which evaluate the basis

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

mapmri_psi_1d

dipy.reconst.mapmri.mapmri_psi_1d(n, x, mu)

One dimensional MAPMRI propagator basis function from [1]_ Eq. (10).

Parameters

nunsigned int

order of the basis

xarray, shape (N,)

points in the r-space in which evaluate the basis

mufloat

scale factor of the basis

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

mapmri_psi_matrix

dipy.reconst.mapmri.mapmri_psi_matrix(radial_order, mu, rgrad)

Compute the MAPMRI psi matrix for the propagator [1]_ eq. (22).

Parameters

radial_orderunsigned int,

an even integer that represent the order of the basis

muarray, shape (3,)

scale factors of the basis for x, y, z

rgradarray, shape (N,3)

points in the r-space in which evaluate the EAP

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

mapmri_odf_matrix

dipy.reconst.mapmri.mapmri_odf_matrix(radial_order, mu, s, vertices)

Compute the MAPMRI ODF matrix [1]_ Eq. (33).

Parameters

radial_orderunsigned int,

an even integer that represent the order of the basis

muarray, shape (3,)

scale factors of the basis for x, y, z

sunsigned int

radial moment of the ODF

verticesarray, shape (N,3)

points of the sphere shell in the r-space in which evaluate the ODF

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

mapmri_isotropic_phi_matrix

dipy.reconst.mapmri.mapmri_isotropic_phi_matrix(radial_order, mu, q)

Three dimensional isotropic MAPMRI signal basis function from [1]_ Eq. (61).

Parameters

radial_orderunsigned int,

radial order of the mapmri basis.

mufloat,

positive isotropic scale factor of the basis

qarray, shape (N,3)

points in the q-space in which evaluate the basis

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

mapmri_isotropic_radial_signal_basis

dipy.reconst.mapmri.mapmri_isotropic_radial_signal_basis(j, l_value, mu, qval)

Radial part of the isotropic 1D-SHORE signal basis [1]_ eq. (61).

Parameters

junsigned int,

a positive integer related to the radial order

l_valueunsigned int,

the spherical harmonic order (l)

mufloat,

isotropic scale factor of the basis

qvalfloat,

points in the q-space in which evaluate the basis

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

mapmri_isotropic_M_mu_independent

dipy.reconst.mapmri.mapmri_isotropic_M_mu_independent(radial_order, q)

Computed the mu independent part of the signal design matrix.

mapmri_isotropic_M_mu_dependent

dipy.reconst.mapmri.mapmri_isotropic_M_mu_dependent(radial_order, mu, qval)

Computed the mu dependent part of the signal design matrix.

mapmri_isotropic_psi_matrix

dipy.reconst.mapmri.mapmri_isotropic_psi_matrix(radial_order, mu, rgrad)

Three dimensional isotropic MAPMRI propagator basis function from [1]_ Eq. (61).

Parameters

radial_orderunsigned int,

radial order of the mapmri basis.

mufloat,

positive isotropic scale factor of the basis

rgradarray, shape (N,3)

points in the r-space in which evaluate the basis

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

mapmri_isotropic_radial_pdf_basis

dipy.reconst.mapmri.mapmri_isotropic_radial_pdf_basis(j, l_value, mu, r)

Radial part of the isotropic 1D-SHORE propagator basis [1]_ eq. (61).

Parameters

junsigned int,

a positive integer related to the radial order

l_valueunsigned int,

the spherical harmonic order (l)

mufloat,

isotropic scale factor of the basis

rfloat,

points in the r-space in which evaluate the basis

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

mapmri_isotropic_K_mu_independent

dipy.reconst.mapmri.mapmri_isotropic_K_mu_independent(radial_order, rgrad)

Computes mu independent part of K. Same trick as with M.

mapmri_isotropic_K_mu_dependent

dipy.reconst.mapmri.mapmri_isotropic_K_mu_dependent(radial_order, mu, rgrad)

Computes mu dependent part of M. Same trick as with M.

binomialfloat

dipy.reconst.mapmri.binomialfloat(n, k)

Custom Binomial function

mapmri_isotropic_odf_matrix

dipy.reconst.mapmri.mapmri_isotropic_odf_matrix(radial_order, mu, s, vertices)

Compute the isotropic MAPMRI ODF matrix [1]_ Eq. 32 but for the isotropic propagator in [1]_ eq. (60). Analytical derivation in [2]_ eq. (C8).

Parameters

radial_orderunsigned int,

an even integer that represent the order of the basis

mufloat,

isotropic scale factor of the isotropic MAP-MRI basis

sunsigned int

radial moment of the ODF

verticesarray, shape (N,3)

points of the sphere shell in the r-space in which evaluate the ODF

Returns

odf_matMatrix, shape (N_vertices, N_mapmri_coef)

ODF design matrix to discrete sphere function

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[2]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

mapmri_isotropic_odf_sh_matrix

dipy.reconst.mapmri.mapmri_isotropic_odf_sh_matrix(radial_order, mu, s)

Compute the isotropic MAPMRI ODF matrix [1]_ Eq. 32 for the isotropic propagator in [1]_ eq. (60). Here we do not compute the sphere function but the spherical harmonics by only integrating the radial part of the propagator. We use the same derivation of the ODF in the isotropic implementation as in [2]_ eq. (C8).

Parameters

radial_orderunsigned int,

an even integer that represent the order of the basis

mufloat,

isotropic scale factor of the isotropic MAP-MRI basis

sunsigned int

radial moment of the ODF

Returns

odf_sh_matMatrix, shape (N_sh_coef, N_mapmri_coef)

ODF design matrix to spherical harmonics

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[2]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

mapmri_isotropic_laplacian_reg_matrix

dipy.reconst.mapmri.mapmri_isotropic_laplacian_reg_matrix(radial_order, mu)

Computes the Laplacian regularization matrix for MAP-MRI’s isotropic implementation [1]_ eq. (C7).

Parameters

radial_orderunsigned int,

an even integer that represent the order of the basis

mufloat,

isotropic scale factor of the isotropic MAP-MRI basis

Returns

LRMatrix, shape (N_coef, N_coef)

Laplacian regularization matrix

References

[1]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

mapmri_isotropic_laplacian_reg_matrix_from_index_matrix

dipy.reconst.mapmri.mapmri_isotropic_laplacian_reg_matrix_from_index_matrix(ind_mat, mu)

Computes the Laplacian regularization matrix for MAP-MRI’s isotropic implementation [1]_ eq. (C7).

Parameters

ind_matmatrix (N_coef, 3),

Basis order matrix

mufloat,

isotropic scale factor of the isotropic MAP-MRI basis

Returns

LRMatrix, shape (N_coef, N_coef)

Laplacian regularization matrix

References

[1]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

mapmri_isotropic_index_matrix

dipy.reconst.mapmri.mapmri_isotropic_index_matrix(radial_order)

Calculates the indices for the isotropic MAPMRI basis [1]_ Fig 8.

Parameters

radial_orderunsigned int

radial order of isotropic MAPMRI basis

Returns

index_matrixarray, shape (N,3)

ordering of the basis in x, y, z

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

create_rspace

dipy.reconst.mapmri.create_rspace(gridsize, radius_max)

Create the real space table, that contains the points in which to compute the pdf.

Parameters

gridsizeunsigned int

dimension of the propagator grid

radius_maxfloat

maximal radius in which compute the propagator

Returns

tabarray, shape (N,3)

real space points in which calculates the pdf

delta

dipy.reconst.mapmri.delta(n, m)

map_laplace_u

dipy.reconst.mapmri.map_laplace_u(n, m)

S(n, m) static matrix for Laplacian regularization [1]_ eq. (13).

Parameters

n, munsigned int

basis order of the MAP-MRI basis in different directions

Returns

Ufloat,

Analytical integral of \(\phi_n(q) * \phi_m(q)\)

References

[1]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

map_laplace_t

dipy.reconst.mapmri.map_laplace_t(n, m)

L(m, n) static matrix for Laplacian regularization [1]_ eq. (12).

Parameters

n, munsigned int

basis order of the MAP-MRI basis in different directions

Returns

Tfloat

Analytical integral of \(\phi_n(q) * \phi_m''(q)\)

References

[1]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

map_laplace_s

dipy.reconst.mapmri.map_laplace_s(n, m)

R(m,n) static matrix for Laplacian regularization [1]_ eq. (11).

Parameters

n, munsigned int

basis order of the MAP-MRI basis in different directions

Returns

Sfloat

Analytical integral of \(\phi_n''(q) * \phi_m''(q)\)

References

[1]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

mapmri_STU_reg_matrices

dipy.reconst.mapmri.mapmri_STU_reg_matrices(radial_order)

Generate the static portions of the Laplacian regularization matrix according to [1]_ eq. (11, 12, 13).

Parameters

radial_orderunsigned int,

an even integer that represent the order of the basis

Returns

S, T, UMatrices, shape (N_coef,N_coef)

Regularization submatrices

References

[1]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

mapmri_laplacian_reg_matrix

dipy.reconst.mapmri.mapmri_laplacian_reg_matrix(ind_mat, mu, S_mat, T_mat, U_mat)

Put the Laplacian regularization matrix together [1]_ eq. (10).

The static parts in S, T and U are multiplied and divided by the voxel-specific scale factors.

Parameters

ind_matmatrix (N_coef, 3),

Basis order matrix

muarray, shape (3,)

scale factors of the basis for x, y, z

S, T, Umatrices, shape (N_coef,N_coef)

Regularization submatrices

Returns

LRmatrix (N_coef, N_coef),

Voxel-specific Laplacian regularization matrix

References

[1]

Fick, Rutger HJ, et al. “MAPL: Tissue microstructure estimation

using Laplacian-regularized MAP-MRI and its application to HCP data.” NeuroImage (2016).

generalized_crossvalidation_array

dipy.reconst.mapmri.generalized_crossvalidation_array(data, M, LR, weights_array=None)

Generalized Cross Validation Function [1]_ eq. (15).

Here weights_array is a numpy array with all values that should be considered in the GCV. It will run through the weights until the cost function starts to increase, then stop and take the last value as the optimum weight.

Parameters

dataarray (N),

Basis order matrix

Mmatrix, shape (N, Ncoef)

mapmri observation matrix

LRmatrix, shape (N_coef, N_coef)

regularization matrix

weights_arrayarray (N_of_weights)

array of optional regularization weights

generalized_crossvalidation

dipy.reconst.mapmri.generalized_crossvalidation(data, M, LR, gcv_startpoint=0.05)

Generalized Cross Validation Function [1]_ eq. (15).

Finds optimal regularization weight based on generalized cross-validation.

Parameters

dataarray (N),

data array

Mmatrix, shape (N, Ncoef)

mapmri observation matrix

LRmatrix, shape (N_coef, N_coef)

regularization matrix

gcv_startpointfloat

startpoint for the gcv optimization

Returns

optimal_lambdafloat,

optimal regularization weight

References

[1]

Craven et al. “Smoothing Noisy Data with Spline Functions.” NUMER MATH 31.4 (1978): 377-403.

gcv_cost_function

dipy.reconst.mapmri.gcv_cost_function(weight, args)

The GCV cost function that is iterated [4].

MultiShellResponse

class dipy.reconst.mcsd.MultiShellResponse(response, sh_order_max, shells, S0=None)

Bases: object

__init__(response, sh_order_max, shells, S0=None)

Estimate Multi Shell response function for multiple tissues and multiple shells.

The method multi_shell_fiber_response allows to create a multi-shell fiber response with the right format, for a three compartments model. It can be referred to in order to understand the inputs of this class.

Parameters

responsendarray

Multi-shell fiber response. The ordering of the responses should follow the same logic as S0.

sh_order_maxint

Maximal spherical harmonics order (l).

shellsint

Number of shells in the data

S0array (3,)

Signal with no diffusion weighting for each tissue compartments, in the same tissue order as response. This S0 can be used for predicting from a fit model later on.

property iso

MultiShellDeconvModel

class dipy.reconst.mcsd.MultiShellDeconvModel(gtab, response, reg_sphere=<dipy.core.sphere.HemiSphere object>, sh_order_max=8, iso=2, tol=20)

Bases: SphHarmModel

__init__(gtab, response, reg_sphere=<dipy.core.sphere.HemiSphere object>, sh_order_max=8, iso=2, tol=20)

Multi-Shell Multi-Tissue Constrained Spherical Deconvolution (MSMT-CSD) [1]_. This method extends the CSD model proposed in [2]_ by the estimation of multiple response functions as a function of multiple b-values and multiple tissue types.

Spherical deconvolution computes a fiber orientation distribution (FOD), also called fiber ODF (fODF) [2]_. The fODF is derived from different tissue types and thus overcomes the overestimation of WM in GM and CSF areas.

The response function is based on the different tissue types and is provided as input to the MultiShellDeconvModel. It will be used as deconvolution kernel, as described in [2]_.

Parameters

gtab : GradientTable response : ndarray or MultiShellResponse object

Pre-computed multi-shell fiber response function in the form of a MultiShellResponse object, or simple response function as a ndarray. The later must be of shape (3, len(bvals)-1, 4), because it will be converted into a MultiShellResponse object via the multi_shell_fiber_response method (important note: the function unique_bvals_tolerance is used here to select unique bvalues from gtab as input). Each column (3,) has two elements. The first is the eigen-values as a (3,) ndarray and the second is the signal value for the response function without diffusion weighting (S0). Note that in order to use more than three compartments, one must create a MultiShellResponse object on the side.

reg_sphereSphere (optional)

sphere used to build the regularization B matrix. Default: ‘symmetric362’.

sh_order_maxint (optional)

Maximal spherical harmonics order (l). Default: 8

iso: int (optional)

Number of tissue compartments for running the MSMT-CSD. Minimum number of compartments required is 2. Default: 2

tolint, optional

Tolerance gap for b-values clustering.

References

[1]

Jeurissen, B., et al. NeuroImage 2014. Multi-tissue constrained spherical deconvolution for improved analysis of multi-shell diffusion MRI data

[2]

Tournier, J.D., et al. NeuroImage 2007. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution

[3]

Tournier, J.D, et al. Imaging Systems and Technology 2012. MRtrix: Diffusion Tractography in Crossing Fiber Regions

fit(data, mask=None)

Fit method for every voxel in data

predict(params, gtab=None, S0=None)

Compute a signal prediction given spherical harmonic coefficients for the provided GradientTable class instance.

Parameters

paramsndarray

The spherical harmonic representation of the FOD from which to make the signal prediction.

gtabGradientTable

The gradients for which the signal will be predicted. Use the model’s gradient table by default.

S0ndarray or float

The non diffusion-weighted signal value.

MSDeconvFit

class dipy.reconst.mcsd.MSDeconvFit(model, coeff, mask)

Bases: SphHarmFit

__init__(model, coeff, mask)

Abstract class which holds the fit result of MultiShellDeconvModel. Inherits the SphHarmFit which fits the diffusion data to a spherical harmonic model.

Parameters

model: object

MultiShellDeconvModel

coeffarray

Spherical harmonic coefficients for the ODF.

mask: ndarray

Mask for fitting

property all_shm_coeff

property shm_coeff

The spherical harmonic coefficients of the odf

Make this a property for now, if there is a use case for modifying the coefficients we can add a setter or expose the coefficients more directly

property volume_fractions

QpFitter

class dipy.reconst.mcsd.QpFitter(X, reg)

Bases: object

__init__(X, reg)

Makes use of the quadratic programming solver solve_qp to fit the model. The initialization for the model is done using the warm-start by default in CVXPY.

Parameters

Xndarray

Matrix to be fit by the QP solver calculated in MultiShellDeconvModel

regndarray

the regularization B matrix calculated in MultiShellDeconvModel

multi_tissue_basis

dipy.reconst.mcsd.multi_tissue_basis(gtab, sh_order_max, iso_comp)

Builds a basis for multi-shell multi-tissue CSD model.

Parameters

gtab : GradientTable sh_order_max : int

Maximal spherical harmonics order (l).

iso_comp: int

Number of tissue compartments for running the MSMT-CSD. Minimum number of compartments required is 2.

Returns

Bndarray

Matrix of the spherical harmonics model used to fit the data

m_valuesint |m_value| <= l_value

The phase factor (m) of the harmonic.

l_valuesint l_value >= 0

The order (l) of the harmonic.

solve_qp

dipy.reconst.mcsd.solve_qp(P, Q, G, H)

Helper function to set up and solve the Quadratic Program (QP) in CVXPY. A QP problem has the following form: minimize 1/2 x’ P x + Q’ x subject to G x <= H

Here the QP solver is based on CVXPY and uses OSQP.

Parameters

Pndarray

n x n matrix for the primal QP objective function.

Qndarray

n x 1 matrix for the primal QP objective function.

Gndarray

m x n matrix for the inequality constraint.

Hndarray

m x 1 matrix for the inequality constraint.

Returns

xarray

Optimal solution to the QP problem.

multi_shell_fiber_response

dipy.reconst.mcsd.multi_shell_fiber_response(sh_order_max, bvals, wm_rf, gm_rf, csf_rf, sphere=None, tol=20, btens=None)

Fiber response function estimation for multi-shell data.

Parameters

sh_order_maxint

Maximum spherical harmonics order (l).

bvalsndarray

Array containing the b-values. Must be unique b-values, like outputted by dipy.core.gradients.unique_bvals_tolerance.

wm_rf(N-1, 4) ndarray

Response function of the WM tissue, for each bvals, where N is the number of unique b-values including the b0.

gm_rf(N-1, 4) ndarray

Response function of the GM tissue, for each bvals.

csf_rf(N-1, 4) ndarray

Response function of the CSF tissue, for each bvals.

spheredipy.core.Sphere instance, optional

Sphere where the signal will be evaluated.

tolint, optional

Tolerance gap for b-values clustering.

btens : can be any of two options, optional

1. an array of strings of shape (N,) specifying encoding tensor shape associated with all unique b-values separately. N corresponds to the number of unique b-values, including the b0. Options for elements in array: ‘LTE’, ‘PTE’, ‘STE’, ‘CTE’ corresponding to linear, planar, spherical, and “cigar-shaped” tensor encoding.

2. an array of shape (N,3,3) specifying the b-tensor of each unique b-values exactly. N corresponds to the number of unique b-values, including the b0.

Returns

MultiShellResponse

MultiShellResponse object.

mask_for_response_msmt

dipy.reconst.mcsd.mask_for_response_msmt(gtab, data, roi_center=None, roi_radii=10, wm_fa_thr=0.7, gm_fa_thr=0.2, csf_fa_thr=0.1, gm_md_thr=0.0007, csf_md_thr=0.002)

Computation of masks for multi-shell multi-tissue (msmt) response

function using FA and MD.

Parameters

gtab : GradientTable data : ndarray

diffusion data (4D)

roi_centerarray-like, (3,)

Center of ROI in data. If center is None, it is assumed that it is the center of the volume with shape data.shape[:3].

roi_radiiint or array-like, (3,)

radii of cuboid ROI

wm_fa_thrfloat

FA threshold for WM.

gm_fa_thrfloat

FA threshold for GM.

csf_fa_thrfloat

FA threshold for CSF.

gm_md_thrfloat

MD threshold for GM.

csf_md_thrfloat

MD threshold for CSF.

Returns

mask_wmndarray

Mask of voxels within the ROI and with FA above the FA threshold for WM.

mask_gmndarray

Mask of voxels within the ROI and with FA below the FA threshold for GM and with MD below the MD threshold for GM.

mask_csfndarray

Mask of voxels within the ROI and with FA below the FA threshold for CSF and with MD below the MD threshold for CSF.

Notes

In msmt-CSD there is an important pre-processing step: the estimation of every tissue’s response function. In order to do this, we look for voxels corresponding to WM, GM and CSF. This function aims to accomplish that by returning a mask of voxels within a ROI and who respect some threshold constraints, for each tissue. More precisely, the WM mask must have a FA value above a given threshold. The GM mask and CSF mask must have a FA below given thresholds and a MD below other thresholds. To get the FA and MD, we need to fit a Tensor model to the datasets.

response_from_mask_msmt

dipy.reconst.mcsd.response_from_mask_msmt(gtab, data, mask_wm, mask_gm, mask_csf, tol=20)

Computation of multi-shell multi-tissue (msmt) response

functions from given tissues masks.

Parameters

gtab : GradientTable data : ndarray

diffusion data

mask_wmndarray

mask from where to compute the WM response function.

mask_gmndarray

mask from where to compute the GM response function.

mask_csfndarray

mask from where to compute the CSF response function.

tolint

tolerance gap for b-values clustering. (Default = 20)

Returns

response_wmndarray, (len(unique_bvals_tolerance(gtab.bvals))-1, 4)

(evals, S0) for WM for each unique bvalues (except b0).

response_gmndarray, (len(unique_bvals_tolerance(gtab.bvals))-1, 4)

(evals, S0) for GM for each unique bvalues (except b0).

response_csfndarray, (len(unique_bvals_tolerance(gtab.bvals))-1, 4)

(evals, S0) for CSF for each unique bvalues (except b0).

Notes

In msmt-CSD there is an important pre-processing step: the estimation of every tissue’s response function. In order to do this, we look for voxels corresponding to WM, GM and CSF. This information can be obtained by using mcsd.mask_for_response_msmt() through masks of selected voxels. The present function uses such masks to compute the msmt response functions.

For the responses, we base our approach on the function csdeconv.response_from_mask_ssst(), with the added layers of multishell and multi-tissue (see the ssst function for more information about the computation of the ssst response function). This means that for each tissue we use the previously found masks and loop on them. For each mask, we loop on the b-values (clustered using the tolerance gap) to get many responses and then average them to get one response per tissue.

auto_response_msmt

dipy.reconst.mcsd.auto_response_msmt(gtab, data, tol=20, roi_center=None, roi_radii=10, wm_fa_thr=0.7, gm_fa_thr=0.3, csf_fa_thr=0.15, gm_md_thr=0.001, csf_md_thr=0.0032)

Automatic estimation of multi-shell multi-tissue (msmt) response

functions using FA and MD.

Parameters

gtab : GradientTable data : ndarray

diffusion data

tolint, optional

Tolerance gap for b-values clustering.

roi_centerarray-like, (3,)

Center of ROI in data. If center is None, it is assumed that it is the center of the volume with shape data.shape[:3].

roi_radiiint or array-like, (3,)

radii of cuboid ROI

wm_fa_thrfloat

FA threshold for WM.

gm_fa_thrfloat

FA threshold for GM.

csf_fa_thrfloat

FA threshold for CSF.

gm_md_thrfloat

MD threshold for GM.

csf_md_thrfloat

MD threshold for CSF.

Returns

response_wmndarray, (len(unique_bvals_tolerance(gtab.bvals))-1, 4)

(evals, S0) for WM for each unique bvalues (except b0).

response_gmndarray, (len(unique_bvals_tolerance(gtab.bvals))-1, 4)

(evals, S0) for GM for each unique bvalues (except b0).

response_csfndarray, (len(unique_bvals_tolerance(gtab.bvals))-1, 4)

(evals, S0) for CSF for each unique bvalues (except b0).

Notes

In msmt-CSD there is an important pre-processing step: the estimation of every tissue’s response function. In order to do this, we look for voxels corresponding to WM, GM and CSF. We get this information from mcsd.mask_for_response_msmt(), which returns masks of selected voxels (more details are available in the description of the function).

With the masks, we compute the response functions by using mcsd.response_from_mask_msmt(), which returns the response for each tissue (more details are available in the description of the function).

MeanDiffusionKurtosisModel

class dipy.reconst.msdki.MeanDiffusionKurtosisModel(gtab, bmag=None, return_S0_hat=False, *args, **kwargs)

Bases: ReconstModel

Mean signal Diffusion Kurtosis Model

__init__(gtab, bmag=None, return_S0_hat=False, *args, **kwargs)

Mean Signal Diffusion Kurtosis Model [1]_. Parameters ———- gtab : GradientTable class instance bmag : int The order of magnitude that the bvalues have to differ to be considered an unique b-value. Default: derive this value from the maximal b-value provided: \(bmag=log_{10}(max(bvals)) - 1\). return_S0_hat : bool If True, also return S0 values for the fit. args, kwargs : arguments and keyword arguments passed to the fit_method. See msdki.wls_fit_msdki for details References ———- .. [1] Henriques, R.N., 2018. Advanced Methods for Diffusion MRI Data Analysis and their Application to the Healthy Ageing Brain (Doctoral thesis). Downing College, University of Cambridge. https://doi.org/10.17863/CAM.29356

fit(data, mask=None)

Fit method of the MSDKI model class

Parameters

datandarray ([X, Y, Z, …], g)

ndarray containing the data signals in its last dimension.

maskarray

A boolean array used to mark the coordinates in the data that should be analyzed that has the shape data.shape[:-1]

predict(msdki_params, S0=1.0)

Predict a signal for this MeanDiffusionKurtosisModel class instance given parameters. Parameters ———- msdki_params : ndarray The parameters of the mean signal diffusion kurtosis model S0 : float or ndarray The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1 Returns ——- S : (…, N) ndarray Simulated mean signal based on the mean signal diffusion kurtosis model Notes —– The predicted signal is given by: \(MS(b) = S_0 * exp(-bD + 1/6 b^{2} D^{2} K)\), where \(D\) and \(K\) are the mean signal diffusivity and mean signal kurtosis. References ———- .. [1] Henriques, R.N., 2018. Advanced Methods for Diffusion MRI Data Analysis and their Application to the Healthy Ageing Brain (Doctoral thesis). Downing College, University of Cambridge. https://doi.org/10.17863/CAM.29356

MeanDiffusionKurtosisFit

class dipy.reconst.msdki.MeanDiffusionKurtosisFit(model, model_params, model_S0=None)

Bases: object

__init__(model, model_params, model_S0=None)

Initialize a MeanDiffusionKurtosisFit class instance.

property S0_hat

msd()

Mean signal diffusitivity (MSD) calculated from the mean signal Diffusion Kurtosis Model.

Returns

msdndarray

Calculated signal mean diffusitivity.

References

[1]

Henriques, R.N., 2018. Advanced Methods for Diffusion MRI Data Analysis and their Application to the Healthy Ageing Brain (Doctoral thesis). Downing College, University of Cambridge. https://doi.org/10.17863/CAM.29356

msk()

Mean signal kurtosis (MSK) calculated from the mean signal Diffusion Kurtosis Model.

Returns

mskndarray

Calculated signal mean kurtosis.

References

[1]

Henriques, R.N., 2018. Advanced Methods for Diffusion MRI Data Analysis and their Application to the Healthy Ageing Brain (Doctoral thesis). Downing College, University of Cambridge. https://doi.org/10.17863/CAM.29356

predict(gtab, S0=1.0)

Given a mean signal diffusion kurtosis model fit, predict the signal on the vertices of a sphere Parameters ———- gtab : a GradientTable class instance This encodes the directions for which a prediction is made S0 : float array The mean non-diffusion weighted signal in each voxel. Default: The fitted S0 value in all voxels if it was fitted. Otherwise 1 in all voxels. Returns ——- S : (…, N) ndarray Simulated mean signal based on the mean signal kurtosis model Notes —– The predicted signal is given by: \(MS(b) = S_0 * exp(-bD + 1/6 b^{2} D^{2} K)\), where \(D\) and \(k\) are the mean signal diffusivity and mean signal kurtosis. References ———- .. [1] Henriques, R.N., 2018. Advanced Methods for Diffusion MRI Data Analysis and their Application to the Healthy Ageing Brain (Doctoral thesis). Downing College, University of Cambridge. https://doi.org/10.17863/CAM.29356

smt2di()

Computes the intrisic diffusivity from the mean signal diffusional kurtosis parameters assuming the 2-compartmental spherical mean technique model [1]_, [2]_

Returns

smt2dindarray

Intrinsic diffusivity computed by converting MSDKI to SMT2.

Notes

Computes the intrinsic diffusivity using equation 16 of [1]_

References

[1]

Neto Henriques R, Jespersen SN, Shemesh N (2019). Microscopic anisotropy misestimation in spherical‐mean single diffusion encoding MRI. Magnetic Resonance in Medicine (In press). doi: 10.1002/mrm.27606

[2]

Kaden E, Kelm ND, Carson RP, et al. (2016) Multi‐compartment microscopic diffusion imaging. Neuroimage 139:346–359.

smt2f()

Computes the axonal water fraction from the mean signal kurtosis assuming the 2-compartmental spherical mean technique model [1]_, [2]_

Returns

ndarray

Axonal volume fraction calculated from MSK.

Notes

Computes the axonal water fraction from the mean signal kurtosis MSK using equation 17 of [1]_

References

[1]

Neto Henriques R, Jespersen SN, Shemesh N (2019). Microscopic anisotropy misestimation in spherical‐mean single diffusion encoding MRI. Magnetic Resonance in Medicine (In press). doi: 10.1002/mrm.27606

[2]

Kaden E, Kelm ND, Carson RP, et al. (2016) Multi‐compartment microscopic diffusion imaging. Neuroimage 139:346–359.

smt2uFA()

Computes the microscopic fractional anisotropy from the mean signal diffusional kurtosis parameters assuming the 2-compartmental spherical mean technique model [1]_, [2]_

Returns

smt2uFAndarray

Microscopic fractional anisotropy computed by converting MSDKI to SMT2.

Notes

Computes the intrinsic diffusivity using equation 10 of [1]_

References

[1]

Neto Henriques R, Jespersen SN, Shemesh N (2019). Microscopic anisotropy misestimation in spherical‐mean single diffusion encoding MRI. Magnetic Resonance in Medicine (In press). doi: 10.1002/mrm.27606

[2]

Kaden E, Kelm ND, Carson RP, et al. (2016) Multi‐compartment microscopic diffusion imaging. Neuroimage 139:346–359.

mean_signal_bvalue

dipy.reconst.msdki.mean_signal_bvalue(data, gtab, bmag=None)

Computes the average signal across different diffusion directions for each unique b-value Parameters ———- data : ndarray ([X, Y, Z, …], g) ndarray containing the data signals in its last dimension. gtab : a GradientTable class instance The gradient table containing diffusion acquisition parameters. bmag : The order of magnitude that the bvalues have to differ to be considered an unique b-value. Default: derive this value from the maximal b-value provided: \(bmag=log_{10}(max(bvals)) - 1\). Returns ——- msignal : ndarray ([X, Y, Z, …, nub]) Mean signal along all gradient directions for each unique b-value Note that the last dimension contains the signal means and nub is the number of unique b-values. ng : ndarray(nub) Number of gradient directions used to compute the mean signal for all unique b-values Notes —– This function assumes that directions are evenly sampled on the sphere or on the hemisphere

msk_from_awf

dipy.reconst.msdki.msk_from_awf(f)

Computes mean signal kurtosis from axonal water fraction estimates of the SMT2 model

Parameters

fndarray ([X, Y, Z, …])

ndarray containing the axonal volume fraction estimate.

Returns

mskndarray(nub)

Mean signal kurtosis (msk)

Notes

Computes mean signal kurtosis using equations 17 of [1]_

References

[1]

Neto Henriques R, Jespersen SN, Shemesh N (2019). Microscopic anisotropy misestimation in spherical‐mean single diffusion encoding MRI. Magnetic Resonance in Medicine (In press). doi: 10.1002/mrm.27606

awf_from_msk

dipy.reconst.msdki.awf_from_msk(msk, mask=None)

Computes the axonal water fraction from the mean signal kurtosis assuming the 2-compartmental spherical mean technique model [1]_, [2]_

Parameters

mskndarray ([X, Y, Z, …])

Mean signal kurtosis (msk)

maskndarray, optional

A boolean array used to mark the coordinates in the data that should be analyzed that has the same shape of the msdki parameters

Returns

awfndarray ([X, Y, Z, …])

ndarray containing the axonal volume fraction estimate.

Notes

Computes the axonal water fraction from the mean signal kurtosis MSK using equation 17 of [1]_

References

[1]

Neto Henriques R, Jespersen SN, Shemesh N (2019). Microscopic anisotropy misestimation in spherical‐mean single diffusion encoding MRI. Magnetic Resonance in Medicine (In press). doi: 10.1002/mrm.27606

[2]

Kaden E, Kelm ND, Carson RP, et al. (2016) Multi‐compartment microscopic diffusion imaging. Neuroimage 139:346–359.

msdki_prediction

dipy.reconst.msdki.msdki_prediction(msdki_params, gtab, S0=1.0)

Predict the mean signal given the parameters of the mean signal DKI, an GradientTable object and S0 signal. Parameters ———- msdki_params : ndarray ([X, Y, Z, …], 2) Array containing the mean signal diffusivity and mean signal kurtosis in its last axis gtab : a GradientTable class instance The gradient table for this prediction S0 : float or ndarray (optional) The non diffusion-weighted signal in every voxel, or across all voxels. Default: 1 Notes —– The predicted signal is given by: \(MS(b) = S_0 * exp(-bD + 1/6 b^{2} D^{2} K)\), where \(D\) and \(K\) are the mean signal diffusivity and mean signal kurtosis. References ———- .. [1] Henriques, R.N., 2018. Advanced Methods for Diffusion MRI Data Analysis and their Application to the Healthy Ageing Brain (Doctoral thesis). Downing College, University of Cambridge. https://doi.org/10.17863/CAM.29356

wls_fit_msdki

dipy.reconst.msdki.wls_fit_msdki(design_matrix, msignal, ng, mask=None, min_signal=0.0001, return_S0_hat=False)

Fits the mean signal diffusion kurtosis imaging based on a weighted least square solution [1]_.

Parameters

design_matrixarray (nub, 3)

Design matrix holding the covariants used to solve for the regression coefficients of the mean signal diffusion kurtosis model. Note that nub is the number of unique b-values

msignalndarray ([X, Y, Z, …, nub])

Mean signal along all gradient directions for each unique b-value Note that the last dimension should contain the signal means and nub is the number of unique b-values.

ngndarray(nub)

Number of gradient directions used to compute the mean signal for all unique b-values

maskarray

A boolean array used to mark the coordinates in the data that should be analyzed that has the shape data.shape[:-1]

min_signalfloat, optional

Voxel with mean signal intensities lower than the min positive signal are not processed. Default: 0.0001

return_S0_hatbool

If True, also return S0 values for the fit.

Returns

paramsarray (…, 2)

Containing the mean signal diffusivity and mean signal kurtosis

References

[1]

Henriques, R.N., 2018. Advanced Methods for Diffusion MRI Data Analysis and their Application to the Healthy Ageing Brain (Doctoral thesis). Downing College, University of Cambridge. https://doi.org/10.17863/CAM.29356

design_matrix

dipy.reconst.msdki.design_matrix(ubvals)

Constructs design matrix for the mean signal diffusion kurtosis model

Parameters

ubvalsarray

Containing the unique b-values of the data.

Returns

design_matrixarray (nb, 3)

Design matrix or B matrix for the mean signal diffusion kurtosis model assuming that parameters are in the following order: design_matrix[j, :] = (msd, msk, S0)

MultiVoxelFit

class dipy.reconst.multi_voxel.MultiVoxelFit(model, fit_array, mask)

Bases: ReconstFit

Holds an array of fits and allows access to their attributes and methods

__init__(model, fit_array, mask)

predict(*args, **kwargs)

Predict for the multi-voxel object using each single-object’s prediction API, with S0 provided from an array.

property shape

CallableArray

class dipy.reconst.multi_voxel.CallableArray

Bases: ndarray

An array which can be called like a function

__init__()

multi_voxel_fit

dipy.reconst.multi_voxel.multi_voxel_fit(single_voxel_fit)

Method decorator to turn a single voxel model fit definition into a multi voxel model fit definition

OdfModel

class dipy.reconst.odf.OdfModel(gtab)

Bases: ReconstModel

An abstract class to be sub-classed by specific odf models

All odf models should provide a fit method which may take data as it’s first and only argument.

__init__(gtab)

Initialization of the abstract class for signal reconstruction models

Parameters

gtab : GradientTable class instance

fit(data)

To be implemented by specific odf models

OdfFit

class dipy.reconst.odf.OdfFit(model, data)

Bases: ReconstFit

__init__(model, data)

odf(sphere)

To be implemented but specific odf models

gfa

dipy.reconst.odf.gfa(samples)

The general fractional anisotropy of a function evaluated on the unit sphere Parameters ———- samples : ndarray Values of data on the unit sphere. Returns ——- gfa : ndarray GFA evaluated in each entry of the array, along the last dimension. An np.nan is returned for coordinates that contain all-zeros in samples. Notes —– The GFA is defined as [1]_ :: sqrt{frac{n sum_i{(Psi_i - <Psi>)^2}}{(n-1) sum{Psi_i ^ 2}}} Where \(\Psi\) is an orientation distribution function sampled discretely on the unit sphere and angle brackets denote average over the samples on the sphere. .. [1] Quality assessment of High Angular Resolution Diffusion Imaging data using bootstrap on Q-ball reconstruction. J. Cohen Adad, M. Descoteaux, L.L. Wald. JMRI 33: 1194-1208.

minmax_normalize

dipy.reconst.odf.minmax_normalize(samples, out=None)

Min-max normalization of a function evaluated on the unit sphere

Normalizes samples to (samples - min(samples)) / (max(samples) - min(samples)) for each unit sphere.

Parameters

samplesndarray (…, N)

N samples on a unit sphere for each point, stored along the last axis of the array.

outndrray (…, N), optional

An array to store the normalized samples.

Returns

outndarray, (…, N)

Normalized samples.

QtdmriModel

class dipy.reconst.qtdmri.QtdmriModel(gtab, radial_order=6, time_order=2, laplacian_regularization=False, laplacian_weighting=0.2, l1_regularization=False, l1_weighting=0.1, cartesian=True, anisotropic_scaling=True, normalization=False, constrain_q0=True, bval_threshold=10000000000.0, eigenvalue_threshold=0.0001, cvxpy_solver='ECOS')

Bases: Cache

The q:math:tau-dMRI model [1] to analytically and continuously represent the q:math:tau diffusion signal attenuation over diffusion sensitization q and diffusion time \(\tau\). The model can be seen as an extension of the MAP-MRI basis [2] towards different diffusion times. The main idea is to model the diffusion signal over time and space as a linear combination of continuous functions, ..math:: :nowrap: begin{equation} hat{E}(textbf{q},tau;textbf{c}) = sum_i^{N_{textbf{q}}}sum_k^{N_tau} textbf{c}_{ik} ,Phi_i(textbf{q}),T_k(tau), end{equation} where \(\Phi\) and \(T\) are the spatial and temporal basis functions, \(N_{\textbf{q}}\) and \(N_\tau\) are the maximum spatial and temporal order, and \(i,k\) are basis order iterators. The estimation of the coefficients \(c_i\) can be regularized using either analytic Laplacian regularization, sparsity regularization using the l1-norm, or both to do a type of elastic net regularization. From the coefficients, there exists an analytical formula to estimate the ODF, RTOP, RTAP, RTPP, QIV and MSD, for any diffusion time. Parameters ———- gtab : GradientTable, gradient directions and bvalues container class. The bvalues should be in the normal s/mm^2. big_delta and small_delta need to given in seconds. radial_order : unsigned int, an even integer representing the spatial/radial order of the basis. time_order : unsigned int, an integer larger or equal than zero representing the time order of the basis. laplacian_regularization : bool, Regularize using the Laplacian of the qt-dMRI basis. laplacian_weighting: string or scalar, The string ‘GCV’ makes it use generalized cross-validation to find the regularization weight [3]. A scalar sets the regularization weight to that value. l1_regularization : bool, Regularize by imposing sparsity in the coefficients using the l1-norm. l1_weighting : ‘CV’ or scalar, The string ‘CV’ makes it use five-fold cross-validation to find the regularization weight. A scalar sets the regularization weight to that value. cartesian : bool Whether to use the Cartesian or spherical implementation of the qt-dMRI basis, which we first explored in [4]. anisotropic_scaling : bool Whether to use anisotropic scaling or isotropic scaling. This option can be used to test if the Cartesian implementation is equivalent with the spherical one when using the same scaling. normalization : bool Whether to normalize the basis functions such that their inner product is equal to one. Normalization is only necessary when imposing sparsity in the spherical basis if cartesian=False. constrain_q0 : bool whether to constrain the q0 point to unity along the tau-space. This is necessary to ensure that \(E(0,\tau)=1\). bval_threshold : float the threshold b-value to be used, such that only data points below that threshold are used when estimating the scale factors. eigenvalue_threshold : float, Sets the minimum of the tensor eigenvalues in order to avoid stability problem. cvxpy_solver : str, optional cvxpy solver name. Optionally optimize the positivity constraint with a particular cvxpy solver. See See https://www.cvxpy.org/ for details. Default: ECOS. References ———- .. [1] Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017. .. [2] Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013. .. [3] Craven et al. “Smoothing Noisy Data with Spline Functions.” NUMER MATH 31.4 (1978): 377-403. .. [4] Fick, Rutger HJ, et al. “A unifying framework for spatial and temporal diffusion in diffusion mri.” International Conference on Information Processing in Medical Imaging. Springer, Cham, 2015.

__init__(gtab, radial_order=6, time_order=2, laplacian_regularization=False, laplacian_weighting=0.2, l1_regularization=False, l1_weighting=0.1, cartesian=True, anisotropic_scaling=True, normalization=False, constrain_q0=True, bval_threshold=10000000000.0, eigenvalue_threshold=0.0001, cvxpy_solver='ECOS')

fit(data, mask=None)

Fit method for every voxel in data

QtdmriFit

class dipy.reconst.qtdmri.QtdmriFit(model, qtdmri_coef, us, ut, tau_scaling, R, lopt, alpha, cvxpy_solution_optimal)

Bases: object

__init__(model, qtdmri_coef, us, ut, tau_scaling, R, lopt, alpha, cvxpy_solution_optimal)

Calculates diffusion properties for a single voxel

Parameters

modelobject,

AnalyticalModel

qtdmri_coef1d ndarray,

qtdmri coefficients

usarray, 3 x 1

spatial scaling factors

utfloat

temporal scaling factor

tau_scalingfloat,

the temporal scaling that used to scale tau to the size of us

R3x3 numpy array,

tensor eigenvectors

loptfloat,

laplacian regularization weight

alphafloat,

the l1 regularization weight

cvxpy_solution_optimal: bool,

indicates whether the cvxpy coefficient estimation reach an optimal solution

fitted_signal(gtab=None)

Recovers the fitted signal for the given gradient table. If no gradient table is given it recovers the signal for the gtab of the model object.

msd(tau)

Calculates the analytical Mean Squared Displacement (MSD) for a given diffusion time tau. It is defined as the Laplacian of the origin of the estimated signal [1]_. The analytical formula for the MAP-MRI basis was derived in [2]_ eq. (C13, D1). The qtdmri coefficients are first converted to mapmri coefficients following [3].

Parameters

taufloat

diffusion time (big_delta - small_delta / 3.) in seconds

References

[1]

Cheng, J., 2014. Estimation and Processing of Ensemble Average Propagator and Its Features in Diffusion MRI. Ph.D. Thesis.

[3]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

norm_of_laplacian_signal()

Calculates the norm of the laplacian of the fitted signal [1]_. This information could be useful to assess if the extrapolation of the fitted signal contains spurious oscillations. A high laplacian norm may indicate that these are present, and any q-space indices that use integrals of the signal may be corrupted (e.g. RTOP, RTAP, RTPP, QIV). In contrast to [1], the Laplacian now describes oscillations in the 4-dimensional qt-signal [2].

References

[2]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

odf(sphere, tau, s=2)

Calculates the analytical Orientation Distribution Function (ODF) for a given diffusion time tau from the signal, [1]_ Eq. (32). The qtdmri coefficients are first converted to mapmri coefficients following [2].

Parameters

spheredipy sphere object

sphere object with vertice orientations to compute the ODF on.

taufloat

diffusion time (big_delta - small_delta / 3.) in seconds

sunsigned int

radial moment of the ODF

References

[1]

Ozarslan E. et. al, “Mean apparent propagator (MAP) MRI: A novel diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[2]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

odf_sh(tau, s=2)

Calculates the real analytical odf for a given discrete sphere. Computes the design matrix of the ODF for the given sphere vertices and radial moment [1]_ eq. (32). The radial moment s acts as a sharpening method. The analytical equation for the spherical ODF basis is given in [2]_ eq. (C8). The qtdmri coefficients are first converted to mapmri coefficients following [3].

Parameters

taufloat

diffusion time (big_delta - small_delta / 3.) in seconds

sunsigned int

radial moment of the ODF

References

[1]

Ozarslan E. et. al, “Mean apparent propagator (MAP) MRI: A novel diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[3]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

pdf(rt_points)

Diffusion propagator on a given set of real points. if the array r_points is non writeable, then intermediate results are cached for faster recalculation

predict(qvals_or_gtab, S0=1.0)

Recovers the reconstructed signal for any qvalue array or gradient table.

qiv(tau)

Calculates the analytical Q-space Inverse Variance (QIV) for given diffusion time tau. It is defined as the inverse of the Laplacian of the origin of the estimated propagator [1]_ eq. (22). The analytical formula for the MAP-MRI basis was derived in [2]_ eq. (C14, D2). The qtdmri coefficients are first converted to mapmri coefficients following [3].

Parameters

taufloat

diffusion time (big_delta - small_delta / 3.) in seconds

References

[1]

Hosseinbor et al. “Bessel fourier orientation reconstruction (bfor): An analytical diffusion propagator reconstruction for hybrid diffusion imaging and computation of q-space indices. NeuroImage 64, 2013, 650–670.

[3]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

qtdmri_to_mapmri_coef(tau)

This function converts the qtdmri coefficients to mapmri coefficients for a given tau [1]_. The conversion is performed by a matrix multiplication that evaluates the time-depenent part of the basis and multiplies it with the coefficients, after which coefficients with the same spatial orders are summed up, resulting in mapmri coefficients.

Parameters

taufloat

diffusion time (big_delta - small_delta / 3.) in seconds

References

[1]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

rtap(tau)

Calculates the analytical return to the axis probability (RTAP) for a given diffusion time tau, [1]_ eq. (40, 44a). The analytical formula for the isotropic MAP-MRI basis was derived in [2]_ eq. (C11). The qtdmri coefficients are first converted to mapmri coefficients following [3].

Parameters

taufloat

diffusion time (big_delta - small_delta / 3.) in seconds

References

[1]

Ozarslan E. et. al, “Mean apparent propagator (MAP) MRI: A novel diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[3]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

rtop(tau)

Calculates the analytical return to the origin probability (RTOP) for a given diffusion time tau [1]_ eq. (36, 43). The analytical formula for the isotropic MAP-MRI basis was derived in [2]_ eq. (C11). The qtdmri coefficients are first converted to mapmri coefficients following [3].

Parameters

taufloat

diffusion time (big_delta - small_delta / 3.) in seconds

References

[1]

Ozarslan E. et. al, “Mean apparent propagator (MAP) MRI: A novel diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[3]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

rtpp(tau)

Calculates the analytical return to the plane probability (RTPP) for a given diffusion time tau, [1]_ eq. (42). The analytical formula for the isotropic MAP-MRI basis was derived in [2]_ eq. (C11). The qtdmri coefficients are first converted to mapmri coefficients following [3].

Parameters

taufloat

diffusion time (big_delta - small_delta / 3.) in seconds

References

[1]

Ozarslan E. et. al, “Mean apparent propagator (MAP) MRI: A novel diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

[3]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

sparsity_abs(threshold=0.99)

As a measure of sparsity, calculates the number of largest coefficients needed to absolute sum up to 99% of the total absolute sum of all coefficients

sparsity_density(threshold=0.99)

As a measure of sparsity, calculates the number of largest coefficients needed to squared sum up to 99% of the total squared sum of all coefficients

qtdmri_to_mapmri_matrix

dipy.reconst.qtdmri.qtdmri_to_mapmri_matrix(radial_order, time_order, ut, tau)

Generate the matrix that maps the qtdmri coefficients to MAP-MRI coefficients for the anisotropic case. The conversion is done by only evaluating the time basis for a diffusion time tau and summing up coefficients with the same spatial basis orders [1].

Parameters

radial_orderunsigned int,

an even integer representing the spatial/radial order of the basis.

time_orderunsigned int,

an integer larger or equal than zero representing the time order of the basis.

utfloat

temporal scaling factor

taufloat

diffusion time (big_delta - small_delta / 3.) in seconds

References

[1]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

qtdmri_isotropic_to_mapmri_matrix

dipy.reconst.qtdmri.qtdmri_isotropic_to_mapmri_matrix(radial_order, time_order, ut, tau)

Generate the matrix that maps the spherical qtdmri coefficients to MAP-MRI coefficients for the isotropic case. The conversion is done by only evaluating the time basis for a diffusion time tau and summing up coefficients with the same spatial basis orders [1].

Parameters

radial_orderunsigned int,

an even integer representing the spatial/radial order of the basis.

time_orderunsigned int,

an integer larger or equal than zero representing the time order of the basis.

utfloat

temporal scaling factor

taufloat

diffusion time (big_delta - small_delta / 3.) in seconds

References

[1]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

qtdmri_temporal_normalization

dipy.reconst.qtdmri.qtdmri_temporal_normalization(ut)

Normalization factor for the temporal basis

qtdmri_mapmri_normalization

dipy.reconst.qtdmri.qtdmri_mapmri_normalization(mu)

Normalization factor for Cartesian MAP-MRI basis. The scaling is the same for every basis function depending only on the spatial scaling mu.

qtdmri_mapmri_isotropic_normalization

dipy.reconst.qtdmri.qtdmri_mapmri_isotropic_normalization(j, l, u0)

Normalization factor for Spherical MAP-MRI basis. The normalization for a basis function with orders [j,l,m] depends only on orders j,l and the isotropic scale factor.

qtdmri_signal_matrix_

dipy.reconst.qtdmri.qtdmri_signal_matrix_(radial_order, time_order, us, ut, q, tau, normalization=False)

Function to generate the qtdmri signal basis.

qtdmri_signal_matrix

dipy.reconst.qtdmri.qtdmri_signal_matrix(radial_order, time_order, us, ut, q, tau)

Constructs the design matrix as a product of 3 separated radial, angular and temporal design matrices. It precomputes the relevant basis orders for each one and finally puts them together according to the index matrix

qtdmri_eap_matrix

dipy.reconst.qtdmri.qtdmri_eap_matrix(radial_order, time_order, us, ut, grid)

Constructs the design matrix as a product of 3 separated radial, angular and temporal design matrices. It precomputes the relevant basis orders for each one and finally puts them together according to the index matrix

qtdmri_isotropic_signal_matrix_

dipy.reconst.qtdmri.qtdmri_isotropic_signal_matrix_(radial_order, time_order, us, ut, q, tau, normalization=False)

qtdmri_isotropic_signal_matrix

dipy.reconst.qtdmri.qtdmri_isotropic_signal_matrix(radial_order, time_order, us, ut, q, tau)

qtdmri_eap_matrix_

dipy.reconst.qtdmri.qtdmri_eap_matrix_(radial_order, time_order, us, ut, grid, normalization=False)

qtdmri_isotropic_eap_matrix_

dipy.reconst.qtdmri.qtdmri_isotropic_eap_matrix_(radial_order, time_order, us, ut, grid, normalization=False)

qtdmri_isotropic_eap_matrix

dipy.reconst.qtdmri.qtdmri_isotropic_eap_matrix(radial_order, time_order, us, ut, grid)

Constructs the design matrix as a product of 3 separated radial, angular and temporal design matrices. It precomputes the relevant basis orders for each one and finally puts them together according to the index matrix

radial_basis_opt

dipy.reconst.qtdmri.radial_basis_opt(j, l, us, q)

Spatial basis dependent on spatial scaling factor us

angular_basis_opt

dipy.reconst.qtdmri.angular_basis_opt(l, m, q, theta, phi)

Angular basis independent of spatial scaling factor us. Though it includes q, it is independent of the data and can be precomputed.

radial_basis_EAP_opt

dipy.reconst.qtdmri.radial_basis_EAP_opt(j, l, us, r)

angular_basis_EAP_opt

dipy.reconst.qtdmri.angular_basis_EAP_opt(j, l, m, r, theta, phi)

temporal_basis

dipy.reconst.qtdmri.temporal_basis(o, ut, tau)

Temporal basis dependent on temporal scaling factor ut

qtdmri_index_matrix

dipy.reconst.qtdmri.qtdmri_index_matrix(radial_order, time_order)

Computes the SHORE basis order indices according to [1].

qtdmri_isotropic_index_matrix

dipy.reconst.qtdmri.qtdmri_isotropic_index_matrix(radial_order, time_order)

Computes the SHORE basis order indices according to [1].

qtdmri_laplacian_reg_matrix

dipy.reconst.qtdmri.qtdmri_laplacian_reg_matrix(ind_mat, us, ut, S_mat=None, T_mat=None, U_mat=None, part1_ut_precomp=None, part23_ut_precomp=None, part4_ut_precomp=None, normalization=False)

Computes the cartesian qt-dMRI Laplacian regularization matrix. If given, uses precomputed matrices for temporal and spatial regularization matrices to speed up computation. Follows the the formulation of Appendix B in [1].

References

[1]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

qtdmri_isotropic_laplacian_reg_matrix

dipy.reconst.qtdmri.qtdmri_isotropic_laplacian_reg_matrix(ind_mat, us, ut, part1_uq_iso_precomp=None, part1_ut_precomp=None, part23_ut_precomp=None, part4_ut_precomp=None, normalization=False)

Computes the spherical qt-dMRI Laplacian regularization matrix. If given, uses precomputed matrices for temporal and spatial regularization matrices to speed up computation. Follows the the formulation of Appendix C in [1].

References

[1]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

part23_reg_matrix_q

dipy.reconst.qtdmri.part23_reg_matrix_q(ind_mat, U_mat, T_mat, us)

Partial cartesian spatial Laplacian regularization matrix following second line of Eq. (B2) in [1].

References

[1]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

part23_iso_reg_matrix_q

dipy.reconst.qtdmri.part23_iso_reg_matrix_q(ind_mat, us)

Partial spherical spatial Laplacian regularization matrix following the equation below Eq. (C4) in [1].

References

[1]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

part4_reg_matrix_q

dipy.reconst.qtdmri.part4_reg_matrix_q(ind_mat, U_mat, us)

Partial cartesian spatial Laplacian regularization matrix following equation Eq. (B2) in [1].

References

[1]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

part4_iso_reg_matrix_q

dipy.reconst.qtdmri.part4_iso_reg_matrix_q(ind_mat, us)

Partial spherical spatial Laplacian regularization matrix following the equation below Eq. (C4) in [1].

References

[1]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

part1_reg_matrix_tau

dipy.reconst.qtdmri.part1_reg_matrix_tau(ind_mat, ut)

Partial temporal Laplacian regularization matrix following Appendix B in [1].

References

[1]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

part23_reg_matrix_tau

dipy.reconst.qtdmri.part23_reg_matrix_tau(ind_mat, ut)

Partial temporal Laplacian regularization matrix following Appendix B in [1].

References

[1]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

part4_reg_matrix_tau

dipy.reconst.qtdmri.part4_reg_matrix_tau(ind_mat, ut)

Partial temporal Laplacian regularization matrix following Appendix B in [1].

References

[1]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

H

dipy.reconst.qtdmri.H(value)

Step function of H(x)=1 if x>=0 and zero otherwise. Used for the temporal laplacian matrix.

generalized_crossvalidation

dipy.reconst.qtdmri.generalized_crossvalidation(data, M, LR, startpoint=0.0005)

Generalized Cross Validation Function [1].

References

[1]

Craven et al. “Smoothing Noisy Data with Spline Functions.” NUMER MATH 31.4 (1978): 377-403.

GCV_cost_function

dipy.reconst.qtdmri.GCV_cost_function(weight, arguments)

Generalized Cross Validation Function that is iterated [1].

References

[1]

Craven et al. “Smoothing Noisy Data with Spline Functions.” NUMER MATH 31.4 (1978): 377-403.

qtdmri_isotropic_scaling

dipy.reconst.qtdmri.qtdmri_isotropic_scaling(data, q, tau)

Constructs design matrix for fitting an exponential to the diffusion time points.

qtdmri_anisotropic_scaling

dipy.reconst.qtdmri.qtdmri_anisotropic_scaling(data, q, bvecs, tau)

Constructs design matrix for fitting an exponential to the diffusion time points.

design_matrix_spatial

dipy.reconst.qtdmri.design_matrix_spatial(bvecs, qvals)

Constructs design matrix for DTI weighted least squares or least squares fitting. (Basser et al., 1994a)

Parameters

bvecsarray (N x 3)

unit b-vectors of the acquisition.

qvalsarray (N,)

corresponding q-values in 1/mm

Returns

design_matrixarray (g,7)

Design matrix or B matrix assuming Gaussian distributed tensor model design_matrix[j, :] = (Bxx, Byy, Bzz, Bxy, Bxz, Byz, dummy)

create_rt_space_grid

dipy.reconst.qtdmri.create_rt_space_grid(grid_size_r, max_radius_r, grid_size_tau, min_radius_tau, max_radius_tau)

Generates EAP grid (for potential positivity constraint).

qtdmri_number_of_coefficients

dipy.reconst.qtdmri.qtdmri_number_of_coefficients(radial_order, time_order)

Computes the total number of coefficients of the qtdmri basis given a radial and temporal order. Equation given below Eq (9) in [1].

References

[1]

Fick, Rutger HJ, et al. “Non-Parametric GraphNet-Regularized Representation of dMRI in Space and Time”, Medical Image Analysis, 2017.

l1_crossvalidation

dipy.reconst.qtdmri.l1_crossvalidation(b0s_mask, E, M, weight_array=array([0., 0.02, 0.04, 0.06, 0.08, 0.1, 0.12, 0.14, 0.16, 0.18, 0.2, 0.22, 0.24, 0.26, 0.28, 0.3, 0.32, 0.34, 0.36, 0.38, 0.4]))

cross-validation function to find the optimal weight of alpha for sparsity regularization

elastic_crossvalidation

dipy.reconst.qtdmri.elastic_crossvalidation(b0s_mask, E, M, L, lopt, weight_array=array([0., 0.01, 0.02, 0.03, 0.04, 0.05, 0.06, 0.07, 0.08, 0.09, 0.1, 0.11, 0.12, 0.13, 0.14, 0.15, 0.16, 0.17, 0.18, 0.19, 0.2]))

cross-validation function to find the optimal weight of alpha for sparsity regularization when also Laplacian regularization is used.

visualise_gradient_table_G_Delta_rainbow

dipy.reconst.qtdmri.visualise_gradient_table_G_Delta_rainbow(gtab, big_delta_start=None, big_delta_end=None, G_start=None, G_end=None, bval_isolines=array([0, 250, 1000, 2500, 5000, 7500, 10000, 14000]), alpha_shading=0.6)

This function visualizes a q-tau acquisition scheme as a function of gradient strength and pulse separation (big_delta). It represents every measurements at its G and big_delta position regardless of b-vector, with a background of b-value isolines for reference. It assumes there is only one unique pulse length (small_delta) in the acquisition scheme.

Parameters

gtabGradientTable object

constructed gradient table with big_delta and small_delta given as inputs.

big_delta_startfloat,

optional minimum big_delta that is plotted in seconds

big_delta_endfloat,

optional maximum big_delta that is plotted in seconds

G_startfloat,

optional minimum gradient strength that is plotted in T/m

G_endfloat,

optional maximum gradient strength that is plotted in T/m

bval_isolinesarray,

optional array of bvalue isolines that are plotted in the background

alpha_shadingfloat between [0-1]

optional shading of the bvalue colors in the background

QtiModel

class dipy.reconst.qti.QtiModel(gtab, fit_method='WLS', cvxpy_solver='SCS')

Bases: ReconstModel

__init__(gtab, fit_method='WLS', cvxpy_solver='SCS')

Covariance tensor model of q-space trajectory imaging [1]_.

Parameters

gtabdipy.core.gradients.GradientTable

Gradient table with b-tensors.

fit_methodstr, optional

Must be one of the following:

‘OLS’ for ordinary least squares

qti._ols_fit()

‘WLS’ for weighted least squares

qti._wls_fit()

‘SDPDc’ for semidefinite programming with positivity

constraints applied [2]_

qti._sdpdc_fit()

cvxpy_solver: str, optionals

solver for the SDP formulation. default: ‘SCS’

References

[1]

Westin, Carl-Fredrik, et al. “Q-space trajectory imaging for multidimensional diffusion MRI of the human brain.” Neuroimage 135 (2016): 345-362. https://doi.org/10.1016/j.neuroimage.2016.02.039.

[2]

Herberthson M., Boito D., Dela Haije T., Feragen A., Westin CF., Ozarslan E., “Q-space trajectory imaging with positivity constraints (QTI+)” in Neuroimage, Volume 238, 2021.

fit(data, mask=None)

Fit QTI to data.

Parameters

datanumpy.ndarray

Array of shape (…, number of acquisitions).

masknumpy.ndarray, optional

Array with the same shape as the data array of a single acquisition.

Returns

qtifitdipy.reconst.qti.QtiFit

The fitted model.

predict(params)

Generate signals from this model class instance and given parameters.

Parameters

paramsnumpy.ndarray

Array of shape (…, 28) containing the model parameters. Element 0 is the natural logarithm of the signal without diffusion-weighting, elements 1-6 are the diffusion tensor elements in Voigt notation, and elements 7-27 are the covariance tensor elements in Voigt notation.

Returns

Snumpy.ndarray

Signals.

QtiFit

class dipy.reconst.qti.QtiFit(params)

Bases: object

__init__(params)

Fitted QTI model.

Parameters

paramsnumpy.ndarray

Array of shape (…, 28) containing the model parameters. Element 0 is the natural logarithm of the signal without diffusion-weighting, elements 1-6 are the diffusion tensor elements in Voigt notation, and elements 7-27 are the covariance tensor elements in Voigt notation.

S0_hat()

Estimated signal without diffusion-weighting.

Returns

S0 : numpy.ndarray

c_c()

Microscopic orientation coherence.

c_c : numpy.ndarray

Microscopic orientation coherence is calculated as

\[C_c = \]

rac{C_ ext{M}}{C_mu}

c_m()

Normalized macroscopic anisotropy.

c_m : numpy.ndarray

Normalized macroscopic anisotropy is calculated as

\[C_ ext{M} = \]

rac{3}{2} rac{langle mathbf{D} angle

otimes langle mathbf{D}

anglemathbb{E}_ ext{shear}}

{langle mathbf{D}

angle otimes langle mathbf{D} angle :

mathbb{E}_ ext{iso}}

c_md()

Normalized variance of mean diffusivities.

c_md : numpy.ndarray

Normalized variance of microscopic mean diffusivities is calculated as

\[C_ ext{MD} = \]

rac{mathbb{C}mathbb{E}_ ext{bulk}}

{langle mathbf{D} otimes mathbf{D}

angle :

mathbb{E}_ ext{bulk}}

c_mu()

Normalized microscopic anisotropy.

c_mu : numpy.ndarray

Normalized microscopic anisotropy is calculated as

\[C_\mu = \]

rac{3}{2} rac{langle mathbf{D} otimes mathbf{D}

anglemathbb{E}_ ext{shear}}{langle mathbf{D} otimes

mathbf{D}

angle : mathbb{E}_ ext{iso}}

d_sq()

Diffusion tensor’s outer product with itself.

Returns

d_sq : numpy.ndarray

fa()

Fractional anisotropy.

Returns

fa : numpy.ndarray

Notes

Fractional anisotropy is calculated as

\[ext{FA} = \sqrt{C_ ext{M}}\]

k_bulk()

Bulk kurtosis.

k_bulk : numpy.ndarray

Bulk kurtosis is calculated as

\[K_ ext{bulk} = 3 \]

rac{mathbb{C}mathbb{E}_ ext{bulk}}

{langle mathbf{D}

angle otimes langle mathbf{D} angle :

mathbb{E}_ ext{bulk}}

k_mu()

Microscopic kurtosis.

k_mu : numpy.ndarray

Microscopic kurtosis is calculated as

\[K_\mu = \]

rac{6}{5} rac{langle mathbf{D} otimes mathbf{D}

angle : mathbb{E}_ ext{shear}}{langle mathbf{D} angle

otimes langle mathbf{D}

angle : mathbb{E}_ ext{bulk}}

k_shear()

Shear kurtosis.

k_shear : numpy.ndarray

Shear kurtosis is calculated as

\[K_ ext{shear} = \]

rac{6}{5} rac{mathbb{C} :

mathbb{E}_ ext{shear}}{langle mathbf{D}

angle otimes

langle mathbf{D}

angle : mathbb{E}_ ext{bulk}}

md()

Mean diffusivity.

md : numpy.ndarray

Mean diffusivity is calculated as

\[ext{MD} = \langle \mathbf{D} \]

angle : mathbf{E}_ ext{iso}

mean_d_sq()

Average of microscopic diffusion tensors’ outer products with

themselves.

mean_d_sq : numpy.ndarray

Average of microscopic diffusion tensors’ outer products with themselves is calculated as

\[\langle \mathbf{D} \otimes \mathbf{D} \]

angle = mathbb{C} +

langle mathbf{D}

angle otimes langle mathbf{D} angle

mk()

Mean kurtosis.

Returns

mk : numpy.ndarray

Notes

Mean kurtosis is calculated as

\[ext{MK} = K_ ext{bulk} + K_ ext{shear}\]

predict(gtab)

Generate signals from this model fit and a given gradient table.

Parameters

gtabdipy.core.gradients.GradientTable

Gradient table with b-tensors.

Returns

Snumpy.ndarray

Signals.

ufa()

Microscopic fractional anisotropy.

Returns

ufa : numpy.ndarray

Notes

Microscopic fractional anisotropy is calculated as

\[\mu ext{FA} = \sqrt{C_\mu}\]

v_iso()

Total isotropic variance.

Returns

v_iso : numpy.ndarray

Notes

Total isotropic variance is calculated as

\[V_ ext{iso} = \mathbb{C} : \mathbb{E}_ ext{iso}\]

v_md()

Variance of microscopic mean diffusivities.

Returns

v_md : numpy.ndarray

Notes

Variance of microscopic mean diffusivities is calculated as

\[V_ ext{MD} = \mathbb{C} : \mathbb{E}_ ext{bulk}\]

v_shear()

Shear variance.

Returns

v_shear : numpy.ndarray

Notes

Shear variance is calculated as

\[V_ ext{shear} = \mathbb{C} : \mathbb{E}_ ext{shear}\]

from_3x3_to_6x1

dipy.reconst.qti.from_3x3_to_6x1(T)

Convert symmetric 3 x 3 matrices into 6 x 1 vectors.

Parameters

Tnumpy.ndarray

An array of size (…, 3, 3).

Returns

Vnumpy.ndarray

Converted vectors of size (…, 6, 1).

Notes

The conversion of a matrix into a vector is defined as

\[\mathbf{V} = egin{bmatrix} T_{11} & T_{22} & T_{33} & \sqrt{2} T_{23} & \sqrt{2} T_{13} & \sqrt{2} T_{12} \end{bmatrix}^T\]

from_6x1_to_3x3

dipy.reconst.qti.from_6x1_to_3x3(V)

Convert 6 x 1 vectors into symmetric 3 x 3 matrices.

Parameters

Vnumpy.ndarray

An array of size (…, 6, 1).

Returns

Tnumpy.ndarray

Converted matrices of size (…, 3, 3).

Notes

The conversion of a matrix into a vector is defined as

\[\mathbf{V} = egin{bmatrix} T_{11} & T_{22} & T_{33} & \sqrt{2} T_{23} & \sqrt{2} T_{13} & \sqrt{2} T_{12} \end{bmatrix}^T\]

from_6x6_to_21x1

dipy.reconst.qti.from_6x6_to_21x1(T)

Convert symmetric 6 x 6 matrices into 21 x 1 vectors.

Parameters

Tnumpy.ndarray

An array of size (…, 6, 6).

Returns

Vnumpy.ndarray

Converted vectors of size (…, 21, 1).

Notes

The conversion of a matrix into a vector is defined as

\[egin{matrix} \mathbf{V} = & ig[ T_{11} & T_{22} & T_{33} \ & \sqrt{2} T_{23} & \sqrt{2} T_{13} & \sqrt{2} T_{12} \ & \sqrt{2} T_{14} & \sqrt{2} T_{15} & \sqrt{2} T_{16} \ & \sqrt{2} T_{24} & \sqrt{2} T_{25} & \sqrt{2} T_{26} \ & \sqrt{2} T_{34} & \sqrt{2} T_{35} & \sqrt{2} T_{36} \ & T_{44} & T_{55} & T_{66} \ & \sqrt{2} T_{45} & \sqrt{2} T_{56} & \sqrt{2} T_{46} ig]^T \end{matrix}\]

from_21x1_to_6x6

dipy.reconst.qti.from_21x1_to_6x6(V)

Convert 21 x 1 vectors into symmetric 6 x 6 matrices.

Parameters

Vnumpy.ndarray

An array of size (…, 21, 1).

Returns

Tnumpy.ndarray

Converted matrices of size (…, 6, 6).

Notes

The conversion of a matrix into a vector is defined as

\[egin{matrix} \mathbf{V} = & ig[ T_{11} & T_{22} & T_{33} \ & \sqrt{2} T_{23} & \sqrt{2} T_{13} & \sqrt{2} T_{12} \ & \sqrt{2} T_{14} & \sqrt{2} T_{15} & \sqrt{2} T_{16} \ & \sqrt{2} T_{24} & \sqrt{2} T_{25} & \sqrt{2} T_{26} \ & \sqrt{2} T_{34} & \sqrt{2} T_{35} & \sqrt{2} T_{36} \ & T_{44} & T_{55} & T_{66} \ & \sqrt{2} T_{45} & \sqrt{2} T_{56} & \sqrt{2} T_{46} ig]^T \end{matrix}\]

cvxpy_1x6_to_3x3

dipy.reconst.qti.cvxpy_1x6_to_3x3(V)

Convert a 1 x 6 vector into a symmetric 3 x 3 matrix.

Parameters

Vnumpy.ndarray

An array of size (1, 6).

Returns

Tcvxpy.bmat

Converted matrix of size (3, 3).

Notes

The conversion of a matrix into a vector is defined as

\[\mathbf{V} = egin{bmatrix} T_{11} & T_{22} & T_{33} & \sqrt{2} T_{23} & \sqrt{2} T_{13} & \sqrt{2} T_{12} \end{bmatrix}^T\]

cvxpy_1x21_to_6x6

dipy.reconst.qti.cvxpy_1x21_to_6x6(V)

Convert 1 x 21 vector into a symmetric 6 x 6 matrix.

Parameters

Vnumpy.ndarray

An array of size (1, 21).

Returns

Tcvxpy.bmat

Converted matrices of size (6, 6).

Notes

The conversion of a matrix into a vector is defined as

\[egin{matrix} \mathbf{V} = & ig[ T_{11} & T_{22} & T_{33} \ & \sqrt{2} T_{23} & \sqrt{2} T_{13} & \sqrt{2} T_{12} \ & \sqrt{2} T_{14} & \sqrt{2} T_{15} & \sqrt{2} T_{16} \ & \sqrt{2} T_{24} & \sqrt{2} T_{25} & \sqrt{2} T_{26} \ & \sqrt{2} T_{34} & \sqrt{2} T_{35} & \sqrt{2} T_{36} \ & T_{44} & T_{55} & T_{66} \ & \sqrt{2} T_{45} & \sqrt{2} T_{56} & \sqrt{2} T_{46} ig]^T \end{matrix}\]

dtd_covariance

dipy.reconst.qti.dtd_covariance(DTD)

Calculate covariance of a diffusion tensor distribution (DTD).

DTDnumpy.ndarray

Diffusion tensor distribution of shape (number of tensors, 3, 3) or (number of tensors, 6, 1).

Cnumpy.ndarray

Covariance tensor of shape (6, 6).

The covariance tensor is calculated according to the following equation and converted into a rank-2 tensor [1]_:

\[\mathbb{C} = \langle \mathbf{D} \otimes \mathbf{D} \]

angle -

langle mathbf{D}

angle otimes langle mathbf{D} angle

[1]

Westin, Carl-Fredrik, et al. “Q-space trajectory imaging for multidimensional diffusion MRI of the human brain.” Neuroimage 135 (2016): 345-362. https://doi.org/10.1016/j.neuroimage.2016.02.039.

qti_signal

dipy.reconst.qti.qti_signal(gtab, D, C, S0=1)

Generate signals using the covariance tensor signal representation.

gtabdipy.core.gradients.GradientTable

Gradient table with b-tensors.

Dnumpy.ndarray

Diffusion tensors of shape (…, 3, 3), (…, 6, 1), or (…, 6).

Cnumpy.ndarray

Covariance tensors of shape (…, 6, 6), (…, 21, 1), or (…, 21).

S0numpy.ndarray, optional

Signal magnitudes without diffusion-weighting. Must be a single number or an array of same shape as D and C without the last two dimensions.

Snumpy.ndarray

Simulated signals.

The signal is generated according to

\[S = S_0 \exp \left(- \mathbf{b} : \langle \mathbf{D} \]

angle

rac{1}{2}(mathbf{b} otimes mathbf{b}) : mathbb{C} ight)

design_matrix

dipy.reconst.qti.design_matrix(btens)

Calculate the design matrix from the b-tensors.

btensnumpy.ndarray

An array of b-tensors of shape (number of acquisitions, 3, 3).

Xnumpy.ndarray

Design matrix.

The design matrix is generated according to

\[X = egin{pmatrix} 1 & -\mathbf{b}_1^T & \]

rac{1}{2}(mathbf{b}_1

otimesmathbf{b}_1)^T

dots & dots & dots 1 &

-mathbf{b}_n^T &

rac{1}{2}(mathbf{b}_notimesmathbf{b}_n)^T

end{pmatrix}

quick_squash

dipy.reconst.quick_squash.quick_squash(obj_arr, mask=None, fill=0)

Try and make a standard array from an object array

This function takes an object array and attempts to convert it to a more useful dtype. If array can be converted to a better dtype, Nones are replaced by fill. To make the behaviour of this function more clear, here are the most common cases:

1. obj_arr is an array of scalars of type T. Returns an array like obj_arr.astype(T)

2. obj_arr is an array of arrays. All items in obj_arr have the same shape S. Returns an array with shape obj_arr.shape + S

3. obj_arr is an array of arrays of different shapes. Returns obj_arr.

4. Items in obj_arr are not ndarrays or scalars. Returns obj_arr.

Parameters

obj_arrarray, dtype=object

The array to be converted.

maskarray, dtype=bool, optional

mask is nonzero where obj_arr has Nones.

fillnumber, optional

Nones are replaced by fill.

Returns

result : array

Examples

>>> arr = np.empty(3, dtype=object)
>>> arr.fill(2)
>>> quick_squash(arr)
array([2, 2, 2])
>>> arr[0] = None
>>> quick_squash(arr)
array([0, 2, 2])
>>> arr.fill(np.ones(2))
>>> r = quick_squash(arr)
>>> r.shape
(3, 2)
>>> r.dtype
dtype('float64')

reduce

dipy.reconst.quick_squash.reduce(function, iterable[, initial]) → value

Apply a function of two arguments cumulatively to the items of a sequence or iterable, from left to right, so as to reduce the iterable to a single value. For example, reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) calculates ((((1+2)+3)+4)+5). If initial is present, it is placed before the items of the iterable in the calculation, and serves as a default when the iterable is empty.

adj_to_countarrs

dipy.reconst.recspeed.adj_to_countarrs(adj_inds)

Convert adjacency sequence to counts and flattened indices

We use this to provide expected input to argmax_from_countarrs

Parameters

adj_indicessequence

length V sequence of sequences, where sequence i contains the neighbors of a particular vertex.

Returns

counts(V,) array

Number of neighbors for each vertex

adj_inds(n,) array

flat array containing adj_indices unrolled as a vector

argmax_from_adj

dipy.reconst.recspeed.argmax_from_adj(vals, vertex_inds, adj_inds)

Indices of local maxima from vals given adjacent points

Parameters

vals(N,) array, dtype np.float64

values at all vertices referred to in either of vertex_inds or adj_inds’

vertex_inds(V,) array

indices into vals giving vertices that may be local maxima.

adj_indssequence

For every vertex in vertex_inds, the indices (into vals) of the neighboring points

Returns

inds(M,) array

Indices into vals giving local maxima of vals, given topology from adj_inds, and restrictions from vertex_inds. Inds are returned sorted by value at that index - i.e. smallest value (at index) first.

argmax_from_countarrs

dipy.reconst.recspeed.argmax_from_countarrs(vals, vertinds, adj_counts, adj_inds)

Indices of local maxima from vals from count, array neighbors

Parameters

vals(N,) array, dtype float

values at all vertices referred to in either of vertex_inds or adj_inds’

vertinds(V,) array, dtype uint32

indices into vals giving vertices that may be local maxima.

adj_counts(V,) array, dtype uint32

For every vertex i in vertex_inds, the number of neighbors for vertex i

adj_inds(P,) array, dtype uint32

Indices for neighbors for each point. P=sum(adj_counts)

Returns

inds(M,) array

Indices into vals giving local maxima of vals, given topology from adj_counts and adj_inds, and restrictions from vertex_inds. Inds are returned sorted by value at that index - i.e. smallest value (at index) first.

le_to_odf

dipy.reconst.recspeed.le_to_odf(odf, LEs, radius, odfn, radiusn, anglesn)

odf for interpolated Laplacian normalized signal

local_maxima

dipy.reconst.recspeed.local_maxima(odf, edges)

Local maxima of a function evaluated on a discrete set of points.

If a function is evaluated on some set of points where each pair of neighboring points is an edge in edges, find the local maxima.

Parameters

odfarray, 1d, dtype=double

The function evaluated on a set of discrete points.

edgesarray (N, 2)

The set of neighbor relations between the points. Every edge, ie edges[i, :], is a pair of neighboring points.

Returns

peak_valuesndarray

Value of odf at a maximum point. Peak values is sorted in descending order.

peak_indicesndarray

Indices of maximum points. Sorted in the same order as peak_values so odf[peak_indices[i]] == peak_values[i].

Notes

A point is a local maximum if it is > at least one neighbor and >= all neighbors. If no points meet the above criteria, 1 maximum is returned such that odf[maximum] == max(odf).

See Also

dipy.core.sphere

proc_reco_args

dipy.reconst.recspeed.proc_reco_args(vals, vertinds)

remove_similar_vertices

dipy.reconst.recspeed.remove_similar_vertices(vertices, theta, return_mapping=False, return_index=False, remove_antipodal=True)

Remove vertices that are less than theta degrees from any other Returns vertices that are at least theta degrees from any other vertex. Vertex v and -v are considered the same so if v and -v are both in vertices only one is kept. Also if v and w are both in vertices, w must be separated by theta degrees from both v and -v to be unique. To disable this, set remove_antipodal to False to keep both directions. Parameters ———- vertices : (N, 3) ndarray N unit vectors. theta : float The minimum separation between vertices in degrees. return_mapping : {False, True}, optional If True, return mapping as well as vertices and maybe indices (see below). return_indices : {False, True}, optional If True, return indices as well as vertices and maybe mapping (see below). remove_antipodal : {False, True}, optional If True, v and -v are considered equal, and only one will be kept. Returns ——- unique_vertices : (M, 3) ndarray Vertices sufficiently separated from one another. mapping : (N,) ndarray For each element vertices[i] (\(i \in 0..N-1\)), the index \(j\) to a vertex in unique_vertices that is less than theta degrees from vertices[i]. Only returned if return_mapping is True. indices : (N,) ndarray indices gives the reverse of mapping. For each element unique_vertices[j] (\(j \in 0..M-1\)), the index \(i\) to a vertex in vertices that is less than theta degrees from unique_vertices[j]. If there is more than one element of vertices that is less than theta degrees from unique_vertices[j], return the first (lowest index) matching value. Only return if return_indices is True.

search_descending

dipy.reconst.recspeed.search_descending(a, relative_threshold)

i in descending array a so a[i] < a[0] * relative_threshold

Call T = a[0] * relative_threshold. Return value i will be the smallest index in the descending array a such that a[i] < T. Equivalently, i will be the largest index such that all(a[:i] >= T). If all values in a are >= T, return the length of array a.

Parameters

andarray, ndim=1, c-contiguous

Array to be searched. We assume a is in descending order.

relative_thresholdfloat

Applied threshold will be T with T = a[0] * relative_threshold.

Returns

inp.intp

If T = a[0] * relative_threshold then i will be the largest index such that all(a[:i] >= T). If all values in a are >= T then i will be len(a).

Examples

>>> a = np.arange(10, 0, -1, dtype=float)
>>> np.allclose(a, np.array([10., 9., 8., 7., 6., 5., 4., 3., 2., 1.]))
True
>>> search_descending(a, 0.5)
6
>>> np.allclose(a < 10 * 0.5, np.array([False, False, False, False, False,
... False,  True,  True,  True,  True]))
True
>>> search_descending(a, 1)
1
>>> search_descending(a, 2)
0
>>> search_descending(a, 0)
10

sum_on_blocks_1d

dipy.reconst.recspeed.sum_on_blocks_1d(arr, blocks, out, outn)

Summations on blocks of 1d array

RumbaSDModel

class dipy.reconst.rumba.RumbaSDModel(gtab, wm_response=array([0.0017, 0.0002, 0.0002]), gm_response=0.0008, csf_response=0.003, n_iter=600, recon_type='smf', n_coils=1, R=1, voxelwise=True, use_tv=False, sphere=None, verbose=False)

Bases: OdfModel

__init__(gtab, wm_response=array([0.0017, 0.0002, 0.0002]), gm_response=0.0008, csf_response=0.003, n_iter=600, recon_type='smf', n_coils=1, R=1, voxelwise=True, use_tv=False, sphere=None, verbose=False)

Robust and Unbiased Model-BAsed Spherical Deconvolution (RUMBA-SD) [1]_

Modification of the Richardson-Lucy algorithm accounting for Rician and Noncentral Chi noise distributions, which more accurately represent MRI noise. Computes a maximum likelihood estimation of the fiber orientation density function (fODF) at each voxel. Includes white matter compartments alongside optional GM and CSF compartments to account for partial volume effects. This fit can be performed voxelwise or globally. The global fit will proceed more quickly than the voxelwise fit provided that the computer has adequate RAM (>= 16 GB should be sufficient for most datasets).

Kernel for deconvolution constructed using a priori knowledge of white matter response function, as well as the mean diffusivity of GM and/or CSF. RUMBA-SD is robust against impulse response imprecision, and thus the default diffusivity values are often adequate [2]_.

Parameters

gtab : GradientTable wm_response : 1d ndarray or 2d ndarray or AxSymShResponse, optional

Tensor eigenvalues as a (3,) ndarray, multishell eigenvalues as a (len(unique_bvals_tolerance(gtab.bvals))-1, 3) ndarray in order of smallest to largest b-value, or an AxSymShResponse. Default: np.array([1.7e-3, 0.2e-3, 0.2e-3])

gm_responsefloat, optional

Mean diffusivity for GM compartment. If None, then grey matter volume fraction is not computed. Default: 0.8e-3

csf_responsefloat, optional

Mean diffusivity for CSF compartment. If None, then CSF volume fraction is not computed. Default: 3.0e-3

n_iterint, optional

Number of iterations for fODF estimation. Must be a positive int. Default: 600

recon_type{‘smf’, ‘sos’}, optional

MRI reconstruction method: spatial matched filter (SMF) or sum-of-squares (SoS). SMF reconstruction generates Rician noise while SoS reconstruction generates Noncentral Chi noise. Default: ‘smf’

n_coilsint, optional

Number of coils in MRI scanner – only relevant in SoS reconstruction. Must be a positive int. Default: 1

Rint, optional

Acceleration factor of the acquisition. For SIEMENS, R = iPAT factor. For GE, R = ASSET factor. For PHILIPS, R = SENSE factor. Typical values are 1 or 2. Must be a positive int. Default: 1

voxelwisebool, optional

If true, performs a voxelwise fit. If false, performs a global fit on the entire brain at once. The global fit requires a 4D brain volume in fit. Default: True

use_tvbool, optional

If true, applies total variation regularization. This only takes effect in a global fit (voxelwise is set to False). TV can only be applied to 4D brain volumes with no singleton dimensions. Default: False

sphereSphere, optional

Sphere on which to construct fODF. If None, uses repulsion724. Default: None

verbosebool, optional

If true, logs updates on estimated signal-to-noise ratio after each iteration. This only takes effect in a global fit (voxelwise is set to False). Default: False

References

[1]

Canales-Rodríguez, E. J., Daducci, A., Sotiropoulos, S. N., Caruyer, E., Aja-Fernández, S., Radua, J., Mendizabal, J. M. Y., Iturria-Medina, Y., Melie-García, L., Alemán-Gómez, Y., Thiran, J.-P., Sarró, S., Pomarol-Clotet, E., & Salvador, R. (2015). Spherical Deconvolution of Multichannel Diffusion MRI Data with Non-Gaussian Noise Models and Spatial Regularization. PLOS ONE, 10(10), e0138910. https://doi.org/10.1371/journal.pone.0138910

[2]

Dell’Acqua, F., Rizzo, G., Scifo, P., Clarke, R., Scotti, G., & Fazio, F. (2007). A Model-Based Deconvolution Approach to Solve Fiber Crossing in Diffusion-Weighted MR Imaging. IEEE Transactions on Bio-Medical Engineering, 54, 462–472. https://doi.org/10.1109/TBME.2006.888830

RumbaFit

class dipy.reconst.rumba.RumbaFit(model, model_params)

Bases: OdfFit

__init__(model, model_params)

Constructs fODF, GM/CSF volume fractions, and other derived results.

fODF and GM/CSF fractions are normalized to collectively sum to 1 for each voxel.

Parameters

modelRumbaSDModel

RumbaSDModel-SD model.

model_paramsndarray ([x, y, z], M)

fODF and GM/CSF volume fractions for each voxel.

combined_odf_iso()

Constructs fODF combined with isotropic volume fraction at discrete vertices on model sphere.

Distributes isotropic compartments evenly along each fODF direction. Sums to 1.

Returns

combinedndarray ([x, y, z], M-2)

fODF combined with isotropic volume fraction.

f_csf()

Constructs CSF volume fraction for each voxel.

Returns

f_csfndarray ([x, y, z])

CSF volume fraction.

f_gm()

Constructs GM volume fraction for each voxel.

Returns

f_gmndarray ([x, y, z])

GM volume fraction.

f_iso()

Constructs isotropic volume fraction for each voxel.

Equivalent to sum of GM and CSF volume fractions.

Returns

f_isondarray ([x, y, z])

Isotropic volume fraction.

f_wm()

Constructs white matter volume fraction for each voxel.

Equivalent to sum of fODF.

Returns

f_wmndarray ([x, y, z])

White matter volume fraction.

odf(sphere=None)

Constructs fODF at discrete vertices on model sphere for each voxel.

Parameters

sphereSphere, optional

Sphere on which to construct fODF. If specified, must be the same sphere used by the RumbaSDModel model. Default: None.

Returns

odfndarray ([x, y, z], M-2)

fODF computed at each vertex on model sphere.

predict(gtab=None, S0=None)

Compute signal prediction on model gradient table given given fODF and GM/CSF volume fractions for each voxel.

Parameters

gtabGradientTable, optional

The gradients for which the signal will be predicted. Use the model’s gradient table if None. Default: None

S0ndarray ([x, y, z]) or float, optional

The non diffusion-weighted signal value for each voxel. If a float, the same value is used for each voxel. If None, 1 is used for each voxel. Default: None

Returns

pred_signdarray ([x, y, z], N)

The predicted signal.

logger

dipy.reconst.rumba.logger()

Instances of the Logger class represent a single logging channel. A “logging channel” indicates an area of an application. Exactly how an “area” is defined is up to the application developer. Since an application can have any number of areas, logging channels are identified by a unique string. Application areas can be nested (e.g. an area of “input processing” might include sub-areas “read CSV files”, “read XLS files” and “read Gnumeric files”). To cater for this natural nesting, channel names are organized into a namespace hierarchy where levels are separated by periods, much like the Java or Python package namespace. So in the instance given above, channel names might be “input” for the upper level, and “input.csv”, “input.xls” and “input.gnu” for the sub-levels. There is no arbitrary limit to the depth of nesting.

rumba_deconv

dipy.reconst.rumba.rumba_deconv(data, kernel, n_iter=600, recon_type='smf', n_coils=1)

Fit fODF and GM/CSF volume fractions for a voxel using RUMBA-SD [1]_. Deconvolves the kernel from the diffusion-weighted signal by computing a maximum likelihood estimation of the fODF. Minimizes the negative log-likelihood of the data under Rician or Noncentral Chi noise distributions by adapting the iterative technique developed in Richardson-Lucy deconvolution. Parameters ———- data : 1d ndarray (N,) Signal values for a single voxel. kernel : 2d ndarray (N, M) Deconvolution kernel mapping volume fractions of the M compartments to N-length signal. Last two columns should be for GM and CSF. n_iter : int, optional Number of iterations for fODF estimation. Must be a positive int. Default: 600 recon_type : {‘smf’, ‘sos’}, optional MRI reconstruction method: spatial matched filter (SMF) or sum-of-squares (SoS). SMF reconstruction generates Rician noise while SoS reconstruction generates Noncentral Chi noise. Default: ‘smf’ n_coils : int, optional Number of coils in MRI scanner – only relevant in SoS reconstruction. Must be a positive int. Default: 1 Returns ——- fit_vec : 1d ndarray (M,) Vector containing fODF and GM/CSF volume fractions. First M-2 components are fODF while last two are GM and CSF respectively. Notes —– The diffusion MRI signal measured at a given voxel is a sum of contributions from each intra-voxel compartment, including parallel white matter (WM) fiber populations in a given orientation as well as effects from GM and CSF. The equation governing these contributions is: \(S_i = S_0\left(\sum_{j=1}^{M}f_j\exp(-b_i\textbf{v}_i^T\textbf{D}_j \textbf{v}_i) + f_{GM}\exp(-b_iD_{GM})+f_{CSF}\exp(-b_iD_{CSF})\right)\) Where \(S_i\) is the resultant signal along the diffusion-sensitizing gradient unit vector \(\textbf{v_i}; i = 1, ..., N\) with a b-value of \(b_i\). \(f_j; j = 1, ..., M\) is the volume fraction of the \(j^{th}\) fiber population with an anisotropic diffusion tensor \(\textbf{D_j}\). \(f_{GM}\) and \(f_{CSF}\) are the volume fractions and \(D_{GM}\) and \(D_{CSF}\) are the mean diffusivities of GM and CSF respectively. This equation is linear in \(f_j, f_{GM}, f_{CSF}\) and can be simplified to a single matrix multiplication: \(\textbf{S} = \textbf{Hf}\) Where \(\textbf{S}\) is the signal vector at a certain voxel, \(\textbf{H}\) is the deconvolution kernel, and \(\textbf{f}\) is the vector of volume fractions for each compartment. Modern MRI scanners produce noise following a Rician or Noncentral Chi distribution, depending on their signal reconstruction technique [2]_. Using this linear model, it can be shown that the likelihood of a signal under a Noncentral Chi noise model is: \(P(\textbf{S}|\textbf{H}, \textbf{f}, \sigma^2, n) = \prod_{i=1}^{N}\left( \frac{S_i}{\bar{S_i}}\right)^n\exp\left\{-\frac{1}{2\sigma^2}\left[ S_i^2 + \bar{S}_i^2\right]\right\}I_{n-1}\left(\frac{S_i\bar{S}_i} {\sigma^2}\right)u(S_i)\) Where \(S_i\) and \(\bar{S}_i = \textbf{Hf}\) are the measured and expected signals respectively, and \(n\) is the number of coils in the scanner, and \(I_{n-1}\) is the modified Bessel function of first kind of order \(n-1\). This gives the likelihood under a Rician distribution when \(n\) is set to 1. By taking the negative log of this with respect to \(\textbf{f}\) and setting the derivative to 0, the \(\textbf{f}\) maximizing likelihood is found to be: \(\textbf{f} = \textbf{f} \circ \frac{\textbf{H}^T\left[\textbf{S}\circ \frac{I_n(\textbf{S}\circ \textbf{Hf}/\sigma^2)} {I_{n-1}(\textbf{S} \circ\textbf{Hf}\sigma^2)} \right ]} {\textbf{H}^T\textbf{Hf}}\) The solution can be found using an iterative scheme, just as in the Richardson-Lucy algorithm: \(\textbf{f}^{k+1} = \textbf{f}^k \circ \frac{\textbf{H}^T\left[\textbf{S} \circ\frac{I_n(\textbf{S}\circ\textbf{Hf}^k/\sigma^2)} {I_{n-1}(\textbf{S} \circ\textbf{Hf}^k/\sigma^2)} \right ]} {\textbf{H}^T\textbf{Hf}^k}\) In order to apply this, a reasonable estimate of \(\sigma^2\) is required. To find this, a separate iterative scheme is found using the derivative of the negative log with respect to \(\sigma^2\), and is run in parallel. This is shown here: \(\alpha^{k+1} = \frac{1}{nN}\left\{ \frac{\textbf{S}^T\textbf{S} + \textbf{f}^T\textbf{H}^T\textbf{Hf}}{2} - \textbf{1}^T_N\left[(\textbf{S} \circ\textbf{Hf})\circ\frac{I_n(\textbf{S}\circ\textbf{Hf}/\alpha^k)} {I_{n-1}(\textbf{S}\circ\textbf{Hf}/\alpha^k)} \right ]\right \}\) For more details, see [1]_. References ———- .. [1] Canales-Rodríguez, E. J., Daducci, A., Sotiropoulos, S. N., Caruyer, E., Aja-Fernández, S., Radua, J., Mendizabal, J. M. Y., Iturria-Medina, Y., Melie-García, L., Alemán-Gómez, Y., Thiran, J.-P.,Sarró, S., Pomarol-Clotet, E., & Salvador, R. (2015). Spherical Deconvolution of Multichannel Diffusion MRI Data with Non-Gaussian Noise Models and Spatial Regularization. PLOS ONE, 10(10), e0138910. https://doi.org/10.1371/journal.pone.0138910 .. [2] Constantinides, C. D., Atalar, E., & McVeigh, E. R. (1997). Signal-to-Noise Measurements in Magnitude Images from NMR Phased Arrays. Magnetic Resonance in Medicine: Official Journal of the Society of Magnetic Resonance in Medicine / Society of Magnetic Resonance in Medicine, 38(5), 852–857.

mbessel_ratio

dipy.reconst.rumba.mbessel_ratio(n, x)

Fast computation of modified Bessel function ratio (first kind). Computes: \(I_{n}(x) / I_{n-1}(x)\) using Perron’s continued fraction equation where \(I_n\) is the modified Bessel function of first kind, order \(n\) [1]_. Parameters ———- n : int Order of Bessel function in numerator (denominator is of order n-1). Must be a positive int. x : float or ndarray Value or array of values with which to compute ratio. Returns ——- y : float or ndarray Result of ratio computation. References ———- .. [1] W. Gautschi and J. Slavik, “On the computation of modified Bessel function ratios,” Math. Comp., vol. 32, no. 143, pp. 865–875, 1978, doi: 10.1090/S0025-5718-1978-0470267-9

generate_kernel

dipy.reconst.rumba.generate_kernel(gtab, sphere, wm_response, gm_response, csf_response)

Generate deconvolution kernel

Compute kernel mapping orientation densities of white matter fiber populations (along each vertex of the sphere) and isotropic volume fractions to a diffusion weighted signal.

Parameters

gtab : GradientTable sphere : Sphere

Sphere with which to sample discrete fiber orientations in order to construct kernel

wm_response1d ndarray or 2d ndarray or AxSymShResponse, optional

Tensor eigenvalues as a (3,) ndarray, multishell eigenvalues as a (len(unique_bvals_tolerance(gtab.bvals))-1, 3) ndarray in order of smallest to largest b-value, or an AxSymShResponse.

gm_responsefloat, optional

Mean diffusivity for GM compartment. If None, then grey matter compartment set to all zeros.

csf_responsefloat, optional

Mean diffusivity for CSF compartment. If None, then CSF compartment set to all zeros.

Returns

kernel2d ndarray (N, M)

Computed kernel; can be multiplied with a vector consisting of volume fractions for each of M-2 fiber populations as well as GM and CSF fractions to produce a diffusion weighted signal.

rumba_deconv_global

dipy.reconst.rumba.rumba_deconv_global(data, kernel, mask, n_iter=600, recon_type='smf', n_coils=1, R=1, use_tv=True, verbose=False)

Fit fODF for all voxels simultaneously using RUMBA-SD. Deconvolves the kernel from the diffusion-weighted signal at each voxel by computing a maximum likelihood estimation of the fODF [1]_. Global fitting also permits the use of total variation regularization (RUMBA-SD + TV). The spatial dependence introduced by TV promotes smoother solutions (i.e. prevents oscillations), while still allowing for sharp discontinuities [2]_. This promotes smoothness and continuity along individual tracts while preventing smoothing of adjacent tracts. Generally, global_fit will proceed more quickly than the voxelwise fit provided that the computer has adequate RAM (>= 16 GB should be more than sufficient). Parameters ———- data : 4d ndarray (x, y, z, N) Signal values for entire brain. None of the volume dimensions x, y, z can be 1 if TV regularization is required. kernel : 2d ndarray (N, M) Deconvolution kernel mapping volume fractions of the M compartments to N-length signal. Last two columns should be for GM and CSF. mask : 3d ndarray(x, y, z) Binary mask specifying voxels of interest with 1; fODF will only be fit at these voxels (0 elsewhere). n_iter : int, optional Number of iterations for fODF estimation. Must be a positive int. Default: 600 recon_type : {‘smf’, ‘sos’}, optional MRI reconstruction method: spatial matched filter (SMF) or sum-of-squares (SoS). SMF reconstruction generates Rician noise while SoS reconstruction generates Noncentral Chi noise. Default: ‘smf’ n_coils : int, optional Number of coils in MRI scanner – only relevant in SoS reconstruction. Must be a positive int. Default: 1 use_tv : bool, optional If true, applies total variation regularization. This requires a brain volume with no singleton dimensions. Default: True verbose : bool, optional If true, logs updates on estimated signal-to-noise ratio after each iteration. Default: False Returns ——- fit_array : 4d ndarray (x, y, z, M) fODF and GM/CSF volume fractions computed for each voxel. First M-2 components are fODF, while last two are GM and CSf respectively. Notes —– TV modifies our cost function as follows: \(J(\textbf{f}) = -\log{P(\textbf{S}|\textbf{H}, \textbf{f}, \sigma^2, n)})+ \alpha_{TV}TV(\textbf{f})\) where the first term is the negative log likelihood described in the notes of rumba_deconv, and the second term is the TV energy, or the sum of gradient absolute values for the fODF across the entire brain. This results in a new multiplicative factor in the iterative scheme, now becoming: \(\textbf{f}^{k+1} = \textbf{f}^k \circ \frac{\textbf{H}^T\left[\textbf{S} \circ\frac{I_n(\textbf{S}\circ\textbf{Hf}^k/\sigma^2)} {I_{n-1}(\textbf{S} \circ\textbf{Hf}^k/\sigma^2)} \right ]} {\textbf{H}^T\textbf{Hf}^k}\circ \textbf{R}^k\) where \(\textbf{R}^k\) is computed voxelwise by: \((\textbf{R}^k)_j = \frac{1}{1 - \alpha_{TV}div\left(\frac{\triangledown[ \textbf{f}^k_{3D}]_j}{\lvert\triangledown[\textbf{f}^k_{3D}]_j \rvert} \right)\biggr\rvert_{x, y, z}}\) Here, \(\triangledown\) is the symbol for the 3D gradient at any voxel. The regularization strength, \(\alpha_{TV}\) is updated after each iteration by the discrepancy principle – specifically, it is selected to match the estimated variance after each iteration [3]_. References ———- .. [1] Canales-Rodríguez, E. J., Daducci, A., Sotiropoulos, S. N., Caruyer, E., Aja-Fernández, S., Radua, J., Mendizabal, J. M. Y., Iturria-Medina, Y., Melie-García, L., Alemán-Gómez, Y., Thiran, J.-P., Sarró, S., Pomarol-Clotet, E., & Salvador, R. (2015). Spherical Deconvolution of Multichannel Diffusion MRI Data with Non-Gaussian Noise Models and Spatial Regularization. PLOS ONE, 10(10), e0138910. https://doi.org/10.1371/journal.pone.0138910 .. [2] Rudin, L. I., Osher, S., & Fatemi, E. (1992). Nonlinear total variation based noise removal algorithms. Physica D: Nonlinear Phenomena, 60(1), 259–268. https://doi.org/10.1016/0167-2789(92)90242-F .. [3] Chambolle A. An algorithm for total variation minimization and applications. Journal of Mathematical Imaging and Vision. 2004; 20:89–97.

IsotropicModel

class dipy.reconst.sfm.IsotropicModel(gtab)

Bases: ReconstModel

A base-class for the representation of isotropic signals.

The default behavior, suitable for single b-value data is to calculate the mean in each voxel as an estimate of the signal that does not depend on direction.

__init__(gtab)

Initialize an IsotropicModel.

Parameters

gtab : a GradientTable class instance

fit(data, mask=None, **kwargs)

Fit an IsotropicModel.

This boils down to finding the mean diffusion-weighted signal in each voxel

Parameters

data : ndarray

Returns

IsotropicFit class instance.

IsotropicFit

class dipy.reconst.sfm.IsotropicFit(model, params)

Bases: ReconstFit

A fit object for representing the isotropic signal as the mean of the diffusion-weighted signal.

__init__(model, params)

Initialize an IsotropicFit object.

Parameters

model : IsotropicModel class instance params : ndarray

The mean isotropic model parameters (the mean diffusion-weighted signal in each voxel).

n_voxint

The number of voxels for which the fit was done.

predict(gtab=None)

Predict the isotropic signal.

Based on a gradient table. In this case, the (naive!) prediction will be the mean of the diffusion-weighted signal in the voxels.

Parameters

gtaba GradientTable class instance (optional)

Defaults to use the gtab from the IsotropicModel from which this fit was derived.

ExponentialIsotropicModel

class dipy.reconst.sfm.ExponentialIsotropicModel(gtab)

Bases: IsotropicModel

Representing the isotropic signal as a fit to an exponential decay function with b-values

__init__(gtab)

Initialize an IsotropicModel.

Parameters

gtab : a GradientTable class instance

fit(data, mask=None, **kwargs)

Parameters

data : ndarray

maskarray, optional

A boolean array used to mark the coordinates in the data that should be analyzed. Has the shape data.shape[:-1]. Default: None, which implies that all points should be analyzed.

Returns

ExponentialIsotropicFit class instance.

ExponentialIsotropicFit

class dipy.reconst.sfm.ExponentialIsotropicFit(model, params)

Bases: IsotropicFit

A fit to the ExponentialIsotropicModel object, based on data.

__init__(model, params)

Initialize an IsotropicFit object.

Parameters

model : IsotropicModel class instance params : ndarray

The mean isotropic model parameters (the mean diffusion-weighted signal in each voxel).

n_voxint

The number of voxels for which the fit was done.

predict(gtab=None)

Predict the isotropic signal, based on a gradient table. In this case, the prediction will be for an exponential decay with the mean diffusivity derived from the data that was fit.

Parameters

gtaba GradientTable class instance (optional)

Defaults to use the gtab from the IsotropicModel from which this fit was derived.

SparseFascicleModel

class dipy.reconst.sfm.SparseFascicleModel(gtab, sphere=None, response=(0.0015, 0.0005, 0.0005), solver='ElasticNet', l1_ratio=0.5, alpha=0.001, isotropic=None, seed=42)

Bases: ReconstModel, Cache

__init__(gtab, sphere=None, response=(0.0015, 0.0005, 0.0005), solver='ElasticNet', l1_ratio=0.5, alpha=0.001, isotropic=None, seed=42)

Initialize a Sparse Fascicle Model

Parameters

gtab : GradientTable class instance

sphereSphere class instance, optional

A sphere on which coefficients will be estimated. Default: symmetric sphere with 362 points (from dipy.data).

response(3,) array-like, optional

The eigenvalues of a canonical tensor to be used as the response function of single-fascicle signals. Default:[0.0015, 0.0005, 0.0005]

solverstring, or initialized linear model object.

This will determine the algorithm used to solve the set of linear equations underlying this model. If it is a string it needs to be one of the following: {‘ElasticNet’, ‘NNLS’}. Otherwise, it can be an object that inherits from dipy.optimize.SKLearnLinearSolver or an object with a similar interface from Scikit Learn: sklearn.linear_model.ElasticNet, sklearn.linear_model.Lasso or sklearn.linear_model.Ridge and other objects that inherit from sklearn.base.RegressorMixin. Default: ‘ElasticNet’.

l1_ratiofloat, optional

Sets the balance between L1 and L2 regularization in ElasticNet [Zou2005]. Default: 0.5

alphafloat, optional

Sets the balance between least-squares error and L1/L2 regularization in ElasticNet [Zou2005]. Default: 0.001

isotropicIsotropicModel class instance

This is a class that implements the function that calculates the value of the isotropic signal. This is a value of the signal that is independent of direction, and therefore removed from both sides of the SFM equation. The default is an instance of IsotropicModel, but other functions can be inherited from IsotropicModel to implement other fits to the aspects of the data that depend on b-value, but not on direction.

Notes

This is an implementation of the SFM, described in [Rokem2015].

[Rokem2014]

Ariel Rokem, Jason D. Yeatman, Franco Pestilli, Kendrick N. Kay, Aviv Mezer, Stefan van der Walt, Brian A. Wandell (2014). Evaluating the accuracy of diffusion MRI models in white matter. PLoS ONE 10(4): e0123272. doi:10.1371/journal.pone.0123272

[Zou2005] (1,2)

Zou H, Hastie T (2005). Regularization and variable selection via the elastic net. J R Stat Soc B:301-320

design_matrix()

The design matrix for a SFM.

Returns

ndarray

The design matrix, where each column is a rotated version of the response function.

fit(data, mask=None, num_processes=1, parallel_backend='multiprocessing')

Fit the SparseFascicleModel object to data.

Parameters

dataarray

The measured signal.

maskarray, optional

A boolean array used to mark the coordinates in the data that should be analyzed. Has the shape data.shape[:-1]. Default: None, which implies that all points should be analyzed.

num_processesint, optional

Split the fit calculation to a pool of children processes using joblib. This only applies to 4D data arrays. Default is 1, which does not require joblib and will run fit serially. If < 0 the maximal number of cores minus num_processes + 1 is used (enter -1 to use as many cores as possible). 0 raises an error.

parallel_backend: str, ParallelBackendBase instance or None

Specify the parallelization backend implementation. Supported backends are: - “loky” used by default, can induce some

communication and memory overhead when exchanging input and output data with the worker Python processes.

• “multiprocessing” previous process-based backend based on multiprocessing.Pool. Less robust than loky.

• “threading” is a very low-overhead backend but it suffers from the Python Global Interpreter Lock if the called function relies a lot on Python objects. “threading” is mostly useful when the execution bottleneck is a compiled extension that explicitly releases the GIL (for instance a Cython loop wrapped in a “with nogil” block or an expensive call to a library such as NumPy).

Default: ‘multiprocessing’.

Returns

SparseFascicleFit object

SparseFascicleFit

class dipy.reconst.sfm.SparseFascicleFit(model, beta, S0, iso)

Bases: ReconstFit

__init__(model, beta, S0, iso)

Initialize a SparseFascicleFit class instance

Parameters

model : a SparseFascicleModel object.

betandarray

The parameters of fit to data.

S0ndarray

The mean non-diffusion-weighted signal.

isoIsotropicFit class instance

A representation of the isotropic signal, together with parameters of the isotropic signal in each voxel, that is capable of deriving/predicting an isotropic signal, based on a gradient-table.

odf(sphere)

The orientation distribution function of the SFM

Parameters

sphereSphere

The points in which the ODF is evaluated

Returns

odf : ndarray of shape (x, y, z, sphere.vertices.shape[0])

predict(gtab=None, response=None, S0=None)

Predict the signal based on the SFM parameters

Parameters

gtabGradientTable, optional

The bvecs/bvals to predict the signal on. Default: the gtab from the model object.

responselist of 3 elements, optional

The eigenvalues of a tensor which will serve as a kernel function. Default: the response of the model object. Default to use model.response.

S0float or array, optional

The non-diffusion-weighted signal. Default: use the S0 of the data

Returns

pred_signdarray

The signal predicted in each voxel/direction

sfm_design_matrix

dipy.reconst.sfm.sfm_design_matrix(gtab, sphere, response, mode='signal')

Construct the SFM design matrix

Parameters

gtabGradientTable or Sphere

Sets the rows of the matrix, if the mode is ‘signal’, this should be a GradientTable. If mode is ‘odf’ this should be a Sphere.

sphereSphere

Sets the columns of the matrix

responselist of 3 elements

The eigenvalues of a tensor which will serve as a kernel function.

modestr {‘signal’ | ‘odf’}, optional

Choose the (default) ‘signal’ for a design matrix containing predicted signal in the measurements defined by the gradient table for putative fascicles oriented along the vertices of the sphere. Otherwise, choose ‘odf’ for an odf convolution matrix, with values of the odf calculated from a tensor with the provided response eigenvalues, evaluated at the b-vectors in the gradient table, for the tensors with principal diffusion directions along the vertices of the sphere.

Returns

matndarray

A design matrix that can be used for one of the following operations: when the ‘signal’ mode is used, each column contains the putative signal in each of the bvectors of the gtab if a fascicle is oriented in the direction encoded by the sphere vertex corresponding to this column. This is used for deconvolution with a measured DWI signal. If the ‘odf’ mode is chosen, each column instead contains the values of the tensor ODF for a tensor with a principal diffusion direction corresponding to this vertex. This is used to generate odfs from the fits of the SFM for the purpose of tracking.

Examples

>>> import dipy.data as dpd
>>> data, gtab = dpd.dsi_voxels()
>>> sphere = dpd.get_sphere()
>>> from dipy.reconst.sfm import sfm_design_matrix

A canonical tensor approximating corpus-callosum voxels [Rokem2014]:

>>> tensor_matrix = sfm_design_matrix(gtab, sphere,
...                                   [0.0015, 0.0005, 0.0005])

A ‘stick’ function ([Behrens2007]):

>>> stick_matrix = sfm_design_matrix(gtab, sphere, [0.001, 0, 0])

Notes

[Rokem2015]

Ariel Rokem, Jason D. Yeatman, Franco Pestilli, Kendrick N. Kay, Aviv Mezer, Stefan van der Walt, Brian A. Wandell (2015). Evaluating the accuracy of diffusion MRI models in white matter. PLoS ONE 10(4): e0123272. doi:10.1371/journal.pone.0123272

[Rokem2014]

Ariel Rokem, Kimberly L. Chan, Jason D. Yeatman, Franco Pestilli, Brian A. Wandell (2014). Evaluating the accuracy of diffusion models at multiple b-values with cross-validation. ISMRM 2014.

[Behrens2007]

Behrens TEJ, Berg HJ, Jbabdi S, Rushworth MFS, Woolrich MW (2007): Probabilistic diffusion tractography with multiple fibre orientations: What can we gain? Neuroimage 34:144-55.

SphHarmModel

class dipy.reconst.shm.SphHarmModel(gtab)

Bases: OdfModel, Cache

To be subclassed by all models that return a SphHarmFit when fit.

__init__(gtab)

Initialization of the abstract class for signal reconstruction models

Parameters

gtab : GradientTable class instance

sampling_matrix(sphere)

The matrix needed to sample ODFs from coefficients of the model.

Parameters

sphereSphere

Points used to sample ODF.

Returns

sampling_matrixarray

The size of the matrix will be (N, M) where N is the number of vertices on sphere and M is the number of coefficients needed by the model.

QballBaseModel

class dipy.reconst.shm.QballBaseModel(gtab, sh_order_max, smooth=0.006, min_signal=1e-05, assume_normed=False)

Bases: SphHarmModel

To be subclassed by Qball type models.

__init__(gtab, sh_order_max, smooth=0.006, min_signal=1e-05, assume_normed=False)

Creates a model that can be used to fit or sample diffusion data

Parameters

gtabGradientTable

Diffusion gradients used to acquire data

sh_order_maxeven int >= 0

the maximal spherical harmonic order (l) of the model

smoothfloat between 0 and 1, optional

The regularization parameter of the model

min_signalfloat, > 0, optional

During fitting, all signal values less than min_signal are clipped to min_signal. This is done primarily to avoid values less than or equal to zero when taking logs.

assume_normedbool, optional

If True, clipping and normalization of the data with respect to the mean B0 signal are skipped during mode fitting. This is an advanced feature and should be used with care.

See Also

normalize_data

fit(data, mask=None)

Fits the model to diffusion data and returns the model fit

SphHarmFit

class dipy.reconst.shm.SphHarmFit(model, shm_coef, mask)

Bases: OdfFit

Diffusion data fit to a spherical harmonic model

__init__(model, shm_coef, mask)

gfa()

odf(sphere)

Samples the odf function on the points of a sphere

Parameters

sphereSphere

The points on which to sample the odf.

Returns

valuesndarray

The value of the odf on each point of sphere.

predict(gtab=None, S0=1.0)

Predict the diffusion signal from the model coefficients.

Parameters

gtaba GradientTable class instance

The directions and bvalues on which prediction is desired

S0float array

The mean non-diffusion-weighted signal in each voxel.

property shape

property shm_coeff

The spherical harmonic coefficients of the odf

Make this a property for now, if there is a use case for modifying the coefficients we can add a setter or expose the coefficients more directly

CsaOdfModel

class dipy.reconst.shm.CsaOdfModel(gtab, sh_order_max, smooth=0.006, min_signal=1e-05, assume_normed=False)

Bases: QballBaseModel

Implementation of Constant Solid Angle reconstruction method.

References

[1]

Aganj, I., et al. 2009. ODF Reconstruction in Q-Ball Imaging With Solid Angle Consideration.

__init__(gtab, sh_order_max, smooth=0.006, min_signal=1e-05, assume_normed=False)

Creates a model that can be used to fit or sample diffusion data

Parameters

gtabGradientTable

Diffusion gradients used to acquire data

sh_order_maxeven int >= 0

the maximal spherical harmonic order (l) of the model

smoothfloat between 0 and 1, optional

The regularization parameter of the model

min_signalfloat, > 0, optional

During fitting, all signal values less than min_signal are clipped to min_signal. This is done primarily to avoid values less than or equal to zero when taking logs.

assume_normedbool, optional

If True, clipping and normalization of the data with respect to the mean B0 signal are skipped during mode fitting. This is an advanced feature and should be used with care.

See Also

normalize_data

max = 0.999

min = 0.001

OpdtModel

class dipy.reconst.shm.OpdtModel(gtab, sh_order_max, smooth=0.006, min_signal=1e-05, assume_normed=False)

Bases: QballBaseModel

Implementation of Orientation Probability Density Transform reconstruction method.

References

[1]

Tristan-Vega, A., et al. 2010. A new methodology for estimation of fiber populations in white matter of the brain with Funk-Radon transform.

[2]

Tristan-Vega, A., et al. 2009. Estimation of fiber orientation probability density functions in high angular resolution diffusion imaging.

__init__(gtab, sh_order_max, smooth=0.006, min_signal=1e-05, assume_normed=False)

Creates a model that can be used to fit or sample diffusion data

Parameters

gtabGradientTable

Diffusion gradients used to acquire data

sh_order_maxeven int >= 0

the maximal spherical harmonic order (l) of the model

smoothfloat between 0 and 1, optional

The regularization parameter of the model

min_signalfloat, > 0, optional

During fitting, all signal values less than min_signal are clipped to min_signal. This is done primarily to avoid values less than or equal to zero when taking logs.

assume_normedbool, optional

If True, clipping and normalization of the data with respect to the mean B0 signal are skipped during mode fitting. This is an advanced feature and should be used with care.

See Also

normalize_data

QballModel

class dipy.reconst.shm.QballModel(gtab, sh_order_max, smooth=0.006, min_signal=1e-05, assume_normed=False)

Bases: QballBaseModel

Implementation of regularized Qball reconstruction method.

References

[1]

Descoteaux, M., et al. 2007. Regularized, fast, and robust analytical Q-ball imaging.

__init__(gtab, sh_order_max, smooth=0.006, min_signal=1e-05, assume_normed=False)

Creates a model that can be used to fit or sample diffusion data

Parameters

gtabGradientTable

Diffusion gradients used to acquire data

sh_order_maxeven int >= 0

the maximal spherical harmonic order (l) of the model

smoothfloat between 0 and 1, optional

The regularization parameter of the model

min_signalfloat, > 0, optional

During fitting, all signal values less than min_signal are clipped to min_signal. This is done primarily to avoid values less than or equal to zero when taking logs.

assume_normedbool, optional

If True, clipping and normalization of the data with respect to the mean B0 signal are skipped during mode fitting. This is an advanced feature and should be used with care.

See Also

normalize_data

ResidualBootstrapWrapper

class dipy.reconst.shm.ResidualBootstrapWrapper(signal_object, B, where_dwi, min_signal=1e-05)

Bases: object

Returns a residual bootstrap sample of the signal_object when indexed

Wraps a signal_object, this signal object can be an interpolator. When indexed, the the wrapper indexes the signal_object to get the signal. There wrapper than samples the residual bootstrap distribution of signal and returns that sample.

__init__(signal_object, B, where_dwi, min_signal=1e-05)

Builds a ResidualBootstrapWapper

Given some linear model described by B, the design matrix, and a signal_object, returns an object which can sample the residual bootstrap distribution of the signal. We assume that the signals are normalized so we clip the bootstrap samples to be between min_signal and 1.

Parameters

signal_objectsome object that can be indexed

This object should return diffusion weighted signals when indexed.

Bndarray, ndim=2

The design matrix of the spherical harmonics model used to fit the data. This is the model that will be used to compute the residuals and sample the residual bootstrap distribution

where_dwi :

indexing object to find diffusion weighted signals from signal

min_signalfloat

The lowest allowable signal.

forward_sdeconv_mat

dipy.reconst.shm.forward_sdeconv_mat(r_rh, l_values)

Build forward spherical deconvolution matrix

Parameters

r_rhndarray

Rotational harmonics coefficients for the single fiber response function. Each element rh[i] is associated with spherical harmonics of order 2*i.

l_valuesndarray

The orders (l) of spherical harmonic function associated with each row of the deconvolution matrix. Only even orders are allowed

Returns

Rndarray (N, N)

Deconvolution matrix with shape (N, N)

sh_to_rh

dipy.reconst.shm.sh_to_rh(r_sh, m_values, l_values)

Spherical harmonics (SH) to rotational harmonics (RH)

Calculate the rotational harmonic decomposition up to harmonic phase factor m, order l for an axially and antipodally symmetric function. Note that all m != 0 coefficients will be ignored as axial symmetry is assumed. Hence, there will be (sh_order/2 + 1) non-zero coefficients.

Parameters

r_shndarray (N,)

ndarray of SH coefficients for the single fiber response function. These coefficients must correspond to the real spherical harmonic functions produced by shm.real_sh_descoteaux_from_index.

m_valuesndarray (N,)

The phase factors (m) of the spherical harmonic function associated with each coefficient.

l_valuesndarray (N,)

The orders (l) of the spherical harmonic function associated with each coefficient.

Returns

r_rhndarray ((sh_order + 1)*(sh_order + 2)/2,)

Rotational harmonics coefficients representing the input r_sh

See Also

shm.real_sh_descoteaux_from_index, shm.real_sh_descoteaux

References

[1]

Tournier, J.D., et al. NeuroImage 2007. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution

gen_dirac

dipy.reconst.shm.gen_dirac(m_values, l_values, theta, phi, legacy=True)

Generate Dirac delta function orientated in (theta, phi) on the sphere

The spherical harmonics (SH) representation of this Dirac is returned as coefficients to spherical harmonic functions produced from descoteaux07 basis.

Parameters

m_valuesndarray (N,)

The phase factors of the spherical harmonic function associated with each coefficient.

l_valuesndarray (N,)

The order (l) of the spherical harmonic function associated with each coefficient.

thetafloat [0, pi]

The polar (colatitudinal) coordinate.

phifloat [0, 2*pi]

The azimuthal (longitudinal) coordinate.

legacy: bool, optional

If true, uses DIPY’s legacy descoteaux07 implementation (where |m| is used for m < 0). Else, implements the basis as defined in Descoteaux et al. 2007 (without the absolute value).

See Also

shm.real_sh_descoteaux_from_index, shm.real_sh_descoteaux

Returns

diracndarray

SH coefficients representing the Dirac function. The shape of this is (m + 2) * (m + 1) / 2.

spherical_harmonics

dipy.reconst.shm.spherical_harmonics(m_values, l_values, theta, phi, use_scipy=True)

Compute spherical harmonics. This may take scalar or array arguments. The inputs will be broadcast against each other. Parameters ———- m_values : array of int |m| <= l The phase factors (m) of the harmonics. l_values : array of int l >= 0 The orders (l) of the harmonics. theta : float [0, 2*pi] The azimuthal (longitudinal) coordinate. phi : float [0, pi] The polar (colatitudinal) coordinate. use_scipy : bool, optional If True, use scipy implementation. Returns ——- y_mn : complex float The harmonic \(Y^m_l\) sampled at theta and phi. Notes —– This is a faster implementation of scipy.special.sph_harm for scipy version < 0.15.0. For scipy 0.15 and onwards, we use the scipy implementation of the function. The usual definitions for theta` and `phi used in DIPY are interchanged in the method definition to agree with the definitions in scipy.special.sph_harm, where theta represents the azimuthal coordinate and phi represents the polar coordinate. Although scipy uses a naming convention where m is the order and n is the degree of the SH, the opposite of DIPY’s, their definition for both parameters is the same as ours, with l >= 0 and |m| <= l.

real_sph_harm

dipy.reconst.shm.real_sph_harm(m_values, l_values, theta, phi)

Compute real spherical harmonics. dipy.reconst.shm.real_sph_harm is deprecated, Please use dipy.reconst.shm.real_sh_descoteaux_from_index instead * deprecated from version: 1.3 * Will raise <class ‘dipy.utils.deprecator.ExpiredDeprecationError’> as of version: 2.0 Where the real harmonic \(Y^m_l\) is defined to be: Imag(\(Y^m_l\)) * sqrt(2) if m > 0 \(Y^0_l\) if m = 0 Real(\(Y^|m|_l\)) * sqrt(2) if m < 0 This may take scalar or array arguments. The inputs will be broadcast against each other. Parameters ———- m_values : array of int |m| <= l The phase factors (m) of the harmonics. l_values : array of int l >= 0 The orders (l) of the harmonics. theta : float [0, pi] The polar (colatitudinal) coordinate. phi : float [0, 2*pi] The azimuthal (longitudinal) coordinate. Returns ——- y_mn : real float The real harmonic \(Y^m_l\) sampled at theta and phi. See Also ——– scipy.special.sph_harm

real_sh_tournier_from_index

dipy.reconst.shm.real_sh_tournier_from_index(m_values, l_values, theta, phi, legacy=True)

Compute real spherical harmonics as initially defined in Tournier 2007 [1]_ then updated in MRtrix3 [2]_, where the real harmonic \(Y^m_l\) is defined to be: Real(\(Y^m_l\)) * sqrt(2) if m > 0 \(Y^0_l\) if m = 0 Imag(\(Y^|m|_l\)) * sqrt(2) if m < 0 This may take scalar or array arguments. The inputs will be broadcast against each other. Parameters ———- m_values : array of int |m| <= l The phase factors (m) of the harmonics. l_values : array of int l >= 0 The orders (l) of the harmonics. theta : float [0, pi] The polar (colatitudinal) coordinate. phi : float [0, 2*pi] The azimuthal (longitudinal) coordinate. legacy: bool, optional If true, uses MRtrix 0.2 SH basis definition, where the sqrt(2) factor is omitted. Else, uses the MRtrix 3 definition presented above. Returns ——- real_sh : real float The real harmonics \(Y^m_l\) sampled at theta and phi. References ———- .. [1] Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution. NeuroImage. 2007;35(4):1459-1472. .. [2] Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, Pietsch M, et al. MRtrix3: A fast, flexible and open software framework for medical image processing and visualisation. NeuroImage. 2019 Nov 15;202:116-137.

real_sh_descoteaux_from_index

dipy.reconst.shm.real_sh_descoteaux_from_index(m_values, l_values, theta, phi, legacy=True)

Compute real spherical harmonics as in Descoteaux et al. 2007 [1]_, where the real harmonic \(Y^m_l\) is defined to be: Imag(\(Y^m_l\)) * sqrt(2) if m > 0 \(Y^0_l\) if m = 0 Real(\(Y^m_l\)) * sqrt(2) if m < 0 This may take scalar or array arguments. The inputs will be broadcast against each other. Parameters ———- m_values : array of int |m| <= l The phase factors (m) of the harmonics. l_values : array of int l >= 0 The orders (l) of the harmonics. theta : float [0, pi] The polar (colatitudinal) coordinate. phi : float [0, 2*pi] The azimuthal (longitudinal) coordinate. legacy: bool, optional If true, uses DIPY’s legacy descoteaux07 implementation (where |m| is used for m < 0). Else, implements the basis as defined in Descoteaux et al. 2007 (without the absolute value). Returns ——- real_sh : real float The real harmonic \(Y^m_l\) sampled at theta and phi. References ———- .. [1] Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510.

real_sh_tournier

dipy.reconst.shm.real_sh_tournier(sh_order_max, theta, phi, full_basis=False, legacy=True)

Compute real spherical harmonics as initially defined in Tournier 2007 [1]_ then updated in MRtrix3 [2]_, where the real harmonic \(Y^m_l\) is defined to be: Real(\(Y^m_l\)) * sqrt(2) if m > 0 \(Y^0_l\) if m = 0 Imag(\(Y^|m|_l\)) * sqrt(2) if m < 0 This may take scalar or array arguments. The inputs will be broadcast against each other. Parameters ———- sh_order_max : int The maximum order (l) of the spherical harmonic basis. theta : float [0, pi] The polar (colatitudinal) coordinate. phi : float [0, 2*pi] The azimuthal (longitudinal) coordinate. full_basis: bool, optional If true, returns a basis including odd order SH functions as well as even order SH functions. Else returns only even order SH functions. legacy: bool, optional If true, uses MRtrix 0.2 SH basis definition, where the sqrt(2) factor is omitted. Else, uses MRtrix 3 definition presented above. Returns ——- real_sh : real float The real harmonic \(Y^m_l\) sampled at theta and phi. m_values : array of int The phase factor (m) of the harmonics. l_values : array of int The order (l) of the harmonics. References ———- .. [1] Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution. NeuroImage. 2007;35(4):1459-1472. .. [2] Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, Pietsch M, et al. MRtrix3: A fast, flexible and open software framework for medical image processing and visualisation. NeuroImage. 2019 Nov 15;202:116-137.

real_sh_descoteaux

dipy.reconst.shm.real_sh_descoteaux(sh_order_max, theta, phi, full_basis=False, legacy=True)

Compute real spherical harmonics as in Descoteaux et al. 2007 [1]_, where the real harmonic \(Y^m_l\) is defined to be: Imag(\(Y^m_l\)) * sqrt(2) if m > 0 \(Y^0_l\) if m = 0 Real(\(Y^m_l\)) * sqrt(2) if m < 0 This may take scalar or array arguments. The inputs will be broadcast against each other. Parameters ———- sh_order_max : int The maximum order (l) of the spherical harmonic basis. theta : float [0, pi] The polar (colatitudinal) coordinate. phi : float [0, 2*pi] The azimuthal (longitudinal) coordinate. full_basis: bool, optional If true, returns a basis including odd order SH functions as well as even order SH functions. Otherwise returns only even order SH functions. legacy: bool, optional If true, uses DIPY’s legacy descoteaux07 implementation (where |m| for m < 0). Else, implements the basis as defined in Descoteaux et al. 2007. Returns ——- real_sh : real float The real harmonic \(Y^m_l\) sampled at theta and phi. m_values : array of int The phase factor (m) of the harmonics. l_values : array of int The order (l) of the harmonics. References ———- .. [1] Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510.

real_sym_sh_mrtrix

dipy.reconst.shm.real_sym_sh_mrtrix(sh_order_max, theta, phi)

dipy.reconst.shm.real_sym_sh_mrtrix is deprecated, Please use dipy.reconst.shm.real_sh_tournier instead * deprecated from version: 1.3 * Will raise <class ‘dipy.utils.deprecator.ExpiredDeprecationError’> as of version: 2.0 Compute real symmetric spherical harmonics as in Tournier 2007 [2]_, where the real harmonic \(Y^m_l\) is defined to be:: Real(\(Y^m_l\)) if m > 0 \(Y^0_l\) if m = 0 Imag(\(Y^|m|_l\)) if m < 0 This may take scalar or array arguments. The inputs will be broadcast against each other. Parameters ———- sh_order_max : int The maximum order (l) of the spherical harmonic basis. theta : float [0, pi] The polar (colatitudinal) coordinate. phi : float [0, 2*pi] The azimuthal (longitudinal) coordinate. Returns ——- y_mn : real float The real harmonic \(Y^m_l\) sampled at theta and phi as implemented in mrtrix. Warning: the basis is Tournier et al. 2007 [2]_; 2004 [1]_ is slightly different. m_values : array The phase factor (m) of the harmonics. l_values : array The order (l) of the harmonics. References ———- .. [1] Tournier J.D., Calamante F., Gadian D.G. and Connelly A. Direct estimation of the fibre orientation density function from diffusion-weighted MRI data using spherical deconvolution. NeuroImage. 2004;23:1176-1185. .. [2] Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution. NeuroImage. 2007;35(4):1459-1472.

real_sym_sh_basis

dipy.reconst.shm.real_sym_sh_basis(sh_order_max, theta, phi)

Samples a real symmetric spherical harmonic basis at point on the sphere dipy.reconst.shm.real_sym_sh_basis is deprecated, Please use dipy.reconst.shm.real_sh_descoteaux instead * deprecated from version: 1.3 * Will raise <class ‘dipy.utils.deprecator.ExpiredDeprecationError’> as of version: 2.0 Samples the basis functions up to order sh_order_max at points on the sphere given by theta and phi. The basis functions are defined here the same way as in Descoteaux et al. 2007 [1]_ where the real harmonic \(Y^m_l\) is defined to be: Imag(\(Y^m_l\)) * sqrt(2) if m > 0 \(Y^0_l\) if m = 0 Real(\(Y^|m|_l\)) * sqrt(2) if m < 0 This may take scalar or array arguments. The inputs will be broadcast against each other. Parameters ———- sh_order_max : int The maximum order (l) of the spherical harmonic basis. Even int > 0, max spherical harmonic order theta : float [0, 2*pi] The azimuthal (longitudinal) coordinate. phi : float [0, pi] The polar (colatitudinal) coordinate. Returns ——- y_mn : real float The real harmonic \(Y^m_l\) sampled at theta and phi m_values : array of int The phase factor (m) of the harmonics. l_values : array of int The order (l) of the harmonics. References ———- .. [1] Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510.

sph_harm_ind_list

dipy.reconst.shm.sph_harm_ind_list(sh_order_max, full_basis=False)

Returns the order (l) and phase_factor (m) of all the symmetric spherical harmonics of order less then or equal to sh_order_max. The results, m_list and l_list are kx1 arrays, where k depends on sh_order_max. They can be passed to real_sh_descoteaux_from_index() and :func:real_sh_tournier_from_index.

Parameters

sh_order_maxint

The maximum order (l) of the spherical harmonic basis. Even int > 0, max order to return

full_basis: bool, optional

True for SH basis with even and odd order terms

Returns

m_listarray of int

phase factors (m) of even spherical harmonics

l_listarray of int

orders (l) of even spherical harmonics

See Also

shm.real_sh_descoteaux_from_index, shm.real_sh_tournier_from_index

order_from_ncoef

dipy.reconst.shm.order_from_ncoef(ncoef, full_basis=False)

Given a number n of coefficients, calculate back the sh_order_max

Parameters

ncoef: int

number of coefficients

full_basis: bool, optional

True when coefficients are for a full SH basis.

Returns

sh_order_max: int

maximum order (l) of SH basis

smooth_pinv

dipy.reconst.shm.smooth_pinv(B, L)

Regularized pseudo-inverse Computes a regularized least square inverse of B Parameters ———- B : array_like (n, m) Matrix to be inverted L : array_like (m,) Returns ——- inv : ndarray (m, n) regularized least square inverse of B Notes —– In the literature this inverse is often written \((B^{T}B+L^{2})^{-1}B^{T}\). However here this inverse is implemented using the pseudo-inverse because it is more numerically stable than the direct implementation of the matrix product.

lazy_index

dipy.reconst.shm.lazy_index(index)

Produces a lazy index

Returns a slice that can be used for indexing an array, if no slice can be made index is returned as is.

normalize_data

dipy.reconst.shm.normalize_data(data, where_b0, min_signal=1e-05, out=None)

Normalizes the data with respect to the mean b0

hat

dipy.reconst.shm.hat(B)

Returns the hat matrix for the design matrix B

lcr_matrix

dipy.reconst.shm.lcr_matrix(H)

Returns a matrix for computing leveraged, centered residuals from data

if r = (d-Hd), the leveraged centered residuals are lcr = (r/l)-mean(r/l) returns the matrix R, such that lcr = Rd

bootstrap_data_array

dipy.reconst.shm.bootstrap_data_array(data, H, R, permute=None)

Applies the Residual Bootstraps to the data given H and R

data must be normalized, ie 0 < data <= 1

This function, and the bootstrap_data_voxel function, calculate residual-bootstrap samples given a Hat matrix and a Residual matrix. These samples can be used for non-parametric statistics or for bootstrap probabilistic tractography:

References

[1]

J. I. Berman, et al., “Probabilistic streamline q-ball tractography using the residual bootstrap” 2008.

[2]

HA Haroon, et al., “Using the model-based residual bootstrap to quantify uncertainty in fiber orientations from Q-ball analysis” 2009.

[3]

B. Jeurissen, et al., “Probabilistic Fiber Tracking Using the Residual Bootstrap with Constrained Spherical Deconvolution” 2011.

bootstrap_data_voxel

dipy.reconst.shm.bootstrap_data_voxel(data, H, R, permute=None)

Like bootstrap_data_array but faster when for a single voxel

data must be 1d and normalized

sf_to_sh

dipy.reconst.shm.sf_to_sh(sf, sphere, sh_order_max=4, basis_type=None, full_basis=False, legacy=True, smooth=0.0)

Spherical function to spherical harmonics (SH).

Parameters

sfndarray

Values of a function on the given sphere.

sphereSphere

The points on which the sf is defined.

sh_order_maxint, optional

Maximum SH order (l) in the SH fit. For sh_order_max, there will be (sh_order_max + 1) * (sh_order_max + 2) / 2 SH coefficients for a symmetric basis and (sh_order_max + 1) * (sh_order_max + 1) coefficients for a full SH basis.

basis_type{None, ‘tournier07’, ‘descoteaux07’}, optional

None for the default DIPY basis, tournier07 for the Tournier 2007 [2]_[3]_ basis, descoteaux07 for the Descoteaux 2007 [1]_ basis, (None defaults to descoteaux07).

full_basis: bool, optional

True for using a SH basis containing even and odd order SH functions. False for using a SH basis consisting only of even order SH functions.

legacy: bool, optional

True to use a legacy basis definition for backward compatibility with previous tournier07 and descoteaux07 implementations.

smoothfloat, optional

Lambda-regularization in the SH fit.

Returns

shndarray

SH coefficients representing the input function.

References

[1]

Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510.

[2]

Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution. NeuroImage. 2007;35(4):1459-1472.

[3]

Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, Pietsch M, et al. MRtrix3: A fast, flexible and open software framework for medical image processing and visualisation. NeuroImage. 2019 Nov 15;202:116-137.

sh_to_sf

dipy.reconst.shm.sh_to_sf(sh, sphere, sh_order_max=4, basis_type=None, full_basis=False, legacy=True)

Spherical harmonics (SH) to spherical function (SF).

Parameters

shndarray

SH coefficients representing a spherical function.

sphereSphere

The points on which to sample the spherical function.

sh_order_maxint, optional

Maximum SH order (l) in the SH fit. For sh_order_max, there will be (sh_order_max + 1) * (sh_order_max + 2) / 2 SH coefficients for a symmetric basis and (sh_order_max + 1) * (sh_order_max + 1) coefficients for a full SH basis.

basis_type{None, ‘tournier07’, ‘descoteaux07’}, optional

None for the default DIPY basis, tournier07 for the Tournier 2007 [2]_[3]_ basis, descoteaux07 for the Descoteaux 2007 [1]_ basis, (None defaults to descoteaux07).

full_basis: bool, optional

True to use a SH basis containing even and odd order SH functions. Else, use a SH basis consisting only of even order SH functions.

legacy: bool, optional

True to use a legacy basis definition for backward compatibility with previous tournier07 and descoteaux07 implementations.

Returns

sfndarray

Spherical function values on the sphere.

References

[1]

Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510.

[2]

Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution. NeuroImage. 2007;35(4):1459-1472.

[3]

Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, Pietsch M, et al. MRtrix3: A fast, flexible and open software framework for medical image processing and visualisation. NeuroImage. 2019 Nov 15;202:116-137.

sh_to_sf_matrix

dipy.reconst.shm.sh_to_sf_matrix(sphere, sh_order_max=4, basis_type=None, full_basis=False, legacy=True, return_inv=True, smooth=0)

Matrix that transforms Spherical harmonics (SH) to spherical function (SF).

Parameters

sphereSphere

The points on which to sample the spherical function.

sh_order_maxint, optional

Maximum SH order in the SH fit. For sh_order_max, there will be (sh_order_max + 1) * (sh_order_max + 2) / 2 SH coefficients for a symmetric basis and (sh_order_max + 1) * (sh_order_max + 1) coefficients for a full SH basis.

basis_type{None, ‘tournier07’, ‘descoteaux07’}, optional

None for the default DIPY basis, tournier07 for the Tournier 2007 [2]_[3]_ basis, descoteaux07 for the Descoteaux 2007 [1]_ basis, (None defaults to descoteaux07).

full_basis: bool, optional

If True, uses a SH basis containing even and odd order SH functions. Else, uses a SH basis consisting only of even order SH functions.

legacy: bool, optional

True to use a legacy basis definition for backward compatibility with previous tournier07 and descoteaux07 implementations.

return_invbool, optional

If True then the inverse of the matrix is also returned.

smoothfloat, optional

Lambda-regularization in the SH fit.

Returns

Bndarray

Matrix that transforms spherical harmonics to spherical function sf = np.dot(sh, B).

invBndarray

Inverse of B.

References

[1]

Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510.

[2]

Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution. NeuroImage. 2007;35(4):1459-1472.

[3]

Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, Pietsch M, et al. MRtrix3: A fast, flexible and open software framework for medical image processing and visualisation. NeuroImage. 2019 Nov 15;202:116-137.

calculate_max_order

dipy.reconst.shm.calculate_max_order(n_coeffs, full_basis=False)

Calculate the maximal harmonic order (l), given that you know the number of parameters that were estimated. Parameters ———- n_coeffs : int The number of SH coefficients full_basis: bool, optional True if the used SH basis contains even and odd order SH functions. False if the SH basis consists only of even order SH functions. Returns ——- L : int The maximal SH order (l), given the number of coefficients Notes —– The calculation in this function for the symmetric SH basis proceeds according to the following logic: .. math:: n = frac{1}{2} (L+1) (L+2) rarrow 2n = L^2 + 3L + 2 rarrow L^2 + 3L + 2 - 2n = 0 rarrow L^2 + 3L + 2(1-n) = 0 rarrow L_{1,2} = frac{-3 pm sqrt{9 - 8 (1-n)}}{2} rarrow L{1,2} = frac{-3 pm sqrt{1 + 8n}}{2} Finally, the positive value is chosen between the two options. For a full SH basis, the calculation consists in solving the equation \(n = (L + 1)^2\) for \(L\), which gives \(L = sqrt(n) - 1\).

anisotropic_power

dipy.reconst.shm.anisotropic_power(sh_coeffs, norm_factor=1e-05, power=2, non_negative=True)

Calculate anisotropic power map with a given SH coefficient matrix. Parameters ———- sh_coeffs : ndarray A ndarray where the last dimension is the SH coefficients estimates for that voxel. norm_factor: float, optional The value to normalize the ap values. power : int, optional The degree to which power maps are calculated. non_negative: bool, optional Whether to rectify the resulting map to be non-negative. Returns ——- log_ap : ndarray The log of the resulting power image. Notes —– Calculate AP image based on a IxJxKxC SH coefficient matrix based on the equation: .. math:: AP = sum_{l=2,4,6,…}{frac{1}{2l+1} sum_{m=-l}^l{|a_{l,m}|^n}} Where the last dimension, C, is made of a flattened array of \(l`x:math:`m\) coefficients, where \(l\) are the SH orders, and \(m = 2l+1\), So l=1 has 1 coefficient, l=2 has 5, … l=8 has 17 and so on. A l=2 SH coefficient matrix will then be composed of a IxJxKx6 volume. The power, \(n\) is usually set to \(n=2\). The final AP image is then shifted by -log(norm_factor), to be strictly non-negative. Remaining values < 0 are discarded (set to 0), per default, and this option is controlled through the non_negative keyword argument. References ———- .. [1] Dell’Acqua, F., Lacerda, L., Catani, M., Simmons, A., 2014. Anisotropic Power Maps: A diffusion contrast to reveal low anisotropy tissues from HARDI data, in: Proceedings of International Society for Magnetic Resonance in Medicine. Milan, Italy.

convert_sh_to_full_basis

dipy.reconst.shm.convert_sh_to_full_basis(sh_coeffs)

Given an array of SH coeffs from a symmetric basis, returns the coefficients for the full SH basis by filling odd order SH coefficients with zeros

Parameters

sh_coeffs: ndarray

A ndarray where the last dimension is the SH coefficients estimates for that voxel.

Returns

full_sh_coeffs: ndarray

A ndarray where the last dimension is the SH coefficients estimates for that voxel in a full SH basis.

convert_sh_from_legacy

dipy.reconst.shm.convert_sh_from_legacy(sh_coeffs, sh_basis, full_basis=False)

Convert SH coefficients in legacy SH basis to SH coefficients of the new SH basis for descoteaux07 [1]_ or tournier07 [2]_[3]_ bases.

Parameters

sh_coeffs: ndarray

A ndarray where the last dimension is the SH coefficients estimates for that voxel.

sh_basis: {‘descoteaux07’, ‘tournier07’}

tournier07 for the Tournier 2007 [2]_[3]_ basis, descoteaux07 for the Descoteaux 2007 [1]_ basis.

full_basis: bool, optional

True if the input SH basis includes both even and odd order SH functions, else False.

Returns

out_sh_coeffs: ndarray

The array of coefficients expressed in the new SH basis.

References

[1]

Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510.

[2]

Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution. NeuroImage. 2007;35(4):1459-1472.

[3]

Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, Pietsch M, et al. MRtrix3: A fast, flexible and open software framework for medical image processing and visualisation. NeuroImage. 2019 Nov 15;202:116-137.

convert_sh_to_legacy

dipy.reconst.shm.convert_sh_to_legacy(sh_coeffs, sh_basis, full_basis=False)

Convert SH coefficients in new SH basis to SH coefficients for the legacy SH basis for descoteaux07 [1]_ or tournier07 [2]_[3]_ bases.

Parameters

sh_coeffs: ndarray

A ndarray where the last dimension is the SH coefficients estimates for that voxel.

sh_basis: {‘descoteaux07’, ‘tournier07’}

tournier07 for the Tournier 2007 [2]_[3]_ basis, descoteaux07 for the Descoteaux 2007 [1]_ basis.

full_basis: bool, optional

True if the input SH basis includes both even and odd order SH functions.

Returns

out_sh_coeffs: ndarray

The array of coefficients expressed in the legacy SH basis.

References

[1]

Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510.

[2]

Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution. NeuroImage. 2007;35(4):1459-1472.

[3]

Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, Pietsch M, et al. MRtrix3: A fast, flexible and open software framework for medical image processing and visualisation. NeuroImage. 2019 Nov 15;202:116-137.

convert_sh_descoteaux_tournier

dipy.reconst.shm.convert_sh_descoteaux_tournier(sh_coeffs)

Convert SH coefficients between legacy-descoteaux07 and tournier07.

Convert SH coefficients between the legacy descoteaux07 SH basis and the non-legacy tournier07 SH basis. Because this conversion is equal to its own inverse, it can be used to convert in either direction: legacy-descoteaux to non-legacy-tournier or non-legacy-tournier to legacy-descoteaux.

This can be used to convert SH representations between DIPY and MRtrix3.

See [descoteaux07] and [tournier19] for the origin of these SH bases. See [mrtrixbasis] for a description of the basis used in MRtrix3. See [mrtrixdipybases] for more details on the conversion.

Parameters

sh_coeffs: ndarray

A ndarray where the last dimension is the SH coefficients estimates for that voxel.

Returns

out_sh_coeffs: ndarray

The array of coefficients expressed in the “other” SH basis. If the input was in the legacy-descoteaux basis then the output will be in the non-legacy-tournier basis, and vice versa.

References

[descoteaux07]

Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510.

[tournier19]

Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, Pietsch M, et al. MRtrix3: A fast, flexible and open software framework for medical image processing and visualisation. NeuroImage. 2019 Nov 15;202:116-137.

[mrtrixbasis]

https://mrtrix.readthedocs.io/en/latest/concepts/spherical_harmonics.html

[mrtrixdipybases]

dipy/dipy#2959

ShoreModel

class dipy.reconst.shore.ShoreModel(gtab, radial_order=6, zeta=700, lambdaN=1e-08, lambdaL=1e-08, tau=0.025330295910584444, constrain_e0=False, positive_constraint=False, pos_grid=11, pos_radius=0.02, cvxpy_solver=None)

Bases: Cache

Simple Harmonic Oscillator based Reconstruction and Estimation (SHORE) [1]_ of the diffusion signal. The main idea is to model the diffusion signal as a linear combination of continuous functions \(\phi_i\), ..math:: :nowrap: begin{equation} S(mathbf{q})= sum_{i=0}^I c_{i} phi_{i}(mathbf{q}). end{equation} where \(\mathbf{q}\) is the wave vector which corresponds to different gradient directions. Numerous continuous functions \(\phi_i\) can be used to model \(S\). Some are presented in [2,3,4]_. From the \(c_i\) coefficients, there exist analytical formulae to estimate the ODF, the return to the origin probability (RTOP), the mean square displacement (MSD), amongst others [5]_. References ———- .. [1] Ozarslan E. et al., “Simple harmonic oscillator based reconstruction and estimation for one-dimensional q-space magnetic resonance 1D-SHORE)”, Proc Intl Soc Mag Reson Med, vol. 16, p. 35., 2008. .. [2] Merlet S. et al., “Continuous diffusion signal, EAP and ODF estimation via Compressive Sensing in diffusion MRI”, Medical Image Analysis, 2013. .. [3] Rathi Y. et al., “Sparse multi-shell diffusion imaging”, MICCAI, 2011. .. [4] Cheng J. et al., “Theoretical Analysis and Practical Insights on EAP Estimation via a Unified HARDI Framework”, MICCAI workshop on Computational Diffusion MRI, 2011. .. [5] Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013. Notes —– The implementation of SHORE depends on CVXPY (https://www.cvxpy.org/).

__init__(gtab, radial_order=6, zeta=700, lambdaN=1e-08, lambdaL=1e-08, tau=0.025330295910584444, constrain_e0=False, positive_constraint=False, pos_grid=11, pos_radius=0.02, cvxpy_solver=None)

Analytical and continuous modeling of the diffusion signal with respect to the SHORE basis [1,2]_. This implementation is a modification of SHORE presented in [1]_. The modification was made to obtain the same ordering of the basis presented in [2,3]_. The main idea is to model the diffusion signal as a linear combination of continuous functions \(\phi_i\), ..math:: :nowrap: begin{equation} S(mathbf{q})= sum_{i=0}^I c_{i} phi_{i}(mathbf{q}). end{equation} where \(\mathbf{q}\) is the wave vector which corresponds to different gradient directions. From the \(c_i\) coefficients, there exists an analytical formula to estimate the ODF. Parameters ———- gtab : GradientTable, gradient directions and bvalues container class radial_order : unsigned int, an even integer that represent the order of the basis zeta : unsigned int, scale factor lambdaN : float, radial regularisation constant lambdaL : float, angular regularisation constant tau : float, diffusion time. By default the value that makes q equal to the square root of the b-value. constrain_e0 : bool, Constrain the optimization such that E(0) = 1. positive_constraint : bool, Constrain the propagator to be positive. pos_grid : int, Grid that define the points of the EAP in which we want to enforce positivity. pos_radius : float, Radius of the grid of the EAP in which enforce positivity in millimeters. By default 20e-03 mm. cvxpy_solver : str, optional cvxpy solver name. Optionally optimize the positivity constraint with a particular cvxpy solver. See https://www.cvxpy.org/ for details. Default: None (cvxpy chooses its own solver) References ———- .. [1] Merlet S. et al., “Continuous diffusion signal, EAP and ODF estimation via Compressive Sensing in diffusion MRI”, Medical Image Analysis, 2013. .. [2] Cheng J. et al., “Theoretical Analysis and Practical Insights on EAP Estimation via a Unified HARDI Framework”, MICCAI workshop on Computational Diffusion MRI, 2011. .. [3] Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013. Examples ——– In this example, where the data, gradient table and sphere tessellation used for reconstruction are provided, we model the diffusion signal with respect to the SHORE basis and compute the real and analytical ODF. >>> import warnings >>> from dipy.data import get_isbi2013_2shell_gtab, default_sphere >>> from dipy.sims.voxel import sticks_and_ball >>> from dipy.reconst.shm import descoteaux07_legacy_msg >>> from dipy.reconst.shore import ShoreModel >>> gtab = get_isbi2013_2shell_gtab() >>> data, golden_directions = sticks_and_ball( … gtab, d=0.0015, S0=1., angles=[(0, 0), (90, 0)], … fractions=[50, 50], snr=None) … >>> radial_order = 4 >>> zeta = 700 >>> asm = ShoreModel(gtab, radial_order=radial_order, zeta=zeta, … lambdaN=1e-8, lambdaL=1e-8) >>> with warnings.catch_warnings(): … warnings.filterwarnings( … “ignore”, message=descoteaux07_legacy_msg, … category=PendingDeprecationWarning) … asmfit = asm.fit(data) … odf = asmfit.odf(default_sphere)

fit(data, mask=None)

Fit method for every voxel in data

ShoreFit

class dipy.reconst.shore.ShoreFit(model, shore_coef)

Bases: object

__init__(model, shore_coef)

Calculates diffusion properties for a single voxel

Parameters

modelobject,

AnalyticalModel

shore_coef1d ndarray,

shore coefficients

fitted_signal()

The fitted signal.

msd()

Calculates the analytical mean squared displacement (MSD) [1]_ ..math:: :nowrap: begin{equation} MSD:{DSI}=int_{-infty}^{infty}int_{-infty}^{infty} int_{-infty}^{infty} P(hat{mathbf{r}}) cdot hat{mathbf{r}}^{2} dr_x dr_y dr_z end{equation} where \(\hat{\mathbf{r}}\) is a point in the 3D propagator space (see Wu et al. [1]_). References ———- .. [1] Wu Y. et al., “Hybrid diffusion imaging”, NeuroImage, vol 36, p. 617-629, 2007.

odf(sphere)

Calculates the ODF for a given discrete sphere.

odf_sh()

Calculates the real analytical ODF in terms of Spherical Harmonics.

pdf(r_points)

Diffusion propagator on a given set of real points. if the array r_points is non writeable, then intermediate results are cached for faster recalculation

pdf_grid(gridsize, radius_max)

Applies the analytical FFT on \(S\) to generate the diffusion propagator. This is calculated on a discrete 3D grid in order to obtain an EAP similar to that which is obtained with DSI. Parameters ———- gridsize : unsigned int dimension of the propagator grid radius_max : float maximal radius in which to compute the propagator Returns ——- eap : ndarray the ensemble average propagator in the 3D grid

rtop_pdf()

Calculates the analytical return to origin probability (RTOP) from the pdf [1]_.

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

rtop_signal()

Calculates the analytical return to origin probability (RTOP) from the signal [1]_.

References

[1]

Ozarslan E. et al., “Mean apparent propagator (MAP) MRI: A novel

diffusion imaging method for mapping tissue microstructure”, NeuroImage, 2013.

property shore_coeff

The SHORE coefficients

shore_matrix

dipy.reconst.shore.shore_matrix(radial_order, zeta, gtab, tau=0.025330295910584444)

Compute the SHORE matrix for modified Merlet’s 3D-SHORE [1]_ ..math:: :nowrap: begin{equation} textbf{E}(qtextbf{u})=sum_{l=0, even}^{N_{max}} sum_{n=l}^{(N_{max}+l)/2} sum_{m=-l}^l c_{nlm} phi_{nlm}(qtextbf{u}) end{equation} where \(\phi_{nlm}\) is ..math:: :nowrap: begin{equation} phi_{nlm}^{SHORE}(qtextbf{u})=Biggl[dfrac{2(n-l)!} {zeta^{3/2} Gamma(n+3/2)} Biggr]^{1/2} Biggl(dfrac{q^2}{zeta}Biggr)^{l/2} expBiggl(dfrac{-q^2}{2zeta}Biggr) L^{l+1/2}_{n-l} Biggl(dfrac{q^2}{zeta}Biggr) Y_l^m(textbf{u}). end{equation} Parameters ———- radial_order : unsigned int, an even integer that represent the order of the basis zeta : unsigned int, scale factor gtab : GradientTable, gradient directions and bvalues container class tau : float, diffusion time. By default the value that makes q=sqrt(b). References ———- .. [1] Merlet S. et al., “Continuous diffusion signal, EAP and ODF estimation via Compressive Sensing in diffusion MRI”, Medical Image Analysis, 2013.

shore_matrix_pdf

dipy.reconst.shore.shore_matrix_pdf(radial_order, zeta, rtab)

Compute the SHORE propagator matrix [1]_”

Parameters

radial_orderunsigned int,

an even integer that represent the order of the basis

zetaunsigned int,

scale factor

rtabarray, shape (N,3)

real space points in which calculates the pdf

References

[1]

Merlet S. et al., “Continuous diffusion signal, EAP and

ODF estimation via Compressive Sensing in diffusion MRI”, Medical Image Analysis, 2013.

shore_matrix_odf

dipy.reconst.shore.shore_matrix_odf(radial_order, zeta, sphere_vertices)

Compute the SHORE ODF matrix [1]_”

Parameters

radial_orderunsigned int,

an even integer that represent the order of the basis

zetaunsigned int,

scale factor

sphere_verticesarray, shape (N,3)

vertices of the odf sphere

References

[1]

Merlet S. et al., “Continuous diffusion signal, EAP and

ODF estimation via Compressive Sensing in diffusion MRI”, Medical Image Analysis, 2013.

l_shore

dipy.reconst.shore.l_shore(radial_order)

Returns the angular regularisation matrix for SHORE basis

n_shore

dipy.reconst.shore.n_shore(radial_order)

Returns the angular regularisation matrix for SHORE basis

create_rspace

dipy.reconst.shore.create_rspace(gridsize, radius_max)

Create the real space table, that contains the points in which

to compute the pdf.

Parameters

gridsizeunsigned int

dimension of the propagator grid

radius_maxfloat

maximal radius in which compute the propagator

Returns

vecsarray, shape (N,3)

positions of the pdf points in a 3D matrix

tabarray, shape (N,3)

real space points in which calculates the pdf

shore_indices

dipy.reconst.shore.shore_indices(radial_order, index)

Given the basis order and the index, return the shore indices n, l, m for modified Merlet’s 3D-SHORE ..math:: :nowrap: begin{equation} textbf{E}(qtextbf{u})=sum_{l=0, even}^{N_{max}} sum_{n=l}^{(N_{max}+l)/2} sum_{m=-l}^l c_{nlm} phi_{nlm}(qtextbf{u}) end{equation} where \(\phi_{nlm}\) is ..math:: :nowrap: begin{equation} phi_{nlm}^{SHORE}(qtextbf{u})=Biggl[dfrac{2(n-l)!} {zeta^{3/2} Gamma(n+3/2)} Biggr]^{1/2} Biggl(dfrac{q^2}{zeta}Biggr)^{l/2} expBiggl(dfrac{-q^2}{2zeta}Biggr) L^{l+1/2}_{n-l} Biggl(dfrac{q^2}{zeta}Biggr) Y_l^m(textbf{u}). end{equation} Parameters ———- radial_order : unsigned int an even integer that represent the maximal order of the basis index : unsigned int index of the coefficients, start from 0 Returns ——- n : unsigned int the index n of the modified shore basis l : unsigned int the index l of the modified shore basis m : unsigned int the index m of the modified shore basis

shore_order

dipy.reconst.shore.shore_order(n, l, m)

Given the indices (n,l,m) of the basis, return the minimum order for those indices and their index for modified Merlet’s 3D-SHORE.

Parameters

nunsigned int

the index n of the modified shore basis

lunsigned int

the index l of the modified shore basis

munsigned int

the index m of the modified shore basis

Returns

radial_orderunsigned int

an even integer that represent the maximal order of the basis

indexunsigned int

index of the coefficient corresponding to (n,l,m), start from 0

dki_design_matrix

dipy.reconst.utils.dki_design_matrix(gtab)

Construct B design matrix for DKI.

Parameters

gtabGradientTable

Measurement directions.

Returns

Barray (N, 22)

Design matrix or B matrix for the DKI model B[j, :] = (Bxx, Bxy, Byy, Bxz, Byz, Bzz,

Bxxxx, Byyyy, Bzzzz, Bxxxy, Bxxxz, Bxyyy, Byyyz, Bxzzz, Byzzz, Bxxyy, Bxxzz, Byyzz, Bxxyz, Bxyyz, Bxyzz, BlogS0)

cti_design_matrix

dipy.reconst.utils.cti_design_matrix(gtab1, gtab2)

Construct B design matrix for CTI.

Parameters

gtab1: dipy.core.gradients.GradientTable

A GradientTable class instance for first DDE diffusion epoch

gtab2: dipy.core.gradients.GradientTable

A GradientTable class instance for second DDE diffusion epoch

Returns

B: array(N, 43) Design matrix or B matrix for the CTI model assuming multiple Gaussian Components

convert_tensors

dipy.reconst.utils.convert_tensors(tensor, from_format, to_format)

Convert tensors from one format to another.

Parameters

tensorndarray

Input tensor.

from_formatstr

Format of the input tensor. Options: ‘dipy’, ‘mrtrix’, ‘ants’, ‘fsl’.

to_formatstr

Format of the output tensor. Options: ‘dipy’, ‘mrtrix’, ‘ants’, ‘fsl’.

Notes

• DIPY order: [Dxx, Dxy, Dyy, Dxz, Dyz, Dzz]. Shape: [i, j , k, 6]. See: dipy/dipy

• MRTRIX order: [Dxx, Dyy, Dzz, Dxy, Dxz, Dyz]

  Shape: [i, j , k, 6]. See: https://mrtrix.readthedocs.io/en/dev/reference/commands/dwi2tensor.html # noqa

• ANTS: [Dxx, Dxy, Dyy, Dxz, Dyz, Dzz].

  Shape: [i, j , k, 1, 6] - Note the extra dimension (5D) See: ANTsX/ANTs # noqa

• FSL: [Dxx, Dxy, Dxz, Dyy, Dyz, Dzz] Shape: [i, j , k, 6]. (Also used for the Fibernavigator) Ref: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT/UserGuide

vec_val_vect

dipy.reconst.vec_val_sum.vec_val_vect(vecs, vals)

Vectorize vecs.diag(vals).`vecs`.T for last 2 dimensions of vecs

Parameters

vecsshape (…, M, N) array

containing tensor in last two dimensions; M, N usually equal to (3, 3)

valsshape (…, N) array

diagonal values carried in last dimension, ... shape above must match that for vecs

Returns

resshape (…, M, M) array

For all the dimensions ellided by ..., loops to get (M, N) vec matrix, and (N,) vals vector, and calculates vec.dot(np.diag(val).dot(vec.T).

Raises

ValueError : non-matching ... dimensions of vecs, vals ValueError : non-matching N dimensions of vecs, vals

Examples

Make a 3D array where the first dimension is only 1

>>> vecs = np.arange(9).reshape((1, 3, 3))
>>> vals = np.arange(3).reshape((1, 3))
>>> vec_val_vect(vecs, vals)
array([[[   9.,   24.,   39.],
        [  24.,   66.,  108.],
        [  39.,  108.,  177.]]])

That’s the same as the 2D case (apart from the float casting):

>>> vecs = np.arange(9).reshape((3, 3))
>>> vals = np.arange(3)
>>> np.dot(vecs, np.dot(np.diag(vals), vecs.T))
array([[  9,  24,  39],
       [ 24,  66, 108],
       [ 39, 108, 177]])