qsiprep.utils.brainsuite_shore module

class qsiprep.utils.brainsuite_shore.BrainSuiteShoreFit(model, shore_coef, regularization=0, alpha=0.0, r2=0.0, cnr=0.0)

Bases: object

__init__(model, shore_coef, regularization=0, alpha=0.0, r2=0.0, cnr=0.0)

Calculate diffusion properties for a single voxel.

Parameters:

• model (object) – AnalyticalModel.

• shore_coef (1d ndarray) – Shore coefficients.

• regularization (int, optional) – Regularization used for fitting coefficients (1 for L1, 2 for L2).

• alpha (float, optional) – The alpha used for the L1 fit.

• r2 (float, optional) – Model r^2.

• cnr (float, optional) – Contrast to noise ratio.

property alpha

The alpha used for the L1 fit.

property cnr

Contrast to Noise ratio.

fitted_signal()

Return the fitted signal.

msd()

Calculate 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,

16. 617-629, 2007.

odf(sphere)

Calculate the ODF for a given discrete sphere.

odf_sh()

Calculate the real analytical ODF in terms of Spherical Harmonics.

pdf(r_points)

Compute the 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)

Apply 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 (int) – Dimension of the propagator grid.

• radius_max (float) – Maximal radius in which to compute the propagator.

Returns:

eap – The ensemble average propagator in the 3D grid.

Return type:

ndarray

predict(gtab, S0=100.0)

Recover the reconstructed signal for any qvalue array or gradient table.

property r2

Model r^2.

property regularization

Regularization used for fitting coefficients.

rtop_pdf()

Calculate 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()

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

class qsiprep.utils.brainsuite_shore.BrainSuiteShoreModel(gtab, regularization='L1', radial_order=6, zeta=700, tau=0.025330295910584444, lambdaN=1e-08, lambdaL=1e-08, regularization_weighting='CV', l1_positive_constraint=False, l1_cv=3, l1_maxiter=1000, l1_verbose=False, l1_alpha=1.0, pos_grid=11, pos_radius=0.02)

Bases: Cache

BrainSuite SHORE model of the diffusion signal.

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$. This specifically comes from [1].

Notes

The implementation of SHORE depends on CVXPY (http://www.cvxpy.org/).

References

[1]

Merlet S. et al., “Continuous diffusion signal, EAP and ODF estimation via Compressive Sensing in diffusion MRI”, Medical Image Analysis, 2013.

__init__(gtab, regularization='L1', radial_order=6, zeta=700, tau=0.025330295910584444, lambdaN=1e-08, lambdaL=1e-08, regularization_weighting='CV', l1_positive_constraint=False, l1_cv=3, l1_maxiter=1000, l1_verbose=False, l1_alpha=1.0, pos_grid=11, pos_radius=0.02)

Initialize the BrainSuite SHORE model.

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.

• regularization ({‘L1’, ‘L2’}, optional) – Regularization used to fit the SHORE coefficients. An L1 fit that fails to converge falls back to L2.

• radial_order (int, optional) – An even integer that represent the order of the basis.

• zeta (int, optional) – Scale factor.

• tau (float, optional) – Diffusion time. By default the value that makes q equal to the square root of the b-value.

• lambdaN (float, optional) – Radial regularisation constant (L2 method).

• lambdaL (float, optional) – Angular regularisation constant (L2 method).

• regularization_weighting (str, optional) – How the L1 penalty weight is chosen. 'CV' selects it by cross-validation; any other value uses l1_alpha.

• l1_positive_constraint (bool, optional) – Whether to constrain the L1 coefficients to be positive.

• l1_cv (int, optional) – Number of cross-validation folds for the L1 fit.

• l1_maxiter (int, optional) – Maximum number of iterations for the L1 fit.

• l1_verbose (bool, optional) – Verbosity of the cross-validated L1 fit.

• l1_alpha (float, optional) – L1 penalty weight, used when regularization_weighting is not 'CV'.

• pos_grid (int, optional) – Grid that define the points of the EAP in which we want to enforce positivity.

• pos_radius (float, optional) – Radius of the grid of the EAP in which enforce positivity in millimeters. By default 20e-03 mm.

References

[1]

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 get_data,get_sphere sphere = get_sphere(‘symmetric724’) fimg, fbvals, fbvecs = get_data(‘ISBI_testing_2shells_table’) bvals, bvecs = read_bvals_bvecs(fbvals, fbvecs) gtab = gradient_table(bvals, bvecs) from dipy.sims.voxel import SticksAndBall data, golden_directions = SticksAndBall(

gtab, d=0.0015, S0=1., angles=[(0, 0), (90, 0)], fractions=[50, 50], snr=None)

from dipy.reconst.canal import ShoreModel radial_order = 4 zeta = 700 asm = ShoreModel(gtab, radial_order=radial_order, zeta=zeta,

lambdaN=1e-8, lambdaL=1e-8)

asmfit = asm.fit(data) odf= asmfit.odf(sphere)

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

Fit method for every voxel in data

qsiprep.utils.brainsuite_shore.brainsuite_shore_basis(radial_order, zeta, gtab, tau=0.025330295910584444)

Calculate the brainsuite shore basis functions.

qsiprep.utils.brainsuite_shore.brainsuite_shore_matrix_pdf(radial_order, zeta, rtab)

Compute the SHORE propagator matrix [1]_.

Parameters:

• radial_order (int) – An even integer that represent the order of the basis.

• zeta (int) – Scale factor.

• rtab (array, 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.

qsiprep.utils.brainsuite_shore.create_rspace(gridsize, radius_max)

Create the real space table, that contains the points in which to compute the pdf.

Parameters:

• gridsize (int) – Dimension of the propagator grid.

• radius_max (float) – Maximal radius in which compute the propagator.

Returns:

• vecs (array, shape (N,3)) – Positions of the pdf points in a 3D matrix.

• tab (array, shape (N,3)) – Real space points in which calculates the pdf.

qsiprep.utils.brainsuite_shore.shore_index_matrix(radial_order)

qsiprep.utils.brainsuite_shore.shore_matrix_odf(radial_order, zeta, sphere_vertices)

Compute the SHORE ODF matrix [1]_.

Parameters:

• radial_order (int) – An even integer that represent the order of the basis.

• zeta (int) – Scale factor.

• sphere_vertices (array, 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.

qsiprep.utils.brainsuite_shore.shore_matrix_pdf(radial_order, zeta, rtab)