core

References

[1] How-To Guide for Descriptors, Raymond Hettinger. http://users.rcn.com/python/download/Descriptor.htm

[2] Python data model, http://docs.python.org/reference/datamodel.html

test

dipy.core.test(label='fast', verbose=1, extra_argv=None, doctests=False, coverage=False, raise_warnings=None, timer=False)

Run tests for module using nose.

Parameters

label{‘fast’, ‘full’, ‘’, attribute identifier}, optional

Identifies the tests to run. This can be a string to pass to the nosetests executable with the ‘-A’ option, or one of several special values. Special values are:

• ‘fast’ - the default - which corresponds to the nosetests -A option of ‘not slow’.

• ‘full’ - fast (as above) and slow tests as in the ‘no -A’ option to nosetests - this is the same as ‘’.

• None or ‘’ - run all tests.

• attribute_identifier - string passed directly to nosetests as ‘-A’.

verboseint, optional

Verbosity value for test outputs, in the range 1-10. Default is 1.

extra_argvlist, optional

List with any extra arguments to pass to nosetests.

doctestsbool, optional

If True, run doctests in module. Default is False.

coveragebool, optional

If True, report coverage of NumPy code. Default is False. (This requires the coverage module).

raise_warningsNone, str or sequence of warnings, optional

This specifies which warnings to configure as ‘raise’ instead of being shown once during the test execution. Valid strings are:

• “develop” : equals (Warning,)

• “release” : equals (), do not raise on any warnings.

timerbool or int, optional

Timing of individual tests with nose-timer (which needs to be installed). If True, time tests and report on all of them. If an integer (say N), report timing results for N slowest tests.

Returns

resultobject

Returns the result of running the tests as a nose.result.TextTestResult object.

Notes

Each NumPy module exposes test in its namespace to run all tests for it. For example, to run all tests for numpy.lib:

>>> np.lib.test() 

Examples

>>> result = np.lib.test() 
Running unit tests for numpy.lib
...
Ran 976 tests in 3.933s

OK

>>> result.errors 
[]
>>> result.knownfail 
[]

Timer

class dipy.core.benchmarks.bench_sphere.Timer

Bases: object

Methods

duration_in_seconds

__init__(*args, **kwargs)

duration_in_seconds()

bench_disperse_charges_alt

dipy.core.benchmarks.bench_sphere.bench_disperse_charges_alt()

func_minimize_adhoc

dipy.core.benchmarks.bench_sphere.func_minimize_adhoc(init_hemisphere, num_iterations)

func_minimize_scipy

dipy.core.benchmarks.bench_sphere.func_minimize_scipy(init_pointset, num_iterations)

cart2sphere

dipy.core.geometry.cart2sphere(x, y, z)

Return angles for Cartesian 3D coordinates x, y, and z

See doc for sphere2cart for angle conventions and derivation of the formulae.

\(0\le\theta\mathrm{(theta)}\le\pi\) and \(-\pi\le\phi\mathrm{(phi)}\le\pi\)

Parameters

xarray_like

x coordinate in Cartesian space

yarray_like

y coordinate in Cartesian space

zarray_like

z coordinate

Returns

rarray

radius

thetaarray

inclination (polar) angle

phiarray

azimuth angle

cart_distance

dipy.core.geometry.cart_distance(pts1, pts2)

Cartesian distance between pts1 and pts2

If either of pts1 or pts2 is 2D, then we take the first dimension to index points, and the second indexes coordinate. More generally, we take the last dimension to be the coordinate dimension.

Parameters

pts1(N,R) or (R,) array_like

where N is the number of points and R is the number of coordinates defining a point (R==3 for 3D)

pts2(N,R) or (R,) array_like

where N is the number of points and R is the number of coordinates defining a point (R==3 for 3D). It should be possible to broadcast pts1 against pts2

Returns

d(N,) or (0,) array

Cartesian distances between corresponding points in pts1 and pts2

See also

sphere_distance

distance between points on sphere surface

Examples

>>> cart_distance([0,0,0], [0,0,3])
3.0

circumradius

dipy.core.geometry.circumradius(a, b, c)

a, b and c are 3-dimensional vectors which are the vertices of a triangle. The function returns the circumradius of the triangle, i.e the radius of the smallest circle that can contain the triangle. In the degenerate case when the 3 points are collinear it returns half the distance between the furthest apart points.

Parameters

a, b, c(3,) array_like

the three vertices of the triangle

Returns

circumradiusfloat

the desired circumradius

compose_matrix

dipy.core.geometry.compose_matrix(scale=None, shear=None, angles=None, translate=None, perspective=None)

Return 4x4 transformation matrix from sequence of transformations.

Code modified from the work of Christoph Gohlke link provided here http://www.lfd.uci.edu/~gohlke/code/transformations.py.html

This is the inverse of the decompose_matrix function.

Parameters

scale(3,) array_like

Scaling factors.

sheararray_like

Shear factors for x-y, x-z, y-z axes.

anglesarray_like

Euler angles about static x, y, z axes.

translatearray_like

Translation vector along x, y, z axes.

perspectivearray_like

Perspective partition of matrix.

Returns

matrix4x4 array

Examples

>>> import math
>>> import numpy as np
>>> import dipy.core.geometry as gm
>>> scale = np.random.random(3) - 0.5
>>> shear = np.random.random(3) - 0.5
>>> angles = (np.random.random(3) - 0.5) * (2*math.pi)
>>> trans = np.random.random(3) - 0.5
>>> persp = np.random.random(4) - 0.5
>>> M0 = gm.compose_matrix(scale, shear, angles, trans, persp)

compose_transformations

dipy.core.geometry.compose_transformations(*mats)

Compose multiple 4x4 affine transformations in one 4x4 matrix

Parameters

mat1array, (4, 4)

mat2array, (4, 4)

…

matNarray, (4, 4)

Returns

matN x … x mat2 x mat1array, (4, 4)

decompose_matrix

dipy.core.geometry.decompose_matrix(matrix)

Return sequence of transformations from transformation matrix.

Code modified from the excellent work of Christoph Gohlke link provided here: http://www.lfd.uci.edu/~gohlke/code/transformations.py.html

Parameters

matrixarray_like

Non-degenerative homogeneous transformation matrix

Returns

scale(3,) ndarray

Three scaling factors.

shear(3,) ndarray

Shear factors for x-y, x-z, y-z axes.

angles(3,) ndarray

Euler angles about static x, y, z axes.

translate(3,) ndarray

Translation vector along x, y, z axes.

perspectivendarray

Perspective partition of matrix.

Raises

ValueError

If matrix is of wrong type or degenerative.

Examples

>>> import numpy as np
>>> T0=np.diag([2,1,1,1])
>>> scale, shear, angles, trans, persp = decompose_matrix(T0)

dist_to_corner

dipy.core.geometry.dist_to_corner(affine)

Calculate the maximal distance from the center to a corner of a voxel, given an affine

Parameters

affine4 by 4 array.

The spatial transformation from the measurement to the scanner space.

Returns

dist: float

The maximal distance to the corner of a voxel, given voxel size encoded in the affine.

euler_matrix

dipy.core.geometry.euler_matrix(ai, aj, ak, axes='sxyz')

Return homogeneous rotation matrix from Euler angles and axis sequence.

Code modified from the work of Christoph Gohlke link provided here http://www.lfd.uci.edu/~gohlke/code/transformations.py.html

Parameters

ai, aj, akEuler’s roll, pitch and yaw angles

axesOne of 24 axis sequences as string or encoded tuple

Returns

matrixndarray (4, 4)

Code modified from the work of Christoph Gohlke link provided here

http://www.lfd.uci.edu/~gohlke/code/transformations.py.html

Examples

>>> import numpy
>>> R = euler_matrix(1, 2, 3, 'syxz')
>>> numpy.allclose(numpy.sum(R[0]), -1.34786452)
True
>>> R = euler_matrix(1, 2, 3, (0, 1, 0, 1))
>>> numpy.allclose(numpy.sum(R[0]), -0.383436184)
True
>>> ai, aj, ak = (4.0*math.pi) * (numpy.random.random(3) - 0.5)
>>> for axes in _AXES2TUPLE.keys():
...    _ = euler_matrix(ai, aj, ak, axes)
>>> for axes in _TUPLE2AXES.keys():
...    _ = euler_matrix(ai, aj, ak, axes)

is_hemispherical

dipy.core.geometry.is_hemispherical(vecs)

Test whether all points on a unit sphere lie in the same hemisphere.

Parameters

vecsnumpy.ndarray

2D numpy array with shape (N, 3) where N is the number of points. All points must lie on the unit sphere.

Returns

is_hemibool

If True, one can find a hemisphere that contains all the points. If False, then the points do not lie in any hemisphere

polenumpy.ndarray

If is_hemi == True, then pole is the “central” pole of the input vectors. Otherwise, pole is the zero vector.

References

https://rstudio-pubs-static.s3.amazonaws.com/27121_a22e51b47c544980bad594d5e0bb2d04.html # noqa

lambert_equal_area_projection_cart

dipy.core.geometry.lambert_equal_area_projection_cart(x, y, z)

Lambert Equal Area Projection from cartesian vector to plane

Return positions in \((y_1,y_2)\) plane corresponding to the directions of the vectors with cartesian coordinates xyz under the Lambert Equal Area Projection mapping (see Mardia and Jupp (2000), Directional Statistics, p. 161).

The Lambert EAP maps the upper hemisphere to the planar disc of radius 1 and the lower hemisphere to the planar annulus between radii 1 and 2, The Lambert EAP maps the upper hemisphere to the planar disc of radius 1 and the lower hemisphere to the planar annulus between radii 1 and 2. and vice versa.

See doc for sphere2cart for angle conventions

Parameters

xarray_like

x coordinate in Cartesion space

yarray_like

y coordinate in Cartesian space

zarray_like

z coordinate

Returns

y(N,2) array

planar coordinates of points following mapping by Lambert’s EAP.

lambert_equal_area_projection_polar

dipy.core.geometry.lambert_equal_area_projection_polar(theta, phi)

Lambert Equal Area Projection from polar sphere to plane

Return positions in (y1,y2) plane corresponding to the points with polar coordinates (theta, phi) on the unit sphere, under the Lambert Equal Area Projection mapping (see Mardia and Jupp (2000), Directional Statistics, p. 161).

See doc for sphere2cart for angle conventions

• \(0 \le \theta \le \pi\) and \(0 \le \phi \le 2 \pi\)

• \(|(y_1,y_2)| \le 2\)

The Lambert EAP maps the upper hemisphere to the planar disc of radius 1 and the lower hemisphere to the planar annulus between radii 1 and 2, and vice versa.

Parameters

thetaarray_like

theta spherical coordinates

phiarray_like

phi spherical coordinates

Returns

y(N,2) array

planar coordinates of points following mapping by Lambert’s EAP.

nearest_pos_semi_def

dipy.core.geometry.nearest_pos_semi_def(B)

Least squares positive semi-definite tensor estimation

Parameters

B(3,3) array_like

B matrix - symmetric. We do not check the symmetry.

Returns

npds(3,3) array

Estimated nearest positive semi-definite array to matrix B.

References

1

Niethammer M, San Jose Estepar R, Bouix S, Shenton M, Westin CF. On diffusion tensor estimation. Conf Proc IEEE Eng Med Biol Soc. 2006;1:2622-5. PubMed PMID: 17946125; PubMed Central PMCID: PMC2791793.

Examples

>>> B = np.diag([1, 1, -1])
>>> nearest_pos_semi_def(B)
array([[ 0.75,  0.  ,  0.  ],
       [ 0.  ,  0.75,  0.  ],
       [ 0.  ,  0.  ,  0.  ]])

normalized_vector

dipy.core.geometry.normalized_vector(vec, axis=- 1)

Return vector divided by its Euclidean (L2) norm

See unit vector and Euclidean norm

Parameters

vecarray_like shape (3,)

Returns

nvecarray shape (3,)

vector divided by L2 norm

Examples

>>> vec = [1, 2, 3]
>>> l2n = np.sqrt(np.dot(vec, vec))
>>> nvec = normalized_vector(vec)
>>> np.allclose(np.array(vec) / l2n, nvec)
True
>>> vec = np.array([[1, 2, 3]])
>>> vec.shape == (1, 3)
True
>>> normalized_vector(vec).shape == (1, 3)
True

perpendicular_directions

dipy.core.geometry.perpendicular_directions(v, num=30, half=False)

Computes n evenly spaced perpendicular directions relative to a given vector v

Parameters

varray (3,)

Array containing the three cartesian coordinates of vector v

numint, optional

Number of perpendicular directions to generate

halfbool, optional

If half is True, perpendicular directions are sampled on half of the unit circumference perpendicular to v, otherwive perpendicular directions are sampled on the full circumference. Default of half is False

Returns

psamplesarray (n, 3)

array of vectors perpendicular to v

Notes

Perpendicular directions are estimated using the following two step procedure:

1) the perpendicular directions are first sampled in a unit circumference parallel to the plane normal to the x-axis.

2) Samples are then rotated and aligned to the plane normal to vector v. The rotational matrix for this rotation is constructed as reference frame basis which axis are the following:

• The first axis is vector v

• The second axis is defined as the normalized vector given by the

cross product between vector v and the unit vector aligned to the x-axis - The third axis is defined as the cross product between the previous computed vector and vector v.

Following this two steps, coordinates of the final perpendicular directions are given as:

\[\left [ -\sin(a_{i}) \sqrt{{v_{y}}^{2}+{v_{z}}^{2}} \; , \; \frac{v_{x}v_{y}\sin(a_{i})-v_{z}\cos(a_{i})} {\sqrt{{v_{y}}^{2}+{v_{z}}^{2}}} \; , \; \frac{v_{x}v_{z}\sin(a_{i})-v_{y}\cos(a_{i})} {\sqrt{{v_{y}}^{2}+{v_{z}}^{2}}} \right ]\]

This procedure has a singularity when vector v is aligned to the x-axis. To solve this singularity, perpendicular directions in procedure’s step 1 are defined in the plane normal to y-axis and the second axis of the rotated frame of reference is computed as the normalized vector given by the cross product between vector v and the unit vector aligned to the y-axis. Following this, the coordinates of the perpendicular directions are given as:

left [ -frac{left (v_{x}v_{y}sin(a_{i})+v_{z}cos(a_{i}) right )} {sqrt{{v_{x}}^{2}+{v_{z}}^{2}}} ; , ; sin(a_{i}) sqrt{{v_{x}}^{2}+{v_{z}}^{2}} ; , ; frac{v_{y}v_{z}sin(a_{i})+v_{x}cos(a_{i})} {sqrt{{v_{x}}^{2}+{v_{z}}^{2}}} right ]

For more details on this calculation, see ` here <http://gsoc2015dipydki.blogspot.it/2015/07/rnh-post-8-computing-perpendicular.html>`_.

rodrigues_axis_rotation

dipy.core.geometry.rodrigues_axis_rotation(r, theta)

Rodrigues formula

Rotation matrix for rotation around axis r for angle theta.

The rotation matrix is given by the Rodrigues formula:

R = Id + sin(theta)*Sn + (1-cos(theta))*Sn^2

with:

       0  -nz  ny
Sn =   nz   0 -nx
      -ny  nx   0

where n = r / ||r||

In case the angle ||r|| is very small, the above formula may lead to numerical instabilities. We instead use a Taylor expansion around theta=0:

R = I + sin(theta)/tetha Sr + (1-cos(theta))/teta2 Sr^2

leading to:

R = I + (1-theta2/6)*Sr + (1/2-theta2/24)*Sr^2

Parameters

rarray_like shape (3,), axis

thetafloat, angle in degrees

Returns

Rarray, shape (3,3), rotation matrix

Examples

>>> import numpy as np
>>> from dipy.core.geometry import rodrigues_axis_rotation
>>> v=np.array([0,0,1])
>>> u=np.array([1,0,0])
>>> R=rodrigues_axis_rotation(v,40)
>>> ur=np.dot(R,u)
>>> np.round(np.rad2deg(np.arccos(np.dot(ur,u))))
40.0

sph2latlon

dipy.core.geometry.sph2latlon(theta, phi)

Convert spherical coordinates to latitude and longitude.

Returns

lat, lonndarray

Latitude and longitude.

sphere2cart

dipy.core.geometry.sphere2cart(r, theta, phi)

Spherical to Cartesian coordinates

This is the standard physics convention where theta is the inclination (polar) angle, and phi is the azimuth angle.

Imagine a sphere with center (0,0,0). Orient it with the z axis running south-north, the y axis running west-east and the x axis from posterior to anterior. theta (the inclination angle) is the angle to rotate from the z-axis (the zenith) around the y-axis, towards the x axis. Thus the rotation is counter-clockwise from the point of view of positive y. phi (azimuth) gives the angle of rotation around the z-axis towards the y axis. The rotation is counter-clockwise from the point of view of positive z.

Equivalently, given a point P on the sphere, with coordinates x, y, z, theta is the angle between P and the z-axis, and phi is the angle between the projection of P onto the XY plane, and the X axis.

Geographical nomenclature designates theta as ‘co-latitude’, and phi as ‘longitude’

Parameters

rarray_like

radius

thetaarray_like

inclination or polar angle

phiarray_like

azimuth angle

Returns

xarray

x coordinate(s) in Cartesion space

yarray

y coordinate(s) in Cartesian space

zarray

z coordinate

Notes

See these pages:

• http://en.wikipedia.org/wiki/Spherical_coordinate_system

• http://mathworld.wolfram.com/SphericalCoordinates.html

for excellent discussion of the many different conventions possible. Here we use the physics conventions, used in the wikipedia page.

Derivations of the formulae are simple. Consider a vector x, y, z of length r (norm of x, y, z). The inclination angle (theta) can be found from: cos(theta) == z / r -> z == r * cos(theta). This gives the hypotenuse of the projection onto the XY plane, which we will call Q. Q == r*sin(theta). Now x / Q == cos(phi) -> x == r * sin(theta) * cos(phi) and so on.

We have deliberately named this function sphere2cart rather than sph2cart to distinguish it from the Matlab function of that name, because the Matlab function uses an unusual convention for the angles that we did not want to replicate. The Matlab function is trivial to implement with the formulae given in the Matlab help.

sphere_distance

dipy.core.geometry.sphere_distance(pts1, pts2, radius=None, check_radius=True)

Distance across sphere surface between pts1 and pts2

Parameters

pts1(N,R) or (R,) array_like

where N is the number of points and R is the number of coordinates defining a point (R==3 for 3D)

pts2(N,R) or (R,) array_like

where N is the number of points and R is the number of coordinates defining a point (R==3 for 3D). It should be possible to broadcast pts1 against pts2

radiusNone or float, optional

Radius of sphere. Default is to work out radius from mean of the length of each point vector

check_radiusbool, optional

If True, check if the points are on the sphere surface - i.e check if the vector lengths in pts1 and pts2 are close to radius. Default is True.

Returns

d(N,) or (0,) array

Distances between corresponding points in pts1 and pts2 across the spherical surface, i.e. the great circle distance

See also

cart_distance

cartesian distance between points

vector_cosine

cosine of angle between vectors

Examples

>>> print('%.4f' % sphere_distance([0,1],[1,0]))
1.5708
>>> print('%.4f' % sphere_distance([0,3],[3,0]))
4.7124

vec2vec_rotmat

dipy.core.geometry.vec2vec_rotmat(u, v)

rotation matrix from 2 unit vectors

u, v being unit 3d vectors return a 3x3 rotation matrix R than aligns u to v.

In general there are many rotations that will map u to v. If S is any rotation using v as an axis then R.S will also map u to v since (S.R)u = S(Ru) = Sv = v. The rotation R returned by vec2vec_rotmat leaves fixed the perpendicular to the plane spanned by u and v.

The transpose of R will align v to u.

Parameters

uarray, shape(3,)

varray, shape(3,)

Returns

Rarray, shape(3,3)

Examples

>>> import numpy as np
>>> from dipy.core.geometry import vec2vec_rotmat
>>> u=np.array([1,0,0])
>>> v=np.array([0,1,0])
>>> R=vec2vec_rotmat(u,v)
>>> np.dot(R,u)
array([ 0.,  1.,  0.])
>>> np.dot(R.T,v)
array([ 1.,  0.,  0.])

vector_cosine

dipy.core.geometry.vector_cosine(vecs1, vecs2)

Cosine of angle between two (sets of) vectors

The cosine of the angle between two vectors v1 and v2 is given by the inner product of v1 and v2 divided by the product of the vector lengths:

v_cos = np.inner(v1, v2) / (np.sqrt(np.sum(v1**2)) *
                            np.sqrt(np.sum(v2**2)))

Parameters

vecs1(N, R) or (R,) array_like

N vectors (as rows) or single vector. Vectors have R elements.

vecs1(N, R) or (R,) array_like

N vectors (as rows) or single vector. Vectors have R elements. It should be possible to broadcast vecs1 against vecs2

Returns

vcos(N,) or (0,) array

Vector cosines. To get the angles you will need np.arccos

Notes

The vector cosine will be the same as the correlation only if all the input vectors have zero mean.

vector_norm

dipy.core.geometry.vector_norm(vec, axis=- 1, keepdims=False)

Return vector Euclidean (L2) norm

See unit vector and Euclidean norm

Parameters

vecarray_like

Vectors to norm.

axisint

Axis over which to norm. By default norm over last axis. If axis is None, vec is flattened then normed.

keepdimsbool

If True, the output will have the same number of dimensions as vec, with shape 1 on axis.

Returns

normarray

Euclidean norms of vectors.

Examples

>>> import numpy as np
>>> vec = [[8, 15, 0], [0, 36, 77]]
>>> vector_norm(vec)
array([ 17.,  85.])
>>> vector_norm(vec, keepdims=True)
array([[ 17.],
       [ 85.]])
>>> vector_norm(vec, axis=0)
array([  8.,  39.,  77.])

GradientTable

class dipy.core.gradients.GradientTable(gradients, big_delta=None, small_delta=None, b0_threshold=50, btens=None)

Bases: object

Diffusion gradient information

Parameters

gradientsarray_like (N, 3)

Diffusion gradients. The direction of each of these vectors corresponds to the b-vector, and the length corresponds to the b-value.

b0_thresholdfloat

Gradients with b-value less than or equal to b0_threshold are considered as b0s i.e. without diffusion weighting.

See also

gradient_table

Notes

The GradientTable object is immutable. Do NOT assign attributes. If you have your gradient table in a bval & bvec format, we recommend using the factory function gradient_table

Attributes

gradients(N,3) ndarray

diffusion gradients

bvals(N,) ndarray

The b-value, or magnitude, of each gradient direction.

qvals: (N,) ndarray

The q-value for each gradient direction. Needs big and small delta.

bvecs(N,3) ndarray

The direction, represented as a unit vector, of each gradient.

b0s_mask(N,) ndarray

Boolean array indicating which gradients have no diffusion weighting, ie b-value is close to 0.

b0_thresholdfloat

Gradients with b-value less than or equal to b0_threshold are considered to not have diffusion weighting.

btens(N,3,3) ndarray

The b-tensor of each gradient direction.

Methods

b0s_mask
bvals
bvecs
gradient_strength
qvals
tau

__init__(gradients, big_delta=None, small_delta=None, b0_threshold=50, btens=None)

Constructor for GradientTable class

b0s_mask()

bvals()

bvecs()

gradient_strength()

property info

qvals()

tau()

HemiSphere

class dipy.core.gradients.HemiSphere(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None, tol=1e-05)

Bases: dipy.core.sphere.Sphere

Points on the unit sphere.

A HemiSphere is similar to a Sphere but it takes antipodal symmetry into account. Antipodal symmetry means that point v on a HemiSphere is the same as the point -v. Duplicate points are discarded when constructing a HemiSphere (including antipodal duplicates). edges and faces are remapped to the remaining points as closely as possible.

The HemiSphere can be constructed using one of three conventions:

HemiSphere(x, y, z)
HemiSphere(xyz=xyz)
HemiSphere(theta=theta, phi=phi)

Parameters

x, y, z1-D array_like

Vertices as x-y-z coordinates.

theta, phi1-D array_like

Vertices as spherical coordinates. Theta and phi are the inclination and azimuth angles respectively.

xyz(N, 3) ndarray

Vertices as x-y-z coordinates.

faces(N, 3) ndarray

Indices into vertices that form triangular faces. If unspecified, the faces are computed using a Delaunay triangulation.

edges(N, 2) ndarray

Edges between vertices. If unspecified, the edges are derived from the faces.

tolfloat

Angle in degrees. Vertices that are less than tol degrees apart are treated as duplicates.

See also

Sphere

Attributes

x

y

z

Methods

find_closest(xyz)	Find the index of the vertex in the Sphere closest to the input vector, taking into account antipodal symmetry
from_sphere(sphere[, tol])	Create instance from a Sphere
mirror()	Create a full Sphere from a HemiSphere
subdivide([n])	Create a more subdivided HemiSphere

edges
faces
vertices

__init__(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None, tol=1e-05)

Create a HemiSphere from points

faces()

find_closest(xyz)

Find the index of the vertex in the Sphere closest to the input vector, taking into account antipodal symmetry

Parameters

xyzarray-like, 3 elements

A unit vector

Returns

idxint

The index into the Sphere.vertices array that gives the closest vertex (in angle).

classmethod from_sphere(sphere, tol=1e-05)

Create instance from a Sphere

mirror()

Create a full Sphere from a HemiSphere

subdivide(n=1)

Create a more subdivided HemiSphere

See Sphere.subdivide for full documentation.

auto_attr

dipy.core.gradients.auto_attr(func)

Decorator to create OneTimeProperty attributes.

Parameters

funcmethod

The method that will be called the first time to compute a value. Afterwards, the method’s name will be a standard attribute holding the value of this computation.

Examples

>>> class MagicProp(object):
...     @auto_attr
...     def a(self):
...         return 99
...
>>> x = MagicProp()
>>> 'a' in x.__dict__
False
>>> x.a
99
>>> 'a' in x.__dict__
True

btens_to_params

dipy.core.gradients.btens_to_params(btens, ztol=1e-10)

Compute trace, anisotropy and assymetry parameters from b-tensors

Parameters

btens(3, 3) OR (N, 3, 3) numpy.ndarray

input b-tensor, or b-tensors, where N = number of b-tensors

ztolfloat

Any parameters smaller than this value are considered to be 0

Returns

bval: numpy.ndarray

b-value(s) (trace(s))

bdelta: numpy.ndarray

normalized tensor anisotropy(s)

b_eta: numpy.ndarray

tensor assymetry(s)

Notes

This function can be used to get b-tensor parameters directly from the GradientTable btens attribute.

Examples

>>> lte = np.array([[1, 0, 0], [0, 0, 0], [0, 0, 0]])
>>> bval, bdelta, b_eta = btens_to_params(lte)
>>> print("bval={}; bdelta={}; b_eta={}".format(bdelta, bval, b_eta))
bval=[ 1.]; bdelta=[ 1.]; b_eta=[ 0.]

check_multi_b

dipy.core.gradients.check_multi_b(gtab, n_bvals, non_zero=True, bmag=None)

Check if you have enough different b-values in your gradient table

Parameters

gtabGradientTable class instance.

n_bvalsint

The number of different b-values you are checking for.

non_zerobool

Whether to check only non-zero bvalues. In this case, we will require at least n_bvals non-zero b-values (where non-zero is defined depending on the gtab object’s b0_threshold attribute)

bmagint

The order of magnitude of the b-values used. The function will normalize the b-values relative \(10^{bmag}\). Default: derive this value from the maximal b-value provided: \(bmag=log_{10}(max(bvals)) - 1\).

Returns

boolWhether there are at least n_bvals different b-values in the

gradient table used.

deprecate_with_version

dipy.core.gradients.deprecate_with_version(message, since='', until='', version_comparator=<function cmp_pkg_version>, warn_class=<class 'DeprecationWarning'>, error_class=<class 'dipy.utils.deprecator.ExpiredDeprecationError'>)

Return decorator function function for deprecation warning / error.

The decorated function / method will:

• Raise the given warning_class warning when the function / method gets called, up to (and including) version until (if specified);

• Raise the given error_class error when the function / method gets called, when the package version is greater than version until (if specified).

Parameters

messagestr

Message explaining deprecation, giving possible alternatives.

sincestr, optional

Released version at which object was first deprecated.

untilstr, optional

Last released version at which this function will still raise a deprecation warning. Versions higher than this will raise an error.

version_comparatorcallable

Callable accepting string as argument, and return 1 if string represents a higher version than encoded in the version_comparator, 0 if the version is equal, and -1 if the version is lower. For example, the version_comparator may compare the input version string to the current package version string.

warn_classclass, optional

Class of warning to generate for deprecation.

error_classclass, optional

Class of error to generate when version_comparator returns 1 for a given argument of until.

Returns

deprecatorfunc

Function returning a decorator.

disperse_charges

dipy.core.gradients.disperse_charges(hemi, iters, const=0.2)

Models electrostatic repulsion on the unit sphere

Places charges on a sphere and simulates the repulsive forces felt by each one. Allows the charges to move for some number of iterations and returns their final location as well as the total potential of the system at each step.

Parameters

hemiHemiSphere

Points on a unit sphere.

itersint

Number of iterations to run.

constfloat

Using a smaller const could provide a more accurate result, but will need more iterations to converge.

Returns

hemiHemiSphere

Distributed points on a unit sphere.

potentialndarray

The electrostatic potential at each iteration. This can be useful to check if the repulsion converged to a minimum.

Notes

This function is meant to be used with diffusion imaging so antipodal symmetry is assumed. Therefor each charge must not only be unique, but if there is a charge at +x, there cannot be a charge at -x. These are treated as the same location and because the distance between the two charges will be zero, the result will be unstable.

generate_bvecs

dipy.core.gradients.generate_bvecs(N, iters=5000)

Generates N bvectors.

Uses dipy.core.sphere.disperse_charges to model electrostatic repulsion on a unit sphere.

Parameters

Nint

The number of bvectors to generate. This should be equal to the number of bvals used.

itersint

Number of iterations to run.

Returns

bvecs(N,3) ndarray

The generated directions, represented as a unit vector, of each gradient.

get_bval_indices

dipy.core.gradients.get_bval_indices(bvals, bval, tol=20)

Get indices where the b-value is bval

Parameters

bvals: ndarray

Array containing the b-values

bval: float or int

b-value to extract indices

tol: int

The tolerated gap between the b-values to extract and the actual b-values.

Returns

Array of indices where the b-value is bval

gradient_table

dipy.core.gradients.gradient_table(bvals, bvecs=None, big_delta=None, small_delta=None, b0_threshold=50, atol=0.01, btens=None)

A general function for creating diffusion MR gradients.

It reads, loads and prepares scanner parameters like the b-values and b-vectors so that they can be useful during the reconstruction process.

Parameters

bvalscan be any of the four options

1. an array of shape (N,) or (1, N) or (N, 1) with the b-values.

2. a path for the file which contains an array like the above (1).

3. an array of shape (N, 4) or (4, N). Then this parameter is considered to be a b-table which contains both bvals and bvecs. In this case the next parameter is skipped.

4. a path for the file which contains an array like the one at (3).

bvecscan be any of two options

1. an array of shape (N, 3) or (3, N) with the b-vectors.

2. a path for the file which contains an array like the previous.

big_deltafloat

acquisition pulse separation time in seconds (default None)

small_deltafloat

acquisition pulse duration time in seconds (default None)

b0_thresholdfloat

All b-values with values less than or equal to bo_threshold are considered as b0s i.e. without diffusion weighting.

atolfloat

All b-vectors need to be unit vectors up to a tolerance.

btenscan be any of three options

1. a string specifying the shape of the encoding tensor for all volumes in data. Options: ‘LTE’, ‘PTE’, ‘STE’, ‘CTE’ corresponding to linear, planar, spherical, and “cigar-shaped” tensor encoding. Tensors are rotated so that linear and cigar tensors are aligned with the corresponding gradient direction and the planar tensor’s normal is aligned with the corresponding gradient direction. Magnitude is scaled to match the b-value.

2. an array of strings of shape (N,), (N, 1), or (1, N) specifying encoding tensor shape for each volume separately. N corresponds to the number volumes in data. Options for elements in array: ‘LTE’, ‘PTE’, ‘STE’, ‘CTE’ corresponding to linear, planar, spherical, and “cigar-shaped” tensor encoding. Tensors are rotated so that linear and cigar tensors are aligned with the corresponding gradient direction and the planar tensor’s normal is aligned with the corresponding gradient direction. Magnitude is scaled to match the b-value.

3. an array of shape (N,3,3) specifying the b-tensor of each volume exactly. N corresponds to the number volumes in data. No rotation or scaling is performed.

Returns

gradientsGradientTable

A GradientTable with all the gradient information.

Notes

1. Often b0s (b-values which correspond to images without diffusion weighting) have 0 values however in some cases the scanner cannot provide b0s of an exact 0 value and it gives a bit higher values e.g. 6 or 12. This is the purpose of the b0_threshold in the __init__.

2. We assume that the minimum number of b-values is 7.

3. B-vectors should be unit vectors.

Examples

>>> from dipy.core.gradients import gradient_table
>>> bvals = 1500 * np.ones(7)
>>> bvals[0] = 0
>>> sq2 = np.sqrt(2) / 2
>>> bvecs = np.array([[0, 0, 0],
...                   [1, 0, 0],
...                   [0, 1, 0],
...                   [0, 0, 1],
...                   [sq2, sq2, 0],
...                   [sq2, 0, sq2],
...                   [0, sq2, sq2]])
>>> gt = gradient_table(bvals, bvecs)
>>> gt.bvecs.shape == bvecs.shape
True
>>> gt = gradient_table(bvals, bvecs.T)
>>> gt.bvecs.shape == bvecs.T.shape
False

gradient_table_from_bvals_bvecs

dipy.core.gradients.gradient_table_from_bvals_bvecs(bvals, bvecs, b0_threshold=50, atol=0.01, btens=None, **kwargs)

Creates a GradientTable from a bvals array and a bvecs array

Parameters

bvalsarray_like (N,)

The b-value, or magnitude, of each gradient direction.

bvecsarray_like (N, 3)

The direction, represented as a unit vector, of each gradient.

b0_thresholdfloat

Gradients with b-value less than or equal to bo_threshold are considered to not have diffusion weighting.

atolfloat

Each vector in bvecs must be a unit vectors up to a tolerance of atol.

btenscan be any of three options

1. a string specifying the shape of the encoding tensor for all volumes in data. Options: ‘LTE’, ‘PTE’, ‘STE’, ‘CTE’ corresponding to linear, planar, spherical, and “cigar-shaped” tensor encoding. Tensors are rotated so that linear and cigar tensors are aligned with the corresponding gradient direction and the planar tensor’s normal is aligned with the corresponding gradient direction. Magnitude is scaled to match the b-value.

2. an array of strings of shape (N,), (N, 1), or (1, N) specifying encoding tensor shape for each volume separately. N corresponds to the number volumes in data. Options for elements in array: ‘LTE’, ‘PTE’, ‘STE’, ‘CTE’ corresponding to linear, planar, spherical, and “cigar-shaped” tensor encoding. Tensors are rotated so that linear and cigar tensors are aligned with the corresponding gradient direction and the planar tensor’s normal is aligned with the corresponding gradient direction. Magnitude is scaled to match the b-value.

3. an array of shape (N,3,3) specifying the b-tensor of each volume exactly. N corresponds to the number volumes in data. No rotation or scaling is performed.

Returns

gradientsGradientTable

A GradientTable with all the gradient information.

Other Parameters

**kwargsdict

Other keyword inputs are passed to GradientTable.

See also

GradientTable, gradient_table

gradient_table_from_gradient_strength_bvecs

dipy.core.gradients.gradient_table_from_gradient_strength_bvecs(gradient_strength, bvecs, big_delta, small_delta, b0_threshold=50, atol=0.01)

A general function for creating diffusion MR gradients.

It reads, loads and prepares scanner parameters like the b-values and b-vectors so that they can be useful during the reconstruction process.

Parameters

gradient_strengthan array of shape (N,),

gradient strength given in T/mm

bvecscan be any of two options

1. an array of shape (N, 3) or (3, N) with the b-vectors.

2. a path for the file which contains an array like the previous.

big_deltafloat or array of shape (N,)

acquisition pulse separation time in seconds

small_deltafloat

acquisition pulse duration time in seconds

b0_thresholdfloat

All b-values with values less than or equal to bo_threshold are considered as b0s i.e. without diffusion weighting.

atolfloat

All b-vectors need to be unit vectors up to a tolerance.

Returns

gradientsGradientTable

A GradientTable with all the gradient information.

Notes

1. Often b0s (b-values which correspond to images without diffusion weighting) have 0 values however in some cases the scanner cannot provide b0s of an exact 0 value and it gives a bit higher values e.g. 6 or 12. This is the purpose of the b0_threshold in the __init__.

2. We assume that the minimum number of b-values is 7.

3. B-vectors should be unit vectors.

Examples

>>> from dipy.core.gradients import (
...    gradient_table_from_gradient_strength_bvecs)
>>> gradient_strength = .03e-3 * np.ones(7)  # clinical strength at 30 mT/m
>>> big_delta = .03  # pulse separation of 30ms
>>> small_delta = 0.01  # pulse duration of 10ms
>>> gradient_strength[0] = 0
>>> sq2 = np.sqrt(2) / 2
>>> bvecs = np.array([[0, 0, 0],
...                   [1, 0, 0],
...                   [0, 1, 0],
...                   [0, 0, 1],
...                   [sq2, sq2, 0],
...                   [sq2, 0, sq2],
...                   [0, sq2, sq2]])
>>> gt = gradient_table_from_gradient_strength_bvecs(
...     gradient_strength, bvecs, big_delta, small_delta)

gradient_table_from_qvals_bvecs

dipy.core.gradients.gradient_table_from_qvals_bvecs(qvals, bvecs, big_delta, small_delta, b0_threshold=50, atol=0.01)

A general function for creating diffusion MR gradients.

It reads, loads and prepares scanner parameters like the b-values and b-vectors so that they can be useful during the reconstruction process.

Parameters

qvalsan array of shape (N,),

q-value given in 1/mm

bvecscan be any of two options

1. an array of shape (N, 3) or (3, N) with the b-vectors.

2. a path for the file which contains an array like the previous.

big_deltafloat or array of shape (N,)

acquisition pulse separation time in seconds

small_deltafloat

acquisition pulse duration time in seconds

b0_thresholdfloat

All b-values with values less than or equal to bo_threshold are considered as b0s i.e. without diffusion weighting.

atolfloat

All b-vectors need to be unit vectors up to a tolerance.

Returns

gradientsGradientTable

A GradientTable with all the gradient information.

Notes

1. Often b0s (b-values which correspond to images without diffusion weighting) have 0 values however in some cases the scanner cannot provide b0s of an exact 0 value and it gives a bit higher values e.g. 6 or 12. This is the purpose of the b0_threshold in the __init__.

2. We assume that the minimum number of b-values is 7.

3. B-vectors should be unit vectors.

Examples

>>> from dipy.core.gradients import gradient_table_from_qvals_bvecs
>>> qvals = 30. * np.ones(7)
>>> big_delta = .03  # pulse separation of 30ms
>>> small_delta = 0.01  # pulse duration of 10ms
>>> qvals[0] = 0
>>> sq2 = np.sqrt(2) / 2
>>> bvecs = np.array([[0, 0, 0],
...                   [1, 0, 0],
...                   [0, 1, 0],
...                   [0, 0, 1],
...                   [sq2, sq2, 0],
...                   [sq2, 0, sq2],
...                   [0, sq2, sq2]])
>>> gt = gradient_table_from_qvals_bvecs(qvals, bvecs,
...                                      big_delta, small_delta)

inv

dipy.core.gradients.inv(a, overwrite_a=False, check_finite=True)

Compute the inverse of a matrix.

Parameters

aarray_like

Square matrix to be inverted.

overwrite_abool, optional

Discard data in a (may improve performance). Default is False.

check_finitebool, optional

Whether to check that the input matrix contains only finite numbers. Disabling may give a performance gain, but may result in problems (crashes, non-termination) if the inputs do contain infinities or NaNs.

Returns

ainvndarray

Inverse of the matrix a.

Raises

LinAlgError

If a is singular.

ValueError

If a is not square, or not 2D.

Examples

>>> from scipy import linalg
>>> a = np.array([[1., 2.], [3., 4.]])
>>> linalg.inv(a)
array([[-2. ,  1. ],
       [ 1.5, -0.5]])
>>> np.dot(a, linalg.inv(a))
array([[ 1.,  0.],
       [ 0.,  1.]])

params_to_btens

dipy.core.gradients.params_to_btens(bval, bdelta, b_eta)

Compute b-tensor from trace, anisotropy and assymetry parameters

Parameters

bval: int or float

b-value (>= 0)

bdelta: int or float

normalized tensor anisotropy (>= -0.5 and <= 1)

b_eta: int or float

tensor assymetry (>= 0 and <= 1)

Returns

(3, 3) numpy.ndarray

output b-tensor

Notes

Implements eq. 7.11. p. 231 in [1].

References

1

4. Topgaard, NMR methods for studying microscopic diffusion

anisotropy, in: R. Valiullin (Ed.), Diffusion NMR of Confined Systems: Fluid Transport in Porous Solids and Heterogeneous Materials, Royal Society of Chemistry, Cambridge, UK, 2016.

polar

dipy.core.gradients.polar(a, side='right')

Compute the polar decomposition.

Returns the factors of the polar decomposition [1] u and p such that a = up (if side is “right”) or a = pu (if side is “left”), where p is positive semidefinite. Depending on the shape of a, either the rows or columns of u are orthonormal. When a is a square array, u is a square unitary array. When a is not square, the “canonical polar decomposition” [2] is computed.

Parameters

a(m, n) array_like

The array to be factored.

side{‘left’, ‘right’}, optional

Determines whether a right or left polar decomposition is computed. If side is “right”, then a = up. If side is “left”, then a = pu. The default is “right”.

Returns

u(m, n) ndarray

If a is square, then u is unitary. If m > n, then the columns of a are orthonormal, and if m < n, then the rows of u are orthonormal.

pndarray

p is Hermitian positive semidefinite. If a is nonsingular, p is positive definite. The shape of p is (n, n) or (m, m), depending on whether side is “right” or “left”, respectively.

References

1

R. A. Horn and C. R. Johnson, “Matrix Analysis”, Cambridge University Press, 1985.

2

N. J. Higham, “Functions of Matrices: Theory and Computation”, SIAM, 2008.

Examples

>>> from scipy.linalg import polar
>>> a = np.array([[1, -1], [2, 4]])
>>> u, p = polar(a)
>>> u
array([[ 0.85749293, -0.51449576],
       [ 0.51449576,  0.85749293]])
>>> p
array([[ 1.88648444,  1.2004901 ],
       [ 1.2004901 ,  3.94446746]])

A non-square example, with m < n:

>>> b = np.array([[0.5, 1, 2], [1.5, 3, 4]])
>>> u, p = polar(b)
>>> u
array([[-0.21196618, -0.42393237,  0.88054056],
       [ 0.39378971,  0.78757942,  0.4739708 ]])
>>> p
array([[ 0.48470147,  0.96940295,  1.15122648],
       [ 0.96940295,  1.9388059 ,  2.30245295],
       [ 1.15122648,  2.30245295,  3.65696431]])
>>> u.dot(p)   # Verify the decomposition.
array([[ 0.5,  1. ,  2. ],
       [ 1.5,  3. ,  4. ]])
>>> u.dot(u.T)   # The rows of u are orthonormal.
array([[  1.00000000e+00,  -2.07353665e-17],
       [ -2.07353665e-17,   1.00000000e+00]])

Another non-square example, with m > n:

>>> c = b.T
>>> u, p = polar(c)
>>> u
array([[-0.21196618,  0.39378971],
       [-0.42393237,  0.78757942],
       [ 0.88054056,  0.4739708 ]])
>>> p
array([[ 1.23116567,  1.93241587],
       [ 1.93241587,  4.84930602]])
>>> u.dot(p)   # Verify the decomposition.
array([[ 0.5,  1.5],
       [ 1. ,  3. ],
       [ 2. ,  4. ]])
>>> u.T.dot(u)  # The columns of u are orthonormal.
array([[  1.00000000e+00,  -1.26363763e-16],
       [ -1.26363763e-16,   1.00000000e+00]])

reorient_bvecs

dipy.core.gradients.reorient_bvecs(gtab, affines, atol=0.01)

Reorient the directions in a GradientTable.

When correcting for motion, rotation of the diffusion-weighted volumes might cause systematic bias in rotationally invariant measures, such as FA and MD, and also cause characteristic biases in tractography, unless the gradient directions are appropriately reoriented to compensate for this effect [Leemans2009].

Parameters

gtabGradientTable

The nominal gradient table with which the data were acquired.

affineslist or ndarray of shape (n, 4, 4) or (n, 3, 3)

Each entry in this list or array contain either an affine transformation (4,4) or a rotation matrix (3, 3). In both cases, the transformations encode the rotation that was applied to the image corresponding to one of the non-zero gradient directions (ordered according to their order in gtab.bvecs[~gtab.b0s_mask])

atol: see gradient_table()

Returns

gtaba GradientTable class instance with the reoriented directions

References

Leemans2009

The B-Matrix Must Be Rotated When Correcting for Subject Motion in DTI Data. Leemans, A. and Jones, D.K. (2009). MRM, 61: 1336-1349

round_bvals

dipy.core.gradients.round_bvals(bvals, bmag=None)

“This function rounds the b-values

Parameters

bvalsndarray

Array containing the b-values

bmagint

The order of magnitude to round the b-values. If not given b-values will be rounded relative to the order of magnitude \(bmag = (bmagmax - 1)\), where bmaxmag is the magnitude order of the larger b-value.

Returns

rbvalsndarray

Array containing the rounded b-values

unique_bvals

dipy.core.gradients.unique_bvals(bvals, bmag=None, rbvals=False)

This function gives the unique rounded b-values of the data

dipy.core.gradients.unique_bvals is deprecated, Please use dipy.core.gradients.unique_bvals_magnitude instead

• deprecated from version: 1.2

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

Parameters

bvalsndarray

Array containing the b-values

bmagint

The order of magnitude that the bvalues have to differ to be considered an unique b-value. B-values are also rounded up to this order of magnitude. Default: derive this value from the maximal b-value provided: \(bmag=log_{10}(max(bvals)) - 1\).

rbvalsbool, optional

If True function also returns all individual rounded b-values. Default: False

Returns

ubvalsndarray

Array containing the rounded unique b-values

unique_bvals_magnitude

dipy.core.gradients.unique_bvals_magnitude(bvals, bmag=None, rbvals=False)

This function gives the unique rounded b-values of the data

Parameters

bvalsndarray

Array containing the b-values

bmagint

The order of magnitude that the bvalues have to differ to be considered an unique b-value. B-values are also rounded up to this order of magnitude. Default: derive this value from the maximal b-value provided: \(bmag=log_{10}(max(bvals)) - 1\).

rbvalsbool, optional

If True function also returns all individual rounded b-values. Default: False

Returns

ubvalsndarray

Array containing the rounded unique b-values

unique_bvals_tolerance

dipy.core.gradients.unique_bvals_tolerance(bvals, tol=20)

Gives the unique b-values of the data, within a tolerance gap

The b-values must be regrouped in clusters easily separated by a distance greater than the tolerance gap. If all the b-values of a cluster fit within the tolerance gap, the highest b-value is kept.

Parameters

bvalsndarray

Array containing the b-values

tolint

The tolerated gap between the b-values to extract and the actual b-values.

Returns

ubvalsndarray

Array containing the unique b-values using the median value for each cluster

vec2vec_rotmat

dipy.core.gradients.vec2vec_rotmat(u, v)

rotation matrix from 2 unit vectors

u, v being unit 3d vectors return a 3x3 rotation matrix R than aligns u to v.

In general there are many rotations that will map u to v. If S is any rotation using v as an axis then R.S will also map u to v since (S.R)u = S(Ru) = Sv = v. The rotation R returned by vec2vec_rotmat leaves fixed the perpendicular to the plane spanned by u and v.

The transpose of R will align v to u.

Parameters

uarray, shape(3,)

varray, shape(3,)

Returns

Rarray, shape(3,3)

Examples

>>> import numpy as np
>>> from dipy.core.geometry import vec2vec_rotmat
>>> u=np.array([1,0,0])
>>> v=np.array([0,1,0])
>>> R=vec2vec_rotmat(u,v)
>>> np.dot(R,u)
array([ 0.,  1.,  0.])
>>> np.dot(R.T,v)
array([ 1.,  0.,  0.])

vector_norm

dipy.core.gradients.vector_norm(vec, axis=- 1, keepdims=False)

Return vector Euclidean (L2) norm

See unit vector and Euclidean norm

Parameters

vecarray_like

Vectors to norm.

axisint

Axis over which to norm. By default norm over last axis. If axis is None, vec is flattened then normed.

keepdimsbool

If True, the output will have the same number of dimensions as vec, with shape 1 on axis.

Returns

normarray

Euclidean norms of vectors.

Examples

>>> import numpy as np
>>> vec = [[8, 15, 0], [0, 36, 77]]
>>> vector_norm(vec)
array([ 17.,  85.])
>>> vector_norm(vec, keepdims=True)
array([[ 17.],
       [ 85.]])
>>> vector_norm(vec, axis=0)
array([  8.,  39.,  77.])

warn

dipy.core.gradients.warn(/, message, category=None, stacklevel=1, source=None)

Issue a warning, or maybe ignore it or raise an exception.

Graph

class dipy.core.graph.Graph

Bases: object

A simple graph class

Methods

add_edge
add_node
all_paths
children
del_node
del_node_and_edges
down
down_short
parents
shortest_path
up
up_short

__init__()

A graph class with nodes and edges :-)

This class allows us to:

1. find the shortest path

2. find all paths

3. add/delete nodes and edges

4. get parent & children nodes

Examples

>>> from dipy.core.graph import Graph
>>> g=Graph()
>>> g.add_node('a',5)
>>> g.add_node('b',6)
>>> g.add_node('c',10)
>>> g.add_node('d',11)
>>> g.add_edge('a','b')
>>> g.add_edge('b','c')
>>> g.add_edge('c','d')
>>> g.add_edge('b','d')
>>> g.up_short('d')
['d', 'b', 'a']

add_edge(n, m, ws=True, wp=True)

add_node(n, attr=None)

all_paths(graph, start, end=None, path=[])

children(n)

del_node(n)

del_node_and_edges(n)

down(n)

down_short(n)

parents(n)

shortest_path(graph, start, end=None, path=[])

up(n)

up_short(n)

histeq

dipy.core.histeq.histeq(arr, num_bins=256)

Performs an histogram equalization on arr. This was taken from: http://www.janeriksolem.net/2009/06/histogram-equalization-with-python-and.html

Parameters

arrndarray

Image on which to perform histogram equalization.

num_binsint

Number of bins used to construct the histogram.

Returns

resultndarray

Histogram equalized image.

Interpolator

class dipy.core.interpolation.Interpolator(data, voxel_size)

Bases: object

Class to be subclassed by different interpolator types

__init__(data, voxel_size)

NearestNeighborInterpolator

class dipy.core.interpolation.NearestNeighborInterpolator(data, voxel_size)

Bases: dipy.core.interpolation.Interpolator

Interpolates data using nearest neighbor interpolation

__init__(data, voxel_size)

OutsideImage

class dipy.core.interpolation.OutsideImage

Bases: Exception

Attributes

args

Methods

with_traceback

Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

__init__(*args, **kwargs)

TriLinearInterpolator

class dipy.core.interpolation.TriLinearInterpolator(data, voxel_size)

Bases: dipy.core.interpolation.Interpolator

Interpolates data using trilinear interpolation

interpolate 4d diffusion volume using 3 indices, ie data[x, y, z]

__init__(data, voxel_size)

interp_rbf

dipy.core.interpolation.interp_rbf()

Interpolate data on the sphere, using radial basis functions.

Parameters

data(N,) ndarray

Function values on the unit sphere.

sphere_originSphere

Positions of data values.

sphere_targetSphere

M target positions for which to interpolate.

function{‘multiquadric’, ‘inverse’, ‘gaussian’}

Radial basis function.

epsilonfloat

Radial basis function spread parameter. Defaults to approximate average distance between nodes.

a good start

smoothfloat

values greater than zero increase the smoothness of the approximation with 0 as pure interpolation. Default: 0.1

normstr

A string indicating the function that returns the “distance” between two points. ‘angle’ - The angle between two vectors ‘euclidean_norm’ - The Euclidean distance

Returns

v(M,) ndarray

Interpolated values.

See also

scipy.interpolate.Rbf

interpolate_scalar_2d

dipy.core.interpolation.interpolate_scalar_2d(image, locations)

Bilinear interpolation of a 2D scalar image

Interpolates the 2D image at the given locations. This function is a wrapper for _interpolate_scalar_2d for testing purposes, it is equivalent to scipy.ndimage.map_coordinates with bilinear interpolation

Parameters

fieldarray, shape (S, R)

the 2D image to be interpolated

locationsarray, shape (n, 2)

(locations[i,0], locations[i,1]), 0<=i<n must contain the row and column coordinates to interpolate the image at

Returns

outarray, shape (n,)

out[i], 0<=i<n will be the interpolated scalar at coordinates locations[i,:], or 0 if locations[i,:] is outside the image

insidearray, (n,)

if locations[i:] is inside the image then inside[i]=1, else inside[i]=0

interpolate_scalar_3d

dipy.core.interpolation.interpolate_scalar_3d(image, locations)

Trilinear interpolation of a 3D scalar image

Interpolates the 3D image at the given locations. This function is a wrapper for _interpolate_scalar_3d for testing purposes, it is equivalent to scipy.ndimage.map_coordinates with trilinear interpolation

Parameters

fieldarray, shape (S, R, C)

the 3D image to be interpolated

locationsarray, shape (n, 3)

(locations[i,0], locations[i,1], locations[i,2), 0<=i<n must contain the coordinates to interpolate the image at

Returns

outarray, shape (n,)

out[i], 0<=i<n will be the interpolated scalar at coordinates locations[i,:], or 0 if locations[i,:] is outside the image

insidearray, (n,)

if locations[i,:] is inside the image then inside[i]=1, else inside[i]=0

interpolate_scalar_nn_2d

dipy.core.interpolation.interpolate_scalar_nn_2d(image, locations)

Nearest neighbor interpolation of a 2D scalar image

Interpolates the 2D image at the given locations. This function is a wrapper for _interpolate_scalar_nn_2d for testing purposes, it is equivalent to scipy.ndimage.map_coordinates with nearest neighbor interpolation

Parameters

imagearray, shape (S, R)

the 2D image to be interpolated

locationsarray, shape (n, 2)

(locations[i,0], locations[i,1]), 0<=i<n must contain the row and column coordinates to interpolate the image at

Returns

outarray, shape (n,)

out[i], 0<=i<n will be the interpolated scalar at coordinates locations[i,:], or 0 if locations[i,:] is outside the image

insidearray, (n,)

if locations[i:] is inside the image then inside[i]=1, else inside[i]=0

interpolate_scalar_nn_3d

dipy.core.interpolation.interpolate_scalar_nn_3d(image, locations)

Nearest neighbor interpolation of a 3D scalar image

Interpolates the 3D image at the given locations. This function is a wrapper for _interpolate_scalar_nn_3d for testing purposes, it is equivalent to scipy.ndimage.map_coordinates with nearest neighbor interpolation

Parameters

imagearray, shape (S, R, C)

the 3D image to be interpolated

locationsarray, shape (n, 3)

(locations[i,0], locations[i,1], locations[i,2), 0<=i<n must contain the coordinates to interpolate the image at

Returns

outarray, shape (n,)

out[i], 0<=i<n will be the interpolated scalar at coordinates locations[i,:], or 0 if locations[i,:] is outside the image

insidearray, (n,)

if locations[i,:] is inside the image then inside[i]=1, else inside[i]=0

interpolate_vector_2d

dipy.core.interpolation.interpolate_vector_2d(field, locations)

Bilinear interpolation of a 2D vector field

Interpolates the 2D vector field at the given locations. This function is a wrapper for _interpolate_vector_2d for testing purposes, it is equivalent to using scipy.ndimage.map_coordinates with bilinear interpolation at each vector component

Parameters

fieldarray, shape (S, R, 2)

the 2D vector field to be interpolated

locationsarray, shape (n, 2)

(locations[i,0], locations[i,1]), 0<=i<n must contain the row and column coordinates to interpolate the vector field at

Returns

outarray, shape (n, 2)

out[i,:], 0<=i<n will be the interpolated vector at coordinates locations[i,:], or (0,0) if locations[i,:] is outside the field

insidearray, (n,)

if (locations[i,0], locations[i,1]) is inside the vector field then inside[i]=1, else inside[i]=0

interpolate_vector_3d

dipy.core.interpolation.interpolate_vector_3d(field, locations)

Trilinear interpolation of a 3D vector field

Interpolates the 3D vector field at the given locations. This function is a wrapper for _interpolate_vector_3d for testing purposes, it is equivalent to using scipy.ndimage.map_coordinates with trilinear interpolation at each vector component

Parameters

fieldarray, shape (S, R, C, 3)

the 3D vector field to be interpolated

locationsarray, shape (n, 3)

(locations[i,0], locations[i,1], locations[i,2), 0<=i<n must contain the coordinates to interpolate the vector field at

Returns

outarray, shape (n, 3)

out[i,:], 0<=i<n will be the interpolated vector at coordinates locations[i,:], or (0,0,0) if locations[i,:] is outside the field

insidearray, (n,)

if locations[i,:] is inside the vector field then inside[i]=1, else inside[i]=0

map_coordinates_trilinear_iso

dipy.core.interpolation.map_coordinates_trilinear_iso()

Trilinear interpolation (isotropic voxel size)

Has similar behavior to map_coordinates from scipy.ndimage

Parameters

dataarray, float64 shape (X, Y, Z)

pointsarray, float64 shape(N, 3)

data_stridesarray npy_intp shape (3,)

Strides sequence for data array

len_pointscnp.npy_intp

Number of points to interpolate

resultarray, float64 shape(N)

The output array. This array should be initialized before you call this function. On exit it will contain the interpolated values from data at points given by points.

Returns

None

Notes

The output array result is filled in-place.

nearestneighbor_interpolate

dipy.core.interpolation.nearestneighbor_interpolate()

trilinear_interp

dipy.core.interpolation.trilinear_interp(data, index, voxel_size)

Interpolates vector from 4D data at 3D point given by index

Interpolates a vector of length T from a 4D volume of shape (I, J, K, T), given point (x, y, z) where (x, y, z) are the coordinates of the point in real units (not yet adjusted for voxel size).

trilinear_interpolate4d

dipy.core.interpolation.trilinear_interpolate4d()

Tri-linear interpolation along the last dimension of a 4d array

Parameters

point1d array (3,)

3 doubles representing a 3d point in space. If point has integer values [i, j, k], the result will be the same as data[i, j, k].

data4d array

Data to be interpolated.

out1d array, optional

The output array for the result of the interpolation.

Returns

out1d array

The result of interpolation.

as_strided

dipy.core.ndindex.as_strided(x, shape=None, strides=None, subok=False, writeable=True)

Create a view into the array with the given shape and strides.

Warning

This function has to be used with extreme care, see notes.

Parameters

xndarray

Array to create a new.

shapesequence of int, optional

The shape of the new array. Defaults to x.shape.

stridessequence of int, optional

The strides of the new array. Defaults to x.strides.

subokbool, optional

New in version 1.10.

If True, subclasses are preserved.

writeablebool, optional

New in version 1.12.

If set to False, the returned array will always be readonly. Otherwise it will be writable if the original array was. It is advisable to set this to False if possible (see Notes).

Returns

viewndarray

See also

broadcast_to

broadcast an array to a given shape.

reshape

reshape an array.

lib.stride_tricks.sliding_window_view

userfriendly and safe function for the creation of sliding window views.

Notes

as_strided creates a view into the array given the exact strides and shape. This means it manipulates the internal data structure of ndarray and, if done incorrectly, the array elements can point to invalid memory and can corrupt results or crash your program. It is advisable to always use the original x.strides when calculating new strides to avoid reliance on a contiguous memory layout.

Furthermore, arrays created with this function often contain self overlapping memory, so that two elements are identical. Vectorized write operations on such arrays will typically be unpredictable. They may even give different results for small, large, or transposed arrays. Since writing to these arrays has to be tested and done with great care, you may want to use writeable=False to avoid accidental write operations.

For these reasons it is advisable to avoid as_strided when possible.