optimizers_fod

Module: optimizers_fod.cvxpy_fod

class dmipy.optimizers_fod.cvxpy_fod.GeneralPurposeCSDOptimizer(acquisition_scheme, model, sh_order=8, unity_constraint=True)

General purpose optimizer for multi-compartment constrained spherical deconvolution (MC-CSD) to estimate Fiber Orientation Distributions (FODs). It can take any number of compartment models as convolution kernels as long as all the kernel’s parameters are fixed. If more than one kernel is given, then the optimizer estimates the volume fractions of the different kernels as well as the FOD.

The optimization package CVXPY [R57] is used for this MC-CSD implementation.

Limitations: It cannot estimate the FOD of multiple kernels that each have an orientation. E.g. it is possible to have a cylinder and a ball kernel as input, but not two cylinders.

IMPORTANT NOTE: This multi-compartment CSD implementation is NOT the same Multi-Tissue CSD (MT-CSD) as proposed by Jeurissen et al. [R58]. In MT-CSD they input tissue response kernels that INCLUDES the differences in b0-intensities between different tissue types. In this current implementation of MC-CSD, the different compartment kernels are directly fitted to the signal attenuation, implicitly assuming each compartment has the same b0-intensity.

Parameters:

acquisition_scheme: DmipyAcquisitionScheme instance, :

acquisition scheme of the to-be-fitted data.

model: dmipy MultiCompartmentModel instance, :

Can be composed of any model combination.

sh_order: even integer larger or equal to zero, :

maximum spherical harmonics order to be included in the FOD estimation.

unity_constrain: bool, :

whether or not to impose that the FOD integrates to unity.

References

[R57](1, 2) Diamond, Steven, and Stephen Boyd. “CVXPY: A Python-embedded modeling language for convex optimization.” The Journal of Machine Learning Research 17.1 (2016): 2909-2913.
[R58](1, 2) Jeurissen, Ben, et al. “Multi-tissue constrained spherical deconvolution for improved analysis of multi-shell diffusion MRI data.” NeuroImage 103 (2014): 411-426.

Methods

prepare_rotational_harmonics(rh_array, rh_order)

Function to extend rotational harmonics and prepare them for MSE.

recover_rotational_harmonics(x0_vector)

Recovers list of rotational harmonics for each model.

GeneralPurposeCSDOptimizer

class dmipy.optimizers_fod.cvxpy_fod.GeneralPurposeCSDOptimizer(acquisition_scheme, model, sh_order=8, unity_constraint=True)

General purpose optimizer for multi-compartment constrained spherical deconvolution (MC-CSD) to estimate Fiber Orientation Distributions (FODs). It can take any number of compartment models as convolution kernels as long as all the kernel’s parameters are fixed. If more than one kernel is given, then the optimizer estimates the volume fractions of the different kernels as well as the FOD.

The optimization package CVXPY [R59] is used for this MC-CSD implementation.

Limitations: It cannot estimate the FOD of multiple kernels that each have an orientation. E.g. it is possible to have a cylinder and a ball kernel as input, but not two cylinders.

IMPORTANT NOTE: This multi-compartment CSD implementation is NOT the same Multi-Tissue CSD (MT-CSD) as proposed by Jeurissen et al. [R60]. In MT-CSD they input tissue response kernels that INCLUDES the differences in b0-intensities between different tissue types. In this current implementation of MC-CSD, the different compartment kernels are directly fitted to the signal attenuation, implicitly assuming each compartment has the same b0-intensity.

Parameters:

acquisition_scheme: DmipyAcquisitionScheme instance, :

acquisition scheme of the to-be-fitted data.

model: dmipy MultiCompartmentModel instance, :

Can be composed of any model combination.

sh_order: even integer larger or equal to zero, :

maximum spherical harmonics order to be included in the FOD estimation.

unity_constrain: bool, :

whether or not to impose that the FOD integrates to unity.

References

[R59](1, 2) Diamond, Steven, and Stephen Boyd. “CVXPY: A Python-embedded modeling language for convex optimization.” The Journal of Machine Learning Research 17.1 (2016): 2909-2913.
[R60](1, 2) Jeurissen, Ben, et al. “Multi-tissue constrained spherical deconvolution for improved analysis of multi-shell diffusion MRI data.” NeuroImage 103 (2014): 411-426.

Methods

__init__(acquisition_scheme, model, sh_order=8, unity_constraint=True)
prepare_rotational_harmonics(rh_array, rh_order)

Function to extend rotational harmonics and prepare them for MSE.

recover_rotational_harmonics(x0_vector)

Recovers list of rotational harmonics for each model.

HemiSphere

class dmipy.optimizers_fod.cvxpy_fod.HemiSphere(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None, tol=1e-05)

Bases: dipy.core.sphere.Sphere

Points on the unit sphere.

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

The HemiSphere can be constructed using one of three conventions:

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

x, y, 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.

See also

Sphere

Attributes

Methods

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

Create a HemiSphere from points

faces()
find_closest(xyz)

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

Parameters:

xyz : array-like, 3 elements

A unit vector

classmethod from_sphere(klass, 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.

get_sphere

dmipy.optimizers_fod.cvxpy_fod.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.optimizers_fod.cvxpy_fod.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_sym_sh_mrtrix

dmipy.optimizers_fod.cvxpy_fod.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.