direction

Module: direction.bootstrap_direction_getter

BootDirectionGetter
peak_directions(odf, sphere, *[, ...])	Get the directions of odf peaks.

Module: direction.closest_peak_direction_getter

BaseDirectionGetter
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
peak_directions(odf, sphere, *[, ...])	Get the directions of odf peaks.

Module: direction.peaks

PeaksAndMetrics
peak_directions_nl(sphere_eval, *[, ...])	Non Linear Direction Finder.
peak_directions(odf, sphere, *[, ...])	Get the directions of odf peaks.
peaks_from_model(model, data, sphere, ...[, ...])	Fit the model to data and computes peaks and metrics
reshape_peaks_for_visualization(peaks)	Reshape peaks for visualization.
peaks_from_positions(positions, odfs, ...[, ...])	Extract the peaks at each positions.

Module: direction.pmf

PmfGen
SHCoeffPmfGen
SimplePmfGen

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).
random(/)

Module: direction.ptt_direction_getter

Implementation of the Parallel Transport Tractography (PTT) algorithm by Aydogan and Shi[1]. PTT Default parameter values are slightly different than 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 voxel-wise peaks.

References

[1]

Dogu Baran Aydogan and Yonggang Shi. Ieee transactions on medical imaging. Parallel Transport Tractography, 2021(40):2, 635-647. doi:10.1109/TMI.2020.3034038.

PTTDirectionGetter	Parallel Transport Tractography (PTT) direction getter.
min_radius_curvature_from_angle(max_angle, ...)	Get minimum radius of curvature from a deviation angle.

BootDirectionGetter

class dipy.direction.bootstrap_direction_getter.BootDirectionGetter

Bases: DirectionGetter

Methods

from_data(data, model, max_angle[, sphere, ...])	Create a BootDirectionGetter using HARDI data and an ODF type model
get_pmf(point)	Produces an ODF from a SH bootstrap sample
initial_direction(point)	Returns best directions at seed location to start tracking.

generate_streamline
get_direction
get_pmf_no_boot

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 b-values 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, 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.

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

Methods

initial_direction(point)

Returns best directions at seed location to start tracking.

generate_streamline
get_direction

BasePmfDirectionGetter

class dipy.direction.closest_peak_direction_getter.BasePmfDirectionGetter

Bases: DirectionGetter

A base class for dynamic direction getters

Methods

initial_direction(point)

Returns best directions at seed location to start tracking.

generate_streamline
get_direction

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.

Methods

from_pmf(pmf, max_angle, sphere[, pmf_threshold])	Constructor for making a DirectionGetter from an array of Pmfs
from_shcoeff(shcoeff, max_angle[, sphere, ...])	Probabilistic direction getter from a distribution of directions on the sphere
initial_direction(point)	Returns best directions at seed location to start tracking.

generate_streamline
get_direction

PmfGenDirectionGetter

class dipy.direction.closest_peak_direction_getter.PmfGenDirectionGetter

Bases: BasePmfDirectionGetter

A base class for direction getter using a pmf

Methods

from_pmf(pmf, max_angle, sphere[, pmf_threshold])	Constructor for making a DirectionGetter from an array of Pmfs
from_shcoeff(shcoeff, max_angle[, sphere, ...])	Probabilistic direction getter from a distribution of directions on the sphere
initial_direction(point)	Returns best directions at seed location to start tracking.

generate_streamline
get_direction

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

legacy: bool, optional

True to use a legacy basis definition for backward compatibility with previous tournier07 and descoteaux07 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, 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.

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

Attributes:

ang_thr

qa_thr

total_weight

Methods

initial_direction(point)

The best starting directions for fiber tracking from point

generate_streamline
get_direction

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.

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

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 :footcite:p:Tournier2007` basis, and descoteaux07 for the Descoteaux 2007 :footcite:p:Descoteaux2007` basis (None defaults to descoteaux07).

legacy: bool, optional

True to use a legacy basis definition for backward compatibility with previous tournier07 and descoteaux07 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 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

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)

peaks_from_positions

dipy.direction.peaks.peaks_from_positions(positions, odfs, sphere, affine, *, relative_peak_threshold=0.5, min_separation_angle=25, is_symmetric=True, npeaks=5)

Extract the peaks at each positions.

Parameters:

positionarray, (N, 3)

World coordinates of the N positions.

odfsarray, (X, Y, Z, M)

Orientation distribution function (spherical function) represented on a sphere of M points.

sphereSphere

A discrete Sphere. The M points on the sphere correspond to the points of the odfs.

affinearray (4, 4)

The mapping between voxel indices and the point space for positions.

relative_peak_thresholdfloat, optional

Only peaks greater than min + relative_peak_threshold * scale are kept, where min = max(0, odf.min()) and scale = odf.max() - min. The relative_peak_threshold should be in the range [0, 1].

min_separation_anglefloat, optional

The minimum distance between directions. If two peaks are too close only the larger of the two is returned. The min_separation_angle should be in the range [0, 90].

is_symmetricbool, optional

If True, v is considered equal to -v.

npeaksint, optional

The maximum number of peaks to extract at from each position.

Returns:

peaks_arrarray (N, npeaks, 3)

PmfGen

class dipy.direction.pmf.PmfGen

Bases: object

Methods

get_pmf
get_pmf_value

get_pmf(point, out=None)

get_pmf_value(point, xyz)

SHCoeffPmfGen

class dipy.direction.pmf.SHCoeffPmfGen

Bases: PmfGen

Methods

get_pmf
get_pmf_value

SimplePmfGen

class dipy.direction.pmf.SimplePmfGen

Bases: PmfGen

Methods

get_pmf
get_pmf_value

DeterministicMaximumDirectionGetter

class dipy.direction.probabilistic_direction_getter.DeterministicMaximumDirectionGetter

Bases: ProbabilisticDirectionGetter

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

Methods

from_pmf(pmf, max_angle, sphere[, pmf_threshold])	Constructor for making a DirectionGetter from an array of Pmfs
from_shcoeff(shcoeff, max_angle[, sphere, ...])	Probabilistic direction getter from a distribution of directions on the sphere
initial_direction(point)	Returns best directions at seed location to start tracking.

generate_streamline
get_direction

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.

Methods

from_pmf(pmf, max_angle, sphere[, pmf_threshold])	Constructor for making a DirectionGetter from an array of Pmfs
from_shcoeff(shcoeff, max_angle[, sphere, ...])	Probabilistic direction getter from a distribution of directions on the sphere
initial_direction(point)	Returns best directions at seed location to start tracking.

generate_streamline
get_direction

random

dipy.direction.probabilistic_direction_getter.random(/)

PTTDirectionGetter

class dipy.direction.ptt_direction_getter.PTTDirectionGetter

Bases: ProbabilisticDirectionGetter

Parallel Transport Tractography (PTT) direction getter.

Methods

from_pmf(pmf, max_angle, sphere[, pmf_threshold])	Constructor for making a DirectionGetter from an array of Pmfs
from_shcoeff(shcoeff, max_angle[, sphere, ...])	Probabilistic direction getter from a distribution of directions on the sphere
initial_direction(point)	Returns best directions at seed location to start tracking.

generate_streamline
get_direction

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.

See [2] for further details about the method.

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

[2]

Jacques-Donald Tournier, Fernando Calamante, and Alan Connelly. MRtrix: Diffusion tractography in crossing fiber regions. International Journal of Imaging Systems and Technology, 22(1):53–66, 2012. URL: https://onlinelibrary.wiley.com/doi/abs/10.1002/ima.22005, doi:https://doi.org/10.1002/ima.22005.