# `core`

Core objects

## Module: `core.geometry`

Utility functions for algebra etc

`sphere2cart`(r, theta, phi) | Spherical to Cartesian coordinates
`cart2sphere`(x, y, z) | Return angles for Cartesian 3D coordinates x, y, and z
`sph2latlon`(theta, phi) | Convert spherical coordinates to latitude and longitude.
`normalized_vector`(vec, *[, axis]) | Return vector divided by its Euclidean (L2) norm
`vector_norm`(vec, *[, axis, keepdims]) | Return vector Euclidean (L2) norm
`rodrigues_axis_rotation`(r, theta) | Rodrigues formula
`nearest_pos_semi_def`(B) | Least squares positive semi-definite tensor estimation.
`sphere_distance`(pts1, pts2, *[, radius, ...]) | Distance across sphere surface between pts1 and pts2
`cart_distance`(pts1, pts2) | Cartesian distance between pts1 and pts2
`vector_cosine`(vecs1, vecs2) | Cosine of angle between two (sets of) vectors
`lambert_equal_area_projection_polar`(theta, phi) | Lambert Equal Area Projection from polar sphere to plane
`lambert_equal_area_projection_cart`(x, y, z) | Lambert Equal Area Projection from cartesian vector to plane
`euler_matrix`(ai, aj, ak, *[, axes]) | Return homogeneous rotation matrix from Euler angles and axis sequence.
`compose_matrix`(*[, scale, shear, angles, ...]) | Return 4x4 transformation matrix from sequence of transformations.
`decompose_matrix`(matrix) | Return sequence of transformations from transformation matrix.
`circumradius`(a, b, c) | a, b and c are 3-dimensional vectors which are the vertices of a triangle.
`vec2vec_rotmat`(u, v) | rotation matrix from 2 unit vectors
`compose_transformations`(*mats) | Compose multiple 4x4 affine transformations in one 4x4 matrix
`perpendicular_directions`(v, *[, num, half]) | Computes n evenly spaced perpendicular directions relative to a given vector v
`dist_to_corner`(affine) | Calculate the maximal distance from the center to a corner of a voxel, given an affine
`is_hemispherical`(vecs) | Test whether all points on a unit sphere lie in the same hemisphere.

## Module: `core.gradients`

`GradientTable`(gradients, *[, big_delta, ...]) | Diffusion gradient information
`b0_threshold_empty_gradient_message`(bvals, ...) | Message about the `b0_threshold` value resulting in no gradient selection.
`b0_threshold_update_slicing_message`(slice_start) | Message for b0 threshold value update for slicing.
`mask_non_weighted_bvals`(bvals, b0_threshold) | Create a diffusion gradient-weighting mask for the b-values according to the provided b0 threshold value.
`gradient_table_from_bvals_bvecs`(bvals, bvecs, *) | Creates a GradientTable from a bvals array and a bvecs array
`gradient_table_from_qvals_bvecs`(qvals, ...) | A general function for creating diffusion MR gradients.
`gradient_table_from_gradient_strength_bvecs`(...) | A general function for creating diffusion MR gradients.
`gradient_table`(bvals, *[, bvecs, big_delta, ...]) | A general function for creating diffusion MR gradients.
`reorient_bvecs`(gtab, affines, *[, atol]) | Reorient the directions in a GradientTable.
`generate_bvecs`(N, *[, iters, rng]) | Generates N bvectors.
`round_bvals`(bvals, *[, bmag]) | "This function rounds the b-values
`unique_bvals_tolerance`(bvals, *[, tol]) | Gives the unique b-values of the data, within a tolerance gap
`get_bval_indices`(bvals, bval, *[, tol]) | Get indices where the b-value is bval
`unique_bvals_magnitude`(bvals, *[, bmag, rbvals]) | This function gives the unique rounded b-values of the data
`check_multi_b`(gtab, n_bvals, *[, non_zero, bmag]) | Check if you have enough different b-values in your gradient table
`btens_to_params`(btens, *[, ztol]) | Compute trace, anisotropy and asymmetry parameters from b-tensors.
`params_to_btens`(bval, bdelta, b_eta) | Compute b-tensor from trace, anisotropy and asymmetry parameters.
`ornt_mapping`(ornt1, ornt2) | Calculate the mapping needing to get from orn1 to orn2.
`reorient_vectors`(bvecs, current_ornt, ...[, ...]) | Change the orientation of gradients or other vectors.
`reorient_on_axis`(bvecs, current_ornt, ...[, ...]) |
`orientation_from_string`(string_ornt) | Return an array representation of an ornt string.
`orientation_to_string`(ornt) | Return a string representation of a 3d ornt.
`extract_b0`(dwi, b0_mask, *[, ...]) | Extract a set of b0 volumes from a dwi dataset.
`extract_dwi_shell`(dwi, gtab, bvals_to_extract, *) | Extract diffusion-weighted imaging (DWI) volumes based on b-value shells.

## Module: `core.graph`

A simple graph class

`Graph`() | A simple graph class

## Module: `core.histeq`

`histeq`(arr, *[, num_bins]) | Performs an histogram equalization on `arr`.

## Module: `core.ndindex`

`ndindex`(shape) | An N-dimensional iterator object to index arrays.

## Module: `core.onetime`

Descriptor support for NIPY.

Copyright (c) 2006-2011, NIPY Developers All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

> - Redistributions of source code must retain the above copyright

>     notice, this list of conditions and the following disclaimer.

> - Redistributions in binary form must reproduce the above

>     copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

> - Neither the name of the NIPY Developers nor the names of any

>     contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Utilities to support special Python descriptors [1], [2] in particular the use of a useful pattern for properties we call ‘one time properties’. These are object attributes which are declared as properties, but become regular attributes once they’ve been read the first time. They can thus be evaluated later in the object’s life cycle, but once evaluated they become normal, static attributes with no function call overhead on access or any other constraints.

A special ResetMixin class is provided to add a .reset() method to users who may want to have their objects capable of resetting these computed properties to their ‘untriggered’ state.

### References

[1]

How-To Guide for Descriptors, Raymond Hettinger. https://users.rcn.com/python/download/Descriptor.htm

[2]

Python data model, https://docs.python.org/reference/datamodel.html

`ResetMixin`() | A Mixin class to add a .reset() method to users of OneTimeProperty.
`OneTimeProperty`(func) | A descriptor to make special properties that become normal attributes.
`auto_attr`(func) | Decorator to create OneTimeProperty attributes.

## Module: `core.optimize`

A unified interface for performing and debugging optimization problems.

`Optimizer`(fun, x0[, args, method, jac, ...]) |
`SKLearnLinearSolver`(*args, **kwargs) | Provide a sklearn-like uniform interface to algorithms that solve problems of the form: \(y = Ax\) for \(x\)
`NonNegativeLeastSquares`(*args, **kwargs) | A sklearn-like interface to scipy.optimize.nnls
`PositiveDefiniteLeastSquares`(m, *[, A, L]) |
`spdot`(A, B) | The same as np.dot(A, B), except it works even if A or B or both are sparse matrices.
`sparse_nnls`(y, X, *[, momentum, step_size, ...]) | Solve y=Xh for h, using gradient descent, with X a sparse matrix.

## Module: `core.profile`

Class for profiling cython code

`Profiler`(*args[, call]) | Profile python/cython files or functions

## Module: `core.rng`

Random number generation utilities.

`WichmannHill2006`(*[, ix, iy, iz, it]) | Wichmann Hill random number generator.
`WichmannHill1982`(*[, ix, iy, iz]) | Algorithm AS 183 Appl.
`LEcuyer`(*[, s1, s2]) | Return a LEcuyer random number generator.

## Module: `core.sphere`

`Sphere`(*[, x, y, z, theta, phi, xyz, faces, ...]) | Points on the unit sphere.
`HemiSphere`(*[, x, y, z, theta, phi, xyz, ...]) | Points on the unit sphere.
`faces_from_sphere_vertices`(vertices) | Triangulate a set of vertices on the sphere.
`unique_edges`(faces, *[, return_mapping]) | Extract all unique edges from given triangular faces.
`unique_sets`(sets, *[, return_inverse]) | Remove duplicate sets.
`disperse_charges`(hemi, iters, *[, const]) | Models electrostatic repulsion on the unit sphere
`fibonacci_sphere`(n_points, *[, hemisphere, ...]) | Generate points on the surface of a sphere using Fibonacci Spiral.
`disperse_charges_alt`(init_pointset, iters, *) | Reimplementation of disperse_charges making use of scipy.optimize.fmin_slsqp.
`euler_characteristic_check`(sphere, *[, chi]) | Checks the euler characteristic of a sphere

## Module: `core.sphere_stats`

Statistics on spheres

`random_uniform_on_sphere`(*[, n, coords]) | Random unit vectors from a uniform distribution on the sphere.
`eigenstats`(points, *[, alpha]) | Principal direction and confidence ellipse
`compare_orientation_sets`(S, T) | Computes the mean cosine distance of the best match between points of two sets of vectors S and T (angular similarity)
`angular_similarity`(S, T) | Computes the cosine distance of the best match between points of two sets of vectors S and T

## Module: `core.subdivide_octahedron`

Create a unit sphere by subdividing all triangles of an octahedron recursively.

The unit sphere has a radius of 1, which also means that all points in this sphere (assumed to have centre at [0, 0, 0]) have an absolute value (modulus) of 1. Another feature of the unit sphere is that the unit normals of this sphere are exactly the same as the vertices.

This recursive method will avoid the common problem of the polar singularity, produced by 2d (lon-lat) parameterization methods.

`create_unit_sphere`(*[, recursion_level]) | Creates a unit sphere by subdividing a unit octahedron.
`create_unit_hemisphere`(*[, recursion_level]) | Creates a unit sphere by subdividing a unit octahedron, returns half the sphere.

## Module: `core.wavelet`

`cshift3D`(x, m, d) | 3D Circular Shift
`permutationinverse`(perm) | Function generating inverse of the permutation
`afb3D_A`(x, af, d) | 3D Analysis Filter Bank
`sfb3D_A`(lo, hi, sf, d) | 3D Synthesis Filter Bank
`sfb3D`(lo, hi, sf1, *[, sf2, sf3]) | 3D Synthesis Filter Bank
`afb3D`(x, af1, *[, af2, af3]) | 3D Analysis Filter Bank
`dwt3D`(x, J, af) | 3-D Discrete Wavelet Transform
`idwt3D`(w, J, sf) | Inverse 3-D Discrete Wavelet Transform

### 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:
    r array_like

      radius

    theta array_like

      inclination or polar angle

    phi array_like

      azimuth angle

  Returns:
    x array

      x coordinate(s) in Cartesian space

    y array

      y coordinate(s) in Cartesian space

    z array

      z coordinate

  Notes

  See these pages:

  - https://en.wikipedia.org/wiki/Spherical_coordinate_system

  - https://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.

### 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:
    x array_like

      x coordinate in Cartesian space

    y array_like

      y coordinate in Cartesian space

    z array_like

      z coordinate

  Returns:
    r array

      radius

    theta array

      inclination (polar) angle

    phi array

      azimuth angle

### sph2latlon

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

  Convert spherical coordinates to latitude and longitude.

  Returns:
    lat, lon ndarray

      Latitude and longitude.

### 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:
    vec array_like shape (3,)
  Returns:
    nvec array 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

### vector_norm

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

  Return vector Euclidean (L2) norm

  See unit vector and Euclidean norm

  Parameters:
    vec array_like

      Vectors to norm.

    axis int

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

    keepdims bool

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

  Returns:
    norm array

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

### 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:

  \mathbf{R} = \mathbf{I} + \sin(\theta)*\mathbf{S}_n + (1-\cos(\theta))*\mathbf{S}_n^2

  with:

  \[\begin{split}Sn = \begin{pmatrix} 0 & -n{z} & n{y} \\ n{z} & 0 & -n{x} \\ -n{y} & n{x} & 0 \end{pmatrix}\end{split}\]

  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)/\theta \mathbf{S}_r + (1-\cos(\theta))/\theta^2 \mathbf{S}_r^2

  leading to:

  R = \mathbf{I} + (1-\theta^2/6)*\mathbf{S}_r + (\frac{1}{2}-\theta^2/24)*\mathbf{S}_r^2
  Parameters:
    r array_like shape (3,)

      Axis.

    theta float

      Angle in degrees.

  Returns:
    R array, 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

### nearest_pos_semi_def

dipy.core.geometry.nearest_pos_semi_def(B)

  Least squares positive semi-definite tensor estimation.

  See [1] for further details about the method.

  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]

  Marc Niethammer, Raúl San José Estepar, Sylvain Bouix, Martha Shenton, and Carl-Fredrik Westin. On Diffusion Tensor Estimation. In International Conference of the IEEE Engineering in Medicine and Biology Society, volume, 2622–2625. 2006. doi:10.1109/IEMBS.2006.259826.

  Examples

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

### 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

    radius None or float, optional

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

    check_radius bool, 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(f'{sphere_distance([0,1],[1,0]):.4f}')
      1.5708
      >>> print(f'{sphere_distance([0,3],[3,0]):.4f}')
      4.7124

### 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

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

### 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:
    theta array_like

      theta spherical coordinates

    phi array_like

      phi spherical coordinates

  Returns:
    y(N,2) array

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

### 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:
    x array_like

      x coordinate in Cartesian space

    y array_like

      y coordinate in Cartesian space

    z array_like

      z coordinate

  Returns:
    y(N,2) array

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

### 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 https://github.com/cgohlke/transformations/blob/master/transformations/transformations.py

  Parameters:
    ai, aj, ak Euler’s roll, pitch and yaw angles
    axes One of 24 axis sequences as string or encoded tuple
  Returns:
    matrix ndarray (4, 4)
    Code modified from the work of Christoph Gohlke, link provided here
    https://github.com/cgohlke/transformations/blob/master/transformations/transformations.py

  Examples

      >>> import numpy
      >>> R = euler_matrix(1, 2, 3, axes='syxz')
      >>> numpy.allclose(numpy.sum(R[0]), -1.34786452)
      True
      >>> R = euler_matrix(1, 2, 3, axes=(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=axes)
      >>> for axes in _TUPLE2AXES.keys():
      ...    _ = euler_matrix(ai, aj, ak, axes=axes)

### 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 https://github.com/cgohlke/transformations/blob/master/transformations/transformations.py

  This is the inverse of the `decompose_matrix` function.

  Parameters:
    scale(3,) array_like

      Scaling factors.

    shear array_like

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

    angles array_like

      Euler angles about static x, y, z axes.

    translate array_like

      Translation vector along x, y, z axes.

    perspective array_like

      Perspective partition of matrix.

  Returns:
    matrix 4x4 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=scale, shear=shear, angles=angles, translate=trans, perspective=persp
      ... )

### 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: https://github.com/cgohlke/transformations/blob/master/transformations/transformations.py

  Parameters:
    matrix array_like

      Non-degenerate 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.

    perspective ndarray

      Perspective partition of matrix.

  Raises:
    ValueError

      If matrix is of wrong type or degenerate.

  Examples

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

### 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:
    circumradius float

      the desired circumradius

### 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:
    u array, shape(3,)
    v array, shape(3,)
  Returns:
    R array, 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.])

### compose_transformations

dipy.core.geometry.compose_transformations(*mats)

  Compose multiple 4x4 affine transformations in one 4x4 matrix

  Parameters:
    mat1 array, (4, 4)
    mat2 array, (4, 4)
    …
    matN array, (4, 4)
  Returns:
    matN x … x mat2 x mat1 array, (4, 4)

### 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:
    v array (3,)

      Array containing the three cartesian coordinates of vector v

    num int, optional

      Number of perpendicular directions to generate

    half bool, 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:
    psamples array (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.

### 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:
    affine 4 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.

### is_hemispherical

dipy.core.geometry.is_hemispherical(vecs)

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

  Parameters:
    vecs numpy.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_hemi bool

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

    pole numpy.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

### `GradientTable`

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

  Bases: `object`

  Diffusion gradient information

  Parameters:
    gradients array_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_threshold float

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

  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_threshold float

      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 |

  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

### b0_threshold_empty_gradient_message

dipy.core.gradients.b0_threshold_empty_gradient_message(bvals, idx, b0_threshold)

  Message about the `b0_threshold` value resulting in no gradient selection.

  Parameters:
    bvals(N,) ndarray

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

    idx ndarray

      Indices of the gradients to be selected.

    b0_threshold float

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

  Returns:
    str

      Message.

### b0_threshold_update_slicing_message

dipy.core.gradients.b0_threshold_update_slicing_message(slice_start)

  Message for b0 threshold value update for slicing.

  Parameters:
    slice_start int

      Starting index for slicing.

  Returns:
    str

      Message.

### mask_non_weighted_bvals

dipy.core.gradients.mask_non_weighted_bvals(bvals, b0_threshold)

  Create a diffusion gradient-weighting mask for the b-values according to the provided b0 threshold value.

  Parameters:
    bvals(N,) ndarray

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

    b0_threshold float

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

  Returns:
    ndarray

      Gradient-weighting mask: True for all b-value indices whose value is smaller or equal to `b0_threshold`; False otherwise.

### 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:
    bvals array_like (N,)

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

    bvecs array_like (N, 3)

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

    b0_threshold float

      Gradients with b-value less than or equal to b0_threshold are considered to not have diffusion weighting. If its value is equal to or larger than all values in b-vals, then it is assumed that no thresholding is requested.

    atol float

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

    btens can 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:
    gradients GradientTable

      A GradientTable with all the gradient information.

  Other Parameters:
    **kwargs dict

      Other keyword inputs are passed to GradientTable.

  See also

  `GradientTable`, `gradient_table`

### 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:
    qvals an array of shape (N,),

      q-value given in 1/mm

    bvecs can 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_delta float or array of shape (N,)

      acquisition pulse separation time in seconds

    small_delta float

      acquisition pulse duration time in seconds

    b0_threshold float

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

    atol float

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

  Returns:
    gradients GradientTable

      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)

### 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_strength an array of shape (N,),

      gradient strength given in T/mm

    bvecs can 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_delta float or array of shape (N,)

      acquisition pulse separation time in seconds

    small_delta float

      acquisition pulse duration time in seconds

    b0_threshold float

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

    atol float

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

  Returns:
    gradients GradientTable

      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

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:
    bvals can 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).

    bvecs can 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_delta float

      acquisition pulse separation time in seconds (default None)

    small_delta float

      acquisition pulse duration time in seconds (default None)

    b0_threshold float

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

    atol float

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

    btens can 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:
    gradients GradientTable

      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=bvecs)
      >>> gt.bvecs.shape == bvecs.shape
      True
      >>> gt = gradient_table(bvals, bvecs=bvecs.T)
      >>> gt.bvecs.shape == bvecs.T.shape
      False

### 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 [2].

  Parameters:
    gtab GradientTable

      The nominal gradient table with which the data were acquired.

    affines list or ndarray of shape (4, 4, n) or (3, 3, n)

      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:
    gtab a GradientTable class instance with the reoriented directions

  References

  [2]

  Alexander Leemans and Derek K.Jones. The B-matrix must be rotated when correcting for subject motion in DTI data. Magnetic Resonance in Medicine, 61(6):1336–1349, 2009. URL: https://doi.org/10.1002/mrm.21890, doi:10.1002/mrm.21890.

### generate_bvecs

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

  Generates N bvectors.

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

  Parameters:
    N int

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

    iters int

      Number of iterations to run.

    rng numpy.random.Generator, optional

      Numpy’s random number generator. If None, the generator is created. Default is None.

  Returns:
    bvecs(N,3) ndarray

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

### round_bvals

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

  “This function rounds the b-values

  Parameters:
    bvals ndarray

      Array containing the b-values

    bmag int

      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:
    rbvals ndarray

      Array containing the rounded 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:
    bvals ndarray

      Array containing the b-values

    tol int

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

  Returns:
    ubvals ndarray

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

### 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

### 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:
    bvals ndarray

      Array containing the b-values

    bmag int

      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\).

    rbvals bool, optional

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

  Returns:
    ubvals ndarray

      Array containing the rounded unique b-values

### 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:
    gtab GradientTable class instance.

      Gradient table.

    n_bvals int

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

    non_zero bool

      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)

    bmag int

      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:
    bool Whether there are at least n_bvals different b-values in the
    gradient table used.

### btens_to_params

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

  Compute trace, anisotropy and asymmetry 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

    ztol float

      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 asymmetry(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(f"bval={bval}; bdelta={bdelta}; b_eta={b_eta}")
      bval=[ 1.]; bdelta=[ 1.]; b_eta=[ 0.]

### params_to_btens

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

  Compute b-tensor from trace, anisotropy and asymmetry 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 asymmetry (>= 0 and <= 1)

  Returns:
    (3, 3) numpy.ndarray

      output b-tensor

  Notes

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

  References

  [3]

  Daniel Topgaard. NMR Methods for Studying Microscopic Diffusion Anisotropy. In Diffusion NMR of Confined Systems: Fluid Transport in Porous Solids and Heterogeneous Materials. The Royal Society of Chemistry, December 2016. URL: https://doi.org/10.1039/9781782623779-00226, doi:10.1039/9781782623779-00226.

### ornt_mapping

dipy.core.gradients.ornt_mapping(ornt1, ornt2)

  Calculate the mapping needing to get from orn1 to orn2.

### reorient_vectors

dipy.core.gradients.reorient_vectors(bvecs, current_ornt, new_ornt, *, axis=0)

  Change the orientation of gradients or other vectors.

  Moves vectors, storted along axis, from current_ornt to new_ornt. For example the vector [x, y, z] in “RAS” will be [-x, -y, z] in “LPS”.

  R: Right A: Anterior S: Superior L: Left P: Posterior I: Inferior

### reorient_on_axis

dipy.core.gradients.reorient_on_axis(bvecs, current_ornt, new_ornt, *, axis=0)

### orientation_from_string

dipy.core.gradients.orientation_from_string(string_ornt)

  Return an array representation of an ornt string.

### orientation_to_string

dipy.core.gradients.orientation_to_string(ornt)

  Return a string representation of a 3d ornt.

### extract_b0

dipy.core.gradients.extract_b0(dwi, b0_mask, *, group_contiguous_b0=False, strategy='mean')

  Extract a set of b0 volumes from a dwi dataset.

  Parameters:
    dwi: ndarray

      4D diffusion-weighted imaging data (X, Y, Z, N), where N is the number of volumes.

    b0_mask: ndarray of bool

      Mask over the time dimension (4th) identifying b0 volumes.

    group_contiguous_b0: bool, optional

      If True, each contiguous b0 volumes are grouped together.

    strategy: str, optional

      The extraction strategy, of either:

      > - first: select the first b0 found.

      > - all: select them all.

      > - mean: average them.

      When used in conjunction with the batch parameter set to True, the strategy is applied individually on each continuous set found.

  Returns:
    b0_data ndarray

      Extracted b0 volumes.

### extract_dwi_shell

dipy.core.gradients.extract_dwi_shell(dwi, gtab, bvals_to_extract, *, tol=20, group_shells=True)

  Extract diffusion-weighted imaging (DWI) volumes based on b-value shells.

  Parameters:
    dwi ndarray

      4D diffusion-weighted imaging data (X, Y, Z, N), where N is the number of volumes.

    gtab GradientTable

      The gradient table associated with the DWI dataset.

    bvals_to_extract list of int

      List of b-values to extract. If None, all b-values are included.

    tol int, optional

      Tolerance range for b-value selection. A value of 20 means volumes with b-values within ±20 units of the specified b-values will be extracted.

    group_shells bool, optional

      If True, extracted volumes are grouped into a single array. If False, returns a list of separate volumes.

  Returns:
    indices ndarray

      Indices of the extracted volumes corresponding to the specified b-values.

    shell_data ndarray or list of ndarrays

      Extracted DWI volumes, grouped if group_shells=True, otherwise returned as a list.

    output_bvals ndarray

      The b-values of the selected volumes.

    output_bvecs ndarray

      The b-vectors of the selected volumes.

### `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 |

### histeq

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

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

  Parameters:
    arr ndarray

      Image on which to perform histogram equalization.

    num_bins int

      Number of bins used to construct the histogram.

  Returns:
    result ndarray

      Histogram equalized image.

### ndindex

dipy.core.ndindex.ndindex(shape)

  An N-dimensional iterator object to index arrays.

  Given the shape of an array, an ndindex instance iterates over the N-dimensional index of the array. At each iteration a tuple of indices is returned; the last dimension is iterated over first.

  Parameters:
    shape tuple of ints

      The dimensions of the array.

  Examples

      >>> from dipy.core.ndindex import ndindex
      >>> shape = (3, 2, 1)
      >>> for index in ndindex(shape):
      ...     print(index)
      (0, 0, 0)
      (0, 1, 0)
      (1, 0, 0)
      (1, 1, 0)
      (2, 0, 0)
      (2, 1, 0)

### `ResetMixin`

class dipy.core.onetime.ResetMixin

  Bases: `object`

  A Mixin class to add a .reset() method to users of OneTimeProperty.

  By default, auto attributes once computed, become static. If they happen to depend on other parts of an object and those parts change, their values may now be invalid.

  This class offers a .reset() method that users can call explicitly when they know the state of their objects may have changed and they want to ensure that all their special attributes should be invalidated. Once reset() is called, all their auto attributes are reset to their OneTimeProperty descriptors, and their accessor functions will be triggered again.

  Warning

  If a class has a set of attributes that are OneTimeProperty, but that can be initialized from any one of them, do NOT use this mixin! For instance, UniformTimeSeries can be initialized with only sampling_rate and t0, sampling_interval and time are auto-computed. But if you were to reset() a UniformTimeSeries, it would lose all 4, and there would be then no way to break the circular dependency chains.

  If this becomes a problem in practice (for our analyzer objects it isn’t, as they don’t have the above pattern), we can extend reset() to check for a _no_reset set of names in the instance which are meant to be kept protected. But for now this is NOT done, so caveat emptor.

  Methods

  `reset`() | Reset all OneTimeProperty attributes that may have fired already.

  Examples

      >>> class A(ResetMixin):
      ...     def __init__(self,x=1.0):
      ...         self.x = x
      ...
      ...     @auto_attr
      ...     def y(self):
      ...         print('*** y computation executed ***')
      ...         return self.x / 2.0
      ...

      >>> a = A(10)

  About to access y twice, the second time no computation is done: >>> a.y * y computation executed * 5.0 >>> a.y 5.0

  Changing x >>> a.x = 20

  a.y doesn’t change to 10, since it is a static attribute: >>> a.y 5.0

  We now reset a, and this will then force all auto attributes to recompute the next time we access them: >>> a.reset()

  About to access y twice again after reset(): >>> a.y * y computation executed * 10.0 >>> a.y 10.0

  reset()

    Reset all OneTimeProperty attributes that may have fired already.

### `OneTimeProperty`

class dipy.core.onetime.OneTimeProperty(func)

  Bases: `object`

  A descriptor to make special properties that become normal attributes.

  This is meant to be used mostly by the auto_attr decorator in this module.

### auto_attr

dipy.core.onetime.auto_attr(func)

  Decorator to create OneTimeProperty attributes.

  Parameters:
    func method

      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:
      ...     @auto_attr
      ...     def a(self):
      ...         return 99
      ...
      >>> x = MagicProp()
      >>> 'a' in x.__dict__
      False
      >>> x.a
      99
      >>> 'a' in x.__dict__
      True

### `Optimizer`

class dipy.core.optimize.Optimizer(fun, x0, args=(), *, method='L-BFGS-B', jac=None, hess=None, hessp=None, bounds=None, constraints=(), tol=None, callback=None, options=None, evolution=False)

  Bases: `object`

  Attributes:
    evolution
    fopt
    message
    nfev
    nit
    xopt

  Methods

  print_summary |

### `SKLearnLinearSolver`

class dipy.core.optimize.SKLearnLinearSolver(*args, **kwargs)

  Bases: `object`

  Provide a sklearn-like uniform interface to algorithms that solve problems of the form: \(y = Ax\) for \(x\)

  Sub-classes of SKLearnLinearSolver should provide a ‘fit’ method that have the following signature: SKLearnLinearSolver.fit(X, y), which would set an attribute SKLearnLinearSolver.coef_, with the shape (X.shape[1],), such that an estimate of y can be calculated as: y_hat = np.dot(X, SKLearnLinearSolver.coef_.T)

  Methods

  `fit`(X, y) | Implement for all derived classes
  `predict`(X) | Predict using the result of the model

  abstractmethod fit(X, y)

    Implement for all derived classes

  predict(X)

    Predict using the result of the model

    Parameters:
      X array-like (n_samples, n_features)

        Samples.

    Returns:
      C array, shape = (n_samples,)

        Predicted values.

### `NonNegativeLeastSquares`

class dipy.core.optimize.NonNegativeLeastSquares(*args, **kwargs)

  Bases: `SKLearnLinearSolver`

  A sklearn-like interface to scipy.optimize.nnls

  Methods

  `fit`(X, y) | Fit the NonNegativeLeastSquares linear model to data
  `predict`(X) | Predict using the result of the model

  fit(X, y)

    Fit the NonNegativeLeastSquares linear model to data

    Parameters:
      X array-like (n_samples, n_features)

        Samples.

      y array-like (n_samples,)

        Target values.

### `PositiveDefiniteLeastSquares`

class dipy.core.optimize.PositiveDefiniteLeastSquares(m, *, A=None, L=None)

  Bases: `object`

  Methods

  `solve`(design_matrix, measurements, *[, check]) | Solve CVXPY problem

  solve(design_matrix, measurements, *, check=False, **kwargs)

    Solve CVXPY problem

    Solve a CVXPY problem instance for a given design matrix and a given set of observations, and return the optimum.

    Parameters:
      design_matrix array (n, m)

        Design matrix.

      measurements array (n)

        Measurements.

      check boolean, optional

        If True check whether the unconstrained optimization solution already satisfies the constraints, before running the constrained optimization. This adds overhead, but can avoid unnecessary constrained optimization calls.

      kwargs keyword arguments

        Arguments passed to the CVXPY solve method.

    Returns:
      h array (m)

        Estimated optimum for problem variables \(h\).

### spdot

dipy.core.optimize.spdot(A, B)

  The same as np.dot(A, B), except it works even if A or B or both are sparse matrices.

  Parameters:
    A, B arrays of shape (m, n), (n, k)
  Returns:
    The matrix product AB. If both A and B are sparse, the result will be a
    sparse matrix. Otherwise, a dense result is returned
    See discussion here:
    https://mail.scipy.org/pipermail/scipy-user/2010-November/027700.html

### sparse_nnls

dipy.core.optimize.sparse_nnls(y, X, *, momentum=1, step_size=0.01, non_neg=True, check_error_iter=10, max_error_checks=10, converge_on_sse=0.99)

  Solve y=Xh for h, using gradient descent, with X a sparse matrix.

  Parameters:
    y 1-d array of shape (N)

      The data. Needs to be dense.

    X ndarray. May be either sparse or dense. Shape (N, M)

      The regressors

    momentum float, optional

      The persistence of the gradient.

    step_size float, optional

      The increment of parameter update in each iteration

    non_neg Boolean, optional

      Whether to enforce non-negativity of the solution.

    check_error_iter int, optional

      How many rounds to run between error evaluation for convergence-checking.

    max_error_checks int, optional

      Don’t check errors more than this number of times if no improvement in r-squared is seen.

    converge_on_sse float, optional

      a percentage improvement in SSE that is required each time to say that things are still going well.

  Returns:
    h_best The best estimate of the parameters.

### `Profiler`

class dipy.core.profile.Profiler(*args, call=None)

  Bases: `object`

  Profile python/cython files or functions

  If you are profiling cython code you need to add # cython: profile=True on the top of your .pyx file

  and for the functions that you do not want to profile you can use this decorator in your cython files

  @cython.profile(False)

  Parameters:
    caller file or function call
    args function arguments
  Attributes:
    stats function, stats.print_stats(10) will prin the 10 slower functions

  Methods

  `print_stats`(*[, N]) | Print stats for profiling

  References

  https://docs.cython.org/src/tutorial/profiling_tutorial.html https://docs.python.org/library/profile.html https://github.com/rkern/line_profiler

  Examples

  from dipy.core.profile import Profiler import numpy as np p=Profiler(np.sum,np.random.rand(1000000,3)) fname=’test.py’ p=Profiler(fname) p.print_stats(10) p.print_stats(‘det’)

  print_stats(*, N=10)

    Print stats for profiling

    You can use it in all different ways developed in pstats for example print_stats(10) will give you the 10 slowest calls or print_stats(‘function_name’) will give you the stats for all the calls with name ‘function_name’

    Parameters:
      N stats.print_stats argument

### WichmannHill2006

dipy.core.rng.WichmannHill2006(*, ix=100001, iy=200002, iz=300003, it=400004)

  Wichmann Hill random number generator.

  See [4] for advice on generating many sequences for use together, and on alternative algorithms and codes

  Parameters:
    ix: int

      First seed value. Should not be null. (default 100001)

    iy: int

      Second seed value. Should not be null. (default 200002)

    iz: int

      Third seed value. Should not be null. (default 300003)

    it: int

      Fourth seed value. Should not be null. (default 400004)

  Returns:
    r_number float

      pseudo-random number uniformly distributed between [0-1]

  References

  [4]

  Brian A. Wichmann and Ian David Hill. Generating good pseudo-random numbers. Computational Statistics & Data Analysis, 51(3):1614–1622, 2006. URL: https://doi.org/10.1016/j.csda.2006.05.019, doi:10.1016/j.csda.2006.05.019.

  Examples

      >>> from dipy.core import rng
      >>> N = 1000
      >>> a = [rng.WichmannHill2006() for i in range(N)]

### WichmannHill1982

dipy.core.rng.WichmannHill1982(*, ix=100001, iy=200002, iz=300003)

  Algorithm AS 183 Appl. Statist. (1982) vol.31, no.2.

  Returns a pseudo-random number rectangularly distributed between 0 and 1. The cycle length is 6.95E+12 (See page 123 of Applied Statistics (1984) vol.33), not as claimed in the original article.

  ix, iy and iz should be set to integer values between 1 and 30000 before the first entry.

  Integer arithmetic up to 5212632 is required.

  Parameters:
    ix: int

      First seed value. Should not be null. (default 100001)

    iy: int

      Second seed value. Should not be null. (default 200002)

    iz: int

      Third seed value. Should not be null. (default 300003)

  Returns:
    r_number float

      pseudo-random number uniformly distributed between [0-1]

  Examples

      >>> from dipy.core import rng
      >>> N = 1000
      >>> a = [rng.WichmannHill1982() for i in range(N)]

### LEcuyer

dipy.core.rng.LEcuyer(*, s1=100001, s2=200002)

  Return a LEcuyer random number generator.

  Generate uniformly distributed random numbers using the 32-bit generator from figure 3 of:

  > L’Ecuyer, P. Efficient and portable combined random number generators, C.A.C.M., vol. 31, 742-749 & 774-?, June 1988.

  The cycle length is claimed to be 2.30584E+18

  Parameters:
    s1: int

      First seed value. Should not be null. (default 100001)

    s2: int

      Second seed value. Should not be null. (default 200002)

  Returns:
    r_number float

      pseudo-random number uniformly distributed between [0-1]

  Examples

      >>> from dipy.core import rng
      >>> N = 1000
      >>> a = [rng.LEcuyer() for i in range(N)]

### `Sphere`

class dipy.core.sphere.Sphere(*, x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None)

  Bases: `object`

  Points on the unit sphere.

  The sphere can be constructed using one of three conventions:

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

  Parameters:
    x, y, z 1-D array_like

      Vertices as x-y-z coordinates.

    theta, phi 1-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.

  Attributes:
    x
    y
    z

  Methods

  `find_closest`(xyz) | Find the index of the vertex in the Sphere closest to the input vector
  `subdivide`(*[, n]) | Subdivides each face of the sphere into four new faces.

  edges |
  faces |
  vertices |

  find_closest(xyz)

    Find the index of the vertex in the Sphere closest to the input vector

    Parameters:
      xyz array-like, 3 elements

        A unit vector

    Returns:
      idx int

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

  subdivide(*, n=1)

    Subdivides each face of the sphere into four new faces.

    New vertices are created at a, b, and c. Then each face [x, y, z] is divided into faces [x, a, c], [y, a, b], [z, b, c], and [a, b, c].

              y
              /\
             /  \
           a/____\b
           /\    /\
          /  \  /  \
         /____\/____\
        x      c     z

    Parameters:
      n int, optional

        The number of subdivisions to perform.

    Returns:
      new_sphere Sphere

        The subdivided sphere.

### `HemiSphere`

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

  Bases: `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, z 1-D array_like

      Vertices as x-y-z coordinates.

    theta, phi 1-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.

    tol float

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

  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 |

  See also

  `Sphere`
  find_closest(xyz)

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

    Parameters:
      xyz array-like, 3 elements

        A unit vector

    Returns:
      idx int

        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.

### faces_from_sphere_vertices

dipy.core.sphere.faces_from_sphere_vertices(vertices)

  Triangulate a set of vertices on the sphere.

  Parameters:
    vertices(M, 3) ndarray

      XYZ coordinates of vertices on the sphere.

  Returns:
    faces(N, 3) ndarray

      Indices into vertices; forms triangular faces.

### unique_edges

dipy.core.sphere.unique_edges(faces, *, return_mapping=False)

  Extract all unique edges from given triangular faces.

  Parameters:
    faces(N, 3) ndarray

      Vertex indices forming triangular faces.

    return_mapping bool

      If true, a mapping to the edges of each face is returned.

  Returns:
    edges(N, 2) ndarray

      Unique edges.

    mapping(N, 3)

      For each face, [x, y, z], a mapping to its edges [a, b, c].

             y
             /               /               a/
          /                  /                   /__________          x      c     z

### unique_sets

dipy.core.sphere.unique_sets(sets, *, return_inverse=False)

  Remove duplicate sets.

  Parameters:
    sets array (N, k)

      N sets of size k.

    return_inverse bool

      If True, also returns the indices of unique_sets that can be used to reconstruct sets (the original ordering of each set may not be preserved).

  Returns:
    unique_sets array

      Unique sets.

    inverse array (N,)

      The indices to reconstruct sets from unique_sets.

### disperse_charges

dipy.core.sphere.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:
    hemi HemiSphere

      Points on a unit sphere.

    iters int

      Number of iterations to run.

    const float

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

  Returns:
    hemi HemiSphere

      Distributed points on a unit sphere.

    potential ndarray

      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. Therefore, 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.

### fibonacci_sphere

dipy.core.sphere.fibonacci_sphere(n_points, *, hemisphere=False, randomize=True, rng=None)

  Generate points on the surface of a sphere using Fibonacci Spiral.

  Parameters:
    n_points int

      The number of points to generate on the sphere surface.

    hemisphere bool, optional

      If True, generate points only on the upper hemisphere. Default is False.

    randomize bool, optional

      If True, randomize the starting point on the sphere.

    rng np.random.Generator, optional

      If None creates random generator in function.

  Returns:
    points ndarray

      An array of 3D points representing coordinates on the sphere surface.

### disperse_charges_alt

dipy.core.sphere.disperse_charges_alt(init_pointset, iters, *, tol=0.001)

  Reimplementation of disperse_charges making use of scipy.optimize.fmin_slsqp.

  Parameters:
    init_pointset(N, 3) ndarray

      Points on a unit sphere.

    iters int

      Number of iterations to run.

    tol float

      Tolerance for the optimization.

  Returns:
    array-like (N, 3)

      Distributed points on a unit sphere.

### euler_characteristic_check

dipy.core.sphere.euler_characteristic_check(sphere, *, chi=2)

  Checks the euler characteristic of a sphere

  If \(f\) = number of faces, \(e\) = number_of_edges and \(v\) = number of vertices, the Euler formula says \(f-e+v = 2\) for a mesh on a sphere. More generally, whether \(f -e + v == \chi\) where \(\chi\) is the Euler characteristic of the mesh.

  - Open chain (track) has \(\chi=1\)

  - Closed chain (loop) has \(\chi=0\)

  - Disk has \(\chi=1\)

  - Sphere has \(\chi=2\)

  - HemiSphere has \(\chi=1\)

  Parameters:
    sphere Sphere

      A Sphere instance with vertices, edges and faces attributes.

    chi int, optional

      The Euler characteristic of the mesh to be checked

  Returns:
    check bool

      True if the mesh has Euler characteristic \(\chi\)

  Examples

      >>> euler_characteristic_check(unit_octahedron)
      True
      >>> hemisphere = HemiSphere.from_sphere(unit_icosahedron)
      >>> euler_characteristic_check(hemisphere, chi=1)
      True

### random_uniform_on_sphere

dipy.core.sphere_stats.random_uniform_on_sphere(*, n=1, coords='xyz')

  Random unit vectors from a uniform distribution on the sphere.

  Parameters:
    n int

      Number of random vectors

    coords{‘xyz’, ‘radians’, ‘degrees’}

      ‘xyz’ for cartesian form ‘radians’ for spherical form in rads ‘degrees’ for spherical form in degrees

  Returns:
    X array, shape (n,3) if coords=’xyz’ or shape (n,2) otherwise

      Uniformly distributed vectors on the unit sphere.

  Notes

  The uniform distribution on the sphere, parameterized by spherical coordinates \((\theta, \phi)\), should verify \(\phi\sim U[0,2\pi]\), while \(z=\cos(\theta)\sim U[-1,1]\).

  References

  [1]

  https://mathworld.wolfram.com/SpherePointPicking.html.

  Examples

      >>> from dipy.core.sphere_stats import random_uniform_on_sphere
      >>> X = random_uniform_on_sphere(n=4, coords='radians')
      >>> X.shape == (4, 2)
      True
      >>> X = random_uniform_on_sphere(n=4, coords='xyz')
      >>> X.shape == (4, 3)
      True

### eigenstats

dipy.core.sphere_stats.eigenstats(points, *, alpha=0.05)

  Principal direction and confidence ellipse

  Implements equations in section 6.3.1(ii) of Fisher, Lewis and Embleton, supplemented by equations in section 3.2.5.

  Parameters:
    points array_like (N,3)

      array of points on the sphere of radius 1 in \(\mathbb{R}^3\)

    alpha real or None

      1 minus the coverage for the confidence ellipsoid, e.g. 0.05 for 95% coverage.

  Returns:
    centre vector (3,)

      centre of ellipsoid

    b1 vector (2,)

      lengths of semi-axes of ellipsoid

### compare_orientation_sets

dipy.core.sphere_stats.compare_orientation_sets(S, T)

  Computes the mean cosine distance of the best match between points of two sets of vectors S and T (angular similarity)

  Parameters:
    S array, shape (m,d)

      First set of vectors.

    T array, shape (n,d)

      Second set of vectors.

  Returns:
    max_mean_cosine float

      Maximum mean cosine distance.

  Examples

      >>> from dipy.core.sphere_stats import compare_orientation_sets
      >>> S=np.array([[1,0,0],[0,1,0],[0,0,1]])
      >>> T=np.array([[1,0,0],[0,0,1]])
      >>> compare_orientation_sets(S,T)
      1.0
      >>> T=np.array([[0,1,0],[1,0,0],[0,0,1]])
      >>> S=np.array([[1,0,0],[0,0,1]])
      >>> compare_orientation_sets(S,T)
      1.0
      >>> from dipy.core.sphere_stats import compare_orientation_sets
      >>> S=np.array([[-1,0,0],[0,1,0],[0,0,1]])
      >>> T=np.array([[1,0,0],[0,0,-1]])
      >>> compare_orientation_sets(S,T)
      1.0

### angular_similarity

dipy.core.sphere_stats.angular_similarity(S, T)

  Computes the cosine distance of the best match between points of two sets of vectors S and T

  Parameters:
    S array, shape (m,d)
    T array, shape (n,d)
  Returns:
    max_cosine_distance:float

  Examples

      >>> import numpy as np
      >>> from dipy.core.sphere_stats import angular_similarity
      >>> S=np.array([[1,0,0],[0,1,0],[0,0,1]])
      >>> T=np.array([[1,0,0],[0,0,1]])
      >>> angular_similarity(S,T)
      2.0
      >>> T=np.array([[0,1,0],[1,0,0],[0,0,1]])
      >>> S=np.array([[1,0,0],[0,0,1]])
      >>> angular_similarity(S,T)
      2.0
      >>> S=np.array([[-1,0,0],[0,1,0],[0,0,1]])
      >>> T=np.array([[1,0,0],[0,0,-1]])
      >>> angular_similarity(S,T)
      2.0
      >>> T=np.array([[0,1,0],[1,0,0],[0,0,1]])
      >>> S=np.array([[1,0,0],[0,1,0],[0,0,1]])
      >>> angular_similarity(S,T)
      3.0
      >>> S=np.array([[0,1,0],[1,0,0],[0,0,1]])
      >>> T=np.array([[1,0,0],[0,np.sqrt(2)/2.,np.sqrt(2)/2.],[0,0,1]])
      >>> angular_similarity(S,T)
      2.7071067811865475
      >>> S=np.array([[0,1,0],[1,0,0],[0,0,1]])
      >>> T=np.array([[1,0,0]])
      >>> angular_similarity(S,T)
      1.0
      >>> S=np.array([[0,1,0],[1,0,0]])
      >>> T=np.array([[0,0,1]])
      >>> angular_similarity(S,T)
      0.0
      >>> S=np.array([[0,1,0],[1,0,0]])
      >>> T=np.array([[0,np.sqrt(2)/2.,np.sqrt(2)/2.]])

  Now we use `print` to reduce the precision of the printed output (so the doctests don’t detect unimportant differences)

      >>> print(f'{angular_similarity(S,T):.12f}')
      0.707106781187
      >>> S=np.array([[0,1,0]])
      >>> T=np.array([[0,np.sqrt(2)/2.,np.sqrt(2)/2.]])
      >>> print(f'{angular_similarity(S,T):.12f}')
      0.707106781187
      >>> S=np.array([[0,1,0],[0,0,1]])
      >>> T=np.array([[0,np.sqrt(2)/2.,np.sqrt(2)/2.]])
      >>> print(f'{angular_similarity(S,T):.12f}')
      0.707106781187

### create_unit_sphere

dipy.core.subdivide_octahedron.create_unit_sphere(*, recursion_level=2)

  Creates a unit sphere by subdividing a unit octahedron.

  Starts with a unit octahedron and subdivides the faces, projecting the resulting points onto the surface of a unit sphere.

  Parameters:
    recursion_level int

      Level of subdivision, recursion_level=1 will return an octahedron, anything bigger will return a more subdivided sphere. The sphere will have \(4^recursion_level+2\) vertices.

  Returns:
    Sphere

      The unit sphere.

  See also

  `create_unit_hemisphere`, `Sphere`

### create_unit_hemisphere

dipy.core.subdivide_octahedron.create_unit_hemisphere(*, recursion_level=2)

  Creates a unit sphere by subdividing a unit octahedron, returns half the sphere.

  Parameters:
    recursion_level int

      Level of subdivision, recursion_level=1 will return an octahedron, anything bigger will return a more subdivided sphere. The sphere will have \((4^recursion_level+2)/2\) vertices.

  Returns:
    HemiSphere

      Half of a unit sphere.

  See also

  `create_unit_sphere`, `Sphere`, `HemiSphere`

### cshift3D

dipy.core.wavelet.cshift3D(x, m, d)

  3D Circular Shift

  Parameters:
    x 3D ndarray

      N1 by N2 by N3 array

    m int

      amount of shift

    d int

      dimension of shift (d = 1,2,3)

  Returns:
    y 3D ndarray

      array x will be shifted by m samples down along dimension d

### permutationinverse

dipy.core.wavelet.permutationinverse(perm)

  Function generating inverse of the permutation

  Parameters:
    perm 1D array
  Returns:
    inverse 1D array

      permutation inverse of the input

### afb3D_A

dipy.core.wavelet.afb3D_A(x, af, d)
  3D Analysis Filter Bank

    (along one dimension only)

  Parameters:
    x 3D ndarray
      N1xN2xN2 matrix, where min(N1,N2,N3) > 2*length(filter)

        (Ni are even)

    af 2D ndarray

      analysis filter for the columns af[:, 1] - lowpass filter af[:, 2] - highpass filter

    d int

      dimension of filtering (d = 1, 2 or 3)

  Returns:
    lo 1D array

      lowpass subbands

    hi 1D array

      highpass subbands

### sfb3D_A

dipy.core.wavelet.sfb3D_A(lo, hi, sf, d)
  3D Synthesis Filter Bank

    (along single dimension only)

  Parameters:
    lo 1D array

      lowpass subbands

    hi 1D array

      highpass subbands

    sf 2D ndarray

      synthesis filters

    d int

      dimension of filtering

  Returns:
    y 3D ndarray

      the N1xN2xN3 matrix

### sfb3D

dipy.core.wavelet.sfb3D(lo, hi, sf1, *, sf2=None, sf3=None)

  3D Synthesis Filter Bank

  Parameters:
    lo 1D array

      lowpass subbands

    hi 1D array

      highpass subbands

    sfi 2D ndarray

      synthesis filters for dimension i

  Returns:
    y 3D ndarray

      output array

### afb3D

dipy.core.wavelet.afb3D(x, af1, *, af2=None, af3=None)

  3D Analysis Filter Bank

  Parameters:
    x 3D ndarray

      N1 by N2 by N3 array matrix, where 1) N1, N2, N3 all even 2) N1 >= 2*len(af1) 3) N2 >= 2*len(af2) 4) N3 >= 2*len(af3)

    afi 2D ndarray

      analysis filters for dimension i afi[:, 1] - lowpass filter afi[:, 2] - highpass filter

  Returns:
    lo 1D array

      lowpass subband

    hi 1D array

      highpass subbands, h[d]- d = 1..7

### dwt3D

dipy.core.wavelet.dwt3D(x, J, af)

  3-D Discrete Wavelet Transform

  Parameters:
    x 3D ndarray

      N1 x N2 x N3 matrix 1) Ni all even 2) min(Ni) >= 2^(J-1)*length(af)

    J int

      number of stages

    af 2D ndarray

      analysis filters

  Returns:
    w cell array

      wavelet coefficients

### idwt3D

dipy.core.wavelet.idwt3D(w, J, sf)

  Inverse 3-D Discrete Wavelet Transform

  Parameters:
    w cell array

      wavelet coefficient

    J int

      number of stages

    sf 2D ndarray

      synthesis filters

  Returns:
    y 3D ndarray

      output array