sims

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 (defaults to 1).

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.

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')

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.

Returns

data : array, shape (datashape)

See Also

add_noise

Examples

>>> def f(t):
...    x = np.sin(t)
...    y = np.cos(t)
...    z = np.linspace(-1, 1, len(x))
...    return x, y, z

>>> data = orbital_phantom(func=f)

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])

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.

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')

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

Parameters

qarray, shape (N,)

q-space value in 1/mm

radiusfloat

cylinder radius in mm

Returns

Earray, shape (N,)

signal attenuation

References

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

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

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.

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

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.

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('small_101D')
>>> bvals, bvecs = read_bvals_bvecs(fbvals, fbvecs)
>>> gtab = gradient_table(bvals, 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)

Parameters

gtab : GradientTable mevals : array (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.

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('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_2s)
>>> mevals = np.array([[0.00099, 0, 0],[0.00226, 0.00087, 0.00087]])
>>> S, dt, kt =  multi_tensor_dki(gtab, mevals)

References

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 [1]_

References

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:

References

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

Parameters

e0(3,) ndarray

Principle tensor axis.

Returns

evecs(3,3) ndarray

Tensor eigenvectors, arranged column-wise.

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])

Parameters

evals1D arrays,

Eigen-values for the tensor. By default, values typical for prolate white matter are used.

taufloat,

diffusion time. By default the value that makes q=sqrt(b).

Returns

rtopfloat,

Return to origin probability.

References

Parameters

mfsequence of floats, bounded [0,1]

Percentages of the fractions for each tensor.

mevalssequence of 1D arrays,

Eigen-values for each tensor. By default, values typical for prolate white matter are used.

taufloat,

diffusion time. By default the value that makes q=sqrt(b).

Returns

rtopfloat,

Return to origin probability.

References

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. You can also think of these as the rotation matrix that determines the orientation of the diffusion tensor.

taufloat,

diffusion time. By default the value that makes q=sqrt(b).

Returns

pdf(N,) ndarray

The diffusion probability at r after time tau.

References

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,

diffusion time. By default the value that makes q=sqrt(b).

Returns

pdf(N,) ndarray,

Probability density function of the water displacement.

References

Parameters

evals1D arrays,

Eigen-values for the tensor. By default, values typical for prolate white matter are used.

taufloat,

diffusion time. By default the value that makes q=sqrt(b).

Returns

msdfloat,

Mean square displacement.

References

Parameters

mfsequence of floats, bounded [0,1]

Percentages of the fractions for each tensor.

mevalssequence of 1D arrays,

Eigen-values for each tensor. By default, values typical for prolate white matter are used.

taufloat,

diffusion time. By default the value that makes q=sqrt(b).

Returns

msdfloat,

Mean square displacement.

References