direction
#
Module: direction.bootstrap_direction_getter
#

Get the directions of odf peaks. 
Module: direction.closest_peak_direction_getter
#
A base class for dynamic direction getters 

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

A base class for direction getter using a pmf 


Get the directions of odf peaks. 
Module: direction.peaks
#

Non Linear Direction Finder. 

Get the directions of odf peaks. 

Fit the model to data and computes peaks and metrics 
Reshape peaks for visualization. 
Module: direction.pmf
#
Module: direction.probabilistic_direction_getter
#
Implementation of a probabilistic direction getter based on sampling from discrete distribution (pmf) at each step of the tracking.
Return direction of a sphere with the highest probability mass function (pmf). 

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


Module: direction.ptt_direction_getter
#
Implementation of the Parallel Transport Tractography (PTT) algorithm by Aydogan et al., (2021). PTT Default parameter values are slightly different then in Trekker to optimise performances. The rejection sampling algorithm also uses fewer samples to estimate the maximum of the posterior, and fewer tries to obtain a suitable propagation candidate. Moreover, the initial tangent direction in this implementation is always obtained from the voxelwise peaks.
 Aydogan DB, Shi Y. Parallel Transport Tractography. IEEE Trans
Med Imaging. 2021 Feb;40(2):635647. doi: 10.1109/TMI.2020.3034038. Epub 2021 Feb 2. PMID: 33104507; PMCID: PMC7931442.
Parallel Transport Tractography (PTT) direction getter. 


Get minimum radius of curvature from a deviation angle. 
BootDirectionGetter
#
 class dipy.direction.bootstrap_direction_getter.BootDirectionGetter#
Bases:
DirectionGetter
 __init__(*args, **kwargs)#
 classmethod from_data(data, model, max_angle, sphere=<dipy.core.sphere.HemiSphere object>, sh_order=0, max_attempts=5, b_tol=20, **kwargs)#
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.
 b_tolfloat
Maximum difference between bvalues to be considered single shell.
 relative_peak_thresholdfloat in [0., 1.]
Relative threshold for excluding ODF peaks.
 min_separation_anglefloat in [0, 90]
Angular threshold for excluding ODF peaks.
 get_pmf(point)#
Produces an ODF from a SH bootstrap sample
 get_pmf_no_boot(point)#
 initial_direction(point)#
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.
peak_directions#
 dipy.direction.bootstrap_direction_getter.peak_directions(odf, sphere, relative_peak_threshold=0.5, min_separation_angle=25, is_symmetric=True)#
Get the directions of odf peaks.
Peaks are defined as points on the odf that are greater than at least one neighbor and greater than or equal to all neighbors. Peaks are sorted in descending order by their values then filtered based on their relative size and spacing on the sphere. An odf may have 0 peaks, for example if the odf is perfectly isotropic.
Parameters#
 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, wheremin = max(0, odf.min())
andscale = 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.
 is_symmetricbool, optional
If True, v is considered equal to v.
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.
BaseDirectionGetter
#
 class dipy.direction.closest_peak_direction_getter.BaseDirectionGetter#
Bases:
BasePmfDirectionGetter
 __init__(*args, **kwargs)#
BasePmfDirectionGetter
#
 class dipy.direction.closest_peak_direction_getter.BasePmfDirectionGetter#
Bases:
DirectionGetter
A base class for dynamic direction getters
 __init__(*args, **kwargs)#
 initial_direction(point)#
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:
PmfGenDirectionGetter
A direction getter that returns the closest odf peak to previous tracking direction.
 __init__(*args, **kwargs)#
PmfGenDirectionGetter
#
 class dipy.direction.closest_peak_direction_getter.PmfGenDirectionGetter#
Bases:
BasePmfDirectionGetter
A base class for direction getter using a pmf
 __init__(*args, **kwargs)#
 classmethod from_pmf(pmf, max_angle, sphere, pmf_threshold=0.1, **kwargs)#
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.
See Also#
dipy.direction.peaks.peak_directions
 classmethod from_shcoeff(shcoeff, max_angle, sphere=<dipy.core.sphere.HemiSphere object>, pmf_threshold=0.1, basis_type=None, legacy=True, sh_to_pmf=False, **kwargs)#
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 ofsphere
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.
 legacy: bool, optional
True to use a legacy basis definition for backward compatibility with previous
tournier07
anddescoteaux07
implementations. sh_to_pmf: bool, optional
If true, map sherical harmonics to spherical function (pmf) before tracking (faster, requires more memory).
See Also#
dipy.direction.peaks.peak_directions
peak_directions#
 dipy.direction.closest_peak_direction_getter.peak_directions(odf, sphere, relative_peak_threshold=0.5, min_separation_angle=25, is_symmetric=True)#
Get the directions of odf peaks.
Peaks are defined as points on the odf that are greater than at least one neighbor and greater than or equal to all neighbors. Peaks are sorted in descending order by their values then filtered based on their relative size and spacing on the sphere. An odf may have 0 peaks, for example if the odf is perfectly isotropic.
Parameters#
 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, wheremin = max(0, odf.min())
andscale = 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.
 is_symmetricbool, optional
If True, v is considered equal to v.
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.
PeaksAndMetrics
#
 class dipy.direction.peaks.PeaksAndMetrics#
Bases:
EuDXDirectionGetter
 __init__()#
peak_directions_nl#
 dipy.direction.peaks.peak_directions_nl(sphere_eval, relative_peak_threshold=0.25, min_separation_angle=25, sphere=<dipy.core.sphere.HemiSphere object>, xtol=1e07)#
Non Linear Direction Finder.
Parameters#
 sphere_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.
peak_directions#
 dipy.direction.peaks.peak_directions(odf, sphere, relative_peak_threshold=0.5, min_separation_angle=25, is_symmetric=True)#
Get the directions of odf peaks.
Peaks are defined as points on the odf that are greater than at least one neighbor and greater than or equal to all neighbors. Peaks are sorted in descending order by their values then filtered based on their relative size and spacing on the sphere. An odf may have 0 peaks, for example if the odf is perfectly isotropic.
Parameters#
 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, wheremin = max(0, odf.min())
andscale = 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.
 is_symmetricbool, optional
If True, v is considered equal to v.
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.
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_max=8, sh_basis_type=None, legacy=True, 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_order_maxint, optional
Maximum SH order (l) in the SH fit. For sh_order_max, there will be
(sh_order_max + 1) * (sh_order_max + 2) / 2
SH coefficients (default 8). sh_basis_type{None, ‘tournier07’, ‘descoteaux07’}
None
for the default DIPY basis,tournier07
for the Tournier 2007 [2] basis, anddescoteaux07
for the Descoteaux 2007 [1] basis (None
defaults todescoteaux07
). legacy: bool, optional
True to use a legacy basis definition for backward compatibility with previous
tournier07
anddescoteaux07
implementations. 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
andtempfile.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#
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#
peaks : nd array (…, 3*N)
PmfGen
#
SHCoeffPmfGen
#
SimplePmfGen
#
DeterministicMaximumDirectionGetter
#
 class dipy.direction.probabilistic_direction_getter.DeterministicMaximumDirectionGetter#
Bases:
ProbabilisticDirectionGetter
Return direction of a sphere with the highest probability mass function (pmf).
 __init__(*args, **kwargs)#
ProbabilisticDirectionGetter
#
 class dipy.direction.probabilistic_direction_getter.ProbabilisticDirectionGetter#
Bases:
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. __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.
See Also#
dipy.direction.peaks.peak_directions
random#
 dipy.direction.probabilistic_direction_getter.random() x in the interval [0, 1). #
PTTDirectionGetter
#
 class dipy.direction.ptt_direction_getter.PTTDirectionGetter#
Bases:
ProbabilisticDirectionGetter
Parallel Transport Tractography (PTT) direction getter.
 __init__()#
PTT used probe for estimating future propagation steps. A probe is a short, cylinderical model of the connecting segment.
Parameters#
 pmf_genPmfGen
Used to get probability mass function for selecting tracking directions.
 max_anglefloat, [0, 90]
Is used to set the upper limits for the k1 and k2 parameters of parallel transport frame (max_curvature).
 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.
 probe_lengthdouble
The length of the probes. Shorter probe_length yields more dispersed fibers.
 probe_radiusdouble
The radius of the probe. A large probe_radius helps mitigate noise in the pmf but it might make it harder to sample thin and intricate connections, also the boundary of fiber bundles might be eroded.
 probe_qualityinteger,
The quality of the probe. This parameter sets the number of segments to split the cylinder along the length of the probe (minimum=2).
 probe_countinteger
The number of probes. This parameter sets the number of parallel lines used to model the cylinder (minimum=1).
 data_support_exponentdouble
Data support to the power dataSupportExponent is used for rejection sampling.
 generate_streamline(seed, dir, voxel_size, step_size, stopping_criterion, streamline, stream_status, fixedstep)#
min_radius_curvature_from_angle#
 dipy.direction.ptt_direction_getter.min_radius_curvature_from_angle(max_angle, step_size)#
Get minimum radius of curvature from a deviation angle.
Parameters#
 max_angle: float
The maximum deviation angle in radian. theta should be between [0  pi/2] otherwise default will be pi/2.
 step_size: float
The tracking step size in mm.
Returns#
 min_radius_curvature: float
Minimum radius of curvature in mm, given the maximum deviation angle theta and the step size.
References#
More information: https://onlinelibrary.wiley.com/doi/full/10.1002/ima.22005