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 


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 (object [,times]) 
for the specified number of times.  
xrange 
alias of builtins.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 on the unit sphere  
local_maxima 
Local maxima of a function evaluated on a discrete set of points.  
ndindex (shape) 
An Ndimensional 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 


PeaksAndMetricsDirectionGetter 
Deterministic Direction Getter based on peak directions.  
Sphere ([x, y, z, theta, phi, xyz, faces, edges]) 
Points on the unit sphere.  
repeat (object [,times]) 
for the specified number of times.  
xrange 
alias of builtins.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 on the unit sphere  
local_maxima 
Local maxima of a function evaluated on a discrete set of points.  
ndindex (shape) 
An Ndimensional 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 initial_direction
Returns best directions at seed location to start tracking. get_direction 
__init__
($self, /, *args, **kwargs)¶ 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 on the sphere initial_direction
Returns best directions at seed location to start tracking. get_direction 
__init__
($self, /, *args, **kwargs)¶ 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 on the sphere initial_direction
Returns best directions at seed location to start tracking. get_direction 
__init__
($self, /, *args, **kwargs)¶ 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)¶ Initialize self. See help(type(self)) for accurate signature.

PeaksAndMetrics
¶

class
dipy.direction.
PeaksAndMetrics
¶ Bases:
dipy.reconst.peak_direction_getter.PeaksAndMetricsDirectionGetter
Attributes:  ang_thr
 qa_thr
 total_weight
Methods
initial_direction
The best starting directions for fiber tracking from point get_direction 
__init__
($self, /, *args, **kwargs)¶ 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
initial_direction
The best starting directions for fiber tracking from point get_direction 
__init__
($self, /, *args, **kwargs)¶ 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 on the sphere initial_direction
Returns best directions at seed location to start tracking. get_direction 
__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.
See also

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 : 1D array_like
Vertices as xyz coordinates.
 theta, phi : 1D array_like
Vertices as spherical coordinates. Theta and phi are the inclination and azimuth angles respectively.
 xyz : (N, 3) ndarray
Vertices as xyz 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 
__init__
(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None)¶ Initialize self. See help(type(self)) for accurate signature.

edges
()¶

faces
()¶

find_closest
(xyz)¶ Find the index of the vertex in the Sphere closest to the input vector
Parameters:  xyz : arraylike, 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
¶
Pool¶

dipy.direction.
Pool
(processes=None, initializer=None, initargs=(), maxtasksperchild=None)¶ Returns a process pool object
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 allzeros in samples.
Notes
The GFA is defined as [1]
\sqrt{\frac{n \sum_i{(\Psi_i  <\Psi>)^2}}{(n1) \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.
[1] Quality assessment of High Angular Resolution Diffusion Imaging data using bootstrap on Qball reconstruction. J. Cohen Adad, M. Descoteaux, L.L. Wald. JMRI 33: 11941208.
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
ndindex¶

dipy.direction.
ndindex
(shape)¶ An Ndimensional iterator object to index arrays.
Given the shape of an array, an ndindex instance iterates over the Ndimensional 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, wheremin = max(0, odf.min())
andscale = 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=1e07)¶ 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, ‘tournier07’, ‘descoteaux07’}
None
for the default DIPY basis,tournier07
for the Tournier 2007 [2] basis, anddescoteaux07
for the Descoteaux 2007 [1] basis (None
defaults todescoteaux07
). sh_smooth : float, optional
Lambdaregularization 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
andtempfile.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
References
[1] (1, 2) Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Qball Imaging. Magn. Reson. Med. 2007;58:497510. [2] (1, 2) Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Nonnegativity constrained superresolved spherical deconvolution. NeuroImage. 2007;35(4):14591472.
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..N1\)), the index \(j\) to a vertex in unique_vertices that is less than theta degrees fromvertices[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..M1\)), the index \(i\) to a vertex in vertices that is less than theta degrees fromunique_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 thata[i] < T
. Equivalently, i will be the largest index such thatall(a[:i] >= T)
. If all values in a are >= T, return the length of array a.Parameters:  a : ndarray, ndim=1, ccontiguous
Array to be searched. We assume a is in descending order.
 relative_threshold : float
Applied threshold will be
T
withT = a[0] * relative_threshold
.
Returns:  i : np.intp
If
T = a[0] * relative_threshold
then i will be the largest index such thatall(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, ‘tournier07’, ‘descoteaux07’}
None
for the default DIPY basis,tournier07
for the Tournier 2007 [2] basis, anddescoteaux07
for the Descoteaux 2007 [1] basis (None
defaults todescoteaux07
). return_inv : bool
If True then the inverse of the matrix is also returned
 smooth : float, optional
Lambdaregularization 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.
References
[1] (1, 2) Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Qball Imaging. Magn. Reson. Med. 2007;58:497510. [2] (1, 2) Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Nonnegativity constrained superresolved spherical deconvolution. NeuroImage. 2007;35(4):14591472.
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)¶ Initialize self. See help(type(self)) for accurate signature.

PeaksAndMetrics
¶

class
dipy.direction.peaks.
PeaksAndMetrics
¶ Bases:
dipy.reconst.peak_direction_getter.PeaksAndMetricsDirectionGetter
Attributes:  ang_thr
 qa_thr
 total_weight
Methods
initial_direction
The best starting directions for fiber tracking from point get_direction 
__init__
($self, /, *args, **kwargs)¶ 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
initial_direction
The best starting directions for fiber tracking from point get_direction 
__init__
($self, /, *args, **kwargs)¶ 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 : 1D array_like
Vertices as xyz coordinates.
 theta, phi : 1D array_like
Vertices as spherical coordinates. Theta and phi are the inclination and azimuth angles respectively.
 xyz : (N, 3) ndarray
Vertices as xyz 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 
__init__
(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None)¶ Initialize self. See help(type(self)) for accurate signature.

edges
()¶

faces
()¶

find_closest
(xyz)¶ Find the index of the vertex in the Sphere closest to the input vector
Parameters:  xyz : arraylike, 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
¶
Pool¶

dipy.direction.peaks.
Pool
(processes=None, initializer=None, initargs=(), maxtasksperchild=None)¶ Returns a process pool object
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 allzeros in samples.
Notes
The GFA is defined as [1]
\sqrt{\frac{n \sum_i{(\Psi_i  <\Psi>)^2}}{(n1) \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.
[1] Quality assessment of High Angular Resolution Diffusion Imaging data using bootstrap on Qball reconstruction. J. Cohen Adad, M. Descoteaux, L.L. Wald. JMRI 33: 11941208.
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
ndindex¶

dipy.direction.peaks.
ndindex
(shape)¶ An Ndimensional iterator object to index arrays.
Given the shape of an array, an ndindex instance iterates over the Ndimensional 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, wheremin = max(0, odf.min())
andscale = 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=1e07)¶ 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, ‘tournier07’, ‘descoteaux07’}
None
for the default DIPY basis,tournier07
for the Tournier 2007 [2] basis, anddescoteaux07
for the Descoteaux 2007 [1] basis (None
defaults todescoteaux07
). sh_smooth : float, optional
Lambdaregularization 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
andtempfile.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
References
[1] (1, 2) Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Qball Imaging. Magn. Reson. Med. 2007;58:497510. [2] (1, 2) Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Nonnegativity constrained superresolved spherical deconvolution. NeuroImage. 2007;35(4):14591472.
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..N1\)), the index \(j\) to a vertex in unique_vertices that is less than theta degrees fromvertices[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..M1\)), the index \(i\) to a vertex in vertices that is less than theta degrees fromunique_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 thata[i] < T
. Equivalently, i will be the largest index such thatall(a[:i] >= T)
. If all values in a are >= T, return the length of array a.Parameters:  a : ndarray, ndim=1, ccontiguous
Array to be searched. We assume a is in descending order.
 relative_threshold : float
Applied threshold will be
T
withT = a[0] * relative_threshold
.
Returns:  i : np.intp
If
T = a[0] * relative_threshold
then i will be the largest index such thatall(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, ‘tournier07’, ‘descoteaux07’}
None
for the default DIPY basis,tournier07
for the Tournier 2007 [2] basis, anddescoteaux07
for the Descoteaux 2007 [1] basis (None
defaults todescoteaux07
). return_inv : bool
If True then the inverse of the matrix is also returned
 smooth : float, optional
Lambdaregularization 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.
References
[1] (1, 2) Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Qball Imaging. Magn. Reson. Med. 2007;58:497510. [2] (1, 2) Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Nonnegativity constrained superresolved spherical deconvolution. NeuroImage. 2007;35(4):14591472.