direction

BootDirectionGetter

Methods

ClosestPeakDirectionGetter A direction getter that returns the closest odf peak to previous tracking direction.
DeterministicMaximumDirectionGetter Return direction of a sphere with the highest probability mass function (pmf).
InTemporaryDirectory([suffix, prefix, dir]) Create, return, and change directory to a temporary directory
PeaksAndMetrics

Attributes

PeaksAndMetricsDirectionGetter Deterministic Direction Getter based on peak directions.
ProbabilisticDirectionGetter Randomly samples direction of a sphere based on probability mass function (pmf).
Sphere([x, y, z, theta, phi, xyz, faces, edges]) Points on the unit sphere.
repeat(...) for the specified number of times. If not specified, returns the object
xrange alias of range
Pool Returns a process pool object
cpu_count Returns the number of CPUs in the system
gfa(samples) The general fractional anisotropy of a function evaluated
local_maxima Local maxima of a function evaluated on a discrete set of points.
ndindex(shape) An N-dimensional iterator object to index arrays.
peak_directions(odf, sphere[, ...]) Get the directions of odf peaks.
peak_directions_nl(sphere_eval[, ...]) Non Linear Direction Finder.
peaks_from_model(model, data, sphere, ...[, ...]) Fit the model to data and computes peaks and metrics
remove_similar_vertices Remove vertices that are less than theta degrees from any other
reshape_peaks_for_visualization(peaks) Reshape peaks for visualization.
search_descending i in descending array a so a[i] < a[0] * relative_threshold
sh_to_sf_matrix(sphere, sh_order[, ...]) Matrix that transforms Spherical harmonics (SH) to spherical function (SF).
warn Issue a warning, or maybe ignore it or raise an exception.

Module: direction.peaks

InTemporaryDirectory([suffix, prefix, dir]) Create, return, and change directory to a temporary directory
PeaksAndMetrics

Attributes

PeaksAndMetricsDirectionGetter Deterministic Direction Getter based on peak directions.
Sphere([x, y, z, theta, phi, xyz, faces, edges]) Points on the unit sphere.
repeat(...) for the specified number of times. If not specified, returns the object
xrange alias of range
Pool Returns a process pool object
cpu_count Returns the number of CPUs in the system
gfa(samples) The general fractional anisotropy of a function evaluated
local_maxima Local maxima of a function evaluated on a discrete set of points.
ndindex(shape) An N-dimensional iterator object to index arrays.
peak_directions(odf, sphere[, ...]) Get the directions of odf peaks.
peak_directions_nl(sphere_eval[, ...]) Non Linear Direction Finder.
peaks_from_model(model, data, sphere, ...[, ...]) Fit the model to data and computes peaks and metrics
remove_similar_vertices Remove vertices that are less than theta degrees from any other
reshape_peaks_for_visualization(peaks) Reshape peaks for visualization.
search_descending i in descending array a so a[i] < a[0] * relative_threshold
sh_to_sf_matrix(sphere, sh_order[, ...]) Matrix that transforms Spherical harmonics (SH) to spherical function (SF).
warn Issue a warning, or maybe ignore it or raise an exception.

BootDirectionGetter

class dipy.direction.BootDirectionGetter

Bases: dipy.direction.closest_peak_direction_getter.BaseDirectionGetter

Methods

from_data Create a BootDirectionGetter using HARDI data and an ODF type model
get_direction
initial_direction Returns best directions at seed location to start tracking.
__init__()

Initialize self. See help(type(self)) for accurate signature.

from_data()

Create a BootDirectionGetter using HARDI data and an ODF type model

Parameters:

data : ndarray, float, (..., N)

Diffusion MRI data with N volumes.

model : dipy diffusion model

Must provide fit with odf method.

max_angle : float (0, 90)

Maximum angle between tract segments. This angle can be more generous (larger) than values typically used with probabilistic direction getters.

sphere : Sphere

The sphere used to sample the diffusion ODF.

sh_order : even int

The order of the SH “model” used to estimate bootstrap residuals.

max_attempts : int

Max number of bootstrap samples used to find tracking direction before giving up.

pmf_threshold : float

Threshold for ODF functions.

relative_peak_threshold : float in [0., 1.]

Relative threshold for excluding ODF peaks.

min_separation_angle : float in [0, 90]

Angular threshold for excluding ODF peaks.

ClosestPeakDirectionGetter

class dipy.direction.ClosestPeakDirectionGetter

Bases: dipy.direction.closest_peak_direction_getter.PmfGenDirectionGetter

A direction getter that returns the closest odf peak to previous tracking direction.

Methods

from_pmf Constructor for making a DirectionGetter from an array of Pmfs
from_shcoeff Probabilistic direction getter from a distribution of directions
get_direction
initial_direction Returns best directions at seed location to start tracking.
__init__()

Initialize self. See help(type(self)) for accurate signature.

DeterministicMaximumDirectionGetter

class dipy.direction.DeterministicMaximumDirectionGetter

Bases: dipy.direction.probabilistic_direction_getter.ProbabilisticDirectionGetter

Return direction of a sphere with the highest probability mass function (pmf).

Methods

from_pmf Constructor for making a DirectionGetter from an array of Pmfs
from_shcoeff Probabilistic direction getter from a distribution of directions
get_direction
initial_direction Returns best directions at seed location to start tracking.
__init__()

Initialize self. See help(type(self)) for accurate signature.

InTemporaryDirectory

class dipy.direction.InTemporaryDirectory(suffix='', prefix='tmp', dir=None)

Bases: nibabel.tmpdirs.TemporaryDirectory

Create, return, and change directory to a temporary directory

Examples

>>> import os
>>> my_cwd = os.getcwd()
>>> with InTemporaryDirectory() as tmpdir:
...     _ = open('test.txt', 'wt').write('some text')
...     assert os.path.isfile('test.txt')
...     assert os.path.isfile(os.path.join(tmpdir, 'test.txt'))
>>> os.path.exists(tmpdir)
False
>>> os.getcwd() == my_cwd
True

Methods

cleanup()
__init__(suffix='', prefix='tmp', dir=None)

PeaksAndMetrics

class dipy.direction.PeaksAndMetrics

Bases: dipy.reconst.peak_direction_getter.PeaksAndMetricsDirectionGetter

Attributes

ang_thr
qa_thr
total_weight

Methods

get_direction
initial_direction The best starting directions for fiber tracking from point
__init__()

Initialize self. See help(type(self)) for accurate signature.

PeaksAndMetricsDirectionGetter

class dipy.direction.PeaksAndMetricsDirectionGetter

Bases: dipy.tracking.local.direction_getter.DirectionGetter

Deterministic Direction Getter based on peak directions.

This class contains the cython portion of the code for PeaksAndMetrics and is not meant to be used on its own.

Attributes

ang_thr
qa_thr
total_weight

Methods

get_direction
initial_direction The best starting directions for fiber tracking from point
__init__()

Initialize self. See help(type(self)) for accurate signature.

ang_thr
initial_direction()

The best starting directions for fiber tracking from point

All the valid peaks in the voxel closest to point are returned as initial directions.

qa_thr
total_weight

ProbabilisticDirectionGetter

class dipy.direction.ProbabilisticDirectionGetter

Bases: dipy.direction.closest_peak_direction_getter.PmfGenDirectionGetter

Randomly samples direction of a sphere based on probability mass function (pmf).

The main constructors for this class are current from_pmf and from_shcoeff. The pmf gives the probability that each direction on the sphere should be chosen as the next direction. To get the true pmf from the “raw pmf” directions more than max_angle degrees from the incoming direction are set to 0 and the result is normalized.

Methods

from_pmf Constructor for making a DirectionGetter from an array of Pmfs
from_shcoeff Probabilistic direction getter from a distribution of directions
get_direction
initial_direction Returns best directions at seed location to start tracking.
__init__()

Direction getter from a pmf generator.

Parameters:

pmf_gen : PmfGen

Used to get probability mass function for selecting tracking directions.

max_angle : float, [0, 90]

The maximum allowed angle between incoming direction and new direction.

sphere : Sphere

The set of directions to be used for tracking.

pmf_threshold : float [0., 1.]

Used to remove direction from the probability mass function for selecting the tracking direction.

relative_peak_threshold : float in [0., 1.]

Used for extracting initial tracking directions. Passed to peak_directions.

min_separation_angle : float in [0, 90]

Used for extracting initial tracking directions. Passed to peak_directions.

Sphere

class dipy.direction.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

edges()
faces()
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.
vertices()
__init__(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None)
edges()
faces()
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

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/____
/\    /            /  \  /             /____\/____          x      c     z
Parameters:

n : int, optional

The number of subdivisions to preform.

Returns:

new_sphere : Sphere

The subdivided sphere.

vertices()
x
y
z

repeat

class dipy.direction.repeat(object[, times]) → create an iterator which returns the object

Bases: object

for the specified number of times. If not specified, returns the object endlessly.

__init__()

Initialize self. See help(type(self)) for accurate signature.

xrange

dipy.direction.xrange

alias of range

Pool

dipy.direction.Pool(self, processes=None, initializer=None, initargs=(), maxtasksperchild=None)

Returns a process pool object

cpu_count

dipy.direction.cpu_count(self)

Returns the number of CPUs in the system

gfa

dipy.direction.gfa(samples)

The general fractional anisotropy of a function evaluated on the unit sphere

Parameters:

samples : ndarray

Values of data on the unit sphere.

Returns:

gfa : ndarray

GFA evaluated in each entry of the array, along the last dimension. An np.nan is returned for coordinates that contain all-zeros in samples.

Notes

The GFA is defined as [R59]

\sqrt{\frac{n \sum_i{(\Psi_i - <\Psi>)^2}}{(n-1) \sum{\Psi_i ^ 2}}}

Where \(\Psi\) is an orientation distribution function sampled discretely on the unit sphere and angle brackets denote average over the samples on the sphere.

[R59]Quality assessment of High Angular Resolution Diffusion Imaging data using bootstrap on Q-ball reconstruction. J. Cohen Adad, M. Descoteaux, L.L. Wald. JMRI 33: 1194-1208.

local_maxima

dipy.direction.local_maxima()

Local maxima of a function evaluated on a discrete set of points.

If a function is evaluated on some set of points where each pair of neighboring points is an edge in edges, find the local maxima.

Parameters:

odf : array, 1d, dtype=double

The function evaluated on a set of discrete points.

edges : array (N, 2)

The set of neighbor relations between the points. Every edge, ie edges[i, :], is a pair of neighboring points.

Returns:

peak_values : ndarray

Value of odf at a maximum point. Peak values is sorted in descending order.

peak_indices : ndarray

Indices of maximum points. Sorted in the same order as peak_values so odf[peak_indices[i]] == peak_values[i].

See also

dipy.core.sphere

ndindex

dipy.direction.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)

peak_directions

dipy.direction.peak_directions(odf, sphere, relative_peak_threshold=0.5, min_separation_angle=25, minmax_norm=True)

Get the directions of odf peaks.

Peaks are defined as points on the odf that are greater than at least one neighbor and greater than or equal to all neighbors. Peaks are sorted in descending order by their values then filtered based on their relative size and spacing on the sphere. An odf may have 0 peaks, for example if the odf is perfectly isotropic.

Parameters:

odf : 1d ndarray

The odf function evaluated on the vertices of sphere

sphere : Sphere

The Sphere providing discrete directions for evaluation.

relative_peak_threshold : float in [0., 1.]

Only peaks greater than min + relative_peak_threshold * scale are kept, where min = max(0, odf.min()) and scale = odf.max() - min.

min_separation_angle : float in [0, 90]

The minimum distance between directions. If two peaks are too close only the larger of the two is returned.

Returns:

directions : (N, 3) ndarray

N vertices for sphere, one for each peak

values : (N,) ndarray

peak values

indices : (N,) ndarray

peak indices of the directions on the sphere

Notes

If the odf has any negative values, they will be clipped to zeros.

peak_directions_nl

dipy.direction.peak_directions_nl(sphere_eval, relative_peak_threshold=0.25, min_separation_angle=25, sphere=<dipy.core.sphere.HemiSphere object>, xtol=1e-07)

Non Linear Direction Finder.

Parameters:

sphere_eval : callable

A function which can be evaluated on a sphere.

relative_peak_threshold : float

Only return peaks greater than relative_peak_threshold * m where m is the largest peak.

min_separation_angle : float in [0, 90]

The minimum distance between directions. If two peaks are too close only the larger of the two is returned.

sphere : Sphere

A discrete Sphere. The points on the sphere will be used for initial estimate of maximums.

xtol : float

Relative tolerance for optimization.

Returns:

directions : array (N, 3)

Points on the sphere corresponding to N local maxima on the sphere.

values : array (N,)

Value of sphere_eval at each point on directions.

peaks_from_model

dipy.direction.peaks_from_model(model, data, sphere, relative_peak_threshold, min_separation_angle, mask=None, return_odf=False, return_sh=True, gfa_thr=0, normalize_peaks=False, sh_order=8, sh_basis_type=None, npeaks=5, B=None, invB=None, parallel=False, nbr_processes=None)

Fit the model to data and computes peaks and metrics

Parameters:

model : a model instance

model will be used to fit the data.

sphere : Sphere

The Sphere providing discrete directions for evaluation.

relative_peak_threshold : float

Only return peaks greater than relative_peak_threshold * m where m is the largest peak.

min_separation_angle : float in [0, 90] The minimum distance between

directions. If two peaks are too close only the larger of the two is returned.

mask : array, optional

If mask is provided, voxels that are False in mask are skipped and no peaks are returned.

return_odf : bool

If True, the odfs are returned.

return_sh : bool

If True, the odf as spherical harmonics coefficients is returned

gfa_thr : float

Voxels with gfa less than gfa_thr are skipped, no peaks are returned.

normalize_peaks : bool

If true, all peak values are calculated relative to max(odf).

sh_order : int, optional

Maximum SH order in the SH fit. For sh_order, there will be (sh_order + 1) * (sh_order + 2) / 2 SH coefficients (default 8).

sh_basis_type : {None, ‘mrtrix’, ‘fibernav’}

None for the default dipy basis which is the fibernav basis, mrtrix for the MRtrix basis, and fibernav for the FiberNavigator basis

sh_smooth : float, optional

Lambda-regularization in the SH fit (default 0.0).

npeaks : int

Maximum number of peaks found (default 5 peaks).

B : ndarray, optional

Matrix that transforms spherical harmonics to spherical function sf = np.dot(sh, B).

invB : ndarray, optional

Inverse of B.

parallel: bool

If True, use multiprocessing to compute peaks and metric (default False). Temporary files are saved in the default temporary directory of the system. It can be changed using import tempfile and tempfile.tempdir = '/path/to/tempdir'.

nbr_processes: int

If parallel is True, the number of subprocesses to use (default multiprocessing.cpu_count()).

Returns:

pam : PeaksAndMetrics

An object with gfa, peak_directions, peak_values, peak_indices, odf, shm_coeffs as attributes

remove_similar_vertices

dipy.direction.remove_similar_vertices()

Remove vertices that are less than theta degrees from any other

Returns vertices that are at least theta degrees from any other vertex. Vertex v and -v are considered the same so if v and -v are both in vertices only one is kept. Also if v and w are both in vertices, w must be separated by theta degrees from both v and -v to be unique.

Parameters:

vertices : (N, 3) ndarray

N unit vectors.

theta : float

The minimum separation between vertices in degrees.

return_mapping : {False, True}, optional

If True, return mapping as well as vertices and maybe indices (see below).

return_indices : {False, True}, optional

If True, return indices as well as vertices and maybe mapping (see below).

Returns:

unique_vertices : (M, 3) ndarray

Vertices sufficiently separated from one another.

mapping : (N,) ndarray

For each element vertices[i] (\(i \in 0..N-1\)), the index \(j\) to a vertex in unique_vertices that is less than theta degrees from vertices[i]. Only returned if return_mapping is True.

indices : (N,) ndarray

indices gives the reverse of mapping. For each element unique_vertices[j] (\(j \in 0..M-1\)), the index \(i\) to a vertex in vertices that is less than theta degrees from unique_vertices[j]. If there is more than one element of vertices that is less than theta degrees from unique_vertices[j], return the first (lowest index) matching value. Only return if return_indices is True.

reshape_peaks_for_visualization

dipy.direction.reshape_peaks_for_visualization(peaks)

Reshape peaks for visualization.

Reshape and convert to float32 a set of peaks for visualisation with mrtrix or the fibernavigator.

search_descending

dipy.direction.search_descending()

i in descending array a so a[i] < a[0] * relative_threshold

Call T = a[0] * relative_threshold. Return value i will be the smallest index in the descending array a such that a[i] < T. Equivalently, i will be the largest index such that all(a[:i] >= T). If all values in a are >= T, return the length of array a.

Parameters:

a : ndarray, ndim=1, c-contiguous

Array to be searched. We assume a is in descending order.

relative_threshold : float

Applied threshold will be T with T = a[0] * relative_threshold.

Returns:

i : np.intp

If T = a[0] * relative_threshold then i will be the largest index such that all(a[:i] >= T). If all values in a are >= T then i will be len(a).

Examples

>>> a = np.arange(10, 0, -1, dtype=float)
>>> a
array([ 10.,   9.,   8.,   7.,   6.,   5.,   4.,   3.,   2.,   1.])
>>> search_descending(a, 0.5)
6
>>> a < 10 * 0.5
array([False, False, False, False, False, False,  True,  True,  True,  True], dtype=bool)
>>> search_descending(a, 1)
1
>>> search_descending(a, 2)
0
>>> search_descending(a, 0)
10

sh_to_sf_matrix

dipy.direction.sh_to_sf_matrix(sphere, sh_order, basis_type=None, return_inv=True, smooth=0)

Matrix that transforms Spherical harmonics (SH) to spherical function (SF).

Parameters:

sphere : Sphere

The points on which to sample the spherical function.

sh_order : int, optional

Maximum SH order in the SH fit. For sh_order, there will be (sh_order + 1) * (sh_order_2) / 2 SH coefficients (default 4).

basis_type : {None, ‘mrtrix’, ‘fibernav’}

None for the default dipy basis, mrtrix for the MRtrix basis, and fibernav for the FiberNavigator basis (default None).

return_inv : bool

If True then the inverse of the matrix is also returned

smooth : float, optional

Lambda-regularization in the SH fit (default 0.0).

Returns:

B : ndarray

Matrix that transforms spherical harmonics to spherical function sf = np.dot(sh, B).

invB : ndarray

Inverse of B.

warn

dipy.direction.warn()

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

InTemporaryDirectory

class dipy.direction.peaks.InTemporaryDirectory(suffix='', prefix='tmp', dir=None)

Bases: nibabel.tmpdirs.TemporaryDirectory

Create, return, and change directory to a temporary directory

Examples

>>> import os
>>> my_cwd = os.getcwd()
>>> with InTemporaryDirectory() as tmpdir:
...     _ = open('test.txt', 'wt').write('some text')
...     assert os.path.isfile('test.txt')
...     assert os.path.isfile(os.path.join(tmpdir, 'test.txt'))
>>> os.path.exists(tmpdir)
False
>>> os.getcwd() == my_cwd
True

Methods

cleanup()
__init__(suffix='', prefix='tmp', dir=None)

PeaksAndMetrics

class dipy.direction.peaks.PeaksAndMetrics

Bases: dipy.reconst.peak_direction_getter.PeaksAndMetricsDirectionGetter

Attributes

ang_thr
qa_thr
total_weight

Methods

get_direction
initial_direction The best starting directions for fiber tracking from point
__init__()

Initialize self. See help(type(self)) for accurate signature.

PeaksAndMetricsDirectionGetter

class dipy.direction.peaks.PeaksAndMetricsDirectionGetter

Bases: dipy.tracking.local.direction_getter.DirectionGetter

Deterministic Direction Getter based on peak directions.

This class contains the cython portion of the code for PeaksAndMetrics and is not meant to be used on its own.

Attributes

ang_thr
qa_thr
total_weight

Methods

get_direction
initial_direction The best starting directions for fiber tracking from point
__init__()

Initialize self. See help(type(self)) for accurate signature.

ang_thr
initial_direction()

The best starting directions for fiber tracking from point

All the valid peaks in the voxel closest to point are returned as initial directions.

qa_thr
total_weight

Sphere

class dipy.direction.peaks.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

edges()
faces()
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.
vertices()
__init__(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None)
edges()
faces()
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

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/____
/\    /            /  \  /             /____\/____          x      c     z
Parameters:

n : int, optional

The number of subdivisions to preform.

Returns:

new_sphere : Sphere

The subdivided sphere.

vertices()
x
y
z

repeat

class dipy.direction.peaks.repeat(object[, times]) → create an iterator which returns the object

Bases: object

for the specified number of times. If not specified, returns the object endlessly.

__init__()

Initialize self. See help(type(self)) for accurate signature.

xrange

dipy.direction.peaks.xrange

alias of range

Pool

dipy.direction.peaks.Pool(self, processes=None, initializer=None, initargs=(), maxtasksperchild=None)

Returns a process pool object

cpu_count

dipy.direction.peaks.cpu_count(self)

Returns the number of CPUs in the system

gfa

dipy.direction.peaks.gfa(samples)

The general fractional anisotropy of a function evaluated on the unit sphere

Parameters:

samples : ndarray

Values of data on the unit sphere.

Returns:

gfa : ndarray

GFA evaluated in each entry of the array, along the last dimension. An np.nan is returned for coordinates that contain all-zeros in samples.

Notes

The GFA is defined as [R60]

\sqrt{\frac{n \sum_i{(\Psi_i - <\Psi>)^2}}{(n-1) \sum{\Psi_i ^ 2}}}

Where \(\Psi\) is an orientation distribution function sampled discretely on the unit sphere and angle brackets denote average over the samples on the sphere.

[R60]Quality assessment of High Angular Resolution Diffusion Imaging data using bootstrap on Q-ball reconstruction. J. Cohen Adad, M. Descoteaux, L.L. Wald. JMRI 33: 1194-1208.

local_maxima

dipy.direction.peaks.local_maxima()

Local maxima of a function evaluated on a discrete set of points.

If a function is evaluated on some set of points where each pair of neighboring points is an edge in edges, find the local maxima.

Parameters:

odf : array, 1d, dtype=double

The function evaluated on a set of discrete points.

edges : array (N, 2)

The set of neighbor relations between the points. Every edge, ie edges[i, :], is a pair of neighboring points.

Returns:

peak_values : ndarray

Value of odf at a maximum point. Peak values is sorted in descending order.

peak_indices : ndarray

Indices of maximum points. Sorted in the same order as peak_values so odf[peak_indices[i]] == peak_values[i].

See also

dipy.core.sphere

ndindex

dipy.direction.peaks.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)

peak_directions

dipy.direction.peaks.peak_directions(odf, sphere, relative_peak_threshold=0.5, min_separation_angle=25, minmax_norm=True)

Get the directions of odf peaks.

Peaks are defined as points on the odf that are greater than at least one neighbor and greater than or equal to all neighbors. Peaks are sorted in descending order by their values then filtered based on their relative size and spacing on the sphere. An odf may have 0 peaks, for example if the odf is perfectly isotropic.

Parameters:

odf : 1d ndarray

The odf function evaluated on the vertices of sphere

sphere : Sphere

The Sphere providing discrete directions for evaluation.

relative_peak_threshold : float in [0., 1.]

Only peaks greater than min + relative_peak_threshold * scale are kept, where min = max(0, odf.min()) and scale = odf.max() - min.

min_separation_angle : float in [0, 90]

The minimum distance between directions. If two peaks are too close only the larger of the two is returned.

Returns:

directions : (N, 3) ndarray

N vertices for sphere, one for each peak

values : (N,) ndarray

peak values

indices : (N,) ndarray

peak indices of the directions on the sphere

Notes

If the odf has any negative values, they will be clipped to zeros.

peak_directions_nl

dipy.direction.peaks.peak_directions_nl(sphere_eval, relative_peak_threshold=0.25, min_separation_angle=25, sphere=<dipy.core.sphere.HemiSphere object>, xtol=1e-07)

Non Linear Direction Finder.

Parameters:

sphere_eval : callable

A function which can be evaluated on a sphere.

relative_peak_threshold : float

Only return peaks greater than relative_peak_threshold * m where m is the largest peak.

min_separation_angle : float in [0, 90]

The minimum distance between directions. If two peaks are too close only the larger of the two is returned.

sphere : Sphere

A discrete Sphere. The points on the sphere will be used for initial estimate of maximums.

xtol : float

Relative tolerance for optimization.

Returns:

directions : array (N, 3)

Points on the sphere corresponding to N local maxima on the sphere.

values : array (N,)

Value of sphere_eval at each point on directions.

peaks_from_model

dipy.direction.peaks.peaks_from_model(model, data, sphere, relative_peak_threshold, min_separation_angle, mask=None, return_odf=False, return_sh=True, gfa_thr=0, normalize_peaks=False, sh_order=8, sh_basis_type=None, npeaks=5, B=None, invB=None, parallel=False, nbr_processes=None)

Fit the model to data and computes peaks and metrics

Parameters:

model : a model instance

model will be used to fit the data.

sphere : Sphere

The Sphere providing discrete directions for evaluation.

relative_peak_threshold : float

Only return peaks greater than relative_peak_threshold * m where m is the largest peak.

min_separation_angle : float in [0, 90] The minimum distance between

directions. If two peaks are too close only the larger of the two is returned.

mask : array, optional

If mask is provided, voxels that are False in mask are skipped and no peaks are returned.

return_odf : bool

If True, the odfs are returned.

return_sh : bool

If True, the odf as spherical harmonics coefficients is returned

gfa_thr : float

Voxels with gfa less than gfa_thr are skipped, no peaks are returned.

normalize_peaks : bool

If true, all peak values are calculated relative to max(odf).

sh_order : int, optional

Maximum SH order in the SH fit. For sh_order, there will be (sh_order + 1) * (sh_order + 2) / 2 SH coefficients (default 8).

sh_basis_type : {None, ‘mrtrix’, ‘fibernav’}

None for the default dipy basis which is the fibernav basis, mrtrix for the MRtrix basis, and fibernav for the FiberNavigator basis

sh_smooth : float, optional

Lambda-regularization in the SH fit (default 0.0).

npeaks : int

Maximum number of peaks found (default 5 peaks).

B : ndarray, optional

Matrix that transforms spherical harmonics to spherical function sf = np.dot(sh, B).

invB : ndarray, optional

Inverse of B.

parallel: bool

If True, use multiprocessing to compute peaks and metric (default False). Temporary files are saved in the default temporary directory of the system. It can be changed using import tempfile and tempfile.tempdir = '/path/to/tempdir'.

nbr_processes: int

If parallel is True, the number of subprocesses to use (default multiprocessing.cpu_count()).

Returns:

pam : PeaksAndMetrics

An object with gfa, peak_directions, peak_values, peak_indices, odf, shm_coeffs as attributes

remove_similar_vertices

dipy.direction.peaks.remove_similar_vertices()

Remove vertices that are less than theta degrees from any other

Returns vertices that are at least theta degrees from any other vertex. Vertex v and -v are considered the same so if v and -v are both in vertices only one is kept. Also if v and w are both in vertices, w must be separated by theta degrees from both v and -v to be unique.

Parameters:

vertices : (N, 3) ndarray

N unit vectors.

theta : float

The minimum separation between vertices in degrees.

return_mapping : {False, True}, optional

If True, return mapping as well as vertices and maybe indices (see below).

return_indices : {False, True}, optional

If True, return indices as well as vertices and maybe mapping (see below).

Returns:

unique_vertices : (M, 3) ndarray

Vertices sufficiently separated from one another.

mapping : (N,) ndarray

For each element vertices[i] (\(i \in 0..N-1\)), the index \(j\) to a vertex in unique_vertices that is less than theta degrees from vertices[i]. Only returned if return_mapping is True.

indices : (N,) ndarray

indices gives the reverse of mapping. For each element unique_vertices[j] (\(j \in 0..M-1\)), the index \(i\) to a vertex in vertices that is less than theta degrees from unique_vertices[j]. If there is more than one element of vertices that is less than theta degrees from unique_vertices[j], return the first (lowest index) matching value. Only return if return_indices is True.

reshape_peaks_for_visualization

dipy.direction.peaks.reshape_peaks_for_visualization(peaks)

Reshape peaks for visualization.

Reshape and convert to float32 a set of peaks for visualisation with mrtrix or the fibernavigator.

search_descending

dipy.direction.peaks.search_descending()

i in descending array a so a[i] < a[0] * relative_threshold

Call T = a[0] * relative_threshold. Return value i will be the smallest index in the descending array a such that a[i] < T. Equivalently, i will be the largest index such that all(a[:i] >= T). If all values in a are >= T, return the length of array a.

Parameters:

a : ndarray, ndim=1, c-contiguous

Array to be searched. We assume a is in descending order.

relative_threshold : float

Applied threshold will be T with T = a[0] * relative_threshold.

Returns:

i : np.intp

If T = a[0] * relative_threshold then i will be the largest index such that all(a[:i] >= T). If all values in a are >= T then i will be len(a).

Examples

>>> a = np.arange(10, 0, -1, dtype=float)
>>> a
array([ 10.,   9.,   8.,   7.,   6.,   5.,   4.,   3.,   2.,   1.])
>>> search_descending(a, 0.5)
6
>>> a < 10 * 0.5
array([False, False, False, False, False, False,  True,  True,  True,  True], dtype=bool)
>>> search_descending(a, 1)
1
>>> search_descending(a, 2)
0
>>> search_descending(a, 0)
10

sh_to_sf_matrix

dipy.direction.peaks.sh_to_sf_matrix(sphere, sh_order, basis_type=None, return_inv=True, smooth=0)

Matrix that transforms Spherical harmonics (SH) to spherical function (SF).

Parameters:

sphere : Sphere

The points on which to sample the spherical function.

sh_order : int, optional

Maximum SH order in the SH fit. For sh_order, there will be (sh_order + 1) * (sh_order_2) / 2 SH coefficients (default 4).

basis_type : {None, ‘mrtrix’, ‘fibernav’}

None for the default dipy basis, mrtrix for the MRtrix basis, and fibernav for the FiberNavigator basis (default None).

return_inv : bool

If True then the inverse of the matrix is also returned

smooth : float, optional

Lambda-regularization in the SH fit (default 0.0).

Returns:

B : ndarray

Matrix that transforms spherical harmonics to spherical function sf = np.dot(sh, B).

invB : ndarray

Inverse of B.

warn

dipy.direction.peaks.warn()

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