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). |
Module: direction.bootstrap_direction_getter
Module: direction.closest_peak_direction_getter
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). |
Module: direction.probabilistic_direction_getter
Implementation of a probabilistic direction getter based on sampling from
discrete distribution (pmf) at each step of the tracking.
-
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. |
generate_streamline |
|
get_direction |
|
-
__init__(*args, **kwargs)
-
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.
-
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. |
generate_streamline |
|
get_direction |
|
-
__init__(*args, **kwargs)
-
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. |
generate_streamline |
|
get_direction |
|
-
__init__(*args, **kwargs)
-
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
generate_streamline |
|
get_direction |
|
-
__init__(*args, **kwargs)
-
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
-
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
-
__init__(suffix='', prefix='tmp', dir=None)
-
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 |
generate_streamline |
|
get_direction |
|
-
__init__(*args, **kwargs)
-
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. |
generate_streamline |
|
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.
-
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. |
-
__init__(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None)
-
edges()
-
faces()
-
find_closest(xyz)
Find the index of the vertex in the Sphere closest to the input vector
- Parameters
- 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
-
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)
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.
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.
- 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].
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.
- datandarray
Diffusion 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
).
- 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(vertices, theta, return_mapping=False, return_index=False)
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(a, relative_threshold)
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.
-
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. |
generate_streamline |
|
get_direction |
|
-
__init__(*args, **kwargs)
-
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.
-
class dipy.direction.bootstrap_direction_getter.BootPmfGen
Bases: dipy.direction.pmf.PmfGen
Methods
get_pmf
|
Produces an ODF from a SH bootstrap sample |
get_pmf_value
|
Return the pmf value corresponding to the closest vertex to the direction xyz. |
-
__init__(*args, **kwargs)
-
get_pmf()
Produces an ODF from a SH bootstrap sample
-
get_pmf_no_boot()
-
class dipy.direction.closest_peak_direction_getter.BasePmfDirectionGetter
Bases: dipy.tracking.direction_getter.DirectionGetter
A base class for dynamic direction getters
Methods
generate_streamline |
|
get_direction |
|
-
__init__(*args, **kwargs)
-
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.
-
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. |
generate_streamline |
|
get_direction |
|
-
__init__(*args, **kwargs)
-
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. |
generate_streamline |
|
get_direction |
|
-
__init__(*args, **kwargs)
-
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 on which the pmf is sampled and 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.
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.
-
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
generate_streamline |
|
get_direction |
|
-
__init__(*args, **kwargs)
-
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
-
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
-
__init__(suffix='', prefix='tmp', dir=None)
-
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 |
generate_streamline |
|
get_direction |
|
-
__init__(*args, **kwargs)
-
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. |
-
__init__(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None)
-
edges()
-
faces()
-
find_closest(xyz)
Find the index of the vertex in the Sphere closest to the input vector
- Parameters
- 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
-
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)
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.
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.
- 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].
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.
- datandarray
Diffusion 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
).
- 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(vertices, theta, return_mapping=False, return_index=False)
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(a, relative_threshold)
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.
-
class dipy.direction.pmf.BootPmfGen
Bases: dipy.direction.pmf.PmfGen
Methods
get_pmf
|
Produces an ODF from a SH bootstrap sample |
get_pmf_value
|
Return the pmf value corresponding to the closest vertex to the direction xyz. |
-
__init__(*args, **kwargs)
-
get_pmf()
Produces an ODF from a SH bootstrap sample
-
get_pmf_no_boot()
-
class dipy.direction.pmf.PmfGen
Bases: object
Methods
get_pmf_value
|
Return the pmf value corresponding to the closest vertex to the direction xyz. |
-
__init__(*args, **kwargs)
-
get_pmf()
-
get_pmf_value()
Return the pmf value corresponding to the closest vertex to the
direction xyz.
-
class dipy.direction.pmf.SHCoeffPmfGen
Bases: dipy.direction.pmf.PmfGen
Methods
get_pmf_value
|
Return the pmf value corresponding to the closest vertex to the direction xyz. |
-
__init__(*args, **kwargs)
-
get_pmf()
-
class dipy.direction.pmf.SimplePmfGen
Bases: dipy.direction.pmf.PmfGen
Methods
get_pmf_value
|
Return the pmf value corresponding to the closest vertex to the direction xyz. |
-
__init__(*args, **kwargs)
-
get_pmf()
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
-
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. |
generate_streamline |
|
get_direction |
|
-
__init__(*args, **kwargs)
-
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. |
generate_streamline |
|
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(/)