`sims`#

Module: `sims.phantom`#

`add_noise`(vol, *[, snr, S0, noise_type, rng])	Add noise of specified distribution to a 4D array.
`diff2eigenvectors`(dx, dy, dz)	numerical derivatives 2 eigenvectors
`orbital_phantom`(*[, gtab, evals, func, t, ...])	Create a phantom based on a 3-D orbit `f(t) -> (x,y,z)`.

Module: `sims.voxel`#

`add_noise`(signal, snr, S0, *[, noise_type, rng])	Add noise of specified distribution to the signal from a single voxel.
`sticks_and_ball`(gtab, *[, d, S0, angles, ...])	Simulate the signal for a Sticks & Ball model.
`callaghan_perpendicular`(q, radius)	Calculates the perpendicular diffusion signal E(q) in a cylinder of radius R using the Soderman model.
`gaussian_parallel`(q, tau, *[, D])	Calculates the parallel Gaussian diffusion signal.
`cylinders_and_ball_soderman`(gtab, tau, *[, ...])	Calculates the three-dimensional signal attenuation E(q) originating from within a cylinder of radius R using the Soderman approximation.
`single_tensor`(gtab[, S0, evals, evecs, snr, rng])	Simulate diffusion-weighted signals with a single tensor.
`multi_tensor`(gtab, mevals, *[, S0, angles, ...])	Simulate a Multi-Tensor signal.
`multi_tensor_dki`(gtab, mevals, *[, S0, ...])	Simulate the diffusion-weight signal, diffusion and kurtosis tensors based on the DKI model
`kurtosis_element`(D_comps, frac, ind_i, ...)	Computes the diffusion kurtosis tensor element (with indexes i, j, k and l) based on the individual diffusion tensor components of a multicompartmental model.
`dki_signal`(gtab, dt, kt, *[, S0, snr])	Simulated signal based on the diffusion and diffusion kurtosis tensors of a single voxel.
`single_tensor_odf`(r, *[, evals, evecs])	Simulated ODF with a single tensor.
`all_tensor_evecs`(e0)	Given the principle tensor axis, return the array of all eigenvectors column-wise (or, the rotation matrix that orientates the tensor).
`multi_tensor_odf`(odf_verts, mevals, angles, ...)	Simulate a Multi-Tensor ODF.
`single_tensor_rtop`(*[, evals, tau])	Simulate a Single-Tensor rtop.
`multi_tensor_rtop`(mf, *[, mevals, tau])	Simulate a Multi-Tensor rtop.
`single_tensor_pdf`(r, *[, evals, evecs, tau])	Simulated ODF with a single tensor.
`multi_tensor_pdf`(pdf_points, mevals, angles, ...)	Simulate a Multi-Tensor ODF.
`single_tensor_msd`(*[, evals, tau])	Simulate a Multi-Tensor rtop.
`multi_tensor_msd`(mf, *[, mevals, tau])	Simulate a Multi-Tensor rtop.

add_noise#

dipy.sims.phantom.add_noise(vol, *, snr=1.0, S0=None, noise_type='rician', rng=None)[source]#

Add noise of specified distribution to a 4D array.

Parameters:

volarray, shape (X,Y,Z,W): Diffusion measurements in W directions at each (X, Y, Z) voxel position.
snrfloat, optional: The desired signal-to-noise ratio. (See notes below.)
S0float, optional: Reference signal for specifying snr.
noise_typestring, optional: The distribution of noise added. Can be either ‘gaussian’ for Gaussian distributed noise, ‘rician’ for Rice-distributed noise (default) or ‘rayleigh’ for a Rayleigh distribution.
rngnumpy.random.Generator class, optional: Numpy’s random generator for setting seed values when needed.

Returns:

volarray, same shape as vol: Volume with added noise.

Notes

SNR is defined here, following [1], as S0 / sigma, where sigma is the standard deviation of the two Gaussian distributions forming the real and imaginary components of the Rician noise distribution (see [2]).

References

Examples

>>> signal = np.arange(800).reshape(2, 2, 2, 100)
>>> signal_w_noise = add_noise(signal, snr=10, noise_type='rician')

diff2eigenvectors#

dipy.sims.phantom.diff2eigenvectors(dx, dy, dz)[source]#: numerical derivatives 2 eigenvectors

orbital_phantom#

dipy.sims.phantom.orbital_phantom(*, gtab=None, evals=array([0.0015, 0.0004, 0.0004]), func=None, t=None, datashape=(64, 64, 64, 65), origin=(32, 32, 32), scale=(25, 25, 25), angles=None, radii=None, S0=100.0, snr=None, rng=None)[source]#

Create a phantom based on a 3-D orbit f(t) -> (x,y,z).

Parameters:

gtabGradientTable: Gradient table of measurement directions.
evalsarray, shape (3,): Tensor eigenvalues.
funcuser defined function f(t)->(x,y,z): It could be desirable for -1=<x,y,z <=1. If None creates a circular orbit.
tarray, shape (K,): Represents time for the orbit. Default is np.linspace(0, 2 * np.pi, 1000).
datashapearray, shape (X,Y,Z,W): Size of the output simulated data
origintuple, shape (3,): Define the center for the volume
scaletuple, shape (3,): Scale the function before applying to the grid
anglesarray, shape (L,): Density angle points, always perpendicular to the first eigen vector Default np.linspace(0, 2 * np.pi, 32).
radiiarray, shape (M,): Thickness radii. Default np.linspace(0.2, 2, 6). angles and radii define the total thickness options
S0double, optional: Maximum simulated signal. Default 100.
snrfloat, optional: The signal to noise ratio set to apply Rician noise to the data. Default is to not add noise at all.
rngnumpy.random.Generator class, optional: Numpy’s random generator for setting seed values when needed. Default is None.

Returns:

dataarray, shape (datashape)

add_noise#

dipy.sims.voxel.add_noise(signal, snr, S0, *, noise_type='rician', rng=None)[source]#

Add noise of specified distribution to the signal from a single voxel.

Parameters:

signal1-d ndarray: The signal in the voxel.
snrfloat: The desired signal-to-noise ratio. (See notes below.) If snr is None, return the signal as-is.
S0float: Reference signal for specifying snr.
noise_typestring, optional: The distribution of noise added. Can be either ‘gaussian’ for Gaussian distributed noise, ‘rician’ for Rice-distributed noise (default) or ‘rayleigh’ for a Rayleigh distribution.
rngnumpy.random.Generator, optional: Random number generator for the noise. If None, uses NumPy’s default random generator.

Returns:

signalarray, same shape as the input: Signal with added noise.

Notes

SNR is defined here, following [1], as S0 / sigma, where sigma is the standard deviation of the two Gaussian distributions forming the real and imaginary components of the Rician noise distribution (see [2]).

References

Examples

>>> signal = np.arange(800).reshape(2, 2, 2, 100)
>>> signal_w_noise = add_noise(signal, 10., 100., noise_type='rician')

sticks_and_ball#

dipy.sims.voxel.sticks_and_ball(gtab, *, d=0.0015, S0=1.0, angles=((0, 0), (90, 0)), fractions=(35, 35), snr=20)[source]#

Simulate the signal for a Sticks & Ball model.

See [3] for a definition of the Sticks & Ball model.

Parameters:

gtabGradientTable: Signal measurement directions.
dfloat, optional: Diffusivity value.
S0float, optional: Unweighted signal value.
anglesarray (K, 2) or (K, 3), optional: List of K polar angles (in degrees) for the sticks or array of K sticks as unit vectors.
fractionsarray-like, optional: Percentage of each stick. Remainder to 100 specifies isotropic component.
snrfloat, optional: Signal to noise ratio, assuming Rician noise. If set to None, no noise is added.

Returns:

S(N,) ndarray: Simulated signal.
sticks(M,3): Sticks in cartesian coordinates.

References

callaghan_perpendicular#

dipy.sims.voxel.callaghan_perpendicular(q, radius)[source]#

Calculates the perpendicular diffusion signal E(q) in a cylinder of radius R using the Soderman model.

Assumes that the pulse length is infinitely short and the diffusion time is infinitely long.

See [4] for details about the Soderman model.

Parameters:

qarray, shape (N,): q-space value in 1/mm
radiusfloat: cylinder radius in mm

Returns:

Earray, shape (N,): signal attenuation

References

gaussian_parallel#

dipy.sims.voxel.gaussian_parallel(q, tau, *, D=0.0007)[source]#

Calculates the parallel Gaussian diffusion signal.

Parameters:

qarray, shape (N,): q-space value in 1/mm
taufloat: diffusion time in s
Dfloat, optional: diffusion constant

Returns:

Earray, shape (N,): signal attenuation

cylinders_and_ball_soderman#

dipy.sims.voxel.cylinders_and_ball_soderman(gtab, tau, *, radii=(0.005, 0.005), D=0.0007, S0=1.0, angles=((0, 0), (90, 0)), fractions=(35, 35), snr=20)[source]#

Calculates the three-dimensional signal attenuation E(q) originating from within a cylinder of radius R using the Soderman approximation.

The diffusion signal is assumed to be separable perpendicular and parallel to the cylinder axis [5].

This function is basically an extension of the ball and stick model. Setting the radius to zero makes them equivalent.

See [4] for details about the Soderman model.

Parameters:

gtabGradientTable: Signal measurement directions.
taufloat: diffusion time in s
radiiarray-like, optional: cylinder radius in mm
Dfloat, optional: diffusion constant
S0float, optional: Unweighted signal value.
anglesarray (K, 2) or (K, 3), optional: List of K polar angles (in degrees) for the sticks or array of K sticks as unit vectors.
fractionsarray-like, optional: Percentage of each stick. Remainder to 100 specifies isotropic component.
snrfloat, optional: Signal to noise ratio, assuming Rician noise. If set to None, no noise is added.

Returns:

Earray, shape (N,): signal attenuation

References

single_tensor#

dipy.sims.voxel.single_tensor(gtab, S0=1, *, evals=None, evecs=None, snr=None, rng=None)[source]#

Simulate diffusion-weighted signals with a single tensor.

See [6], [7].

Parameters:

gtabGradientTable: Table with information of b-values and gradient directions g. Note that if gtab has a btens attribute, simulations will be performed according to the given b-tensor B information.
S0double, optional: Strength of signal in the presence of no diffusion gradient (also called the b=0 value).
evals(3,) ndarray, optional: Eigenvalues of the diffusion tensor. By default, values typical for prolate white matter are used.
evecs(3, 3) ndarray, optional: Eigenvectors of the tensor. You can also think of this as a rotation matrix that transforms the direction of the tensor. The eigenvectors need to be column wise.
snrfloat, optional: Signal to noise ratio, assuming Rician noise. None implies no noise.
rngnumpy.random.Generator, optional: Random number generator for the noise. If None, uses NumPy’s default random generator.

Returns:

S(N,) ndarray

Simulated signal:: S(b, g) = S_0 e^(-b g^T R D R.T g), if gtab.tens=None S(B) = S_0 e^(-B:D), if gtab.tens information is given

References

multi_tensor#

dipy.sims.voxel.multi_tensor(gtab, mevals, *, S0=1.0, angles=((0, 0), (90, 0)), fractions=(50, 50), snr=20, rng=None)[source]#

Simulate a Multi-Tensor signal.

Parameters:

gtabGradientTable: Table with information of b-values and gradient directions. Note that if gtab has a btens attribute, simulations will be performed according to the given b-tensor information.
mevalsarray (K, 3): each tensor’s eigenvalues in each row
S0float, optional: Unweighted signal value (b0 signal).
anglesarray (K, 2) or (K, 3), optional: List of K tensor directions in polar angles (in degrees) or unit vectors
fractionsarray-like, optional: Percentage of the contribution of each tensor. The sum of fractions should be equal to 100%.
snrfloat, optional: Signal to noise ratio, assuming Rician noise. If set to None, no noise is added.
rngnumpy.random.Generator, optional: Random number generator for the noise. If None, uses NumPy’s default random generator.

Returns:

S(N,) ndarray: Simulated signal.
sticks(M,3): Sticks in cartesian coordinates.

Examples

>>> import numpy as np
>>> from dipy.sims.voxel import multi_tensor
>>> from dipy.data import get_fnames
>>> from dipy.core.gradients import gradient_table
>>> from dipy.io.gradients import read_bvals_bvecs
>>> fimg, fbvals, fbvecs = get_fnames(name='small_101D')
>>> bvals, bvecs = read_bvals_bvecs(fbvals, fbvecs)
>>> gtab = gradient_table(bvals, bvecs=bvecs)
>>> mevals=np.array(([0.0015, 0.0003, 0.0003],[0.0015, 0.0003, 0.0003]))
>>> e0 = np.array([1, 0, 0.])
>>> e1 = np.array([0., 1, 0])
>>> S = multi_tensor(gtab, mevals)

multi_tensor_dki#

dipy.sims.voxel.multi_tensor_dki(gtab, mevals, *, S0=1.0, angles=((90.0, 0.0), (90.0, 0.0)), fractions=(50, 50), snr=20)[source]#

Simulate the diffusion-weight signal, diffusion and kurtosis tensors based on the DKI model

See [8] for further details.

Parameters:

gtabGradientTable: Gradient table.
mevalsarray (K, 3): eigenvalues of the diffusion tensor for each individual compartment
S0float, optional: Unweighted signal value (b0 signal).
anglesarray (K,2) or (K,3), optional: List of K tensor directions of the diffusion tensor of each compartment in polar angles (in degrees) or unit vectors
fractionsfloat (K,), optional: Percentage of the contribution of each tensor. The sum of fractions should be equal to 100%.
snrfloat, optional: Signal to noise ratio, assuming Rician noise. If set to None, no noise is added.

Returns:

S(N,) ndarray: Simulated signal based on the DKI model.
dt(6,): elements of the diffusion tensor.
kt(15,): elements of the kurtosis tensor.

Notes

Simulations are based on multicompartmental models which assumes that tissue is well described by impermeable diffusion compartments characterized by their only diffusion tensor. Since simulations are based on the DKI model, coefficients larger than the fourth order of the signal’s taylor expansion approximation are neglected.

References

Examples

>>> import numpy as np
>>> from dipy.sims.voxel import multi_tensor_dki
>>> from dipy.data import get_fnames
>>> from dipy.core.gradients import gradient_table
>>> from dipy.io.gradients import read_bvals_bvecs
>>> fimg, fbvals, fbvecs = get_fnames(name='small_64D')
>>> bvals, bvecs = read_bvals_bvecs(fbvals, fbvecs)
>>> bvals_2s = np.concatenate((bvals, bvals * 2), axis=0)
>>> bvecs_2s = np.concatenate((bvecs, bvecs), axis=0)
>>> gtab = gradient_table(bvals_2s, bvecs=bvecs_2s)
>>> mevals = np.array([[0.00099, 0, 0],[0.00226, 0.00087, 0.00087]])
>>> S, dt, kt =  multi_tensor_dki(gtab, mevals)

kurtosis_element#

dipy.sims.voxel.kurtosis_element(D_comps, frac, ind_i, ind_j, ind_k, ind_l, *, DT=None, MD=None)[source]#

Computes the diffusion kurtosis tensor element (with indexes i, j, k and l) based on the individual diffusion tensor components of a multicompartmental model.

Parameters:

D_comps(K,3,3) ndarray: Diffusion tensors for all K individual compartment of the multicompartmental model.
frac[float]: Percentage of the contribution of each tensor. The sum of fractions should be equal to 100%.
ind_iint: Element’s index i (0 for x, 1 for y, 2 for z)
ind_jint: Element’s index j (0 for x, 1 for y, 2 for z)
ind_kint: Element’s index k (0 for x, 1 for y, 2 for z)
ind_l: int: Elements index l (0 for x, 1 for y, 2 for z)
DT(3,3) ndarray, optional: Voxel’s global diffusion tensor.
MDfloat, optional: Voxel’s global mean diffusivity.

Returns:

wijklfloat: kurtosis tensor element of index i, j, k, l

Notes

wijkl is calculated using equation 8 given in [8].

References

dki_signal#

dipy.sims.voxel.dki_signal(gtab, dt, kt, *, S0=150, snr=None)[source]#

Simulated signal based on the diffusion and diffusion kurtosis tensors of a single voxel. Simulations are performed assuming the DKI model.

See [8] for further details.

Parameters:

gtabGradientTable: Measurement directions.
dt(6,) ndarray: Elements of the diffusion tensor.
kt(15, ) ndarray: Elements of the diffusion kurtosis tensor.
S0float, optional: Strength of signal in the presence of no diffusion gradient.
snrfloat, optional: Signal to noise ratio, assuming Rician noise. None implies no noise.

Returns:

S(N,) ndarray: Simulated signal based on the DKI model:

\[S=S_{0}e^{-bD+\frac{1}{6}b^{2}D^{2}K}\]

References

single_tensor_odf#

dipy.sims.voxel.single_tensor_odf(r, *, evals=None, evecs=None)[source]#

Simulated ODF with a single tensor.

See [9] for further details.

Parameters:

r(N,3) or (M,N,3) ndarray: Measurement positions in (x, y, z), either as a list or on a grid.
evals(3,): Eigenvalues of diffusion tensor. By default, use values typical for prolate white matter.
evecs(3, 3) ndarray: Eigenvectors of the tensor, written column-wise. You can also think of these as the rotation matrix that determines the orientation of the diffusion tensor.

Returns:

ODF(N,) ndarray: The diffusion probability at r after time tau.

References

all_tensor_evecs#

dipy.sims.voxel.all_tensor_evecs(e0)[source]#

Given the principle tensor axis, return the array of all eigenvectors column-wise (or, the rotation matrix that orientates the tensor).

Parameters:

e0(3,) ndarray: Principle tensor axis.

Returns:

evecs(3,3) ndarray: Tensor eigenvectors, arranged column-wise.

multi_tensor_odf#

dipy.sims.voxel.multi_tensor_odf(odf_verts, mevals, angles, fractions)[source]#

Simulate a Multi-Tensor ODF.

Parameters:

odf_verts(N,3) ndarray: Vertices of the reconstruction sphere.
mevalssequence of 1D arrays,: Eigen-values for each tensor.
anglessequence of 2d tuples,: Sequence of principal directions for each tensor in polar angles or cartesian unit coordinates.
fractionssequence of floats,: Percentages of the fractions for each tensor.

Returns:

ODF(N,) ndarray: Orientation distribution function.

Examples

Simulate a MultiTensor ODF with two peaks and calculate its exact ODF.

>>> import numpy as np
>>> from dipy.sims.voxel import multi_tensor_odf, all_tensor_evecs
>>> from dipy.data import default_sphere
>>> vertices, faces = default_sphere.vertices, default_sphere.faces
>>> mevals = np.array(([0.0015, 0.0003, 0.0003],[0.0015, 0.0003, 0.0003]))
>>> angles = [(0, 0), (90, 0)]
>>> odf = multi_tensor_odf(vertices, mevals, angles, [50, 50])

single_tensor_rtop#

dipy.sims.voxel.single_tensor_rtop(*, evals=None, tau=0.025330295910584444)[source]#

Simulate a Single-Tensor rtop.

See [10] for further details.

Parameters:

evals1D arrays, optional: Eigen-values for the tensor. By default, values typical for prolate white matter are used.
taufloat, optional: diffusion time. By default the value that makes q=sqrt(b).

Returns:

rtopfloat,: Return to origin probability.

References

multi_tensor_rtop#

dipy.sims.voxel.multi_tensor_rtop(mf, *, mevals=None, tau=0.025330295910584444)[source]#

Simulate a Multi-Tensor rtop.

See [10] for further details.

Parameters:

mfsequence of floats, bounded [0,1]: Percentages of the fractions for each tensor.
mevalssequence of 1D arrays, optional: Eigen-values for each tensor. By default, values typical for prolate white matter are used.
taufloat, optional: diffusion time. By default the value that makes q=sqrt(b).

Returns:

rtopfloat,: Return to origin probability.

References

single_tensor_pdf#

dipy.sims.voxel.single_tensor_pdf(r, *, evals=None, evecs=None, tau=0.025330295910584444)[source]#

Simulated ODF with a single tensor.

See [10] for further details.

Parameters:

r(N,3) or (M,N,3) ndarray: Measurement positions in (x, y, z), either as a list or on a grid.
evals(3,), optional: Eigenvalues of diffusion tensor. By default, use values typical for prolate white matter.
evecs(3, 3) ndarray, optional: Eigenvectors of the tensor. You can also think of these as the rotation matrix that determines the orientation of the diffusion tensor.
taufloat, optional: diffusion time. By default the value that makes q=sqrt(b).

Returns:

pdf(N,) ndarray: The diffusion probability at r after time tau.

References

multi_tensor_pdf#

dipy.sims.voxel.multi_tensor_pdf(pdf_points, mevals, angles, fractions, *, tau=0.025330295910584444)[source]#

Simulate a Multi-Tensor ODF.

See [10] for further details.

Parameters:

pdf_points(N, 3) ndarray: Points to evaluate the PDF.
mevalssequence of 1D arrays,: Eigen-values for each tensor. By default, values typical for prolate white matter are used.
anglessequence,: Sequence of principal directions for each tensor in polar angles or cartesian unit coordinates.
fractionssequence of floats,: Percentages of the fractions for each tensor.
taufloat, optional: diffusion time. By default the value that makes q=sqrt(b).

Returns:

pdf(N,) ndarray,: Probability density function of the water displacement.

References

single_tensor_msd#

dipy.sims.voxel.single_tensor_msd(*, evals=None, tau=0.025330295910584444)[source]#

Simulate a Multi-Tensor rtop.

See [10] for further details.

Parameters:

evals1D arrays, optional: Eigen-values for the tensor. By default, values typical for prolate white matter are used.
taufloat, optional: diffusion time. By default the value that makes q=sqrt(b).

Returns:

msdfloat,: Mean square displacement.

References

multi_tensor_msd#

dipy.sims.voxel.multi_tensor_msd(mf, *, mevals=None, tau=0.025330295910584444)[source]#

Simulate a Multi-Tensor rtop.

See [10] for further details.

Parameters:

mfsequence of floats, bounded [0,1]: Percentages of the fractions for each tensor.
mevalssequence of 1D arrays, optional: Eigen-values for each tensor. By default, values typical for prolate white matter are used.
taufloat, optional: diffusion time. By default the value that makes q=sqrt(b).

Returns:

msdfloat,: Mean square displacement.

References

sims#

Module: sims.phantom#

Module: sims.voxel#

add_noise#

diff2eigenvectors#

orbital_phantom#

add_noise#

sticks_and_ball#

callaghan_perpendicular#

gaussian_parallel#

cylinders_and_ball_soderman#

single_tensor#

multi_tensor#

multi_tensor_dki#

kurtosis_element#

dki_signal#

single_tensor_odf#

all_tensor_evecs#

multi_tensor_odf#

single_tensor_rtop#

multi_tensor_rtop#

single_tensor_pdf#

multi_tensor_pdf#

single_tensor_msd#

multi_tensor_msd#

`sims`#

Module: `sims.phantom`#

Module: `sims.voxel`#