tracking
tracking._utils
tracking.benchmarks
tracking.benchmarks.bench_streamline
tracking.learning
tracking.life
tracking.local_tracking
tracking.mesh
tracking.metrics
tracking.streamline
tracking.utils
LifeSignalMaker
FiberModel
FiberFit
LocalTracking
ParticleFilteringTracking
tracking
Tracking objects
tracking._utils
This is a helper module for dipy.tracking.utils.
tracking.benchmarks
tracking.benchmarks.bench_streamline
Benchmarks for functions related to streamline
Run all benchmarks with:
import dipy.tracking as dipytracking
dipytracking.bench()
With Pytest, Run this benchmark with:
pytest svv c bench.ini /path/to/bench_streamline.py




tracking.learning
Learning algorithms for tractography

Detect corresponding tracks from list tracks1 to list tracks2 where tracks1 & tracks2 are lists of tracks 

Detect corresponding tracks from 1 to 2 where tracks1 & tracks2 are sequences of tracks 
tracking.life
This is an implementation of the Linear Fascicle Evaluation (LiFE) algorithm described in:
Pestilli, F., Yeatman, J, Rokem, A. Kay, K. and Wandell B.A. (2014). Validation and statistical inference in living connectomes. Nature Methods 11: 10581063. doi:10.1038/nmeth.3098

A class for generating signals from streamlines in an efficient and speedy manner. 

A class for representing and solving predictive models based on tractography solutions. 

A fit of the LiFE model to diffusion data 

Return the gradient of an Ndimensional array. 

Calculate the gradients of the streamline along the spatial dimension 

Calculate the 3 by 3 tensor for a given spatial gradient, given a canonical tensor shape (also as a 3 by 3), pointing at [1,0,0] 

The tensors generated by this fiber. 

The signal from a single streamline estimate along each of its nodes. 

Maps voxels to streamlines and streamlines to voxels, for setting up the LiFE equations matrix 
tracking.local_tracking



tracking.mesh

Generate random triangles_indices and trilinear_coord 

Compute points from triangles_indices and trilinear_coord 

Compute the local area of each triangle 

Change from values per vertex to values per triangle 
tracking.metrics
Metrics for tracks, where tracks are arrays of points

Total turning angle projected. 

Euclidean length of track line 

Size of track in bytes. 

Midpoint of track 

downsample for a specific number of points along the streamline Uses the length of the curve. 

Center of mass of streamline 

magnitude of vector 

FrenetSerret Space Curve Invariants Calculates the 3 vector and 2 scalar invariants of a space curve defined by vectors r = (x,y,z). 

Calculates the mean curvature of a curve 

Calculates the mean orientation of a curve 

Combine sets of size n from items 

Return longest track or length sorted track indices in bundle 

If any segment of the track is intersecting with a sphere of specific center and radius return True otherwise False 

If any point of the track is inside a sphere of a specified center and radius return True otherwise False. 

If a track intersects with a sphere of a specified center and radius return the points that are inside the sphere otherwise False. 

Generate Bsplines as documented in http://www.scipy.org/Cookbook/Interpolation 

First point of the track 

Parameters xyz array, shape(N,3) Track. 

Select an arbitrary point along distance on the track (curve) 

We use PCA to calculate the 3 principal directions for a track 

Calculate distance from midpoint of a curve to arbitrary point p 
tracking.streamline

Return the streamlines not as a list but as an array and an offset 

Given a representation of a set of streamlines as a large array and an offsets array return the streamlines as a list of shorter arrays. 

Move streamlines to the origin 

Apply deformation field to streamlines 

Apply affine transformation to streamlines 

Select a random set of streamlines 

Select streamlines based on logical relations with several regions of interest (ROIs). 

Computes the cluster confidence index (cci), which is an estimation of the support a set of streamlines gives to a particular pathway. 

Orient a set of streamlines according to a pair of ROIs 

Orient a bundle of streamlines to a standard streamline. 

Extract values of a scalar/vector along each streamline from a volume. 

tracking.utils
Various tools related to creating and working with streamlines.
This module provides tools for targeting streamlines using ROIs, for making connectivity matrices from whole brain fiber tracking and some other tools that allow streamlines to interact with image data.
Dipy uses affine matrices to represent the relationship between streamline
points, which are defined as points in a continuous 3d space, and image voxels,
which are typically arranged in a discrete 3d grid. Dipy uses a convention
similar to nifti files to interpret these affine matrices. This convention is
that the point at the center of voxel [i, j, k]
is represented by the point
[x, y, z]
where [x, y, z, 1] = affine * [i, j, k, 1]
. Also when the
phrase “voxel coordinates” is used, it is understood to be the same as affine
= eye(4)
.
As an example, let’s take a 2d image where the affine is:
[[1., 0., 0.],
[0., 2., 0.],
[0., 0., 1.]]
The pixels of an image with this affine would look something like:
A
   
 C   
   
B
   
   
   

   
   
   
D
And the letters AD represent the following points in “real world coordinates”:
A = [.5, 1.]
B = [ .5, 1.]
C = [ 0., 0.]
D = [ 2.5, 5.]

Count the number of unique streamlines that pass through each voxel. 

Count the streamlines that start and end at each label pair. 

Like bincount, but for ndindices. 

Reduce an array of labels to the integers from 0 to n with smallest possible n. 

Split the segments of the streamlines into small segments. 

Create seeds for fiber tracking from a binary mask. 

Create randomly placed seeds for fiber tracking from a binary mask. 

Filter streamlines based on whether or not they pass through an ROI. 

Filter streamlines based on whether or not they pass through a ROI, using a linebased algorithm. 

Is a streamline near an ROI. 

Provide filtering criteria for a set of streamlines based on whether they fall within a tolerance distance from an ROI. 

Calculate the lengths of many streamlines in a bundle. 

Find the unique rows in an array. 

Apply a linear transformation, given by affine, to streamlines. 

Reduce multiple ROIs to one inclusion and one exclusion ROI. 

Compute the shortest path, along any streamline, between aoi and each voxel. 
Get the maximum deviation angle from the minimum radius curvature. 


Get minimum radius of curvature from a deviation angle. 
Detect corresponding tracks from list tracks1 to list tracks2 where tracks1 & tracks2 are lists of tracks
of indices of tracks1 that are to be detected in tracks2
of tracks as arrays, shape (N1,3) .. (Nm,3)
of tracks as arrays, shape (M1,3) .. (Mm,3)
it shows the correspondence in the following way: the first column is the current index in tracks1 the second column is the corresponding index in tracks2
>>> import numpy as np
>>> import dipy.tracking.learning as tl
>>> A = np.array([[0, 0, 0], [1, 1, 1], [2, 2, 2]])
>>> B = np.array([[1, 0, 0], [2, 0, 0], [3, 0, 0]])
>>> C = np.array([[0, 0, 1], [0, 0, 2], [0, 0, 3]])
>>> bundle1 = [A, B, C]
>>> bundle2 = [B, A]
>>> indices = [0, 1]
>>> arr = tl.detect_corresponding_tracks(indices, bundle1, bundle2)
To find the corresponding tracks we use mam_distances with ‘avg’ option. Then we calculate the argmin of all the calculated distances and return it for every index. (See 3rd column of arr in the example given below.)
Detect corresponding tracks from 1 to 2 where tracks1 & tracks2 are sequences of tracks
of indices of tracks1 that are to be detected in tracks2
of tracks as arrays, shape (N1,3) .. (Nm,3)
of indices of tracks2 in the initial brain
of tracks as arrays, shape (M1,3) .. (Mm,3)
of int showing the correspondence in th following way the first column is the current index of tracks1 the second column is the corresponding index in tracks2
>>> import numpy as np
>>> import dipy.tracking.learning as tl
>>> A = np.array([[0, 0, 0], [1, 1, 1], [2, 2, 2]])
>>> B = np.array([[1, 0, 0], [2, 0, 0], [3, 0, 0]])
>>> C = np.array([[0, 0, 1], [0, 0, 2], [0, 0, 3]])
>>> bundle1 = [A, B, C]
>>> bundle2 = [B, A]
>>> indices = [0, 1]
>>> indices2 = indices
>>> arr = tl.detect_corresponding_tracks_plus(indices, bundle1, indices2, bundle2)
To find the corresponding tracks we use mam_distances with ‘avg’ option. Then we calculate the argmin of all the calculated distances and return it for every index. (See 3rd column of arr in the example given below.)
distances.mam_distances
LifeSignalMaker
Bases: object
A class for generating signals from streamlines in an efficient and speedy manner.
Initialize a signal maker
The gradient table on which the signal is calculated.
The eigenvalues of the canonical tensor to use in calculating the signal.
The discrete sphere to use as an approximation for the continuous
sphere on which the signal is represented. If integer  we will use
an instance of one of the symmetric spheres cached in
dps.get_sphere. If a ‘dipy.core.Sphere’ class instance is
provided, we will use this object. Default: the dipy.data
symmetric sphere with 724 vertices
FiberModel
Bases: ReconstModel
A class for representing and solving predictive models based on tractography solutions.
This is an implementation of the LiFE model described in [1]
B.A. (2014). Validation and statistical inference in living connectomes. Nature Methods.
Fit the LiFE FiberModel for data and a set of streamlines associated with this data
Diffusionweighted data
A bunch of streamlines
The mapping from voxel coordinates to streamline points. The voxel_to_rasmm matrix, typically from a NIFTI file.
The eigenvalues of the tensor response function used in constructing the model signal. Default: [0.001, 0, 0]
Whether to approximate (and cache) the signal on a discrete sphere. This may confer a significant speedup in setting up the problem, but is not as accurate. If False, we use the exact gradients along the streamlines to calculate the matrix, instead of an approximation.
FiberFit class instance
Set up the necessary components for the LiFE model: the matrix of fibercontributions to the DWI signal, and the coordinates of voxels for which the equations will be solved
Streamlines, each is an array of shape (n, 3)
The mapping from voxel coordinates to streamline points. The voxel_to_rasmm matrix, typically from a NIFTI file.
The eigenvalues of the canonical tensor used as a response function. Default:[0.001, 0, 0].
Whether to approximate (and cache) the signal on a discrete
sphere. This may confer a significant speedup in setting up the
problem, but is not as accurate. If False, we use the exact
gradients along the streamlines to calculate the matrix, instead of
an approximation. Defaults to use the 724vertex symmetric sphere
from dipy.data
FiberFit
Bases: ReconstFit
A fit of the LiFE model to diffusion data
fiber_model : A FiberModel class instance
params : the parameters derived from a fit of the model to the data.
Predict the signal
Default: use self.gtab
The nondiffusionweighted signal in the voxels for which a prediction is made. Default: use self.b0_signal
An array with a prediction of the signal in each voxel/direction
Return the gradient of an Ndimensional array.
The gradient is computed using central differences in the interior and first differences at the boundaries. The returned gradient hence has the same shape as the input array.
An Ndimensional array containing samples of a scalar function.
N arrays of the same shape as f giving the derivative of f with respect to each dimension.
>>> x = np.array([1, 2, 4, 7, 11, 16], dtype=float)
>>> gradient(x)
array([ 1. , 1.5, 2.5, 3.5, 4.5, 5. ])
>>> gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=float))
[array([[ 2., 2., 1.],
[ 2., 2., 1.]]), array([[ 1. , 2.5, 4. ],
[ 1. , 1. , 1. ]])]
This is a simplified implementation of gradient that is part of numpy 1.8. In order to mitigate the effects of changes added to this implementation in version 1.9 of numpy, we include this implementation here.
Calculate the 3 by 3 tensor for a given spatial gradient, given a canonical tensor shape (also as a 3 by 3), pointing at [1,0,0]
The spatial gradient (e.g between two nodes of a streamline).
The eigenvalues of a canonical tensor to be used as a response function.
The tensors generated by this fiber.
The 3d coordinates of a single streamline
The estimated eigenvalues of a single fiber tensor.
An n_nodes by 3 by 3 array with the tensor for each node in the fiber.
Estimates of the radial/axial diffusivities may rely on empirical measurements (for example, the AD in the Corpus Callosum), or may be based on a biophysical model of some kind.
The signal from a single streamline estimate along each of its nodes.
streamline : a single streamline
gtab : GradientTable class instance
The eigenvalues of the canonical tensor used as an estimate of the signal generated by each node of the streamline.
Maps voxels to streamlines and streamlines to voxels, for setting up the LiFE equations matrix
A collection of streamlines, each n by 3, with n being the number of nodes in the fiber.
The mapping from voxel coordinates to streamline points. The voxel_to_rasmm matrix, typically from a NIFTI file.
The unique indices in the streamlines
v2f, v2fn : tuple of dicts
The first dict in the tuple answers the question: Given a voxel (from the unique indices in this model), which fibers pass through it?
The second answers the question: Given a streamline, for each voxel that this streamline passes through, which nodes of that streamline are in that voxel?
LocalTracking
Bases: object
Creates streamlines by using local fibertracking.
Used to get directions for fiber tracking.
Identifies endpoints and invalid points to inform tracking.
Points to seed the tracking. Seed points should be given in point
space of the track (see affine
).
Coordinate space for the streamline point with respect to voxel indices of input data. This affine can contain scaling, rotational, and translational components but should not contain any shearing. An identity matrix can be used to generate streamlines in “voxel coordinates” as long as isotropic voxels were used to acquire the data.
Step size used for tracking.
The maximum number of direction to track from each seed in crossing voxels. By default all initial directions are tracked.
Maximum number of steps to track from seed. Used to prevent infinite loops.
If true, a fixed stepsize is used, otherwise a variable step size is used.
If true, return all generated streamlines, otherwise only streamlines reaching end points or exiting the image.
The seed for the random seed generator (numpy.random.seed and random.seed).
If True, return seeds alongside streamlines
ParticleFilteringTracking
Bases: LocalTracking
A streamline generator using the particle filtering tractography method [1].
Used to get directions for fiber tracking.
Identifies endpoints and invalid points to inform tracking.
Points to seed the tracking. Seed points should be given in point
space of the track (see affine
).
Coordinate space for the streamline point with respect to voxel indices of input data. This affine can contain scaling, rotational, and translational components but should not contain any shearing. An identity matrix can be used to generate streamlines in “voxel coordinates” as long as isotropic voxels were used to acquire the data.
Step size used for tracking.
The maximum number of direction to track from each seed in crossing voxels. By default all initial directions are tracked.
Maximum number of steps to track from seed. Used to prevent infinite loops.
Distance in mm to back track before starting the particle filtering tractography. The total particle filtering tractography distance is equal to back_tracking_dist + front_tracking_dist. By default this is set to 2 mm.
Distance in mm to run the particle filtering tractography after the the back track distance. The total particle filtering tractography distance is equal to back_tracking_dist + front_tracking_dist. By default this is set to 1 mm.
Maximum number of trial for the particle filtering tractography (Prevents infinite loops).
Number of particles to use in the particle filter.
If true, return all generated streamlines, otherwise only streamlines reaching end points or exiting the image.
The seed for the random seed generator (numpy.random.seed and random.seed).
If True, return seeds alongside streamlines
Generate random triangles_indices and trilinear_coord
for each triangles inside the given triangles_mask
The amount of triangles in the mesh
The number of random indices and coordinates generated.
Specifies which triangles should be chosen (or not)
Specifies the weight/probability of choosing each triangle
The seed for the random seed generator (numpy.random.seed).
Randomly chosen triangles_indices
Randomly chosen trilinear_coordinates
seeds_from_surface_coordinates, random_seeds_from_mask
Compute points from triangles_indices and trilinear_coord
A list of triangles from a mesh
List of values to interpolates from coordinates along vertices, (vertices, vertices_normal, vertices_colors …)
Specifies which triangles should be chosen (or not)
Specifies the weight/probability of choosing each triangle
Interpolated values of vertices with triangles_idx and trilinear_coord
random_coordinates_from_surface
Compute the local area of each triangle
A list of triangles from a mesh
List of vertices
List of area for each triangle in the mesh
random_coordinates_from_surface
Change from values per vertex to values per triangle
A list of triangles from a mesh
List of values to interpolates from coordinates along vertices, (vertices, vertices_normal, vertices_colors …)
List of values for each triangle in the mesh
random_coordinates_from_surface
Total turning angle projected.
Project space curve to best fitting plane. Calculate the cumulative signed angle between each line segment and the previous one.
Array representing x,y,z of N points in a track.
Total turning angle in degrees.
Euclidean length of track line
This will give length in mm if tracks are expressed in world coordinates.
array representing x,y,z of N points in a track
If True, return array giving cumulative length along track, otherwise (default) return scalar giving total length.
scalar in case of along == False, giving total length, array if along == True, giving cumulative lengths.
>>> from dipy.tracking.metrics import length
>>> xyz = np.array([[1,1,1],[2,3,4],[0,0,0]])
>>> expected_lens = np.sqrt([1+2**2+3**2, 2**2+3**2+4**2])
>>> length(xyz) == expected_lens.sum()
True
>>> len_along = length(xyz, along=True)
>>> np.allclose(len_along, expected_lens.cumsum())
True
>>> length([])
0
>>> length([[1, 2, 3]])
0
>>> length([], along=True)
array([0])
Midpoint of track
array representing x,y,z of N points in a track
Middle point of line, such that, if L is the line length then np is the point such that the length xyz[0] to mp and from mp to xyz[1] is L/2. If the middle point is not a point in xyz, then we take the interpolation between the two nearest xyz points. If xyz is empty, return a ValueError
>>> from dipy.tracking.metrics import midpoint
>>> midpoint([])
Traceback (most recent call last):
...
ValueError: xyz array cannot be empty
>>> midpoint([[1, 2, 3]])
array([1, 2, 3])
>>> xyz = np.array([[1,1,1],[2,3,4]])
>>> midpoint(xyz)
array([ 1.5, 2. , 2.5])
>>> xyz = np.array([[0,0,0],[1,1,1],[2,2,2]])
>>> midpoint(xyz)
array([ 1., 1., 1.])
>>> xyz = np.array([[0,0,0],[1,0,0],[3,0,0]])
>>> midpoint(xyz)
array([ 1.5, 0. , 0. ])
>>> xyz = np.array([[0,9,7],[1,9,7],[3,9,7]])
>>> midpoint(xyz)
array([ 1.5, 9. , 7. ])
downsample for a specific number of points along the streamline Uses the length of the curve. It works in a similar fashion to midpoint and arbitrarypoint but it also reduces the number of segments of a streamline.
dipy.tracking.metrics.downsample is deprecated, Please use dipy.tracking.streamline.set_number_of_points instead
deprecated from version: 1.2
Raises <class ‘dipy.utils.deprecator.ExpiredDeprecationError’> as of version: 1.4
array representing x,y,z of N points in a streamlines
integer representing number of points (poles) we need along the curve.
array representing x,y,z of M points that where extrapolated. M should be equal to n_pols
Center of mass of streamline
array representing x,y,z of N points in a track
center of mass of streamline
>>> from dipy.tracking.metrics import center_of_mass
>>> center_of_mass([])
Traceback (most recent call last):
...
ValueError: xyz array cannot be empty
>>> center_of_mass([[1,1,1]])
array([ 1., 1., 1.])
>>> xyz = np.array([[0,0,0],[1,1,1],[2,2,2]])
>>> center_of_mass(xyz)
array([ 1., 1., 1.])
FrenetSerret Space Curve Invariants Calculates the 3 vector and 2 scalar invariants of a space curve defined by vectors r = (x,y,z). If z is omitted (i.e. the array xyz has shape (N,2)), then the curve is only 2D (planar), but the equations are still valid. Similar to http://www.mathworks.com/matlabcentral/fileexchange/11169 In the following equations the prime (\('\)) indicates differentiation with respect to the parameter \(s\) of a parametrised curve \(\mathbf{r}(s)\).  \(\mathbf{T}=\mathbf{r'}/\mathbf{r'}\qquad\) (Tangent vector)}  \(\mathbf{N}=\mathbf{T'}/\mathbf{T'}\qquad\) (Normal vector)  \(\mathbf{B}=\mathbf{T}\times\mathbf{N}\qquad\) (Binormal vector)  \(\kappa=\mathbf{T'}\qquad\) (Curvature)  \(\mathrm{\tau}=\mathbf{B'}\cdot\mathbf{N}\) (Torsion) Parameters ——— xyz : arraylike shape (N,3) array representing x,y,z of N points in a track Returns —— T : array shape (N,3) array representing the tangent of the curve xyz N : array shape (N,3) array representing the normal of the curve xyz B : array shape (N,3) array representing the binormal of the curve xyz k : array shape (N,1) array representing the curvature of the curve xyz t : array shape (N,1) array representing the torsion of the curve xyz Examples ——– Create a helix and calculate its tangent, normal, binormal, curvature and torsion >>> from dipy.tracking import metrics as tm >>> import numpy as np >>> theta = 2*np.pi*np.linspace(0,2,100) >>> x=np.cos(theta) >>> y=np.sin(theta) >>> z=theta/(2*np.pi) >>> xyz=np.vstack((x,y,z)).T >>> T,N,B,k,t=tm.frenet_serret(xyz)
Calculates the mean curvature of a curve
array representing x,y,z of N points in a curve
Mean curvature.
Create a straight line and a semicircle and print their mean curvatures
>>> from dipy.tracking import metrics as tm
>>> import numpy as np
>>> x=np.linspace(0,1,100)
>>> y=0*x
>>> z=0*x
>>> xyz=np.vstack((x,y,z)).T
>>> m=tm.mean_curvature(xyz) #mean curvature straight line
>>> theta=np.pi*np.linspace(0,1,100)
>>> x=np.cos(theta)
>>> y=np.sin(theta)
>>> z=0*x
>>> xyz=np.vstack((x,y,z)).T
>>> _= tm.mean_curvature(xyz) #mean curvature for semicircle
Combine sets of size n from items
items : sequence n : int
ic : iterator
>>> from dipy.tracking.metrics import generate_combinations
>>> ic=generate_combinations(range(3),2)
>>> for i in ic: print(i)
[0, 1]
[0, 2]
[1, 2]
Return longest track or length sorted track indices in bundle
If sort == True, return the indices of the sorted tracks in the bundle, otherwise return the longest track.
of tracks as arrays, shape (N1,3) … (Nm,3)
If False (default) return longest track. If True, return length sorted indices for tracks in bundle
longest track  shape (N,3)  (if sort is False), or indices of length sorted tracks (if sort is True)
>>> from dipy.tracking.metrics import longest_track_bundle
>>> import numpy as np
>>> bundle = [np.array([[0,0,0],[2,2,2]]),np.array([[0,0,0],[4,4,4]])]
>>> longest_track_bundle(bundle)
array([[0, 0, 0],
[4, 4, 4]])
>>> longest_track_bundle(bundle, True)
array([0, 1]...)
If any segment of the track is intersecting with a sphere of specific center and radius return True otherwise False
representing x,y,z of the N points of the track
center of the sphere
radius of the sphere
True if track xyz intersects sphere
>>> from dipy.tracking.metrics import intersect_sphere
>>> line=np.array(([0,0,0],[1,1,1],[2,2,2]))
>>> sph_cent=np.array([1,1,1])
>>> sph_radius = 1
>>> intersect_sphere(line,sph_cent,sph_radius)
True
The ray to sphere intersection method used here is similar with http://local.wasp.uwa.edu.au/~pbourke/geometry/sphereline/ http://local.wasp.uwa.edu.au/~pbourke/geometry/sphereline/source.cpp we just applied it for every segment neglecting the intersections where the intersecting points are not inside the segment
If any point of the track is inside a sphere of a specified center and radius return True otherwise False. Mathematically this can be simply described by \(xc\le r\) where \(x\) a point \(c\) the center of the sphere and \(r\) the radius of the sphere. Parameters ——— xyz : array, shape (N,3) representing x,y,z of the N points of the track center : array, shape (3,) center of the sphere radius : float radius of the sphere Returns —— tf : {True,False} Whether point is inside sphere. Examples ——– >>> from dipy.tracking.metrics import inside_sphere >>> line=np.array(([0,0,0],[1,1,1],[2,2,2])) >>> sph_cent=np.array([1,1,1]) >>> sph_radius = 1 >>> inside_sphere(line,sph_cent,sph_radius) True
If a track intersects with a sphere of a specified center and radius return the points that are inside the sphere otherwise False. Mathematically this can be simply described by \(xc \le r\) where \(x\) a point \(c\) the center of the sphere and \(r\) the radius of the sphere. Parameters ——— xyz : array, shape (N,3) representing x,y,z of the N points of the track center : array, shape (3,) center of the sphere radius : float radius of the sphere Returns —— xyzn : array, shape(M,3) array representing x,y,z of the M points inside the sphere Examples ——– >>> from dipy.tracking.metrics import inside_sphere_points >>> line=np.array(([0,0,0],[1,1,1],[2,2,2])) >>> sph_cent=np.array([1,1,1]) >>> sph_radius = 1 >>> inside_sphere_points(line,sph_cent,sph_radius) array([[1, 1, 1]])
Generate Bsplines as documented in http://www.scipy.org/Cookbook/Interpolation
The scipy.interpolate packages wraps the netlib FITPACK routines (Dierckx) for calculating smoothing splines for various kinds of data and geometries. Although the data is evenly spaced in this example, it need not be so to use this routine.
array representing x,y,z of N points in 3d space
A smoothing condition. The amount of smoothness is determined by satisfying the conditions: sum((w * (y  g))**2,axis=0) <= s where g(x) is the smoothed interpolation of (x,y). The user can use s to control the tradeoff between closeness and smoothness of fit. Larger satisfying the conditions: sum((w * (y  g))**2,axis=0) <= s where g(x) is the smoothed interpolation of (x,y). The user can use s to control the tradeoff between closeness and smoothness of fit. Larger s means more smoothing while smaller values of s indicate less smoothing. Recommended values of s depend on the weights, w. If the weights represent the inverse of the standarddeviation of y, then a: good s value should be found in the range (msqrt(2*m),m+sqrt(2*m)) where m is the number of datapoints in x, y, and w.
Degree of the spline. Cubic splines are recommended. Even values of k should be avoided especially with a small svalue. for the same set of data. If task=1 find the weighted least square spline for a given set of knots, t.
An overestimate of the total number of knots of the spline to help in determining the storage space. None results in value m+2*k. 1 results in m+k+1. Always large enough is nest=m+k+1. Default is 1.
array representing x,y,z of the M points inside the sphere
>>> import numpy as np
>>> t=np.linspace(0,1.75*2*np.pi,100)# make ascending spiral in 3space
>>> x = np.sin(t)
>>> y = np.cos(t)
>>> z = t
>>> x+= np.random.normal(scale=0.1, size=x.shape) # add noise
>>> y+= np.random.normal(scale=0.1, size=y.shape)
>>> z+= np.random.normal(scale=0.1, size=z.shape)
>>> xyz=np.vstack((x,y,z)).T
>>> xyzn=spline(xyz,3,2,1)
>>> len(xyzn) > len(xyz)
True
scipy.interpolate.splprep scipy.interpolate.splev
First point of the track
Track.
First track point.
>>> from dipy.tracking.metrics import startpoint
>>> import numpy as np
>>> theta=np.pi*np.linspace(0,1,100)
>>> x=np.cos(theta)
>>> y=np.sin(theta)
>>> z=0*x
>>> xyz=np.vstack((x,y,z)).T
>>> sp=startpoint(xyz)
>>> sp.any()==xyz[0].any()
True
Track.
First track point.
>>> from dipy.tracking.metrics import endpoint
>>> import numpy as np
>>> theta=np.pi*np.linspace(0,1,100)
>>> x=np.cos(theta)
>>> y=np.sin(theta)
>>> z=0*x
>>> xyz=np.vstack((x,y,z)).T
>>> ep=endpoint(xyz)
>>> ep.any()==xyz[1].any()
True
Select an arbitrary point along distance on the track (curve)
array representing x,y,z of N points in a track
float representing distance travelled from the xyz[0] point of the curve along the curve.
Arbitrary point of line, such that, if the arbitrary point is not a point in xyz, then we take the interpolation between the two nearest xyz points. If xyz is empty, return a ValueError
>>> import numpy as np
>>> from dipy.tracking.metrics import arbitrarypoint, length
>>> theta=np.pi*np.linspace(0,1,100)
>>> x=np.cos(theta)
>>> y=np.sin(theta)
>>> z=0*x
>>> xyz=np.vstack((x,y,z)).T
>>> ap=arbitrarypoint(xyz,length(xyz)/3)
We use PCA to calculate the 3 principal directions for a track
array representing x,y,z of N points in a track
eigenvalues
eigenvectors
>>> import numpy as np
>>> from dipy.tracking.metrics import principal_components
>>> theta=np.pi*np.linspace(0,1,100)
>>> x=np.cos(theta)
>>> y=np.sin(theta)
>>> z=0*x
>>> xyz=np.vstack((x,y,z)).T
>>> va, ve = principal_components(xyz)
>>> np.allclose(va, [0.51010101, 0.09883545, 0])
True
Calculate distance from midpoint of a curve to arbitrary point p
array representing x,y,z of N points in a track
array representing an arbitrary point with x,y,z coordinates in space.
a float number representing Euclidean distance
>>> import numpy as np
>>> from dipy.tracking.metrics import midpoint2point, midpoint
>>> theta=np.pi*np.linspace(0,1,100)
>>> x=np.cos(theta)
>>> y=np.sin(theta)
>>> z=0*x
>>> xyz=np.vstack((x,y,z)).T
>>> dist=midpoint2point(xyz,np.array([0,0,0]))
Apply deformation field to streamlines
List of 2D ndarrays of shape[1]==3
x,y,z displacements stored in volume, shape[1]==3
transform matrix voxmm space to original grid space
transform matrix original grid space to world coordinates
transform matrix voxmm space to new grid space
transform matrix new grid space to world coordinates
List of the transformed 2D ndarrays of shape[1]==3
Apply affine transformation to streamlines
Streamlines object
transformation matrix
If True then change data in place. Be careful changes input streamlines.
Sequence transformed 2D ndarrays of shape[1]==3
Select a random set of streamlines
Object of 2D ndarrays of shape[1]==3
Number of streamlines to select. If there are less streamlines
than select
then select=len(streamlines)
.
Default None.
selected_streamlines : list
The same streamline will not be selected twice.
Select streamlines based on logical relations with several regions of interest (ROIs). For example, select streamlines that pass near ROI1, but only if they do not pass near ROI2.
A list of candidate streamlines for selection
The mapping from voxel coordinates to streamline points. The voxel_to_rasmm matrix, typically from a NIFTI file.
A list of 3D arrays, each with shape (x, y, z) corresponding to the shape of the brain volume, or a 4D array with shape (n_rois, x, y, z). Nonzeros in each volume are considered to be within the region
A list or 1D array of boolean values marking inclusion or exclusion criteria. If a streamline is near any of the inclusion ROIs, it should evaluate to True, unless it is also near any of the exclusion ROIs.
One of {“any”, “all”, “either_end”, “both_end”}, where a streamline is associated with an ROI if:
“any” : any point is within tol from ROI. Default.
“all” : all points are within tol from ROI.
“either_end” : either of the endpoints is within tol from ROI
“both_end” : both end points are within tol from ROI.
Distance (in the units of the streamlines, usually mm). If any coordinate in the streamline is within this distance from the center of any voxel in the ROI, the filtering criterion is set to True for this streamline, otherwise False. Defaults to the distance between the center of each voxel and the corner of the voxel.
The only operation currently possible is “(A or B or …) and not (X or Y or …)”, where A, B are inclusion regions and X, Y are exclusion regions.
Generates the streamlines to be included based on these criteria.
dipy.tracking.utils.near_roi()
dipy.tracking.utils.reduce_rois()
>>> streamlines = [np.array([[0, 0., 0.9],
... [1.9, 0., 0.]]),
... np.array([[0., 0., 0],
... [0, 1., 1.],
... [0, 2., 2.]]),
... np.array([[2, 2, 2],
... [3, 3, 3]])]
>>> mask1 = np.zeros((4, 4, 4), dtype=bool)
>>> mask2 = np.zeros_like(mask1)
>>> mask1[0, 0, 0] = True
>>> mask2[1, 0, 0] = True
>>> selection = select_by_rois(streamlines, np.eye(4), [mask1, mask2],
... [True, True],
... tol=1)
>>> list(selection) # The result is a generator
[array([[ 0. , 0. , 0.9],
[ 1.9, 0. , 0. ]]), array([[ 0., 0., 0.],
[ 0., 1., 1.],
[ 0., 2., 2.]])]
>>> selection = select_by_rois(streamlines, np.eye(4), [mask1, mask2],
... [True, False],
... tol=0.87)
>>> list(selection)
[array([[ 0., 0., 0.],
[ 0., 1., 1.],
[ 0., 2., 2.]])]
>>> selection = select_by_rois(streamlines, np.eye(4), [mask1, mask2],
... [True, True],
... mode="both_end",
... tol=1.0)
>>> list(selection)
[array([[ 0. , 0. , 0.9],
[ 1.9, 0. , 0. ]])]
>>> mask2[0, 2, 2] = True
>>> selection = select_by_rois(streamlines, np.eye(4), [mask1, mask2],
... [True, True],
... mode="both_end",
... tol=1.0)
>>> list(selection)
[array([[ 0. , 0. , 0.9],
[ 1.9, 0. , 0. ]]), array([[ 0., 0., 0.],
[ 0., 1., 1.],
[ 0., 2., 2.]])]
Computes the cluster confidence index (cci), which is an estimation of the support a set of streamlines gives to a particular pathway.
Ex: A single streamline with no others in the dataset following a similar pathway has a low cci. A streamline in a bundle of 100 streamlines that follow similar pathways has a high cci.
See: Jordan et al. 2017 (Based on streamline MDF distance from Garyfallidis et al. 2012)
A sequence of streamlines of length N (# streamlines)
The maximum MDF distance (mm) that will be considered a “supporting” streamline and included in cci calculation
The number of points that are considered for each streamline in the calculation. To save on calculation time, each streamline is subsampled to subsampleN points.
The power to which the MDF distance for each streamline will be raised to determine how much it contributes to the cci. High values of power make the contribution value degrade much faster. E.g., a streamline with 5mm MDF similarity contributes 1/5 to the cci if power is 1, but only contributes 1/5^2 = 1/25 if power is 2.
override means that the cci calculation will still occur even though there are short streamlines in the dataset that may alter expected behaviour.
Returns an array of CCI scores
[Jordan17] Jordan K. Et al., Cluster Confidence Index: A StreamlineWise Pathway Reproducibility Metric for DiffusionWeighted MRI Tractography, Journal of Neuroimaging, vol 28, no 1, 2017.
[Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for tractography simplification, Frontiers in Neuroscience, vol 6, no 175, 2012.
Orient a set of streamlines according to a pair of ROIs
List or generator of 2d arrays of 3d coordinates. Each array contains the xyz coordinates of a single streamline.
The mapping from voxel coordinates to streamline points. The voxel_to_rasmm matrix, typically from a NIFTI file.
Binary masks designating the location of the regions of interest, or coordinate arrays (nby3 array with ROI coordinate in each row).
Whether to make the change inplace in the original list (and return a reference to the list), or to make a copy of the list and return this copy, with the relevant streamlines reoriented. Default: False.
Whether to return a generator as output. Default: False
The same 3D arrays as a list or generator, but reoriented with respect to the ROIs
>>> streamlines = [np.array([[0, 0., 0],
... [1, 0., 0.],
... [2, 0., 0.]]),
... np.array([[2, 0., 0.],
... [1, 0., 0],
... [0, 0, 0.]])]
>>> roi1 = np.zeros((4, 4, 4), dtype=bool)
>>> roi2 = np.zeros_like(roi1)
>>> roi1[0, 0, 0] = True
>>> roi2[1, 0, 0] = True
>>> orient_by_rois(streamlines, np.eye(4), roi1, roi2)
[array([[ 0., 0., 0.],
[ 1., 0., 0.],
[ 2., 0., 0.]]), array([[ 0., 0., 0.],
[ 1., 0., 0.],
[ 2., 0., 0.]])]
Orient a bundle of streamlines to a standard streamline.
The input streamlines to orient.
This provides the standard orientation according to which the streamlines in the provided bundle should be reoriented.
The number of samples to apply to each of the streamlines.
Whether to make the change inplace in the original input (and return a reference), or to make a copy of the list and return this copy, with the relevant streamlines reoriented. Default: False.
Whether to return a generator as output. Default: False
possible to the standard.
Extract values of a scalar/vector along each streamline from a volume.
Scalar (for 3D) and vector (for 4D) values to be extracted. For 4D data, interpolation will be done on the 3 spatial dimensions in each volume.
If array, of shape (n_streamlines, n_nodes, 3) If list, len(n_streamlines) with (n_nodes, 3) array in each element of the list.
The mapping from voxel coordinates to streamline points. The voxel_to_rasmm matrix, typically from a NIFTI file.
coordinate along the length of each streamline.
Values are extracted from the image based on the 3D coordinates of the nodes that comprise the points in the streamline, without any interpolation into segments between the nodes. Using this function with streamlines that have been resampled into a very small number of nodes will result in very few values.
Count the number of unique streamlines that pass through each voxel.
A sequence of streamlines.
The mapping from voxel coordinates to streamline points. The voxel_to_rasmm matrix, typically from a NIFTI file.
The shape of the volume to be returned containing the streamlines counts
The number of streamline points in each voxel of volume.
When the points of the streamlines lie outside of the return volume.
A streamline can pass through a voxel even if one of the points of the streamline does not lie in the voxel. For example a step from [0,0,0] to [0,0,2] passes through [0,0,1]. Consider subsegmenting the streamlines when the edges of the voxels are smaller than the steps of the streamlines.
Count the streamlines that start and end at each label pair.
A sequence of streamlines.
The mapping from voxel coordinates to streamline coordinates. The voxel_to_rasmm matrix, typically from a NIFTI file.
An image volume with an integer data type, where the intensities in the volume map to anatomical structures.
Whether to analyze the entire streamline, as opposed to just the endpoints. Allowing this will increase calculation time and mapping size, especially if mapping_as_streamlines is True. False by default.
Symmetric means we don’t distinguish between start and end points. If
symmetric is True, matrix[i, j] == matrix[j, i]
.
If True, a mapping is returned which maps matrix indices to streamlines.
If True voxel indices map to lists of streamline objects. Otherwise voxel indices map to lists of integers.
The number of connection between each pair of regions in label_volume.
mapping[i, j]
returns all the streamlines that connect region i
to region j. If symmetric is True mapping will only have one key
for each start end pair such that if i < j
mapping will have key
(i, j)
but not key (j, i)
.
Reduce an array of labels to the integers from 0 to n with smallest possible n.
>>> labels = np.array([[1, 3, 9],
... [1, 3, 8],
... [1, 3, 7]])
>>> new_labels, lookup = reduce_labels(labels)
>>> lookup
array([1, 3, 7, 8, 9])
>>> new_labels
array([[0, 1, 4],
[0, 1, 3],
[0, 1, 2]]...)
>>> (lookup[new_labels] == labels).all()
True
Split the segments of the streamlines into small segments.
Replaces each segment of each of the streamlines with the smallest possible number of equally sized smaller segments such that no segment is longer than max_segment_length. Among other things, this can useful for getting streamline counts on a grid that is smaller than the length of the streamline segments.
The streamlines to be subsegmented.
The longest allowable segment length.
A set of streamlines.
Segments of 0 length are removed. If unchanged
>>> streamlines = [np.array([[0,0,0],[2,0,0],[5,0,0]])]
>>> list(subsegment(streamlines, 3.))
[array([[ 0., 0., 0.],
[ 2., 0., 0.],
[ 5., 0., 0.]])]
>>> list(subsegment(streamlines, 1))
[array([[ 0., 0., 0.],
[ 1., 0., 0.],
[ 2., 0., 0.],
[ 3., 0., 0.],
[ 4., 0., 0.],
[ 5., 0., 0.]])]
>>> list(subsegment(streamlines, 1.6))
[array([[ 0. , 0. , 0. ],
[ 1. , 0. , 0. ],
[ 2. , 0. , 0. ],
[ 3.5, 0. , 0. ],
[ 5. , 0. , 0. ]])]
Create seeds for fiber tracking from a binary mask.
Seeds points are placed evenly distributed in all voxels of mask
which
are True
.
A binary array specifying where to place the seeds for fiber tracking.
The mapping between voxel indices and the point space for seeds.
The voxel_to_rasmm matrix, typically from a NIFTI file.
A seed point at the center the voxel [i, j, k]
will be represented as [x, y, z]
where
[x, y, z, 1] == np.dot(affine, [i, j, k , 1])
.
Specifies the number of seeds to place along each dimension. A
density
of 2 is the same as [2, 2, 2]
and will result in a
total of 8 seeds per voxel.
random_seeds_from_mask
When mask
is not a threedimensional array
>>> mask = np.zeros((3,3,3), 'bool')
>>> mask[0,0,0] = 1
>>> seeds_from_mask(mask, np.eye(4), [1,1,1])
array([[ 0., 0., 0.]])
Create randomly placed seeds for fiber tracking from a binary mask.
Seeds points are placed randomly distributed in voxels of mask
which are True
.
If seed_count_per_voxel
is True
, this function is
similar to seeds_from_mask()
, with the difference that instead of
evenly distributing the seeds, it randomly places the seeds within the
voxels specified by the mask
.
A binary array specifying where to place the seeds for fiber tracking.
The mapping between voxel indices and the point space for seeds.
The voxel_to_rasmm matrix, typically from a NIFTI file.
A seed point at the center the voxel [i, j, k]
will be represented as [x, y, z]
where
[x, y, z, 1] == np.dot(affine, [i, j, k , 1])
.
The number of seeds to generate. If seed_count_per_voxel
is True,
specifies the number of seeds to place in each voxel. Otherwise,
specifies the total number of seeds to place in the mask.
If True, seeds_count is per voxel, else seeds_count is the total number of seeds.
The seed for the random seed generator (numpy.random.seed).
seeds_from_mask
When mask
is not a threedimensional array
>>> mask = np.zeros((3,3,3), 'bool')
>>> mask[0,0,0] = 1
>>> random_seeds_from_mask(mask, np.eye(4), seeds_count=1,
... seed_count_per_voxel=True, random_seed=1)
array([[0.0640051 , 0.47407377, 0.04966248]])
>>> random_seeds_from_mask(mask, np.eye(4), seeds_count=6,
... seed_count_per_voxel=True, random_seed=1)
array([[0.0640051 , 0.47407377, 0.04966248],
[ 0.0507979 , 0.20814782, 0.20909526],
[ 0.46702984, 0.04723225, 0.47268436],
[0.27800683, 0.37073231, 0.29328084],
[ 0.39286015, 0.16802019, 0.32122912],
[0.42369171, 0.27991879, 0.06159077]])
>>> mask[0,1,2] = 1
>>> random_seeds_from_mask(mask, np.eye(4),
... seeds_count=2, seed_count_per_voxel=True, random_seed=1)
array([[0.0640051 , 0.47407377, 0.04966248],
[0.27800683, 1.37073231, 1.70671916],
[ 0.0507979 , 0.20814782, 0.20909526],
[0.48962585, 1.00187459, 1.99577329]])
Filter streamlines based on whether or not they pass through an ROI.
A sequence of streamlines. Each streamline should be a (N, 3) array, where N is the length of the streamline.
The mapping between voxel indices and the point space for seeds. The voxel_to_rasmm matrix, typically from a NIFTI file.
A mask used as a target. Nonzero values are considered to be within the target region.
If True, streamlines passing through target_mask are kept. If False, the streamlines not passing through target_mask are kept.
A sequence of streamlines that pass through target_mask.
When the points of the streamlines lie outside of the target_mask.
density_map
Filter streamlines based on whether or not they pass through a ROI, using a linebased algorithm. Mostly used as a replacement of target for compressed streamlines.
This function never returns singlepoint streamlines, whatever the value of include.
A sequence of streamlines. Each streamline should be a (N, 3) array, where N is the length of the streamline.
The mapping between voxel indices and the point space for seeds. The voxel_to_rasmm matrix, typically from a NIFTI file.
A mask used as a target. Nonzero values are considered to be within the target region.
If True, streamlines passing through target_mask are kept. If False, the streamlines not passing through target_mask are kept.
A sequence of streamlines that pass through target_mask.
digital plotter”, IBM Systems Journal, vol 4, no. 1, 1965.
streamlines with variable step sizes, ISMRM 2015.
dipy.tracking.utils.density_map dipy.tracking.streamline.compress_streamlines
Is a streamline near an ROI.
Implements the inner loops of the near_roi()
function.
A single streamline
ROI coordinates transformed to the streamline coordinate frame.
Distance (in the units of the streamlines, usually mm). If any coordinate in the streamline is within this distance from the center of any voxel in the ROI, this function returns True.
One of {“any”, “all”, “either_end”, “both_end”}, where return True if:
“any” : any point is within tol from ROI.
“all” : all points are within tol from ROI.
“either_end” : either of the endpoints is within tol from ROI
“both_end” : both end points are within tol from ROI.
out : boolean
Provide filtering criteria for a set of streamlines based on whether they fall within a tolerance distance from an ROI.
A sequence of streamlines. Each streamline should be a (N, 3) array, where N is the length of the streamline.
The mapping between voxel indices and the point space for seeds. The voxel_to_rasmm matrix, typically from a NIFTI file.
A mask used as a target. Nonzero values are considered to be within the target region.
Distance (in the units of the streamlines, usually mm). If any coordinate in the streamline is within this distance from the center of any voxel in the ROI, the filtering criterion is set to True for this streamline, otherwise False. Defaults to the distance between the center of each voxel and the corner of the voxel.
One of {“any”, “all”, “either_end”, “both_end”}, where return True if:
“any” : any point is within tol from ROI. Default.
“all” : all points are within tol from ROI.
“either_end” : either of the endpoints is within tol from ROI
“both_end” : both end points are within tol from ROI.
1D array of boolean dtype, shape (len(streamlines), )
This contains True for indices corresponding to each streamline that passes within a tolerance distance from the target ROI, False otherwise.
Find the unique rows in an array.
The array for which the unique rows should be found
This determines the intermediate representation used for the values. Should at least preserve the values of the input array.
Array with the unique rows of the original array.
Apply a linear transformation, given by affine, to streamlines.
Either streamlines (list, ArraySequence) or a tuple with streamlines and seeds together
The mapping between voxel indices and the point space for seeds. The voxel_to_rasmm matrix, typically from a NIFTI file.
If set, seeds associated to streamlines will be also moved and returned
A generator for the sequence of transformed streamlines. If save_seeds is True, also return a generator for the transformed seeds.
Reduce multiple ROIs to one inclusion and one exclusion ROI.
A list of 3D arrays, each with shape (x, y, z) corresponding to the shape of the brain volume, or a 4D array with shape (n_rois, x, y, z). Nonzeros in each volume are considered to be within the region.
A list or 1D array of boolean marking inclusion or exclusion criteria.
An array marking the inclusion mask.
An array marking the exclusion mask
The include_roi and exclude_roi can be used to perform the operation: “(A or B or …) and not (X or Y or …)”, where A, B are inclusion regions and X, Y are exclusion regions.
Compute the shortest path, along any streamline, between aoi and each voxel.
A sequence of streamlines, path length is given in mm along the curve of the streamline.
A mask (binary array) of voxels from which to start computing distance.
The mapping between voxel indices and the point space for seeds. The voxel_to_rasmm matrix, typically from a NIFTI file.
The value of voxel in the path length map that are not connected to the aoi.
Same shape as aoi. The minimum distance between every point and aoi along the path of a streamline.
Get the maximum deviation angle from the minimum radius curvature.
Minimum radius of curvature in mm.
The tracking step size in mm.
The maximum deviation angle in radian, given the radius curvature and the step size.
For more information: https://onlinelibrary.wiley.com/doi/full/10.1002/ima.22005
Get minimum radius of curvature from a deviation angle.
The maximum deviation angle in radian. theta should be between [0  pi/2] otherwise default will be pi/2.
The tracking step size in mm.
Minimum radius of curvature in mm, given the maximum deviation angle theta and the step size.
More information: https://onlinelibrary.wiley.com/doi/full/10.1002/ima.22005