utils

Module: utils.spherical_convolution

dmipy.utils.spherical_convolution.real_sym_rh_basis(sh_order, theta, phi)

Samples a real symmetric rotational harmonic basis at point on the sphere

Samples the basis functions up to order sh_order at points on the sphere given by theta and phi. The basis functions are defined here the same way as in fibernavigator, where the real harmonic \(Y^m_n\) is defined to be:

\(Y^0_n\) if m = 0
Parameters:

sh_order : int

even int > 0, max spherical harmonic degree

theta : float [0, 2*pi]

The azimuthal (longitudinal) coordinate.

phi : float [0, pi]

The polar (colatitudinal) coordinate.

Returns:

real_rh_matrix : array of shape ()

The real harmonic \(Y^0_n\) sampled at theta and phi

dmipy.utils.spherical_convolution.sh_convolution(f_distribution_sh, kernel_rh)

Spherical convolution between a fiber distribution (f) in spherical harmonics and a kernel in terms of rotational harmonics (oriented along the z-axis).

Parameters:

f_distribution_sh : array, shape (sh_coef)

spherical harmonic coefficients of a fiber distribution.

kernel_rh : array, shape (sh_coef),

rotational harmonic coefficients of the convolution kernel. In our case this is the spherical signal of one micro-environment at one b-value.

Returns:

f_kernel_convolved : array, shape (sh_coef)

spherical harmonic coefficients of the convolved kernel and distribution.

Module: utils.spherical_mean

dmipy.utils.spherical_mean.estimate_spherical_mean_multi_shell(E_attenuation, acquisition_scheme, sh_order=6)

Estimates the spherical mean per shell of multi-shell acquisition. Uses spherical harmonics to do the estimation.

Parameters:

E_attenuation : array, shape (N),

signal attenuation.

bvecs : array, shape (N x 3),

x, y, z components of cartesian unit b-vectors.

b_shell_indices : array, shape (N)

array of integers indicating which measurement belongs to which shell. 0 should be used for b0 measurements, 1 for the lowest b-value shell, 2 for the second lowest etc.

Returns:

E_mean : array, shape (number of b-shells)

spherical means of the signal attenuation per shell of the. For example, if there are three shells in the acquisition then the array is of length 3.

dmipy.utils.spherical_mean.estimate_spherical_mean_shell(E_shell, bvecs_shell, sh_order=6, sh_mat=None)

Estimates spherical mean of a shell of measurements using spherical harmonics. The spherical mean is contained only in the Y00 spherical harmonic, as long as the basis expansion order is sufficient to capture the spherical signal.

Parameters:

E_shell : array, shape(N),

signal attenuation values.

bvecs_shell : array, shape (N x 3),

Cartesian unit vectors describing the orientation of the signal attenuation values.

sh_order : integer,

maximum spherical harmonics order. It needs to be high enough to describe the spherical profile of the signal attenuation. The order 6 is sufficient to describe a stick at b-values up to 10,000 s/mm^2.

sh_mat : array of size (N_bvecs, N_coefficients),

possibly precomputed spherical harmonics transform matrix.

Returns:

E_mean : float,

spherical mean of the signal attenuation.

Module: utils.utils

dmipy.utils.utils.perpendicular_vector(v)

Returns a perpendicular vector to vector “v”.

Parameters:

v : array, shape (3)

normally Cartesian unit vector, but can also be any vector.

Returns:

v_perp : array, shape (3)

If v is unit vector, v_perp is a Cartesian unit vector perpendicular to v.

dmipy.utils.utils.rotation_matrix_around_100(psi)

Generates a rotation matrix that rotates around the x-axis (1, 0, 0).

Parameters:

psi : float,

euler angle [0, pi].

Returns:

R : array, shape (3 x 3)

Rotation matrix.

dmipy.utils.utils.rotation_matrix_100_to_theta_phi(theta, phi)

Generates a rotation matrix that rotates from the x-axis (1, 0, 0) to an other position on the unit sphere.

Parameters:

theta : float,

inclination of polar angle of main angle mu [0, pi].

phi : float,

polar angle of main angle mu [-pi, pi].

Returns:

R : array, shape (3 x 3)

Rotation matrix.

dmipy.utils.utils.rotation_matrix_100_to_xyz(x, y, z)

Generates a rotation matrix that rotates from the x-axis (1, 0, 0) to an other position in Cartesian space.

Parameters:

x, y, z : floats,

position in Cartesian space.

Returns:

R : array, shape (3 x 3)

Rotation matrix.

dmipy.utils.utils.rotation_matrix_001_to_xyz(x, y, z)

Generates a rotation matrix that rotates from the z-axis (0, 0, 1) to an other position in Cartesian space.

Parameters:

x, y, z : floats,

position in Cartesian space.

Returns:

R : array, shape (3 x 3)

Rotation matrix.

dmipy.utils.utils.rotation_matrix_100_to_theta_phi_psi(theta, phi, psi)

Generates a rotation matrix that rotates from the x-axis (1, 0, 0) to an other position in Cartesian space, and rotates about its axis.

Parameters:

theta : float,

inclination of polar angle of main angle mu [0, pi].

phi : float,

polar angle of main angle mu [-pi, pi].

psi : float,

angle in radians of the bingham distribution around mu [0, pi].

Returns:

R : array, shape (3 x 3)

Rotation matrix.

dmipy.utils.utils.T1_tortuosity(lambda_par, vf_intra, vf_extra=None)

Tortuosity model for perpendicular extra-axonal diffusivity [1, 2, 3]. If vf_extra=None, then vf_intra must be a nested volume fraction, in the sense that E_bundle = vf_intra * E_intra + (1 - vf_intra) * E_extra, with vf_intra + (1 - vf_intra) = 1. If both vf_intra and vf_extra are given, then they have be be normalized fractions, in the sense that vf_intra + vf_extra <= 1.

Parameters:

lambda_par : float,

parallel diffusivity.

vf_intra : float,

intra-axonal volume fraction [0, 1].

vf_extra : float, (optional)

extra-axonal volume fraction [0, 1].

Returns:

lambda_perp : float,

Rotation matrix.

References :

——- :

.. [1] Bruggeman, Von DAG. “Berechnung verschiedener physikalischer :

Konstanten von heterogenen Substanzen. I. Dielektrizitätskonstanten und Leitfähigkeiten der Mischkörper aus isotropen Substanzen.” Annalen der physik 416.7 (1935): 636-664.

.. [2] Sen et al. “A self-similar model for sedimentary rocks with :

application to the dielectric constant of fused glass beads.” Geophysics 46.5 (1981): 781-795.

.. [3] Szafer et al. “Theoretical model for water diffusion in tissues.” :

Magnetic resonance in medicine 33.5 (1995): 697-712.

dmipy.utils.utils.parameter_equality(param)

Function to force two model parameters to be equal in the optimization

dmipy.utils.utils.define_shell_indices(bvals, b_value_ranges)

Function to facilitate defining shell indices given some manual ranges in b-values. This function is useful as in practice the actual b-values may fluctuate slightly around the planned b-value. This information is needed by some models doing spherical convolutions or spherical means. CAUTION: If a data set has variations in pulse duration delta and/or pulse separation Delta, then different shells can have similar b-values. This means these shells may not be separable in b-value, and you’ll have to do it manually.

Parameters:

bvals : 1D array of size (N_data),

The b-values corresponding to the measured DWIs.

b_value_ranges : 2D array of size (N_shells, 2)

A list indicating for every shell the lower and upper b-value range.

Returns:

shell_indices : 1D integer array of size (N_data),

The shell indices corresponding to each DWI measurement. The index 0 corresponds with the b0 measurements, while higher numbers indicate other shells. The numbers are ordered in the same order they are given in b_value_ranges.

mean_shell_bvals : 1D array of size (N_shells),

The mean b-value in each shell.

dmipy.utils.utils.cart2sphere(cartesian_coordinates)

“Function to estimate spherical coordinates from cartesian coordinates according to wikipedia. Conforms with the dipy notation.

Parameters:

cartesian_coordinates : array of size (3) or (N x 3),

array of cartesian coordinate vectors [x, y, z].

Returns:

spherical_coordinates : array of size (3) or (N x 3),

array of spherical coordinate vectors [r, theta, phi]. range of theta [0, pi]. range of phi [-pi, pi].

dmipy.utils.utils.cart2mu(xyz)

Function to estimate spherical coordinates from cartesian coordinates according to wikipedia. Conforms with the dipy notation.

Parameters:

cartesian_coordinates : array of size (3) or (N x 3),

array of cartesian coordinate vectors [x, y, z].

Returns:

spherical_coordinates : array of size (2) or (N x 2),

array of spherical coordinate vectors [theta, phi]. range of theta [0, pi]. range of phi [-pi, pi].

dmipy.utils.utils.R2mu_psi(R)

Function to estimate orientation mu and secondary orientation angle psi from a 3x3 rotation matrix. Can be given array of rotation matrices.

Parameters:

R : Array of size (N, 3, 3)

rotation matrices that possibly can be estimated by DTI.

Returns:

mu : array of size (N, 2),

orientations in [theta, phi] angles

psi : array of size (N),

secondary orientation psi (for Bingham for example).

dmipy.utils.utils.sphere2cart(spherical_coordinates)

“Function to estimate cartesian coordinates from spherical coordinates according to wikipedia. Conforms with the dipy notation.

Parameters:

spherical_coordinates : array of size (3) or (N x 3),

array of spherical coordinate vectors [r, theta, phi]. range of theta [0, pi]. range of phi [-pi, pi].

Returns:

cartesian_coordinates : array of size (3) or (N x 3),

array of cartesian coordinate vectors [x, y, z].

dmipy.utils.utils.unitsphere2cart_1d(mu)

Optimized function dedicated to convert 1D unit sphere coordinates to cartesian coordinates.

Parameters:

mu : array of size (2)

unit sphere coordinates, as theta, phi = mu

Returns:

mu_cart, array of size (3) :

mu in cartesian coordinates, as x, y, z = mu_cart

dmipy.utils.utils.unitsphere2cart_Nd(mu)

Optimized function deicated to convert 1D unit sphere coordinates to cartesian coordinates.

Parameters:

mu : Nd array of size (…, 2)

unit sphere coordinates, as theta, phi = mu

Returns:

mu_cart, Nd array of size (…, 3) :

mu in cartesian coordinates, as x, y, z = mu_cart

optional_package

dmipy.utils.spherical_convolution.optional_package(name, trip_msg=None)

Return package-like thing and module setup for package name

Parameters:

name : str

package name

trip_msg : None or str

message to give when someone tries to use the return package, but we could not import it, and have returned a TripWire object instead. Default message if None.

Returns:

pkg_like : module or TripWire instance

If we can import the package, return it. Otherwise return an object raising an error when accessed

have_pkg : bool

True if import for package was successful, false otherwise

module_setup : function

callable usually set as setup_module in calling namespace, to allow skipping tests.

real_sph_harm

dmipy.utils.spherical_convolution.real_sph_harm(m, n, theta, phi)

Compute real spherical harmonics.

Where the real harmonic \(Y^m_n\) is defined to be:

Imag(\(Y^m_n\)) * sqrt(2) if m > 0 \(Y^0_n\) if m = 0 Real(\(Y^|m|_n\)) * sqrt(2) if m < 0

This may take scalar or array arguments. The inputs will be broadcasted against each other.

Parameters:

m : int |m| <= n

The order of the harmonic.

n : int >= 0

The degree of the harmonic.

theta : float [0, 2*pi]

The azimuthal (longitudinal) coordinate.

phi : float [0, pi]

The polar (colatitudinal) coordinate.

Returns:

y_mn : real float

The real harmonic \(Y^m_n\) sampled at theta and phi.

See also

scipy.special.sph_harm

real_sym_rh_basis

dmipy.utils.spherical_convolution.real_sym_rh_basis(sh_order, theta, phi)

Samples a real symmetric rotational harmonic basis at point on the sphere

Samples the basis functions up to order sh_order at points on the sphere given by theta and phi. The basis functions are defined here the same way as in fibernavigator, where the real harmonic \(Y^m_n\) is defined to be:

\(Y^0_n\) if m = 0
Parameters:

sh_order : int

even int > 0, max spherical harmonic degree

theta : float [0, 2*pi]

The azimuthal (longitudinal) coordinate.

phi : float [0, pi]

The polar (colatitudinal) coordinate.

Returns:

real_rh_matrix : array of shape ()

The real harmonic \(Y^0_n\) sampled at theta and phi

sh_convolution

dmipy.utils.spherical_convolution.sh_convolution(f_distribution_sh, kernel_rh)

Spherical convolution between a fiber distribution (f) in spherical harmonics and a kernel in terms of rotational harmonics (oriented along the z-axis).

Parameters:

f_distribution_sh : array, shape (sh_coef)

spherical harmonic coefficients of a fiber distribution.

kernel_rh : array, shape (sh_coef),

rotational harmonic coefficients of the convolution kernel. In our case this is the spherical signal of one micro-environment at one b-value.

Returns:

f_kernel_convolved : array, shape (sh_coef)

spherical harmonic coefficients of the convolved kernel and distribution.

estimate_spherical_mean_multi_shell

dmipy.utils.spherical_mean.estimate_spherical_mean_multi_shell(E_attenuation, acquisition_scheme, sh_order=6)

Estimates the spherical mean per shell of multi-shell acquisition. Uses spherical harmonics to do the estimation.

Parameters:

E_attenuation : array, shape (N),

signal attenuation.

bvecs : array, shape (N x 3),

x, y, z components of cartesian unit b-vectors.

b_shell_indices : array, shape (N)

array of integers indicating which measurement belongs to which shell. 0 should be used for b0 measurements, 1 for the lowest b-value shell, 2 for the second lowest etc.

Returns:

E_mean : array, shape (number of b-shells)

spherical means of the signal attenuation per shell of the. For example, if there are three shells in the acquisition then the array is of length 3.

estimate_spherical_mean_shell

dmipy.utils.spherical_mean.estimate_spherical_mean_shell(E_shell, bvecs_shell, sh_order=6, sh_mat=None)

Estimates spherical mean of a shell of measurements using spherical harmonics. The spherical mean is contained only in the Y00 spherical harmonic, as long as the basis expansion order is sufficient to capture the spherical signal.

Parameters:

E_shell : array, shape(N),

signal attenuation values.

bvecs_shell : array, shape (N x 3),

Cartesian unit vectors describing the orientation of the signal attenuation values.

sh_order : integer,

maximum spherical harmonics order. It needs to be high enough to describe the spherical profile of the signal attenuation. The order 6 is sufficient to describe a stick at b-values up to 10,000 s/mm^2.

sh_mat : array of size (N_bvecs, N_coefficients),

possibly precomputed spherical harmonics transform matrix.

Returns:

E_mean : float,

spherical mean of the signal attenuation.

real_sym_sh_mrtrix

dmipy.utils.spherical_mean.real_sym_sh_mrtrix(sh_order, theta, phi)

Compute real spherical harmonics as in mrtrix, where the real harmonic \(Y^m_n\) is defined to be:

Real(:math:`Y^m_n`)       if m > 0
:math:`Y^0_n`             if m = 0
Imag(:math:`Y^|m|_n`)     if m < 0

This may take scalar or array arguments. The inputs will be broadcasted against each other.

Parameters:

sh_order : int

The maximum degree or the spherical harmonic basis.

theta : float [0, pi]

The polar (colatitudinal) coordinate.

phi : float [0, 2*pi]

The azimuthal (longitudinal) coordinate.

Returns:

y_mn : real float

The real harmonic \(Y^m_n\) sampled at theta and phi as implemented in mrtrix. Warning: the basis is Tournier et al 2004 and 2007 is slightly different.

m : array

The order of the harmonics.

n : array

The degree of the harmonics.

R2mu_psi

dmipy.utils.utils.R2mu_psi(R)

Function to estimate orientation mu and secondary orientation angle psi from a 3x3 rotation matrix. Can be given array of rotation matrices.

Parameters:

R : Array of size (N, 3, 3)

rotation matrices that possibly can be estimated by DTI.

Returns:

mu : array of size (N, 2),

orientations in [theta, phi] angles

psi : array of size (N),

secondary orientation psi (for Bingham for example).

T1_tortuosity

dmipy.utils.utils.T1_tortuosity(lambda_par, vf_intra, vf_extra=None)

Tortuosity model for perpendicular extra-axonal diffusivity [1, 2, 3]. If vf_extra=None, then vf_intra must be a nested volume fraction, in the sense that E_bundle = vf_intra * E_intra + (1 - vf_intra) * E_extra, with vf_intra + (1 - vf_intra) = 1. If both vf_intra and vf_extra are given, then they have be be normalized fractions, in the sense that vf_intra + vf_extra <= 1.

Parameters:

lambda_par : float,

parallel diffusivity.

vf_intra : float,

intra-axonal volume fraction [0, 1].

vf_extra : float, (optional)

extra-axonal volume fraction [0, 1].

Returns:

lambda_perp : float,

Rotation matrix.

References :

——- :

.. [1] Bruggeman, Von DAG. “Berechnung verschiedener physikalischer :

Konstanten von heterogenen Substanzen. I. Dielektrizitätskonstanten und Leitfähigkeiten der Mischkörper aus isotropen Substanzen.” Annalen der physik 416.7 (1935): 636-664.

.. [2] Sen et al. “A self-similar model for sedimentary rocks with :

application to the dielectric constant of fused glass beads.” Geophysics 46.5 (1981): 781-795.

.. [3] Szafer et al. “Theoretical model for water diffusion in tissues.” :

Magnetic resonance in medicine 33.5 (1995): 697-712.

cart2mu

dmipy.utils.utils.cart2mu(xyz)

Function to estimate spherical coordinates from cartesian coordinates according to wikipedia. Conforms with the dipy notation.

Parameters:

cartesian_coordinates : array of size (3) or (N x 3),

array of cartesian coordinate vectors [x, y, z].

Returns:

spherical_coordinates : array of size (2) or (N x 2),

array of spherical coordinate vectors [theta, phi]. range of theta [0, pi]. range of phi [-pi, pi].

cart2sphere

dmipy.utils.utils.cart2sphere(cartesian_coordinates)

“Function to estimate spherical coordinates from cartesian coordinates according to wikipedia. Conforms with the dipy notation.

Parameters:

cartesian_coordinates : array of size (3) or (N x 3),

array of cartesian coordinate vectors [x, y, z].

Returns:

spherical_coordinates : array of size (3) or (N x 3),

array of spherical coordinate vectors [r, theta, phi]. range of theta [0, pi]. range of phi [-pi, pi].

define_shell_indices

dmipy.utils.utils.define_shell_indices(bvals, b_value_ranges)

Function to facilitate defining shell indices given some manual ranges in b-values. This function is useful as in practice the actual b-values may fluctuate slightly around the planned b-value. This information is needed by some models doing spherical convolutions or spherical means. CAUTION: If a data set has variations in pulse duration delta and/or pulse separation Delta, then different shells can have similar b-values. This means these shells may not be separable in b-value, and you’ll have to do it manually.

Parameters:

bvals : 1D array of size (N_data),

The b-values corresponding to the measured DWIs.

b_value_ranges : 2D array of size (N_shells, 2)

A list indicating for every shell the lower and upper b-value range.

Returns:

shell_indices : 1D integer array of size (N_data),

The shell indices corresponding to each DWI measurement. The index 0 corresponds with the b0 measurements, while higher numbers indicate other shells. The numbers are ordered in the same order they are given in b_value_ranges.

mean_shell_bvals : 1D array of size (N_shells),

The mean b-value in each shell.

fractional_parameter

dmipy.utils.utils.fractional_parameter(fractional_parameter, parameter2)

Defines fractional parameter link where the original parameter ranges between 0-1 of parameter2.

Parameters:

fractional_parameter : string

new parameter that ranges between 0 and 1.

parameter2 : string

parameter that is larger or equal than the original parameter

get_sphere

dmipy.utils.utils.get_sphere(name='symmetric362')

provide triangulated spheres

Parameters:

name : str

which sphere - one of: * ‘symmetric362’ * ‘symmetric642’ * ‘symmetric724’ * ‘repulsion724’ * ‘repulsion100’ * ‘repulsion200’

Returns:

sphere : a dipy.core.sphere.Sphere class instance

Examples

>>> import numpy as np
>>> from dipy.data import get_sphere
>>> sphere = get_sphere('symmetric362')
>>> verts, faces = sphere.vertices, sphere.faces
>>> verts.shape == (362, 3)
True
>>> faces.shape == (720, 3)
True
>>> verts, faces = get_sphere('not a sphere name') 
Traceback (most recent call last):
    ...
DataError: No sphere called "not a sphere name"

optional_package

dmipy.utils.utils.optional_package(name, trip_msg=None)

Return package-like thing and module setup for package name

Parameters:

name : str

package name

trip_msg : None or str

message to give when someone tries to use the return package, but we could not import it, and have returned a TripWire object instead. Default message if None.

Returns:

pkg_like : module or TripWire instance

If we can import the package, return it. Otherwise return an object raising an error when accessed

have_pkg : bool

True if import for package was successful, false otherwise

module_setup : function

callable usually set as setup_module in calling namespace, to allow skipping tests.

parameter_equality

dmipy.utils.utils.parameter_equality(param)

Function to force two model parameters to be equal in the optimization

perpendicular_vector

dmipy.utils.utils.perpendicular_vector(v)

Returns a perpendicular vector to vector “v”.

Parameters:

v : array, shape (3)

normally Cartesian unit vector, but can also be any vector.

Returns:

v_perp : array, shape (3)

If v is unit vector, v_perp is a Cartesian unit vector perpendicular to v.

rotation_matrix_001_to_xyz

dmipy.utils.utils.rotation_matrix_001_to_xyz(x, y, z)

Generates a rotation matrix that rotates from the z-axis (0, 0, 1) to an other position in Cartesian space.

Parameters:

x, y, z : floats,

position in Cartesian space.

Returns:

R : array, shape (3 x 3)

Rotation matrix.

rotation_matrix_100_to_theta_phi

dmipy.utils.utils.rotation_matrix_100_to_theta_phi(theta, phi)

Generates a rotation matrix that rotates from the x-axis (1, 0, 0) to an other position on the unit sphere.

Parameters:

theta : float,

inclination of polar angle of main angle mu [0, pi].

phi : float,

polar angle of main angle mu [-pi, pi].

Returns:

R : array, shape (3 x 3)

Rotation matrix.

rotation_matrix_100_to_theta_phi_psi

dmipy.utils.utils.rotation_matrix_100_to_theta_phi_psi(theta, phi, psi)

Generates a rotation matrix that rotates from the x-axis (1, 0, 0) to an other position in Cartesian space, and rotates about its axis.

Parameters:

theta : float,

inclination of polar angle of main angle mu [0, pi].

phi : float,

polar angle of main angle mu [-pi, pi].

psi : float,

angle in radians of the bingham distribution around mu [0, pi].

Returns:

R : array, shape (3 x 3)

Rotation matrix.

rotation_matrix_100_to_xyz

dmipy.utils.utils.rotation_matrix_100_to_xyz(x, y, z)

Generates a rotation matrix that rotates from the x-axis (1, 0, 0) to an other position in Cartesian space.

Parameters:

x, y, z : floats,

position in Cartesian space.

Returns:

R : array, shape (3 x 3)

Rotation matrix.

rotation_matrix_around_100

dmipy.utils.utils.rotation_matrix_around_100(psi)

Generates a rotation matrix that rotates around the x-axis (1, 0, 0).

Parameters:

psi : float,

euler angle [0, pi].

Returns:

R : array, shape (3 x 3)

Rotation matrix.

sphere2cart

dmipy.utils.utils.sphere2cart(spherical_coordinates)

“Function to estimate cartesian coordinates from spherical coordinates according to wikipedia. Conforms with the dipy notation.

Parameters:

spherical_coordinates : array of size (3) or (N x 3),

array of spherical coordinate vectors [r, theta, phi]. range of theta [0, pi]. range of phi [-pi, pi].

Returns:

cartesian_coordinates : array of size (3) or (N x 3),

array of cartesian coordinate vectors [x, y, z].

unitsphere2cart_1d

dmipy.utils.utils.unitsphere2cart_1d(mu)

Optimized function dedicated to convert 1D unit sphere coordinates to cartesian coordinates.

Parameters:

mu : array of size (2)

unit sphere coordinates, as theta, phi = mu

Returns:

mu_cart, array of size (3) :

mu in cartesian coordinates, as x, y, z = mu_cart

unitsphere2cart_Nd

dmipy.utils.utils.unitsphere2cart_Nd(mu)

Optimized function deicated to convert 1D unit sphere coordinates to cartesian coordinates.

Parameters:

mu : Nd array of size (…, 2)

unit sphere coordinates, as theta, phi = mu

Returns:

mu_cart, Nd array of size (…, 3) :

mu in cartesian coordinates, as x, y, z = mu_cart