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

EuDXDirectionGetter

Deterministic Direction Getter based on peak directions.

InTemporaryDirectory([suffix, prefix, dir])

Create, return, and change directory to a temporary directory

PeaksAndMetrics

Attributes

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.

Pool([processes, initializer, initargs, …])

Returns a process pool object

deprecated_params(old_name[, new_name, …])

Deprecate a renamed or removed function argument.

determine_num_processes(num_processes)

Determine the effective number of processes for parallelization.

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 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(/, message[, category, stacklevel, source])

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

Module: direction.bootstrap_direction_getter

BootDirectionGetter

Methods

BootPmfGen

Methods

Module: direction.closest_peak_direction_getter

BaseDirectionGetter

Methods

BasePmfDirectionGetter

A base class for dynamic direction getters

ClosestPeakDirectionGetter

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

PmfGenDirectionGetter

A base class for direction getter using a pmf

order_from_ncoef(ncoef[, full_basis])

Given a number n of coefficients, calculate back the sh_order

peak_directions(odf, sphere[, …])

Get the directions of odf peaks.

warn(/, message[, category, stacklevel, source])

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

Module: direction.peaks

EuDXDirectionGetter

Deterministic Direction Getter based on peak directions.

InTemporaryDirectory([suffix, prefix, dir])

Create, return, and change directory to a temporary directory

PeaksAndMetrics

Attributes

Sphere([x, y, z, theta, phi, xyz, faces, edges])

Points on the unit sphere.

repeat(object [,times])

for the specified number of times.

Pool([processes, initializer, initargs, …])

Returns a process pool object

deprecated_params(old_name[, new_name, …])

Deprecate a renamed or removed function argument.

determine_num_processes(num_processes)

Determine the effective number of processes for parallelization.

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 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(/, message[, category, stacklevel, source])

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

Module: direction.pmf

BootPmfGen

Methods

PmfGen

Methods

SHCoeffPmfGen

Methods

SimplePmfGen

Methods

cart2sphere(x, y, z)

Return angles for Cartesian 3D coordinates x, y, and z

Module: direction.probabilistic_direction_getter

Implementation of a probabilistic direction getter based on sampling from discrete distribution (pmf) at each step of the tracking.

DeterministicMaximumDirectionGetter

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

ProbabilisticDirectionGetter

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

peak_directions(odf, sphere[, …])

Get the directions of odf peaks.

random()

BootDirectionGetter

class dipy.direction.BootDirectionGetter

Bases: dipy.direction.closest_peak_direction_getter.BasePmfDirectionGetter

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__(*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
datandarray, float, (…, N)

Diffusion MRI data with N volumes.

modeldipy diffusion model

Must provide fit with odf method.

max_anglefloat (0, 90)

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

sphereSphere

The sphere used to sample the diffusion ODF.

sh_ordereven int

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

max_attemptsint

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

pmf_thresholdfloat

Threshold for ODF functions.

relative_peak_thresholdfloat in [0., 1.]

Relative threshold for excluding ODF peaks.

min_separation_anglefloat 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__(*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__(*args, **kwargs)

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

EuDXDirectionGetter

class dipy.direction.EuDXDirectionGetter

Bases: dipy.tracking.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__(*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

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.eudx_direction_getter.EuDXDirectionGetter

Attributes
ang_thr
qa_thr
total_weight

Methods

initial_direction

The best starting directions for fiber tracking from point

get_direction

__init__(*args, **kwargs)

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

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_genPmfGen

Used to get probability mass function for selecting tracking directions.

max_anglefloat, [0, 90]

The maximum allowed angle between incoming direction and new direction.

sphereSphere

The set of directions to be used for tracking.

pmf_thresholdfloat [0., 1.]

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

relative_peak_thresholdfloat in [0., 1.]

Used for extracting initial tracking directions. Passed to peak_directions.

min_separation_anglefloat 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, z1-D array_like

Vertices as x-y-z coordinates.

theta, phi1-D array_like

Vertices as spherical coordinates. Theta and phi are the inclination and azimuth angles respectively.

xyz(N, 3) ndarray

Vertices as x-y-z coordinates.

faces(N, 3) ndarray

Indices into vertices that form triangular faces. If unspecified, the faces are computed using a Delaunay triangulation.

edges(N, 2) ndarray

Edges between vertices. If unspecified, the edges are derived from the faces.

Attributes
x
y
z

Methods

find_closest(xyz)

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

subdivide([n])

Subdivides each face of the sphere into four new faces.

edges

faces

vertices

__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
xyzarray-like, 3 elements

A unit vector

Returns
idxint

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

subdivide(n=1)

Subdivides each face of the sphere into four new faces.

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

      y
      /\
     /  \
   a/____\b
   /\    /\
  /  \  /  \
 /____\/____\
x      c     z
Parameters
nint, optional

The number of subdivisions to preform.

Returns
new_sphereSphere

The subdivided sphere.

vertices()
property x
property y
property 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__(*args, **kwargs)

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

Pool

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

Returns a process pool object

deprecated_params

dipy.direction.deprecated_params(old_name, new_name=None, since='', until='', version_comparator=<function cmp_pkg_version>, arg_in_kwargs=False, warn_class=<class 'dipy.utils.deprecator.ArgsDeprecationWarning'>, error_class=<class 'dipy.utils.deprecator.ExpiredDeprecationError'>, alternative='')

Deprecate a renamed or removed function argument.

The decorator assumes that the argument with the old_name was removed from the function signature and the new_name replaced it at the same position in the signature. If the old_name argument is given when calling the decorated function the decorator will catch it and issue a deprecation warning and pass it on as new_name argument.

Parameters
old_namestr or list/tuple thereof

The old name of the argument.

new_namestr or list/tuple thereof or None, optional

The new name of the argument. Set this to None to remove the argument old_name instead of renaming it.

sincestr or number or list/tuple thereof, optional

The release at which the old argument became deprecated.

untilstr or number or list/tuple thereof, optional

Last released version at which this function will still raise a deprecation warning. Versions higher than this will raise an error.

version_comparatorcallable

Callable accepting string as argument, and return 1 if string represents a higher version than encoded in the version_comparator, 0 if the version is equal, and -1 if the version is lower. For example, the version_comparator may compare the input version string to the current package version string.

arg_in_kwargsbool or list/tuple thereof, optional

If the argument is not a named argument (for example it was meant to be consumed by **kwargs) set this to True. Otherwise the decorator will throw an Exception if the new_name cannot be found in the signature of the decorated function. Default is False.

warn_classwarning, optional

Warning to be issued.

error_classException, optional

Error to be issued

alternativestr, optional

An alternative function or class name that the user may use in place of the deprecated object if new_name is None. The deprecation warning will tell the user about this alternative if provided.

Raises
TypeError

If the new argument name cannot be found in the function signature and arg_in_kwargs was False or if it is used to deprecate the name of the *args-, **kwargs-like arguments. At runtime such an Error is raised if both the new_name and old_name were specified when calling the function and “relax=False”.

Notes

This function is based on the Astropy (major modification). https://github.com/astropy/astropy. See COPYING file distributed along with the astropy package for the copyright and license terms.

Examples

The deprecation warnings are not shown in the following examples. To deprecate a positional or keyword argument:: >>> from dipy.utils.deprecator import deprecated_params >>> @deprecated_params(‘sig’, ‘sigma’, ‘0.3’) … def test(sigma): … return sigma >>> test(2) 2 >>> test(sigma=2) 2 >>> test(sig=2) # doctest: +SKIP 2

It is also possible to replace multiple arguments. The old_name, new_name and since have to be tuple or list and contain the same number of entries:: >>> @deprecated_params([‘a’, ‘b’], [‘alpha’, ‘beta’], … [‘0.2’, 0.4]) … def test(alpha, beta): … return alpha, beta >>> test(a=2, b=3) # doctest: +SKIP (2, 3)

determine_num_processes

dipy.direction.determine_num_processes(num_processes)

Determine the effective number of processes for parallelization.

  • For num_processes = None` return the maximum number of cores retrieved

by cpu_count().

  • For num_processes > 0, return this value.

  • For num_processes < 0, return the maximal number of cores minus

|num_processes + 1|. In particular num_processes = -1 will use as many cores as possible.

  • For num_processes = 0 a ValueError is raised.

Parameters
num_processesint or None

Desired number of processes to be used.

gfa

dipy.direction.gfa(samples)

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

Parameters
samplesndarray

Values of data on the unit sphere.

Returns
gfandarray

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 [1]

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

1

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
odfarray, 1d, dtype=double

The function evaluated on a set of discrete points.

edgesarray (N, 2)

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

Returns
peak_valuesndarray

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

peak_indicesndarray

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

Notes

A point is a local maximum if it is > at least one neighbor and >= all neighbors. If no points meet the above criteria, 1 maximum is returned such that odf[maximum] == max(odf).

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
shapetuple 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)

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
odf1d ndarray

The odf function evaluated on the vertices of sphere

sphereSphere

The Sphere providing discrete directions for evaluation.

relative_peak_thresholdfloat 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_anglefloat 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_evalcallable

A function which can be evaluated on a sphere.

relative_peak_thresholdfloat

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

min_separation_anglefloat in [0, 90]

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

sphereSphere

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

xtolfloat

Relative tolerance for optimization.

Returns
directionsarray (N, 3)

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

valuesarray (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, num_processes=None)

Fit the model to data and computes peaks and metrics

Parameters
modela model instance

model will be used to fit the data.

sphereSphere

The Sphere providing discrete directions for evaluation.

relative_peak_thresholdfloat

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

min_separation_anglefloat in [0, 90] The minimum distance between

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

maskarray, optional

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

return_odfbool

If True, the odfs are returned.

return_shbool

If True, the odf as spherical harmonics coefficients is returned

gfa_thrfloat

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

normalize_peaksbool

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

sh_orderint, 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, and descoteaux07 for the Descoteaux 2007 [1] basis (None defaults to descoteaux07).

sh_smoothfloat, optional

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

npeaksint

Maximum number of peaks found (default 5 peaks).

Bndarray, optional

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

invBndarray, 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'.

num_processes: int, optional

If parallel is True, the number of subprocesses to use (default multiprocessing.cpu_count()). If < 0 the maximal number of cores minus |num_processes + 1| is used (enter -1 to use as many cores as possible). 0 raises an error.

Returns
pamPeaksAndMetrics

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

References

1

Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510.

2

Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution. NeuroImage. 2007;35(4):1459-1472.

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.

thetafloat

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.

Parameters
peaks: nd array (…, N, 3) or PeaksAndMetrics object

The peaks to be reshaped and converted to float32.

Returns
peaksnd array (…, 3*N)

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
andarray, ndim=1, c-contiguous

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

relative_thresholdfloat

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

Returns
inp.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=4, basis_type=None, full_basis=False, legacy=True, return_inv=True, smooth=0)

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

Parameters
sphereSphere

The points on which to sample the spherical function.

sh_orderint, optional

Maximum SH order in the SH fit. For sh_order, there will be (sh_order + 1) * (sh_order + 2) / 2 SH coefficients for a symmetric basis and (sh_order + 1) * (sh_order + 1) coefficients for a full SH basis.

basis_type{None, ‘tournier07’, ‘descoteaux07’}, optional

None for the default DIPY basis, tournier07 for the Tournier 2007 [R0296267dba6e-2]_[R0296267dba6e-3]_ basis, descoteaux07 for the Descoteaux 2007 [1] basis, (None defaults to descoteaux07).

full_basis: bool, optional

If True, uses a SH basis containing even and odd order SH functions. Else, uses a SH basis consisting only of even order SH functions.

legacy: bool, optional

True to use a legacy basis definition for backward compatibility with previous tournier07 and descoteaux07 implementations.

return_invbool, optional

If True then the inverse of the matrix is also returned.

smoothfloat, optional

Lambda-regularization in the SH fit.

Returns
Bndarray

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

invBndarray

Inverse of B.

References

1

Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510.

2

Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution. NeuroImage. 2007;35(4):1459-1472.

3

Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, Pietsch M, et al. MRtrix3: A fast, flexible and open software framework for medical image processing and visualisation. NeuroImage. 2019 Nov 15;202:116-137.

warn

dipy.direction.warn(/, message, category=None, stacklevel=1, source=None)

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

BootDirectionGetter

class dipy.direction.bootstrap_direction_getter.BootDirectionGetter

Bases: dipy.direction.closest_peak_direction_getter.BasePmfDirectionGetter

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__(*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
datandarray, float, (…, N)

Diffusion MRI data with N volumes.

modeldipy diffusion model

Must provide fit with odf method.

max_anglefloat (0, 90)

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

sphereSphere

The sphere used to sample the diffusion ODF.

sh_ordereven int

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

max_attemptsint

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

pmf_thresholdfloat

Threshold for ODF functions.

relative_peak_thresholdfloat in [0., 1.]

Relative threshold for excluding ODF peaks.

min_separation_anglefloat in [0, 90]

Angular threshold for excluding ODF peaks.

BootPmfGen

class dipy.direction.bootstrap_direction_getter.BootPmfGen

Bases: dipy.direction.pmf.PmfGen

Methods

get_pmf

get_pmf_no_boot

__init__(*args, **kwargs)

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

get_pmf_no_boot()

BaseDirectionGetter

class dipy.direction.closest_peak_direction_getter.BaseDirectionGetter

Bases: dipy.direction.closest_peak_direction_getter.BasePmfDirectionGetter

Methods

initial_direction

Returns best directions at seed location to start tracking.

get_direction

__init__(*args, **kwargs)

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

BasePmfDirectionGetter

class dipy.direction.closest_peak_direction_getter.BasePmfDirectionGetter

Bases: dipy.tracking.direction_getter.DirectionGetter

A base class for dynamic direction getters

Methods

initial_direction

Returns best directions at seed location to start tracking.

get_direction

__init__(*args, **kwargs)

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

initial_direction()

Returns best directions at seed location to start tracking.

Parameters
pointndarray, shape (3,)

The point in an image at which to lookup tracking directions.

Returns
directionsndarray, shape (N, 3)

Possible tracking directions from point. N may be 0, all directions should be unique.

ClosestPeakDirectionGetter

class dipy.direction.closest_peak_direction_getter.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__(*args, **kwargs)

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

PmfGenDirectionGetter

class dipy.direction.closest_peak_direction_getter.PmfGenDirectionGetter

Bases: dipy.direction.closest_peak_direction_getter.BasePmfDirectionGetter

A base class for direction getter using a 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__(*args, **kwargs)

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

from_pmf()

Constructor for making a DirectionGetter from an array of Pmfs

Parameters
pmfarray, 4d

The pmf to be used for tracking at each voxel.

max_anglefloat, [0, 90]

The maximum allowed angle between incoming direction and new direction.

sphereSphere

The set of directions to be used for tracking.

pmf_thresholdfloat [0., 1.]

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

relative_peak_thresholdfloat in [0., 1.]

Used for extracting initial tracking directions. Passed to peak_directions.

min_separation_anglefloat in [0, 90]

Used for extracting initial tracking directions. Passed to peak_directions.

from_shcoeff()

Probabilistic direction getter from a distribution of directions on the sphere

Parameters
shcoeffarray

The distribution of tracking directions at each voxel represented as a function on the sphere using the real spherical harmonic basis. For example the FOD of the Constrained Spherical Deconvolution model can be used this way. This distribution will be discretized using sphere and tracking directions will be chosen from the vertices of sphere based on the distribution.

max_anglefloat, [0, 90]

The maximum allowed angle between incoming direction and new direction.

sphereSphere

The set of directions to be used for tracking.

pmf_thresholdfloat [0., 1.]

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

basis_typename of basis

The basis that shcoeff are associated with. dipy.reconst.shm.real_sh_descoteaux is used by default.

relative_peak_thresholdfloat in [0., 1.]

Used for extracting initial tracking directions. Passed to peak_directions.

min_separation_anglefloat in [0, 90]

Used for extracting initial tracking directions. Passed to peak_directions.

order_from_ncoef

dipy.direction.closest_peak_direction_getter.order_from_ncoef(ncoef, full_basis=False)

Given a number n of coefficients, calculate back the sh_order

Parameters
ncoef: int

number of coefficients

full_basis: bool, optional

True when coefficients are for a full SH basis.

Returns
sh_order: int

maximum order of SH basis

peak_directions

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

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
odf1d ndarray

The odf function evaluated on the vertices of sphere

sphereSphere

The Sphere providing discrete directions for evaluation.

relative_peak_thresholdfloat 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_anglefloat 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.

warn

dipy.direction.closest_peak_direction_getter.warn(/, message, category=None, stacklevel=1, source=None)

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

EuDXDirectionGetter

class dipy.direction.peaks.EuDXDirectionGetter

Bases: dipy.tracking.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__(*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

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.eudx_direction_getter.EuDXDirectionGetter

Attributes
ang_thr
qa_thr
total_weight

Methods

initial_direction

The best starting directions for fiber tracking from point

get_direction

__init__(*args, **kwargs)

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

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, z1-D array_like

Vertices as x-y-z coordinates.

theta, phi1-D array_like

Vertices as spherical coordinates. Theta and phi are the inclination and azimuth angles respectively.

xyz(N, 3) ndarray

Vertices as x-y-z coordinates.

faces(N, 3) ndarray

Indices into vertices that form triangular faces. If unspecified, the faces are computed using a Delaunay triangulation.

edges(N, 2) ndarray

Edges between vertices. If unspecified, the edges are derived from the faces.

Attributes
x
y
z

Methods

find_closest(xyz)

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

subdivide([n])

Subdivides each face of the sphere into four new faces.

edges

faces

vertices

__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
xyzarray-like, 3 elements

A unit vector

Returns
idxint

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

subdivide(n=1)

Subdivides each face of the sphere into four new faces.

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

      y
      /\
     /  \
   a/____\b
   /\    /\
  /  \  /  \
 /____\/____\
x      c     z
Parameters
nint, optional

The number of subdivisions to preform.

Returns
new_sphereSphere

The subdivided sphere.

vertices()
property x
property y
property 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__(*args, **kwargs)

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

Pool

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

Returns a process pool object

deprecated_params

dipy.direction.peaks.deprecated_params(old_name, new_name=None, since='', until='', version_comparator=<function cmp_pkg_version>, arg_in_kwargs=False, warn_class=<class 'dipy.utils.deprecator.ArgsDeprecationWarning'>, error_class=<class 'dipy.utils.deprecator.ExpiredDeprecationError'>, alternative='')

Deprecate a renamed or removed function argument.

The decorator assumes that the argument with the old_name was removed from the function signature and the new_name replaced it at the same position in the signature. If the old_name argument is given when calling the decorated function the decorator will catch it and issue a deprecation warning and pass it on as new_name argument.

Parameters
old_namestr or list/tuple thereof

The old name of the argument.

new_namestr or list/tuple thereof or None, optional

The new name of the argument. Set this to None to remove the argument old_name instead of renaming it.

sincestr or number or list/tuple thereof, optional

The release at which the old argument became deprecated.

untilstr or number or list/tuple thereof, optional

Last released version at which this function will still raise a deprecation warning. Versions higher than this will raise an error.

version_comparatorcallable

Callable accepting string as argument, and return 1 if string represents a higher version than encoded in the version_comparator, 0 if the version is equal, and -1 if the version is lower. For example, the version_comparator may compare the input version string to the current package version string.

arg_in_kwargsbool or list/tuple thereof, optional

If the argument is not a named argument (for example it was meant to be consumed by **kwargs) set this to True. Otherwise the decorator will throw an Exception if the new_name cannot be found in the signature of the decorated function. Default is False.

warn_classwarning, optional

Warning to be issued.

error_classException, optional

Error to be issued

alternativestr, optional

An alternative function or class name that the user may use in place of the deprecated object if new_name is None. The deprecation warning will tell the user about this alternative if provided.

Raises
TypeError

If the new argument name cannot be found in the function signature and arg_in_kwargs was False or if it is used to deprecate the name of the *args-, **kwargs-like arguments. At runtime such an Error is raised if both the new_name and old_name were specified when calling the function and “relax=False”.

Notes

This function is based on the Astropy (major modification). https://github.com/astropy/astropy. See COPYING file distributed along with the astropy package for the copyright and license terms.

Examples

The deprecation warnings are not shown in the following examples. To deprecate a positional or keyword argument:: >>> from dipy.utils.deprecator import deprecated_params >>> @deprecated_params(‘sig’, ‘sigma’, ‘0.3’) … def test(sigma): … return sigma >>> test(2) 2 >>> test(sigma=2) 2 >>> test(sig=2) # doctest: +SKIP 2

It is also possible to replace multiple arguments. The old_name, new_name and since have to be tuple or list and contain the same number of entries:: >>> @deprecated_params([‘a’, ‘b’], [‘alpha’, ‘beta’], … [‘0.2’, 0.4]) … def test(alpha, beta): … return alpha, beta >>> test(a=2, b=3) # doctest: +SKIP (2, 3)

determine_num_processes

dipy.direction.peaks.determine_num_processes(num_processes)

Determine the effective number of processes for parallelization.

  • For num_processes = None` return the maximum number of cores retrieved

by cpu_count().

  • For num_processes > 0, return this value.

  • For num_processes < 0, return the maximal number of cores minus

|num_processes + 1|. In particular num_processes = -1 will use as many cores as possible.

  • For num_processes = 0 a ValueError is raised.

Parameters
num_processesint or None

Desired number of processes to be used.

gfa

dipy.direction.peaks.gfa(samples)

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

Parameters
samplesndarray

Values of data on the unit sphere.

Returns
gfandarray

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 [1]

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

1

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
odfarray, 1d, dtype=double

The function evaluated on a set of discrete points.

edgesarray (N, 2)

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

Returns
peak_valuesndarray

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

peak_indicesndarray

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

Notes

A point is a local maximum if it is > at least one neighbor and >= all neighbors. If no points meet the above criteria, 1 maximum is returned such that odf[maximum] == max(odf).

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
shapetuple 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)

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
odf1d ndarray

The odf function evaluated on the vertices of sphere

sphereSphere

The Sphere providing discrete directions for evaluation.

relative_peak_thresholdfloat 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_anglefloat 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_evalcallable

A function which can be evaluated on a sphere.

relative_peak_thresholdfloat

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

min_separation_anglefloat in [0, 90]

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

sphereSphere

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

xtolfloat

Relative tolerance for optimization.

Returns
directionsarray (N, 3)

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

valuesarray (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, num_processes=None)

Fit the model to data and computes peaks and metrics

Parameters
modela model instance

model will be used to fit the data.

sphereSphere

The Sphere providing discrete directions for evaluation.

relative_peak_thresholdfloat

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

min_separation_anglefloat in [0, 90] The minimum distance between

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

maskarray, optional

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

return_odfbool

If True, the odfs are returned.

return_shbool

If True, the odf as spherical harmonics coefficients is returned

gfa_thrfloat

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

normalize_peaksbool

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

sh_orderint, 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, and descoteaux07 for the Descoteaux 2007 [1] basis (None defaults to descoteaux07).

sh_smoothfloat, optional

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

npeaksint

Maximum number of peaks found (default 5 peaks).

Bndarray, optional

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

invBndarray, 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'.

num_processes: int, optional

If parallel is True, the number of subprocesses to use (default multiprocessing.cpu_count()). If < 0 the maximal number of cores minus |num_processes + 1| is used (enter -1 to use as many cores as possible). 0 raises an error.

Returns
pamPeaksAndMetrics

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

References

1

Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510.

2

Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution. NeuroImage. 2007;35(4):1459-1472.

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.

thetafloat

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.

Parameters
peaks: nd array (…, N, 3) or PeaksAndMetrics object

The peaks to be reshaped and converted to float32.

Returns
peaksnd array (…, 3*N)

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
andarray, ndim=1, c-contiguous

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

relative_thresholdfloat

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

Returns
inp.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=4, basis_type=None, full_basis=False, legacy=True, return_inv=True, smooth=0)

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

Parameters
sphereSphere

The points on which to sample the spherical function.

sh_orderint, optional

Maximum SH order in the SH fit. For sh_order, there will be (sh_order + 1) * (sh_order + 2) / 2 SH coefficients for a symmetric basis and (sh_order + 1) * (sh_order + 1) coefficients for a full SH basis.

basis_type{None, ‘tournier07’, ‘descoteaux07’}, optional

None for the default DIPY basis, tournier07 for the Tournier 2007 [Rc855ec825848-2]_[Rc855ec825848-3]_ basis, descoteaux07 for the Descoteaux 2007 [1] basis, (None defaults to descoteaux07).

full_basis: bool, optional

If True, uses a SH basis containing even and odd order SH functions. Else, uses a SH basis consisting only of even order SH functions.

legacy: bool, optional

True to use a legacy basis definition for backward compatibility with previous tournier07 and descoteaux07 implementations.

return_invbool, optional

If True then the inverse of the matrix is also returned.

smoothfloat, optional

Lambda-regularization in the SH fit.

Returns
Bndarray

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

invBndarray

Inverse of B.

References

1

Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510.

2

Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution. NeuroImage. 2007;35(4):1459-1472.

3

Tournier J-D, Smith R, Raffelt D, Tabbara R, Dhollander T, Pietsch M, et al. MRtrix3: A fast, flexible and open software framework for medical image processing and visualisation. NeuroImage. 2019 Nov 15;202:116-137.

warn

dipy.direction.peaks.warn(/, message, category=None, stacklevel=1, source=None)

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

BootPmfGen

class dipy.direction.pmf.BootPmfGen

Bases: dipy.direction.pmf.PmfGen

Methods

get_pmf

get_pmf_no_boot

__init__(*args, **kwargs)

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

get_pmf_no_boot()

PmfGen

class dipy.direction.pmf.PmfGen

Bases: object

Methods

get_pmf

__init__(*args, **kwargs)

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

get_pmf()

SHCoeffPmfGen

class dipy.direction.pmf.SHCoeffPmfGen

Bases: dipy.direction.pmf.PmfGen

Methods

get_pmf

__init__(*args, **kwargs)

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

SimplePmfGen

class dipy.direction.pmf.SimplePmfGen

Bases: dipy.direction.pmf.PmfGen

Methods

get_pmf

__init__(*args, **kwargs)

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

cart2sphere

dipy.direction.pmf.cart2sphere(x, y, z)

Return angles for Cartesian 3D coordinates x, y, and z

See doc for sphere2cart for angle conventions and derivation of the formulae.

\(0\le\theta\mathrm{(theta)}\le\pi\) and \(-\pi\le\phi\mathrm{(phi)}\le\pi\)

Parameters
xarray_like

x coordinate in Cartesian space

yarray_like

y coordinate in Cartesian space

zarray_like

z coordinate

Returns
rarray

radius

thetaarray

inclination (polar) angle

phiarray

azimuth angle

DeterministicMaximumDirectionGetter

class dipy.direction.probabilistic_direction_getter.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__(*args, **kwargs)

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

ProbabilisticDirectionGetter

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

Used to get probability mass function for selecting tracking directions.

max_anglefloat, [0, 90]

The maximum allowed angle between incoming direction and new direction.

sphereSphere

The set of directions to be used for tracking.

pmf_thresholdfloat [0., 1.]

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

relative_peak_thresholdfloat in [0., 1.]

Used for extracting initial tracking directions. Passed to peak_directions.

min_separation_anglefloat in [0, 90]

Used for extracting initial tracking directions. Passed to peak_directions.

peak_directions

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

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
odf1d ndarray

The odf function evaluated on the vertices of sphere

sphereSphere

The Sphere providing discrete directions for evaluation.

relative_peak_thresholdfloat 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_anglefloat 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.

random

dipy.direction.probabilistic_direction_getter.random() → x in the interval [0, 1).