tracking
tracking._utils
tracking.benchmarks
tracking.benchmarks.bench_streamline
tracking.direction_getter
tracking.distances
tracking.fbcmeasures
tracking.learning
tracking.life
tracking.local_tracking
tracking.localtrack
tracking.mesh
tracking.metrics
tracking.propspeed
tracking.stopping_criterion
tracking.streamline
tracking.streamlinespeed
tracking.utils
tracking.vox2track
Streamlines
Streamlines
DirectionGetter
EnhancementKernel
FBCMeasures
KDTree
interp1d
FiberFit
FiberModel
LifeSignalMaker
ReconstFit
ReconstModel
AnatomicalStoppingCriterion
Iterable
LocalTracking
ParticleFilteringTracking
StreamlineStatus
ActStoppingCriterion
AnatomicalStoppingCriterion
BinaryStoppingCriterion
CmcStoppingCriterion
StoppingCriterion
StreamlineStatus
ThresholdStoppingCriterion
Streamlines
Streamlines
OrderedDict
combinations
defaultdict
groupby
tracking
Tracking objects
alias of 


Run benchmarks for module using nose. 

Run tests for module using nose. 
tracking._utils
This is a helper module for dipy.tracking.utils.

Issue a warning, or maybe ignore it or raise an exception. 
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
alias of 


Raises an AssertionError if two objects are not equal up to desired precision. 

Raises an AssertionError if two array_like objects are not equal. 
Compress streamlines by linearization as in [Presseau15]. 


Python version of the FiberCompression found on https://github.com/scilus/FiberCompression. 



Provide full paths to example or test datasets. 
Euclidean length of streamlines 




Load the stateful tractogram from any format (trk, tck, vtk, fib, dpy) 

Return elapsed time for executing code in the namespace of the caller. 
Change the number of points of streamlines 




tracking.distances
Optimized track distances, similarities and distanch clustering algorithms
Fast and simple trajectory approximation algorithm by Eleftherios and Ian 

Implementation of Lee et al Approximate Trajectory Partitioning Algorithm 

Calculate distances between list of tracks A and list of tracks B 

Calculate distances between list of tracks A and list of tracks B 

Extract divergence vectors and points of intersection between planes normal to the reference fiber and other tracks 

Intersect Segment S(t) = sa +t(sbsa), 0 <=t<= 1 against cylinder specified by p,q and r 

Reassign tracks to existing clusters by merging clusters that their representative tracks are not very distant i.e. 

Generate a first pass clustering using 3 points on the tracks only. 

Calculates angle distance metric for the distance between two line segments 

Calculates perpendicular distance metric for the distance between two line segments 

Efficient tractography clustering 

Does a first pass clustering 

Min/Max/Mean Average Minimum Distance between tracks xyz1 and xyz2 

Find the minimum distance between two curves xyz1, xyz2 

Find the most similar track in a bundle using distances calculated from Zhang et. 

Euclidean (L2) norm of length 3 vector 

Return normalized 3D vector 

Calculate the squared distance from a point c to a finite line segment ab. 

Check if square distance of track from point is smaller than threshold 

Calculate the euclidean distance between two 3pt tracks 

Check if a track is intersecting a region of interest 


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

Methods 


kdtree for quick nearestneighbor lookup 

Interpolate a 1D function. 
Compute the relative fiber to bundle coherence (RFBC) 

Return number of cpus as determined by omp_get_num_procs. 

Determine the effective number of threads to be used for OpenMP calls 


provide triangulated spheres 

Return the logarithm of x to the given base. 
Return the lowest cumulative sum for the score of a streamline segment 


An Ndimensional iterator object to index arrays. 

Return the square root of x. 
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 fit of the LiFE model to diffusion data 

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

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

Abstract class which holds the fit result of ReconstModel 

Abstract class for signal reconstruction models 

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] 

Return the gradient of an Ndimensional array. 

Calculate the gradients of the streamline along the spatial dimension 

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

The tensors generated by this fiber. 

Apply affine transformation to streamlines 

This (quickly) finds the unique rows in an array 

Maps voxels to streamlines and streamlines to voxels, for setting up the LiFE equations matrix 
tracking.local_tracking
Abstract class that takes as input included and excluded tissue maps. 





An enumeration. 

Tracks one direction from a seed. 

Tracks one direction from a seed using the particle filtering algorithm. 
tracking.localtrack
Tracks one direction from a seed. 

Tracks one direction from a seed using the particle filtering algorithm. 


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

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

Size of track in bytes. 

Center of mass of streamline 

Return decorator function function for deprecation warning / error. 

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



FrenetSerret Space Curve Invariants 

Combine sets of size n from items 

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. 

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

Euclidean length of track line 

Return longest track or length sorted track indices in bundle 

magnitude of vector 

Calculates the mean curvature of a curve 

Calculates the mean orientation of a curve 

Midpoint of track 

Calculate distance from midpoint of a curve to arbitrary point p 

We use PCA to calculate the 3 principal directions for a track 
Change the number of points of streamlines 


Evaluate a Bspline or its derivatives. 

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

Find the Bspline representation of an ND curve. 

First point of the track 

Total turning angle projected. 
tracking.propspeed
Track propagation performance functions


Find offset in an Ndimensional ndarray using strides 
tracking.stopping_criterion
AnatomicallyConstrained Tractography (ACT) stopping criterion from [1]. 

Abstract class that takes as input included and excluded tissue maps. 

cdef: 

Continuous map criterion (CMC) stopping criterion from [1]. 

Methods 

An enumeration. 

# Declarations from stopping_criterion.pxd bellow cdef: double threshold, interp_out_double[1] double[:] interp_out_view = interp_out_view double[:, :, :] metric_map 
tracking.streamline
alias of 


Apply affine matrix aff to points pts 
Calculate distances between list of tracks A and list of tracks B 


Compute distance between each pair of the two collections of inputs. 

Move streamlines to the origin 

Computes the cluster confidence index (cci), which is an estimation of the support a set of streamlines gives to a particular pathway. 
Compress streamlines by linearization as in [Presseau15]. 


Deep copy operation on arbitrary Python objects. 

Apply deformation field to streamlines 

Calculate the maximal distance from the center to a corner of a voxel, given an affine 
Trilinear interpolation of a 3D scalar image 

Trilinear interpolation of a 3D vector field 

Euclidean length of streamlines 




Orient a set of streamlines according to a pair of ROIs 

Orient a bundle of streamlines to a standard streamline. 

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. 

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

Select a random set of streamlines 
Change the number of points of streamlines 


Apply affine transformation to streamlines 

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

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

Issue a warning, or maybe ignore it or raise an exception. 
tracking.streamlinespeed
alias of 

Compress streamlines by linearization as in [Presseau15]. 

Euclidean length of streamlines 

Change the number of points of streamlines 
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, lets 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.]
Dictionary that remembers insertion order 

combinations(iterable, r) –> combinations object 

defaultdict(default_factory[, …]) –> dict with default factory 


keys and groups from the iterable. 

Apply affine matrix aff to points pts 

Convert the input to an array. 

Compute distance between each pair of the two collections of inputs. 

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

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

Calculate the maximal distance from the center to a corner of a voxel, given an affine 

Return a new array of given shape and type, without initializing entries. 

Calculate the lengths of many streamlines in a bundle. 

Performs unbuffered in place operation on operand ‘a’ for elements specified by ‘indices’. 

Like bincount, but for ndindices. 

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

Computes the shortest path, along any streamline, between aoi and each voxel. 

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

Converts a tuple of index arrays into an array of flat indices, applying boundary modes to the multiindex. 

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

Reduce multiple ROIs to one inclusion and one exclusion ROI. 

Create seeds for fiber tracking from a binary mask. 

Is a streamline near an ROI. 

Splits the segments of the streamlines into small segments. 

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

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

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

This (quickly) finds the unique rows in an array 

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

Decorator factory to apply update_wrapper() to a wrapper function 
tracking.vox2track
This module contains the parts of dipy.tracking.utils that need to be implemented in cython.
Creates a mapping from voxel indices to streamlines. 

Counts of points in tracks that pass through voxels in volume 
dipy.tracking.
bench
(label='fast', verbose=1, extra_argv=None)Run benchmarks for module using nose.
Identifies the benchmarks to run. This can be a string to pass to the nosetests executable with the ‘A’ option, or one of several special values. Special values are:
‘fast’  the default  which corresponds to the nosetests A
option of ‘not slow’.
‘full’  fast (as above) and slow benchmarks as in the ‘no A’ option to nosetests  this is the same as ‘’.
None or ‘’  run all tests.
attribute_identifier  string passed directly to nosetests as ‘A’.
Verbosity value for benchmark outputs, in the range 110. Default is 1.
List with any extra arguments to pass to nosetests.
Returns True if running the benchmarks works, False if an error occurred.
Notes
Benchmarks are like tests, but have names starting with “bench” instead of “test”, and can be found under the “benchmarks” subdirectory of the module.
Each NumPy module exposes bench in its namespace to run all benchmarks for it.
Examples
>>> success = np.lib.bench()
Running benchmarks for numpy.lib
...
using 562341 items:
unique:
0.11
unique1d:
0.11
ratio: 1.0
nUnique: 56230 == 56230
...
OK
>>> success
True
dipy.tracking.
test
(label='fast', verbose=1, extra_argv=None, doctests=False, coverage=False, raise_warnings=None, timer=False)Run tests for module using nose.
Identifies the tests to run. This can be a string to pass to the nosetests executable with the ‘A’ option, or one of several special values. Special values are:
‘fast’  the default  which corresponds to the nosetests A
option of ‘not slow’.
‘full’  fast (as above) and slow tests as in the ‘no A’ option to nosetests  this is the same as ‘’.
None or ‘’  run all tests.
attribute_identifier  string passed directly to nosetests as ‘A’.
Verbosity value for test outputs, in the range 110. Default is 1.
List with any extra arguments to pass to nosetests.
If True, run doctests in module. Default is False.
If True, report coverage of NumPy code. Default is False. (This requires the coverage module).
This specifies which warnings to configure as ‘raise’ instead of being shown once during the test execution. Valid strings are:
“develop” : equals (Warning,)
“release” : equals ()
, do not raise on any warnings.
Timing of individual tests with nosetimer
(which needs to be
installed). If True, time tests and report on all of them.
If an integer (say N
), report timing results for N
slowest
tests.
Returns the result of running the tests as a
nose.result.TextTestResult
object.
Notes
Each NumPy module exposes test in its namespace to run all tests for it. For example, to run all tests for numpy.lib:
>>> np.lib.test()
Examples
>>> result = np.lib.test()
Running unit tests for numpy.lib
...
Ran 976 tests in 3.933s
OK
>>> result.errors
[]
>>> result.knownfail
[]
dipy.tracking.benchmarks.bench_streamline.
assert_array_almost_equal
(x, y, decimal=6, err_msg='', verbose=True)Raises an AssertionError if two objects are not equal up to desired precision.
Note
It is recommended to use one of assert_allclose, assert_array_almost_equal_nulp or assert_array_max_ulp instead of this function for more consistent floating point comparisons.
The test verifies identical shapes and that the elements of actual
and
desired
satisfy.
abs(desiredactual) < 1.5 * 10**(decimal)
That is a looser test than originally documented, but agrees with what the actual implementation did up to rounding vagaries. An exception is raised at shape mismatch or conflicting values. In contrast to the standard usage in numpy, NaNs are compared like numbers, no assertion is raised if both objects have NaNs in the same positions.
The actual object to check.
The desired, expected object.
Desired precision, default is 6.
The error message to be printed in case of failure.
If True, the conflicting values are appended to the error message.
If actual and desired are not equal up to specified precision.
See also
assert_allclose
Compare two array_like objects for equality with desired relative and/or absolute precision.
assert_array_almost_equal_nulp
, assert_array_max_ulp
, assert_equal
Examples
the first assert does not raise an exception
>>> np.testing.assert_array_almost_equal([1.0,2.333,np.nan],
... [1.0,2.333,np.nan])
>>> np.testing.assert_array_almost_equal([1.0,2.33333,np.nan],
... [1.0,2.33339,np.nan], decimal=5)
Traceback (most recent call last):
...
AssertionError:
Arrays are not almost equal to 5 decimals
Mismatched elements: 1 / 3 (33.3%)
Max absolute difference: 6.e05
Max relative difference: 2.57136612e05
x: array([1. , 2.33333, nan])
y: array([1. , 2.33339, nan])
>>> np.testing.assert_array_almost_equal([1.0,2.33333,np.nan],
... [1.0,2.33333, 5], decimal=5)
Traceback (most recent call last):
...
AssertionError:
Arrays are not almost equal to 5 decimals
x and y nan location mismatch:
x: array([1. , 2.33333, nan])
y: array([1. , 2.33333, 5. ])
dipy.tracking.benchmarks.bench_streamline.
assert_array_equal
(x, y, err_msg='', verbose=True)Raises an AssertionError if two array_like objects are not equal.
Given two array_like objects, check that the shape is equal and all elements of these objects are equal (but see the Notes for the special handling of a scalar). An exception is raised at shape mismatch or conflicting values. In contrast to the standard usage in numpy, NaNs are compared like numbers, no assertion is raised if both objects have NaNs in the same positions.
The usual caution for verifying equality with floating point numbers is advised.
The actual object to check.
The desired, expected object.
The error message to be printed in case of failure.
If True, the conflicting values are appended to the error message.
If actual and desired objects are not equal.
See also
assert_allclose
Compare two array_like objects for equality with desired relative and/or absolute precision.
assert_array_almost_equal_nulp
, assert_array_max_ulp
, assert_equal
Notes
When one of x and y is a scalar and the other is array_like, the function checks that each element of the array_like object is equal to the scalar.
Examples
The first assert does not raise an exception:
>>> np.testing.assert_array_equal([1.0,2.33333,np.nan],
... [np.exp(0),2.33333, np.nan])
Assert fails with numerical imprecision with floats:
>>> np.testing.assert_array_equal([1.0,np.pi,np.nan],
... [1, np.sqrt(np.pi)**2, np.nan])
Traceback (most recent call last):
...
AssertionError:
Arrays are not equal
Mismatched elements: 1 / 3 (33.3%)
Max absolute difference: 4.4408921e16
Max relative difference: 1.41357986e16
x: array([1. , 3.141593, nan])
y: array([1. , 3.141593, nan])
Use assert_allclose or one of the nulp (number of floating point values) functions for these cases instead:
>>> np.testing.assert_allclose([1.0,np.pi,np.nan],
... [1, np.sqrt(np.pi)**2, np.nan],
... rtol=1e10, atol=0)
As mentioned in the Notes section, assert_array_equal has special handling for scalars. Here the test checks that each value in x is 3:
>>> x = np.full((2, 5), fill_value=3)
>>> np.testing.assert_array_equal(x, 3)
dipy.tracking.benchmarks.bench_streamline.
compress_streamlines
()Compress streamlines by linearization as in [Presseau15].
The compression consists in merging consecutive segments that are nearly collinear. The merging is achieved by removing the point the two segments have in common.
The linearization process [Presseau15] ensures that every point being removed are within a certain margin (in mm) of the resulting streamline. Recommendations for setting this margin can be found in [Presseau15] (in which they called it tolerance error).
The compression also ensures that two consecutive points won’t be too far from each other (precisely less or equal than `max_segment_length`mm). This is a tradeoff to speed up the linearization process [Rheault15]. A low value will result in a faster linearization but low compression, whereas a high value will result in a slower linearization but high compression.
Array representing x,y,z of N points in a streamline.
Tolerance error in mm (default: 0.01). A rule of thumb is to set it to 0.01mm for deterministic streamlines and 0.1mm for probabilitic streamlines.
Maximum length in mm of any given segment produced by the compression. The default is 10mm. (In [Presseau15], they used a value of np.inf).
Results of the linearization process.
Notes
Be aware that compressed streamlines have variable step sizes. One needs to be careful when computing streamlinesbased metrics [Houde15].
References
Presseau C. et al., A new compression format for fiber tracking datasets, NeuroImage, no 109, 7383, 2015.
Rheault F. et al., Real Time Interaction with Millions of Streamlines, ISMRM, 2015.
Houde J.C. et al. How to Avoid Biased StreamlinesBased Metrics for Streamlines with Variable Step Sizes, ISMRM, 2015.
Examples
>>> from dipy.tracking.streamline import compress_streamlines
>>> import numpy as np
>>> # One streamline: a wiggling line
>>> rng = np.random.RandomState(42)
>>> streamline = np.linspace(0, 10, 100*3).reshape((100, 3))
>>> streamline += 0.2 * rng.rand(100, 3)
>>> c_streamline = compress_streamlines(streamline, tol_error=0.2)
>>> len(streamline)
100
>>> len(c_streamline)
10
>>> # Multiple streamlines
>>> streamlines = [streamline, streamline[::2]]
>>> c_streamlines = compress_streamlines(streamlines, tol_error=0.2)
>>> [len(s) for s in streamlines]
[100, 50]
>>> [len(s) for s in c_streamlines]
[10, 7]
dipy.tracking.benchmarks.bench_streamline.
compress_streamlines_python
(streamline, tol_error=0.01, max_segment_length=10)Python version of the FiberCompression found on https://github.com/scilus/FiberCompression.
dipy.tracking.benchmarks.bench_streamline.
get_fnames
(name='small_64D')Provide full paths to example or test datasets.
the filename/s of which dataset to return, one of:  ‘small_64D’ small region of interest nifti,bvecs,bvals 64 directions  ‘small_101D’ small region of interest nifti, bvecs, bvals
101 directions
‘aniso_vox’ volume with anisotropic voxel size as Nifti
‘fornix’ 300 tracks in Trackvis format (from Pittsburgh Brain Competition)
‘gqi_vectors’ the scanner wave vectors needed for a GQI acquisitions of 101 directions tested on Siemens 3T Trio
‘small_25’ small ROI (10x8x2) DTI data (b value 2000, 25 directions)
‘test_piesno’ slice of N=8, K=14 diffusion data
‘reg_c’ small 2D image used for validating registration
‘reg_o’ small 2D image used for validation registration
‘cb_2’ two vectorized cingulum bundles
filenames for dataset
Examples
>>> import numpy as np
>>> from dipy.io.image import load_nifti
>>> from dipy.data import get_fnames
>>> fimg, fbvals, fbvecs = get_fnames('small_101D')
>>> bvals=np.loadtxt(fbvals)
>>> bvecs=np.loadtxt(fbvecs).T
>>> data, affine = load_nifti(fimg)
>>> data.shape == (6, 10, 10, 102)
True
>>> bvals.shape == (102,)
True
>>> bvecs.shape == (102, 3)
True
dipy.tracking.benchmarks.bench_streamline.
length
()Euclidean length of streamlines
Length is in mm only if streamlines are expressed in world coordinates.
dipy.tracking.Streamlines
If ndarray, must have shape (N,3) where N is the number of points
of the streamline.
If list, each item must be ndarray shape (Ni,3) where Ni is the number
of points of streamline i.
If dipy.tracking.Streamlines
, its common_shape must be 3.
If there is only one streamline, a scalar representing the length of the streamline. If there are several streamlines, ndarray containing the length of every streamline.
Examples
>>> from dipy.tracking.streamline import length
>>> import numpy as np
>>> streamline = np.array([[1, 1, 1], [2, 3, 4], [0, 0, 0]])
>>> expected_length = np.sqrt([1+2**2+3**2, 2**2+3**2+4**2]).sum()
>>> length(streamline) == expected_length
True
>>> streamlines = [streamline, np.vstack([streamline, streamline[::1]])]
>>> expected_lengths = [expected_length, 2*expected_length]
>>> lengths = [length(streamlines[0]), length(streamlines[1])]
>>> np.allclose(lengths, expected_lengths)
True
>>> length([])
0.0
>>> length(np.array([[1, 2, 3]]))
0.0
dipy.tracking.benchmarks.bench_streamline.
load_tractogram
(filename, reference, to_space=<Space.RASMM: 'rasmm'>, to_origin=<Origin.NIFTI: 'center'>, bbox_valid_check=True, trk_header_check=True)Load the stateful tractogram from any format (trk, tck, vtk, fib, dpy)
Filename with valid extension
trk.header (dict), or ‘same’ if the input is a trk file. Reference that provides the spatial attribute. Typically a niftirelated object from the native diffusion used for streamlines generation
Space to which the streamlines will be transformed after loading
NIFTI standard, default (center of the voxel) TRACKVIS standard (corner of the voxel)
Verification for negative voxel coordinates or values above the volume dimensions. Default is True, to enforce valid file.
Verification that the reference has the same header as the spatial attributes as the input tractogram when a Trk is loaded
The tractogram to load (must have been saved properly)
dipy.tracking.benchmarks.bench_streamline.
measure
(code_str, times=1, label=None)Return elapsed time for executing code in the namespace of the caller.
The supplied code string is compiled with the Python builtin compile
.
The precision of the timing is 10 milliseconds. If the code will execute
fast on this timescale, it can be executed many times to get reasonable
timing accuracy.
The code to be timed.
The number of times the code is executed. Default is 1. The code is only compiled once.
A label to identify code_str with. This is passed into compile
as the second argument (for runtime error messages).
Total elapsed time in seconds for executing code_str times times.
Examples
>>> times = 10
>>> etime = np.testing.measure('for i in range(1000): np.sqrt(i**2)', times=times)
>>> print("Time for a single execution : ", etime / times, "s")
Time for a single execution : 0.005 s
dipy.tracking.benchmarks.bench_streamline.
set_number_of_points
()(either by downsampling or upsampling)
Change the number of points of streamlines in order to obtain nb_points1 segments of equal length. Points of streamlines will be modified along the curve.
dipy.tracking.Streamlines
If ndarray, must have shape (N,3) where N is the number of points
of the streamline.
If list, each item must be ndarray shape (Ni,3) where Ni is the number
of points of streamline i.
If dipy.tracking.Streamlines
, its common_shape must be 3.
integer representing number of points wanted along the curve.
dipy.tracking.Streamlines
Results of the downsampling or upsampling process.
Examples
>>> from dipy.tracking.streamline import set_number_of_points
>>> import numpy as np
One streamline, a semicircle:
>>> theta = np.pi*np.linspace(0, 1, 100)
>>> x = np.cos(theta)
>>> y = np.sin(theta)
>>> z = 0 * x
>>> streamline = np.vstack((x, y, z)).T
>>> modified_streamline = set_number_of_points(streamline, 3)
>>> len(modified_streamline)
3
Multiple streamlines:
>>> streamlines = [streamline, streamline[::2]]
>>> new_streamlines = set_number_of_points(streamlines, 10)
>>> [len(s) for s in streamlines]
[100, 50]
>>> [len(s) for s in new_streamlines]
[10, 10]
DirectionGetter
dipy.tracking.direction_getter.
DirectionGetter
Bases: object
Methods
get_direction 

initial_direction 
dipy.tracking.distances.
approx_polygon_track
()Fast and simple trajectory approximation algorithm by Eleftherios and Ian
It will reduce the number of points of the track by keeping intact the start and endpoints of the track and trying to remove as many points as possible without distorting much the shape of the track
initial trajectory
smoothing parameter (<0.392 smoother, >0.392 rougher) if the trajectory was a smooth circle then with alpha =0.393 ~=pi/8. the circle would be approximated with an decahexagon if alpha = 0.7853 ~=pi/4. with an octagon.
Notes
Assuming that a good approximation for a circle is an octagon then that means that the points of the octagon will have angle alpha = 2*pi/8 = pi/4 . We calculate the angle between every two neighbour segments of a trajectory and if the angle is higher than pi/4 we choose that point as a characteristic point otherwise we move at the next point.
Examples
Approximating a helix:
>>> t=np.linspace(0,1.75*2*np.pi,100)
>>> x = np.sin(t)
>>> y = np.cos(t)
>>> z = t
>>> xyz=np.vstack((x,y,z)).T
>>> xyza = approx_polygon_track(xyz)
>>> len(xyza) < len(xyz)
True
dipy.tracking.distances.
approximate_mdl_trajectory
()Implementation of Lee et al Approximate Trajectory Partitioning Algorithm
This is base on the minimum description length principle
initial trajectory
smoothing parameter (>1 smoother, <1 rougher)
dipy.tracking.distances.
bundles_distances_mam
()Calculate distances between list of tracks A and list of tracks B
of tracks as arrays, shape (N1,3) .. (Nm,3)
of tracks as arrays, shape (N1,3) .. (Nm,3)
‘avg’, ‘min’, ‘max’
distances between tracksA and tracksB according to metric
dipy.tracking.distances.
bundles_distances_mdf
()Calculate distances between list of tracks A and list of tracks B
All tracks need to have the same number of points
of tracks as arrays, [(N,3) .. (N,3)]
of tracks as arrays, [(N,3) .. (N,3)]
distances between tracksA and tracksB according to metric
dipy.tracking.distances.
cut_plane
()Extract divergence vectors and points of intersection between planes normal to the reference fiber and other tracks
of tracks as arrays, shape (N1,3) .. (Nm,3)
reference track
list of points and rcds (radial coefficient of divergence)
Notes
The orthogonality relationship
np.inner(hits[p][q][0:3]ref[p+1],ref[p+2]ref[r][p+1])
will hold
throughout for every point q in the hits plane at point (p+1) on the
reference track.
Examples
>>> refx = np.array([[0,0,0],[1,0,0],[2,0,0],[3,0,0]],dtype='float32')
>>> bundlex = [np.array([[0.5,1,0],[1.5,2,0],[2.5,3,0]],dtype='float32')]
>>> res = cut_plane(bundlex,refx)
>>> len(res)
2
>>> print(res[0])
[[ 1. 1.5 0. 0.70710683 0. ]]
>>> print(res[1])
[[ 2. 2.5 0. 0.70710677 0. ]]
dipy.tracking.distances.
intersect_segment_cylinder
()Intersect Segment S(t) = sa +t(sbsa), 0 <=t<= 1 against cylinder specified by p,q and r
See p.197 from Real Time Collision Detection by C. Ericson
Examples
Define cylinder using a segment defined by
>>> p=np.array([0,0,0],dtype=np.float32)
>>> q=np.array([1,0,0],dtype=np.float32)
>>> r=0.5
Define segment
>>> sa=np.array([0.5,1 ,0],dtype=np.float32)
>>> sb=np.array([0.5,1,0],dtype=np.float32)
Intersection
>>> intersect_segment_cylinder(sa, sb, p, q, r)
(1.0, 0.25, 0.75)
dipy.tracking.distances.
larch_3merge
()Reassign tracks to existing clusters by merging clusters that their representative tracks are not very distant i.e. less than sqd_thr. Using tracks consisting of 3 points (first, mid and last). This is necessary after running larch_fast_split after multiple split in different levels (squared thresholds) as some of them have created independent clusters.
of indices 3tracks (tracks consisting of 3 points only)
squared euclidean distance threshold
a tree graph containing the clusters
dipy.tracking.distances.
larch_3split
()Generate a first pass clustering using 3 points on the tracks only.
of tracks as arrays, shape (N1,3) .. (Nm,3)
, where 3 points are
(first, mid and last)
Sequence of integer indices of tracks
squared euclidean distance threshold
A tree graph containing the clusters.
Notes
If a 3 point track (3track) is far away from all clusters then add a new cluster and assign this 3track as the rep(representative) track for the new cluster. Otherwise the rep 3track of each cluster is the average track of the cluster.
Examples
>>> tracks=[np.array([[0,0,0],[1,0,0,],[2,0,0]],dtype=np.float32),
... np.array([[3,0,0],[3.5,1,0],[4,2,0]],dtype=np.float32),
... np.array([[3.2,0,0],[3.7,1,0],[4.4,2,0]],dtype=np.float32),
... np.array([[3.4,0,0],[3.9,1,0],[4.6,2,0]],dtype=np.float32),
... np.array([[0,0.2,0],[1,0.2,0],[2,0.2,0]],dtype=np.float32),
... np.array([[2,0.2,0],[1,0.2,0],[0,0.2,0]],dtype=np.float32),
... np.array([[0,0,0],[0,1,0],[0,2,0]],dtype=np.float32),
... np.array([[0.2,0,0],[0.2,1,0],[0.2,2,0]],dtype=np.float32),
... np.array([[0.2,0,0],[0.2,1,0],[0.2,2,0]],dtype=np.float32)]
>>> C = larch_3split(tracks, None, 0.5)
Here is an example of how to visualize the clustering above:
from dipy.viz import window, actor
scene = window.Scene()
scene.add(actor.line(tracks,window.colors.red))
window.show(scene)
for c in C:
color=np.random.rand(3)
for i in C[c]['indices']:
scene.add(actor.line(tracks[i],color))
window.show(scene)
for c in C:
scene.add(actor.line(C[c]['rep3']/C[c]['N'],
window.colors.white))
window.show(scene)
dipy.tracking.distances.
lee_angle_distance
()Calculates angle distance metric for the distance between two line segments
Based on Lee , Han & Whang SIGMOD07.
This function assumes that norm(end0start0)>norm(end1start1) i.e. that the first segment will be bigger than the second one.
Notes
l_0 = np.inner(end0start0,end0start0) l_1 = np.inner(end1start1,end1start1)
cos_theta_squared = np.inner(end0start0,end1start1)**2/ (l_0*l_1) return np.sqrt((1cos_theta_squared)*l_1)
Examples
>>> lee_angle_distance([0,0,0],[1,0,0],[3,4,5],[5,4,3])
2.0
dipy.tracking.distances.
lee_perpendicular_distance
()Calculates perpendicular distance metric for the distance between two line segments
Based on Lee , Han & Whang SIGMOD07.
This function assumes that norm(end0start0)>norm(end1start1) i.e. that the first segment will be bigger than the second one.
Notes
l0 = np.inner(end0start0,end0start0) l1 = np.inner(end1start1,end1start1)
k0=end0start0
u1 = np.inner(start1start0,k0)/l0 u2 = np.inner(end1start0,k0)/l0
ps = start0+u1*k0 pe = start0+u2*k0
lperp1 = np.sqrt(np.inner(psstart1,psstart1)) lperp2 = np.sqrt(np.inner(peend1,peend1))
return (lperp1**2+lperp2**2)/(lperp1+lperp2)
return 0.
Examples
>>> d = lee_perpendicular_distance([0,0,0],[1,0,0],[3,4,5],[5,4,3])
>>> print('%.6f' % d)
5.787888
dipy.tracking.distances.
local_skeleton_clustering
()Efficient tractography clustering
Every track can needs to have the same number of points. Use dipy.tracking.metrics.downsample to restrict the number of points
of tracks as arrays, shape (N,3) .. (N,3) where N=points
average euclidean distance threshold
Clusters.
See also
Notes
The distance calculated between two tracks:
t_1 t_2
0* a *0
\ 
\ 
1* 
 b *1
 \
2* \
c *2
is equal to \((a+b+c)/3\) where \(a\) the euclidean distance between t_1[0]
and t_2[0]
, \(b\) between t_1[1]
and t_2[1]
and \(c\) between
t_1[2]
and t_2[2]
. Also the same with t2 flipped (so t_1[0]
compared to t_2[2]
etc).
Visualization:
It is possible to visualize the clustering C from the example above using the dipy.viz module:
from dipy.viz import window, actor
scene = window.Scene()
for c in C:
color=np.random.rand(3)
for i in C[c]['indices']:
scene.add(actor.line(tracks[i],color))
window.show(scene)
Examples
>>> tracks=[np.array([[0,0,0],[1,0,0,],[2,0,0]]),
... np.array([[3,0,0],[3.5,1,0],[4,2,0]]),
... np.array([[3.2,0,0],[3.7,1,0],[4.4,2,0]]),
... np.array([[3.4,0,0],[3.9,1,0],[4.6,2,0]]),
... np.array([[0,0.2,0],[1,0.2,0],[2,0.2,0]]),
... np.array([[2,0.2,0],[1,0.2,0],[0,0.2,0]]),
... np.array([[0,0,0],[0,1,0],[0,2,0]])]
>>> C = local_skeleton_clustering(tracks, d_thr=0.5)
dipy.tracking.distances.
local_skeleton_clustering_3pts
()Does a first pass clustering
Every track can only have 3 pts neither less or more. Use dipy.tracking.metrics.downsample to restrict the number of points
of tracks as arrays, shape (N,3) .. (N,3) where N=3
Average euclidean distance threshold
Clusters.
Notes
It is possible to visualize the clustering C from the example above using the fvtk module:
r=fvtk.ren()
for c in C:
color=np.random.rand(3)
for i in C[c]['indices']:
fvtk.add(r,fos.line(tracks[i],color))
fvtk.show(r)
Examples
>>> tracks=[np.array([[0,0,0],[1,0,0,],[2,0,0]]),
... np.array([[3,0,0],[3.5,1,0],[4,2,0]]),
... np.array([[3.2,0,0],[3.7,1,0],[4.4,2,0]]),
... np.array([[3.4,0,0],[3.9,1,0],[4.6,2,0]]),
... np.array([[0,0.2,0],[1,0.2,0],[2,0.2,0]]),
... np.array([[2,0.2,0],[1,0.2,0],[0,0.2,0]]),
... np.array([[0,0,0],[0,1,0],[0,2,0]])]
>>> C=local_skeleton_clustering_3pts(tracks,d_thr=0.5)
dipy.tracking.distances.
mam_distances
()Min/Max/Mean Average Minimum Distance between tracks xyz1 and xyz2
Based on the metrics in Zhang, Correia, Laidlaw 2008 http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=4479455 which in turn are based on those of Corouge et al. 2004
arrays representing x,y,z of the N1 and N2 points of two tracks
Metric to calculate. {‘avg’,’min’,’max’} return a scalar. ‘all’ returns a tuple
average_mean_closest_distance
minimum_mean_closest_distance
maximum_mean_closest_distance
Notes
Algorithmic description
Lets say we have curves A and B.
For every point in A calculate the minimum distance from every point in B stored in minAB
For every point in B calculate the minimum distance from every point in A stored in minBA
find average of minAB stored as avg_minAB find average of minBA stored as avg_minBA
if metric is ‘avg’ then return (avg_minAB + avg_minBA)/2.0 if metric is ‘min’ then return min(avg_minAB,avg_minBA) if metric is ‘max’ then return max(avg_minAB,avg_minBA)
dipy.tracking.distances.
minimum_closest_distance
()Find the minimum distance between two curves xyz1, xyz2
arrays representing x,y,z of the N1 and N2 points of two tracks
Notes
Algorithmic description
Lets say we have curves A and B
for every point in A calculate the minimum distance from every point in B stored in minAB for every point in B calculate the minimum distance from every point in A stored in minBA find min of minAB stored in min_minAB find min of minBA stored in min_minBA
Then return (min_minAB + min_minBA)/2.0
dipy.tracking.distances.
most_similar_track_mam
()Find the most similar track in a bundle using distances calculated from Zhang et. al 2008.
of tracks as arrays, shape (N1,3) .. (Nm,3)
‘avg’, ‘min’, ‘max’
index of the most similar track in tracks. This can be used as a reference track for a bundle.
similarities between tracks[si] and the rest of the tracks in the bundle
Notes
A vague description of this function is given below:
for (i,j) in tracks_combinations_of_2:
calculate the mean_closest_distance from i to j (mcd_i) calculate the mean_closest_distance from j to i (mcd_j)
 if ‘avg’:
s holds the average similarities
 if ‘min’:
s holds the minimum similarities
 if ‘max’:
s holds the maximum similarities
si holds the index of the track with min {avg,min,max} average metric
dipy.tracking.distances.
point_segment_sq_distance
()Calculate the squared distance from a point c to a finite line segment ab.
Examples
>>> a=np.array([0,0,0], dtype=np.float32)
>>> b=np.array([1,0,0], dtype=np.float32)
>>> c=np.array([0,1,0], dtype=np.float32)
>>> point_segment_sq_distance(a, b, c)
1.0
>>> c = np.array([0,3,0], dtype=np.float32)
>>> point_segment_sq_distance(a,b,c)
9.0
>>> c = np.array([1,1,0], dtype=np.float32)
>>> point_segment_sq_distance(a, b, c)
2.0
dipy.tracking.distances.
point_track_sq_distance_check
()Check if square distance of track from point is smaller than threshold
Examples
>>> t=np.random.rand(10,3).astype(np.float32)
>>> p=np.array([0.5,0.5,0.5],dtype=np.float32)
>>> point_track_sq_distance_check(t,p,2**2)
True
>>> t=np.array([[0,0,0],[1,1,1],[2,2,2]],dtype='f4')
>>> p=np.array([1,1.,1],dtype='f4')
>>> point_track_sq_distance_check(t,p,.2**2)
False
>>> point_track_sq_distance_check(t,p,2**2)
True
dipy.tracking.distances.
track_dist_3pts
()Calculate the euclidean distance between two 3pt tracks
Both direct and flip distances are calculated but only the smallest is returned
Examples
>>> a = np.array([[0,0,0],[1,0,0,],[2,0,0]])
>>> b = np.array([[3,0,0],[3.5,1,0],[4,2,0]])
>>> c = track_dist_3pts(a, b)
>>> print('%.6f' % c)
2.721573
dipy.tracking.distances.
track_roi_intersection_check
()Check if a track is intersecting a region of interest
Examples
>>> roi=np.array([[0,0,0],[1,0,0],[2,0,0]],dtype='f4')
>>> t=np.array([[0,0,0],[1,1,1],[2,2,2]],dtype='f4')
>>> track_roi_intersection_check(t,roi,1)
True
>>> track_roi_intersection_check(t,np.array([[10,0,0]],dtype='f4'),1)
False
EnhancementKernel
dipy.tracking.fbcmeasures.
EnhancementKernel
Bases: object
Methods
Evaluate the kernel at position x relative to position y, with orientation r relative to orientation v. 

Return the computed lookup table. 

Return the orientations. 

Get the sphere corresponding with the orientations 
__init__
()Compute a lookup table for the contextual enhancement kernel
Spatial diffusion
Angular diffusion
Diffusion time
Always compute the lookup table even if it is available in cache. Default is False.
Specify the number of orientations to be used with electrostatic repulsion, or provide a Sphere object. The default sphere is ‘repulsion100’.
Enable verbose mode.
References
J. Portegies, R. Duits. (2016) Fast implementations of contextual PDE’s for HARDI data processing in DIPY. ISMRM 2016 conference.
on the space of positions and orientations and their application to crossingpreserving smoothing of HARDI images. International Journal of Computer Vision, 92:231264.
(2015) New Approximation of a Scale Space Kernel on SE(3) and Applications in Neuroimaging. Fifth International Conference on Scale Space and Variational Methods in Computer Vision
G. Girard, and R. Duits. (2015) Improving Fiber Alignment in HARDI by Combining Contextual PDE flow with Constrained Spherical Deconvolution. PLoS One.
FBCMeasures
dipy.tracking.fbcmeasures.
FBCMeasures
Bases: object
Methods
Set a threshold on the RFBC to remove spurious fibers. 
__init__
()Compute the fiber to bundle coherence measures for a set of streamlines.
A collection of streamlines, each n by 3, with n being the number of nodes in the fiber.
A diffusion kernel object created from EnhancementKernel.
Fibers with fewer points than minimum_length are excluded from FBC computation.
The maximal window size used to calculate the average LFBC region
Number of threads to be used for OpenMP parallelization. If None (default) the value of OMP_NUM_THREADS environment variable is used if it is set, otherwise all available threads are used. If < 0 the maximal number of threads minus num_threads + 1 is used (enter 1 to use as many threads as possible). 0 raises an error.
Enable verbose mode.
References
J. Portegies, P. Ossenblok, R. Duits. (2016) Cleaning output of tractography via fiber to bundle coherence, a new open source implementation. Human Brain Mapping conference 2016.
G.Girard, and R. Duits. (2015) Improving Fiber Alignment in HARDI by Combining Contextual PDE flow with Constrained Spherical Deconvolution. PLoS One.
get_points_rfbc_thresholded
()Set a threshold on the RFBC to remove spurious fibers.
The threshold to set on the RFBC, should be within 0 and 1.
Enhances the coloring of the fibers by LFBC. Increasing emphasis will stress spurious fibers by logarithmic weighting.
Prints info about the found RFBC for the set of fibers such as median, mean, min and max values.
The output contains: 1) a collection of streamlines, each n by 3, with n being the number of nodes in the fiber that remain after filtering 2) the r,g,b values of the local fiber to bundle coherence (LFBC) 3) the relative fiber to bundle coherence (RFBC)
KDTree
dipy.tracking.fbcmeasures.
KDTree
(data, leafsize=10)Bases: object
kdtree for quick nearestneighbor lookup
This class provides an index into a set of kD points which can be used to rapidly look up the nearest neighbors of any point.
The data points to be indexed. This array is not copied, and so modifying this data will result in bogus results.
The number of points at which the algorithm switches over to bruteforce. Has to be positive.
The maximum recursion limit can be exceeded for large data sets. If this happens, either increase the value for the leafsize parameter or increase the recursion limit by:
>>> import sys
>>> sys.setrecursionlimit(10000)
See also
cKDTree
Implementation of KDTree in Cython
Notes
The algorithm used is described in Maneewongvatana and Mount 1999. The general idea is that the kdtree is a binary tree, each of whose nodes represents an axisaligned hyperrectangle. Each node specifies an axis and splits the set of points based on whether their coordinate along that axis is greater than or less than a particular value.
During construction, the axis and splitting point are chosen by the “sliding midpoint” rule, which ensures that the cells do not all become long and thin.
The tree can be queried for the r closest neighbors of any given point (optionally returning only those within some maximum distance of the point). It can also be queried, with a substantial gain in efficiency, for the r approximate closest neighbors.
For large dimensions (20 is already large) do not expect this to run significantly faster than brute force. Highdimensional nearestneighbor queries are a substantial open problem in computer science.
The tree also supports allneighbors queries, both with arrays of points and with other kdtrees. These do use a reasonably efficient algorithm, but the kdtree is not necessarily the best data structure for this sort of calculation.
Methods

Count how many nearby pairs can be formed. 

Query the kdtree for nearest neighbors 

Find all points within distance r of point(s) x. 

Find all pairs of points whose distance is at most r 

Find all pairs of points within a distance. 

Compute a sparse distance matrix 
innernode 

leafnode 

node 
count_neighbors
(other, r, p=2.0)Count how many nearby pairs can be formed.
Count the number of pairs (x1,x2) can be formed, with x1 drawn
from self and x2 drawn from other
, and where
distance(x1, x2, p) <= r
.
This is the “twopoint correlation” described in Gray and Moore 2000,
“Nbody problems in statistical learning”, and the code here is based
on their algorithm.
The other tree to draw points from.
The radius to produce a count for. Multiple radii are searched with a single tree traversal.
Which Minkowski pnorm to use
The number of pairs. Note that this is internally stored in a numpy int, and so may overflow if very large (2e9).
node
Bases: object
query
(x, k=1, eps=0, p=2, distance_upper_bound=inf)Query the kdtree for nearest neighbors
An array of points to query.
The number of nearest neighbors to return.
Return approximate nearest neighbors; the kth returned value is guaranteed to be no further than (1+eps) times the distance to the real kth nearest neighbor.
Which Minkowski pnorm to use. 1 is the sumofabsolutevalues “Manhattan” distance 2 is the usual Euclidean distance infinity is the maximumcoordinatedifference distance
Return only neighbors within this distance. This is used to prune tree searches, so if you are doing a series of nearestneighbor queries, it may help to supply the distance to the nearest neighbor of the most recent point.
The distances to the nearest neighbors. If x has shape tuple+(self.m,), then d has shape tuple if k is one, or tuple+(k,) if k is larger than one. Missing neighbors (e.g. when k > n or distance_upper_bound is given) are indicated with infinite distances. If k is None, then d is an object array of shape tuple, containing lists of distances. In either case the hits are sorted by distance (nearest first).
The locations of the neighbors in self.data. i is the same shape as d.
Examples
>>> from scipy import spatial
>>> x, y = np.mgrid[0:5, 2:8]
>>> tree = spatial.KDTree(list(zip(x.ravel(), y.ravel())))
>>> tree.data
array([[0, 2],
[0, 3],
[0, 4],
[0, 5],
[0, 6],
[0, 7],
[1, 2],
[1, 3],
[1, 4],
[1, 5],
[1, 6],
[1, 7],
[2, 2],
[2, 3],
[2, 4],
[2, 5],
[2, 6],
[2, 7],
[3, 2],
[3, 3],
[3, 4],
[3, 5],
[3, 6],
[3, 7],
[4, 2],
[4, 3],
[4, 4],
[4, 5],
[4, 6],
[4, 7]])
>>> pts = np.array([[0, 0], [2.1, 2.9]])
>>> tree.query(pts)
(array([ 2. , 0.14142136]), array([ 0, 13]))
>>> tree.query(pts[0])
(2.0, 0)
query_ball_point
(x, r, p=2.0, eps=0)Find all points within distance r of point(s) x.
The point or points to search for neighbors of.
The radius of points to return.
Which Minkowski pnorm to use. Should be in the range [1, inf].
Approximate search. Branches of the tree are not explored if their
nearest points are further than r / (1 + eps)
, and branches are
added in bulk if their furthest points are nearer than
r * (1 + eps)
.
If x is a single point, returns a list of the indices of the neighbors of x. If x is an array of points, returns an object array of shape tuple containing lists of neighbors.
Notes
If you have many points whose neighbors you want to find, you may save substantial amounts of time by putting them in a KDTree and using query_ball_tree.
Examples
>>> from scipy import spatial
>>> x, y = np.mgrid[0:5, 0:5]
>>> points = np.c_[x.ravel(), y.ravel()]
>>> tree = spatial.KDTree(points)
>>> tree.query_ball_point([2, 0], 1)
[5, 10, 11, 15]
Query multiple points and plot the results:
>>> import matplotlib.pyplot as plt
>>> points = np.asarray(points)
>>> plt.plot(points[:,0], points[:,1], '.')
>>> for results in tree.query_ball_point(([2, 0], [3, 3]), 1):
... nearby_points = points[results]
... plt.plot(nearby_points[:,0], nearby_points[:,1], 'o')
>>> plt.margins(0.1, 0.1)
>>> plt.show()
query_ball_tree
(other, r, p=2.0, eps=0)Find all pairs of points whose distance is at most r
The tree containing points to search against.
The maximum distance, has to be positive.
Which Minkowski norm to use. p has to meet the condition
1 <= p <= infinity
.
Approximate search. Branches of the tree are not explored
if their nearest points are further than r/(1+eps)
, and
branches are added in bulk if their furthest points are nearer
than r * (1+eps)
. eps has to be nonnegative.
For each element self.data[i]
of this tree, results[i]
is a
list of the indices of its neighbors in other.data
.
query_pairs
(r, p=2.0, eps=0)Find all pairs of points within a distance.
The maximum distance.
Which Minkowski norm to use. p has to meet the condition
1 <= p <= infinity
.
Approximate search. Branches of the tree are not explored
if their nearest points are further than r/(1+eps)
, and
branches are added in bulk if their furthest points are nearer
than r * (1+eps)
. eps has to be nonnegative.
Set of pairs (i,j)
, with i < j
, for which the corresponding
positions are close.
sparse_distance_matrix
(other, max_distance, p=2.0)Compute a sparse distance matrix
Computes a distance matrix between two KDTrees, leaving as zero any distance greater than max_distance.
Sparse matrix representing the results in “dictionary of keys” format.
interp1d
dipy.tracking.fbcmeasures.
interp1d
(x, y, kind='linear', axis=1, copy=True, bounds_error=None, fill_value=nan, assume_sorted=False)Bases: scipy.interpolate.polyint._Interpolator1D
Interpolate a 1D function.
x and y are arrays of values used to approximate some function f:
y = f(x)
. This class returns a function whose call method uses
interpolation to find the value of new points.
Note that calling interp1d with NaNs present in input values results in undefined behaviour.
A 1D array of real values.
A ND array of real values. The length of y along the interpolation axis must be equal to the length of x.
Specifies the kind of interpolation as a string (‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’, ‘previous’, ‘next’, where ‘zero’, ‘slinear’, ‘quadratic’ and ‘cubic’ refer to a spline interpolation of zeroth, first, second or third order; ‘previous’ and ‘next’ simply return the previous or next value of the point) or as an integer specifying the order of the spline interpolator to use. Default is ‘linear’.
Specifies the axis of y along which to interpolate. Interpolation defaults to the last axis of y.
If True, the class makes internal copies of x and y. If False, references to x and y are used. The default is to copy.
If True, a ValueError is raised any time interpolation is attempted on
a value outside of the range of x (where extrapolation is
necessary). If False, out of bounds values are assigned fill_value.
By default, an error is raised unless fill_value="extrapolate"
.
if a ndarray (or float), this value will be used to fill in for requested points outside of the data range. If not provided, then the default is NaN. The arraylike must broadcast properly to the dimensions of the noninterpolation axes.
If a twoelement tuple, then the first element is used as a
fill value for x_new < x[0]
and the second element is used for
x_new > x[1]
. Anything that is not a 2element tuple (e.g.,
list or ndarray, regardless of shape) is taken to be a single
arraylike argument meant to be used for both bounds as
below, above = fill_value, fill_value
.
New in version 0.17.0.
If “extrapolate”, then points outside the data range will be extrapolated.
New in version 0.17.0.
If False, values of x can be in any order and they are sorted first. If True, x has to be an array of monotonically increasing values.
See also
splrep
, splev
Spline interpolation/smoothing based on FITPACK.
UnivariateSpline
An objectoriented wrapper of the FITPACK routines.
interp2d
2D interpolation
Examples
>>> import matplotlib.pyplot as plt
>>> from scipy import interpolate
>>> x = np.arange(0, 10)
>>> y = np.exp(x/3.0)
>>> f = interpolate.interp1d(x, y)
>>> xnew = np.arange(0, 9, 0.1)
>>> ynew = f(xnew) # use interpolation function returned by `interp1d`
>>> plt.plot(x, y, 'o', xnew, ynew, '')
>>> plt.show()
fill_value
The fill value.
Methods

Evaluate the interpolant 
dipy.tracking.fbcmeasures.
compute_rfbc
()Compute the relative fiber to bundle coherence (RFBC)
Contains the length of each streamline
Contains the local fiber to bundle coherence (LFBC) for each streamline element.
The maximal window size used to calculate the average LFBC region
dipy.tracking.fbcmeasures.
determine_num_threads
()Determine the effective number of threads to be used for OpenMP calls
For num_threads = None
,
 if the OMP_NUM_THREADS
environment variable is set, return that
value
 otherwise, return the maximum number of cores retrieved by
openmp.opm_get_num_procs()
.
For num_threads > 0
, return this value.
For num_threads < 0
, return the maximal number of threads minus
num_threads + 1
. In particular num_threads = 1
will use as
many threads as there are available cores on the machine.
For num_threads = 0
a ValueError is raised.
Desired number of threads to be used.
dipy.tracking.fbcmeasures.
get_sphere
(name='symmetric362')provide triangulated spheres
which sphere  one of: * ‘symmetric362’ * ‘symmetric642’ * ‘symmetric724’ * ‘repulsion724’ * ‘repulsion100’ * ‘repulsion200’
Examples
>>> import numpy as np
>>> from dipy.data import get_sphere
>>> sphere = get_sphere('symmetric362')
>>> verts, faces = sphere.vertices, sphere.faces
>>> verts.shape == (362, 3)
True
>>> faces.shape == (720, 3)
True
>>> verts, faces = get_sphere('not a sphere name')
Traceback (most recent call last):
...
DataError: No sphere called "not a sphere name"
dipy.tracking.fbcmeasures.
ndindex
(shape)An Ndimensional iterator object to index arrays.
Given the shape of an array, an ndindex instance iterates over the Ndimensional index of the array. At each iteration a tuple of indices is returned; the last dimension is iterated over first.
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)
dipy.tracking.learning.
detect_corresponding_tracks
(indices, tracks1, tracks2)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 correspondance in the following way: the first column is the current index in tracks1 the second column is the corresponding index in tracks2
Notes
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.)
Examples
>>> 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)
dipy.tracking.learning.
detect_corresponding_tracks_plus
(indices, tracks1, indices2, tracks2)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 correspondance in th following way the first colum is the current index of tracks1 the second column is the corresponding index in tracks2
See also
distances.mam_distances
Notes
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.)
Examples
>>> 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)
FiberFit
dipy.tracking.life.
FiberFit
(fiber_model, life_matrix, vox_coords, to_fit, beta, weighted_signal, b0_signal, relative_signal, mean_sig, vox_data, streamline, affine, evals)Bases: dipy.reconst.base.ReconstFit
A fit of the LiFE model to diffusion data
Methods

Predict the signal 
__init__
(fiber_model, life_matrix, vox_coords, to_fit, beta, weighted_signal, b0_signal, relative_signal, mean_sig, vox_data, streamline, affine, evals)predict
(gtab=None, S0=None)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
FiberModel
dipy.tracking.life.
FiberModel
(gtab)Bases: dipy.reconst.base.ReconstModel
A class for representing and solving predictive models based on tractography solutions.
Notes
This is an implementation of the LiFE model described in [1]_
B.A. (2014). Validation and statistical inference in living connectomes. Nature Methods.
Methods

Fit the LiFE FiberModel for data and a set of streamlines associated with this data 

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 
fit
(data, streamline, affine, evals=[0.001, 0, 0], sphere=None)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.
setup
(streamline, affine, evals=[0.001, 0, 0], sphere=None)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
LifeSignalMaker
dipy.tracking.life.
LifeSignalMaker
(gtab, evals=[0.001, 0, 0], sphere=None)Bases: object
A class for generating signals from streamlines in an efficient and speedy manner.
Methods

Approximate the signal for a given streamline 
calc_signal 
__init__
(gtab, evals=[0.001, 0, 0], sphere=None)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
ReconstFit
dipy.tracking.life.
ReconstFit
(model, data)Bases: object
Abstract class which holds the fit result of ReconstModel
For example that could be holding FA or GFA etc.
ReconstModel
dipy.tracking.life.
ReconstModel
(gtab)Bases: object
Abstract class for signal reconstruction models
Methods
fit 
dipy.tracking.life.
grad_tensor
(grad, evals)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.
dipy.tracking.life.
gradient
(f)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.
Notes
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.
Examples
>>> 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. ]])]
dipy.tracking.life.
streamline_signal
(streamline, gtab, evals=[0.001, 0, 0])The signal from a single streamline estimate along each of its nodes.
The eigenvalues of the canonical tensor used as an estimate of the signal generated by each node of the streamline.
dipy.tracking.life.
streamline_tensors
(streamline, evals=[0.001, 0, 0])The tensors generated by this fiber.
The 3d coordinates of a single streamline
The estimated eigenvalues of a single fiber tensor. (default: [0.001, 0, 0]).
Notes
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.
dipy.tracking.life.
transform_streamlines
(streamlines, mat, in_place=False)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
dipy.tracking.life.
unique_rows
(in_array, dtype='f4')This (quickly) finds 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.
dipy.tracking.life.
voxel2streamline
(streamline, affine, unique_idx=None)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
AnatomicalStoppingCriterion
dipy.tracking.local_tracking.
AnatomicalStoppingCriterion
Bases: dipy.tracking.stopping_criterion.StoppingCriterion
Abstract class that takes as input included and excluded tissue maps. The ‘include_map’ defines when the streamline reached a ‘valid’ stopping region (e.g. gray matter partial volume estimation (PVE) map) and the ‘exclude_map’ defines when the streamline reached an ‘invalid’ stopping region (e.g. corticospinal fluid PVE map). The background of the anatomical image should be added to the ‘include_map’ to keep streamlines exiting the brain (e.g. through the brain stem).
double interp_out_double[1] double[:] interp_out_view = interp_out_view double[:, :, :] include_map, exclude_map
Methods
AnatomicalStoppingCriterion from partial volume fraction (PVE) maps. 
check_point 

get_exclude 

get_include 
from_pve
()AnatomicalStoppingCriterion from partial volume fraction (PVE) maps.
The partial volume fraction of white matter at each voxel.
The partial volume fraction of gray matter at each voxel.
The partial volume fraction of corticospinal fluid at each voxel.
LocalTracking
dipy.tracking.local_tracking.
LocalTracking
(direction_getter, stopping_criterion, seeds, affine, step_size, max_cross=None, maxlen=500, fixedstep=True, return_all=True, random_seed=None, save_seeds=False)Bases: object
__init__
(direction_getter, stopping_criterion, seeds, affine, step_size, max_cross=None, maxlen=500, fixedstep=True, return_all=True, random_seed=None, save_seeds=False)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
dipy.tracking.local_tracking.
ParticleFilteringTracking
(direction_getter, stopping_criterion, seeds, affine, step_size, max_cross=None, maxlen=500, pft_back_tracking_dist=2, pft_front_tracking_dist=1, pft_max_trial=20, particle_count=15, return_all=True, random_seed=None, save_seeds=False)Bases: dipy.tracking.local_tracking.LocalTracking
__init__
(direction_getter, stopping_criterion, seeds, affine, step_size, max_cross=None, maxlen=500, pft_back_tracking_dist=2, pft_front_tracking_dist=1, pft_max_trial=20, particle_count=15, return_all=True, random_seed=None, save_seeds=False)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
References
Girard, G., Whittingstall, K., Deriche, R., & Descoteaux, M. Towards quantitative connectivity analysis: reducing tractography biases. NeuroImage, 98, 266278, 2014.
StreamlineStatus
dipy.tracking.local_tracking.
StreamlineStatus
Bases: enum.IntEnum
An enumeration.
dipy.tracking.local_tracking.
local_tracker
()Tracks one direction from a seed.
This function is the main workhorse of the LocalTracking
class defined
in dipy.tracking.local_tracking
.
Used to choosing tracking directions.
Used to check the streamline status (e.g. endpoint) along path.
First point of the (partial) streamline.
Initial seeding direction. Used as prev_dir
for selecting the step
direction from the seed point.
Size of voxels in the data set.
Output of tracking will be put into this array. The length of this
array, N
, will set the maximum allowable length of the streamline.
Size of tracking steps in mm if fixed_step
.
If true, a fixed step_size is used, otherwise a variable step size is used.
Length of the tracked streamline
Ending state of the streamlines as determined by the StoppingCriterion.
dipy.tracking.local_tracking.
pft_tracker
()Tracks one direction from a seed using the particle filtering algorithm.
This function is the main workhorse of the ParticleFilteringTracking
class defined in dipy.tracking.local_tracking
.
Used to choosing tracking directions.
Used to check the streamline status (e.g. endpoint) along path.
First point of the (partial) streamline.
Initial seeding direction. Used as prev_dir
for selecting the step
direction from the seed point.
Size of voxels in the data set.
Output of tracking will be put into this array. The length of this
array, N
, will set the maximum allowable length of the streamline.
Output of tracking directions will be put into this array. The length
of this array, N
, will set the maximum allowable length of the
streamline.
Size of tracking steps in mm if fixed_step
.
Number of tracking steps to back track before starting the particle filtering tractography.
Number of additional tracking steps to track.
Maximum number of trials for the particle filtering tractography (Prevents infinite loops).
Number of particles to use in the particle filter.
Temporary array for paths followed by all particles.
Temporary array for directions followed by particles.
Temporary array for the weights of particles.
Temporary array for the number of steps of particles.
Temporary array for the stream status of particles.
Length of the tracked streamline
Ending state of the streamlines as determined by the StoppingCriterion.
dipy.tracking.localtrack.
local_tracker
()Tracks one direction from a seed.
This function is the main workhorse of the LocalTracking
class defined
in dipy.tracking.local_tracking
.
Used to choosing tracking directions.
Used to check the streamline status (e.g. endpoint) along path.
First point of the (partial) streamline.
Initial seeding direction. Used as prev_dir
for selecting the step
direction from the seed point.
Size of voxels in the data set.
Output of tracking will be put into this array. The length of this
array, N
, will set the maximum allowable length of the streamline.
Size of tracking steps in mm if fixed_step
.
If true, a fixed step_size is used, otherwise a variable step size is used.
Length of the tracked streamline
Ending state of the streamlines as determined by the StoppingCriterion.
dipy.tracking.localtrack.
pft_tracker
()Tracks one direction from a seed using the particle filtering algorithm.
This function is the main workhorse of the ParticleFilteringTracking
class defined in dipy.tracking.local_tracking
.
Used to choosing tracking directions.
Used to check the streamline status (e.g. endpoint) along path.
First point of the (partial) streamline.
Initial seeding direction. Used as prev_dir
for selecting the step
direction from the seed point.
Size of voxels in the data set.
Output of tracking will be put into this array. The length of this
array, N
, will set the maximum allowable length of the streamline.
Output of tracking directions will be put into this array. The length
of this array, N
, will set the maximum allowable length of the
streamline.
Size of tracking steps in mm if fixed_step
.
Number of tracking steps to back track before starting the particle filtering tractography.
Number of additional tracking steps to track.
Maximum number of trials for the particle filtering tractography (Prevents infinite loops).
Number of particles to use in the particle filter.
Temporary array for paths followed by all particles.
Temporary array for directions followed by particles.
Temporary array for the weights of particles.
Temporary array for the number of steps of particles.
Temporary array for the stream status of particles.
Length of the tracked streamline
Ending state of the streamlines as determined by the StoppingCriterion.
dipy.tracking.mesh.
random_coordinates_from_surface
(nb_triangles, nb_seed, triangles_mask=None, triangles_weight=None, rand_gen=None)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
See also
seeds_from_surface_coordinates
, random_seeds_from_mask
dipy.tracking.mesh.
seeds_from_surface_coordinates
(triangles, vts_values, triangles_idx, trilinear_coord)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
See also
dipy.tracking.mesh.
vertices_to_triangles_values
(triangles, vts_values)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
See also
dipy.tracking.metrics.
arbitrarypoint
(xyz, distance)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
Examples
>>> 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)
dipy.tracking.metrics.
center_of_mass
(xyz)Center of mass of streamline
array representing x,y,z of N points in a track
center of mass of streamline
Examples
>>> 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.])
dipy.tracking.metrics.
deprecate_with_version
(message, since='', until='', version_comparator=<function cmp_pkg_version>, warn_class=<class 'DeprecationWarning'>, error_class=<class 'dipy.utils.deprecator.ExpiredDeprecationError'>)Return decorator function function for deprecation warning / error.
The decorated function / method will:
Raise the given warning_class warning when the function / method gets called, up to (and including) version until (if specified);
Raise the given error_class error when the function / method gets called, when the package version is greater than version until (if specified).
Message explaining deprecation, giving possible alternatives.
Released version at which object was first deprecated.
Last released version at which this function will still raise a deprecation warning. Versions higher than this will raise an error.
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.
Class of warning to generate for deprecation.
Class of error to generate when version_comparator returns 1 for a
given argument of until
.
Function returning a decorator.
dipy.tracking.metrics.
downsample
(xyz, n_pols=3)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
dipy.tracking.metrics.
endpoint
(xyz)Track.
First track point.
Examples
>>> 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
dipy.tracking.metrics.
frenet_serret
(xyz)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)
array representing x,y,z of N points in a track
array representing the tangent of the curve xyz
array representing the normal of the curve xyz
array representing the binormal of the curve xyz
array representing the curvature of the curve xyz
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)
dipy.tracking.metrics.
inside_sphere
(xyz, center, radius)If any point of the track is inside a sphere of a specified center and radius return True otherwise False. Mathematicaly 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.
representing x,y,z of the N points of the track
center of the sphere
radius of the sphere
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
dipy.tracking.metrics.
inside_sphere_points
(xyz, center, radius)If a track intersects with a sphere of a specified center and radius return the points that are inside the sphere otherwise False. Mathematicaly 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.
representing x,y,z of the N points of the track
center of the sphere
radius of the sphere
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]])
dipy.tracking.metrics.
intersect_sphere
(xyz, center, radius)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)
..
Notes
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
dipy.tracking.metrics.
length
(xyz, along=False)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.
Examples
>>> 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])
dipy.tracking.metrics.
longest_track_bundle
(bundle, sort=False)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)
Examples
>>> 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]...)
dipy.tracking.metrics.
mean_curvature
(xyz)Calculates the mean curvature of a curve
array representing x,y,z of N points in a curve
Mean curvature.
Examples
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
dipy.tracking.metrics.
midpoint
(xyz)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
Examples
>>> 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. ])
dipy.tracking.metrics.
midpoint2point
(xyz, p)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
Examples
>>> 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]))
dipy.tracking.metrics.
principal_components
(xyz)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
Examples
>>> 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
dipy.tracking.metrics.
set_number_of_points
()(either by downsampling or upsampling)
Change the number of points of streamlines in order to obtain nb_points1 segments of equal length. Points of streamlines will be modified along the curve.
dipy.tracking.Streamlines
If ndarray, must have shape (N,3) where N is the number of points
of the streamline.
If list, each item must be ndarray shape (Ni,3) where Ni is the number
of points of streamline i.
If dipy.tracking.Streamlines
, its common_shape must be 3.
integer representing number of points wanted along the curve.
dipy.tracking.Streamlines
Results of the downsampling or upsampling process.
Examples
>>> from dipy.tracking.streamline import set_number_of_points
>>> import numpy as np
One streamline, a semicircle:
>>> theta = np.pi*np.linspace(0, 1, 100)
>>> x = np.cos(theta)
>>> y = np.sin(theta)
>>> z = 0 * x
>>> streamline = np.vstack((x, y, z)).T
>>> modified_streamline = set_number_of_points(streamline, 3)
>>> len(modified_streamline)
3
Multiple streamlines:
>>> streamlines = [streamline, streamline[::2]]
>>> new_streamlines = set_number_of_points(streamlines, 10)
>>> [len(s) for s in streamlines]
[100, 50]
>>> [len(s) for s in new_streamlines]
[10, 10]
dipy.tracking.metrics.
splev
(x, tck, der=0, ext=0)Evaluate a Bspline or its derivatives.
Given the knots and coefficients of a Bspline representation, evaluate the value of the smoothing polynomial and its derivatives. This is a wrapper around the FORTRAN routines splev and splder of FITPACK.
An array of points at which to return the value of the smoothed spline or its derivatives. If tck was returned from splprep, then the parameter values, u should be given.
If a tuple, then it should be a sequence of length 3 returned by splrep or splprep containing the knots, coefficients, and degree of the spline. (Also see Notes.)
The order of derivative of the spline to compute (must be less than or equal to k, the degree of the spline).
Controls the value returned for elements of x
not in the
interval defined by the knot sequence.
if ext=0, return the extrapolated value.
if ext=1, return 0
if ext=2, raise a ValueError
if ext=3, return the boundary value.
The default value is 0.
An array of values representing the spline function evaluated at the points in x. If tck was returned from splprep, then this is a list of arrays representing the curve in an ND space.
See also
splprep
, splrep
, sproot
, spalde
, splint
bisplrep
, bisplev
BSpline
Notes
Manipulating the tcktuples directly is not recommended. In new code, prefer using BSpline objects.
References
C. de Boor, “On calculating with bsplines”, J. Approximation Theory, 6, p.5062, 1972.
M. G. Cox, “The numerical evaluation of bsplines”, J. Inst. Maths Applics, 10, p.134149, 1972.
P. Dierckx, “Curve and surface fitting with splines”, Monographs on Numerical Analysis, Oxford University Press, 1993.
dipy.tracking.metrics.
spline
(xyz, s=3, k=2, nest=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
See also
scipy.interpolate.splprep
scipy.interpolate.splev
Examples
>>> 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
dipy.tracking.metrics.
splprep
(x, w=None, u=None, ub=None, ue=None, k=3, task=0, s=None, t=None, full_output=0, nest=None, per=0, quiet=1)Find the Bspline representation of an ND curve.
Given a list of N rank1 arrays, x, which represent a curve in ND space parametrized by u, find a smooth approximating spline curve g(u). Uses the FORTRAN routine parcur from FITPACK.
A list of sample vector arrays representing the curve.
Strictly positive rank1 array of weights the same length as x[0].
The weights are used in computing the weighted leastsquares spline
fit. If the errors in the x values have standarddeviation given by
the vector d, then w should be 1/d. Default is ones(len(x[0]))
.
An array of parameter values. If not given, these values are
calculated automatically as M = len(x[0])
, where
v[0] = 0
v[i] = v[i1] + distance(x[i], x[i1])
u[i] = v[i] / v[M1]
The endpoints of the parameters interval. Defaults to u[0] and u[1].
Degree of the spline. Cubic splines are recommended.
Even values of k should be avoided especially with a small svalue.
1 <= k <= 5
, default is 3.
If task==0 (default), find t and c for a given smoothing factor, s. If task==1, find t and c for another value of the smoothing factor, s. There must have been a previous call with task=0 or task=1 for the same set of data. If task=1 find the weighted least square spline for a given set of knots, t.
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 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
data points in x, y, and w.
The knots needed for task=1.
If nonzero, then return optional outputs.
An overestimate of the total number of knots of the spline to help in determining the storage space. By default nest=m/2. Always large enough is nest=m+k+1.
If nonzero, data points are considered periodic with period
x[m1]  x[0]
and a smooth periodic spline approximation is
returned. Values of y[m1]
and w[m1]
are not used.
Nonzero to suppress messages. This parameter is deprecated; use standard Python warning filters instead.
(t,c,k) a tuple containing the vector of knots, the Bspline coefficients, and the degree of the spline.
An array of the values of the parameter.
The weighted sum of squared residuals of the spline approximation.
An integer flag about splrep success. Success is indicated if ier<=0. If ier in [1,2,3] an error occurred but was not raised. Otherwise an error is raised.
A message corresponding to the integer flag, ier.
See also
splrep
, splev
, sproot
, spalde
, splint
bisplrep
, bisplev
UnivariateSpline
, BivariateSpline
BSpline
make_interp_spline
Notes
See splev for evaluation of the spline and its derivatives. The number of dimensions N must be smaller than 11.
The number of coefficients in the c array is k+1
less then the number
of knots, len(t)
. This is in contrast with splrep, which zeropads
the array of coefficients to have the same length as the array of knots.
These additional coefficients are ignored by evaluation routines, splev
and BSpline.
References
P. Dierckx, “Algorithms for smoothing data with periodic and parametric splines, Computer Graphics and Image Processing”, 20 (1982) 171184.
P. Dierckx, “Algorithms for smoothing data with periodic and parametric splines”, report tw55, Dept. Computer Science, K.U.Leuven, 1981.
P. Dierckx, “Curve and surface fitting with splines”, Monographs on Numerical Analysis, Oxford University Press, 1993.
Examples
Generate a discretization of a limacon curve in the polar coordinates:
>>> phi = np.linspace(0, 2.*np.pi, 40)
>>> r = 0.5 + np.cos(phi) # polar coords
>>> x, y = r * np.cos(phi), r * np.sin(phi) # convert to cartesian
And interpolate:
>>> from scipy.interpolate import splprep, splev
>>> tck, u = splprep([x, y], s=0)
>>> new_points = splev(u, tck)
Notice that (i) we force interpolation by using s=0,
(ii) the parameterization, u
, is generated automatically.
Now plot the result:
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> ax.plot(x, y, 'ro')
>>> ax.plot(new_points[0], new_points[1], 'r')
>>> plt.show()
dipy.tracking.metrics.
startpoint
(xyz)First point of the track
Track.
First track point.
Examples
>>> 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
dipy.tracking.metrics.
winding
(xyz)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.
dipy.tracking.propspeed.
eudx_both_directions
()Point where the tracking starts.
Index of peak to follow first.
Anisotropy matrix, where Np
is the number of maximum allowed peaks.
Index of the track orientation.
Sampling directions on the sphere.
Threshold for QA, we want everything higher than this threshold.
Angle threshold, we only select fiber orientation within this range.
dipy.tracking.propspeed.
ndarray_offset
()Find offset in an Ndimensional ndarray using strides
Indices of the array which we want to find the offset.
Strides of array.
len of the indices array.
Number of bytes for data type e.g. if 8 for double, 4 for int32
Index position in flattened array
Examples
>>> import numpy as np
>>> from dipy.tracking.propspeed import ndarray_offset
>>> I=np.array([1,1])
>>> A=np.array([[1,0,0],[0,2,0],[0,0,3]])
>>> S=np.array(A.strides)
>>> ndarray_offset(I,S,2,A.dtype.itemsize)
4
>>> A.ravel()[4]==A[1,1]
True
ActStoppingCriterion
dipy.tracking.stopping_criterion.
ActStoppingCriterion
Bases: dipy.tracking.stopping_criterion.AnatomicalStoppingCriterion
AnatomicallyConstrained Tractography (ACT) stopping criterion from [1]. This implements the use of partial volume fraction (PVE) maps to determine when the tracking stops. The proposed ([1]) method that cuts streamlines going through subcortical gray matter regions is not implemented here. The backtracking technique for streamlines reaching INVALIDPOINT is not implemented either. cdef:
double interp_out_double[1] double[:] interp_out_view = interp_out_view double[:, :, :] include_map, exclude_map
“Anatomicallyconstrained tractography: Improved diffusion MRI streamlines tractography through effective use of anatomical information.” NeuroImage, 63(3), 19241938, 2012.
Methods

AnatomicalStoppingCriterion from partial volume fraction (PVE) maps. 
check_point 

get_exclude 

get_include 
AnatomicalStoppingCriterion
dipy.tracking.stopping_criterion.
AnatomicalStoppingCriterion
Bases: dipy.tracking.stopping_criterion.StoppingCriterion
Abstract class that takes as input included and excluded tissue maps. The ‘include_map’ defines when the streamline reached a ‘valid’ stopping region (e.g. gray matter partial volume estimation (PVE) map) and the ‘exclude_map’ defines when the streamline reached an ‘invalid’ stopping region (e.g. corticospinal fluid PVE map). The background of the anatomical image should be added to the ‘include_map’ to keep streamlines exiting the brain (e.g. through the brain stem).
double interp_out_double[1] double[:] interp_out_view = interp_out_view double[:, :, :] include_map, exclude_map
Methods
AnatomicalStoppingCriterion from partial volume fraction (PVE) maps. 
check_point 

get_exclude 

get_include 
from_pve
()AnatomicalStoppingCriterion from partial volume fraction (PVE) maps.
The partial volume fraction of white matter at each voxel.
The partial volume fraction of gray matter at each voxel.
The partial volume fraction of corticospinal fluid at each voxel.
BinaryStoppingCriterion
dipy.tracking.stopping_criterion.
BinaryStoppingCriterion
Bases: dipy.tracking.stopping_criterion.StoppingCriterion
unsigned char[:, :, :] mask
Methods
check_point 
CmcStoppingCriterion
dipy.tracking.stopping_criterion.
CmcStoppingCriterion
Bases: dipy.tracking.stopping_criterion.AnatomicalStoppingCriterion
Continuous map criterion (CMC) stopping criterion from [1]. This implements the use of partial volume fraction (PVE) maps to determine when the tracking stops.
double interp_out_double[1] double[:] interp_out_view = interp_out_view double[:, :, :] include_map, exclude_map double step_size double average_voxel_size double correction_factor
References
“Towards quantitative connectivity analysis: reducing tractography biases.” NeuroImage, 98, 266278, 2014.
Methods

AnatomicalStoppingCriterion from partial volume fraction (PVE) maps. 
check_point 

get_exclude 

get_include 
StoppingCriterion
dipy.tracking.stopping_criterion.
StoppingCriterion
Bases: object
Methods
check_point 
StreamlineStatus
dipy.tracking.stopping_criterion.
StreamlineStatus
Bases: enum.IntEnum
An enumeration.
ThresholdStoppingCriterion
dipy.tracking.stopping_criterion.
ThresholdStoppingCriterion
Bases: dipy.tracking.stopping_criterion.StoppingCriterion
# Declarations from stopping_criterion.pxd bellow cdef:
double threshold, interp_out_double[1] double[:] interp_out_view = interp_out_view double[:, :, :] metric_map
Methods
check_point 
dipy.tracking.streamline.
apply_affine
(aff, pts)Apply affine matrix aff to points pts
Returns result of application of aff to the right of pts. The coordinate dimension of pts should be the last.
For the 3D case, aff will be shape (4,4) and pts will have final axis length 3  maybe it will just be N by 3. The return value is the transformed points, in this case:
res = np.dot(aff[:3,:3], pts.T) + aff[:3,3:4]
transformed_pts = res.T
This routine is more general than 3D, in that aff can have any shape (N,N), and pts can have any shape, as long as the last dimension is for the coordinates, and is therefore length N1.
Homogenous affine, for 3D points, will be 4 by 4. Contrary to first appearance, the affine will be applied on the left of pts.
Points, where the last dimension contains the coordinates of each point. For 3D, the last dimension will be length 3.
transformed points
Examples
>>> aff = np.array([[0,2,0,10],[3,0,0,11],[0,0,4,12],[0,0,0,1]])
>>> pts = np.array([[1,2,3],[2,3,4],[4,5,6],[6,7,8]])
>>> apply_affine(aff, pts)
array([[14, 14, 24],
[16, 17, 28],
[20, 23, 36],
[24, 29, 44]]...)
Just to show that in the simple 3D case, it is equivalent to:
>>> (np.dot(aff[:3,:3], pts.T) + aff[:3,3:4]).T
array([[14, 14, 24],
[16, 17, 28],
[20, 23, 36],
[24, 29, 44]]...)
But pts can be a more complicated shape:
>>> pts = pts.reshape((2,2,3))
>>> apply_affine(aff, pts)
array([[[14, 14, 24],
[16, 17, 28]],
[[20, 23, 36],
[24, 29, 44]]]...)
dipy.tracking.streamline.
bundles_distances_mdf
()Calculate distances between list of tracks A and list of tracks B
All tracks need to have the same number of points
of tracks as arrays, [(N,3) .. (N,3)]
of tracks as arrays, [(N,3) .. (N,3)]
distances between tracksA and tracksB according to metric
dipy.tracking.streamline.
cdist
(XA, XB, metric='euclidean', *args, **kwargs)Compute distance between each pair of the two collections of inputs.
See Notes for common calling conventions.
An \(m_A\) by \(n\) array of \(m_A\) original observations in an \(n\)dimensional space. Inputs are converted to float type.
An \(m_B\) by \(n\) array of \(m_B\) original observations in an \(n\)dimensional space. Inputs are converted to float type.
The distance metric to use. If a string, the distance function can be ‘braycurtis’, ‘canberra’, ‘chebyshev’, ‘cityblock’, ‘correlation’, ‘cosine’, ‘dice’, ‘euclidean’, ‘hamming’, ‘jaccard’, ‘jensenshannon’, ‘kulsinski’, ‘mahalanobis’, ‘matching’, ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’, ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, ‘wminkowski’, ‘yule’.
Additional arguments should be passed as keyword arguments
Extra arguments to metric: refer to each metric documentation for a list of all possible arguments.
Some possible arguments:
p : scalar The pnorm to apply for Minkowski, weighted and unweighted. Default: 2.
w : ndarray The weight vector for metrics that support weights (e.g., Minkowski).
V : ndarray The variance vector for standardized Euclidean. Default: var(vstack([XA, XB]), axis=0, ddof=1)
VI : ndarray The inverse of the covariance matrix for Mahalanobis. Default: inv(cov(vstack([XA, XB].T))).T
out : ndarray The output array If not None, the distance matrix Y is stored in this array. Note: metric independent, it will become a regular keyword arg in a future scipy version
A \(m_A\) by \(m_B\) distance matrix is returned.
For each \(i\) and \(j\), the metric
dist(u=XA[i], v=XB[j])
is computed and stored in the
\(ij\) th entry.
An exception is thrown if XA and XB do not have the same number of columns.
Notes
The following are common calling conventions:
Y = cdist(XA, XB, 'euclidean')
Computes the distance between \(m\) points using Euclidean distance (2norm) as the distance metric between the points. The points are arranged as \(m\) \(n\)dimensional row vectors in the matrix X.
Y = cdist(XA, XB, 'minkowski', p=2.)
Computes the distances using the Minkowski distance \(uv_p\) (\(p\)norm) where \(p \geq 1\).
Y = cdist(XA, XB, 'cityblock')
Computes the city block or Manhattan distance between the points.
Y = cdist(XA, XB, 'seuclidean', V=None)
Computes the standardized Euclidean distance. The standardized
Euclidean distance between two nvectors u
and v
is
V is the variance vector; V[i] is the variance computed over all the i’th components of the points. If not passed, it is automatically computed.
Y = cdist(XA, XB, 'sqeuclidean')
Computes the squared Euclidean distance \(uv_2^2\) between the vectors.
Y = cdist(XA, XB, 'cosine')
Computes the cosine distance between vectors u and v,
where \(*_2\) is the 2norm of its argument *
, and
\(u \cdot v\) is the dot product of \(u\) and \(v\).
Y = cdist(XA, XB, 'correlation')
Computes the correlation distance between vectors u and v. This is
where \(\bar{v}\) is the mean of the elements of vector v, and \(x \cdot y\) is the dot product of \(x\) and \(y\).
Y = cdist(XA, XB, 'hamming')
Computes the normalized Hamming distance, or the proportion of
those vector elements between two nvectors u
and v
which disagree. To save memory, the matrix X
can be of type
boolean.
Y = cdist(XA, XB, 'jaccard')
Computes the Jaccard distance between the points. Given two
vectors, u
and v
, the Jaccard distance is the
proportion of those elements u[i]
and v[i]
that
disagree where at least one of them is nonzero.
Y = cdist(XA, XB, 'chebyshev')
Computes the Chebyshev distance between the points. The Chebyshev distance between two nvectors
u
andv
is the maximum norm1 distance between their respective elements. More precisely, the distance is given by\[d(u,v) = \max_i {u_iv_i}.\]
Y = cdist(XA, XB, 'canberra')
Computes the Canberra distance between the points. The Canberra distance between two points
u
andv
is\[d(u,v) = \sum_i \frac{u_iv_i} {u_i+v_i}.\]
Y = cdist(XA, XB, 'braycurtis')
Computes the BrayCurtis distance between the points. The BrayCurtis distance between two points
u
andv
is\[d(u,v) = \frac{\sum_i (u_iv_i)} {\sum_i (u_i+v_i)}\]
Y = cdist(XA, XB, 'mahalanobis', VI=None)
Computes the Mahalanobis distance between the points. The Mahalanobis distance between two points
u
andv
is \(\sqrt{(uv)(1/V)(uv)^T}\) where \((1/V)\) (theVI
variable) is the inverse covariance. IfVI
is not None,VI
will be used as the inverse covariance matrix.
Y = cdist(XA, XB, 'yule')
Computes the Yule distance between the boolean vectors. (see yule function documentation)
Y = cdist(XA, XB, 'matching')
Synonym for ‘hamming’.
Y = cdist(XA, XB, 'dice')
Computes the Dice distance between the boolean vectors. (see dice function documentation)
Y = cdist(XA, XB, 'kulsinski')
Computes the Kulsinski distance between the boolean vectors. (see kulsinski function documentation)
Y = cdist(XA, XB, 'rogerstanimoto')
Computes the RogersTanimoto distance between the boolean vectors. (see rogerstanimoto function documentation)
Y = cdist(XA, XB, 'russellrao')
Computes the RussellRao distance between the boolean vectors. (see russellrao function documentation)
Y = cdist(XA, XB, 'sokalmichener')
Computes the SokalMichener distance between the boolean vectors. (see sokalmichener function documentation)
Y = cdist(XA, XB, 'sokalsneath')
Computes the SokalSneath distance between the vectors. (see sokalsneath function documentation)
Y = cdist(XA, XB, 'wminkowski', p=2., w=w)
Computes the weighted Minkowski distance between the vectors. (see wminkowski function documentation)
Y = cdist(XA, XB, f)
Computes the distance between all pairs of vectors in X using the user supplied 2arity function f. For example, Euclidean distance between the vectors could be computed as follows:
dm = cdist(XA, XB, lambda u, v: np.sqrt(((uv)**2).sum()))Note that you should avoid passing a reference to one of the distance functions defined in this library. For example,:
dm = cdist(XA, XB, sokalsneath)would calculate the pairwise distances between the vectors in X using the Python function sokalsneath. This would result in sokalsneath being called \({n \choose 2}\) times, which is inefficient. Instead, the optimized C version is more efficient, and we call it using the following syntax:
dm = cdist(XA, XB, 'sokalsneath')
Examples
Find the Euclidean distances between four 2D coordinates:
>>> from scipy.spatial import distance
>>> coords = [(35.0456, 85.2672),
... (35.1174, 89.9711),
... (35.9728, 83.9422),
... (36.1667, 86.7833)]
>>> distance.cdist(coords, coords, 'euclidean')
array([[ 0. , 4.7044, 1.6172, 1.8856],
[ 4.7044, 0. , 6.0893, 3.3561],
[ 1.6172, 6.0893, 0. , 2.8477],
[ 1.8856, 3.3561, 2.8477, 0. ]])
Find the Manhattan distance from a 3D point to the corners of the unit cube:
>>> a = np.array([[0, 0, 0],
... [0, 0, 1],
... [0, 1, 0],
... [0, 1, 1],
... [1, 0, 0],
... [1, 0, 1],
... [1, 1, 0],
... [1, 1, 1]])
>>> b = np.array([[ 0.1, 0.2, 0.4]])
>>> distance.cdist(a, b, 'cityblock')
array([[ 0.7],
[ 0.9],
[ 1.3],
[ 1.5],
[ 1.5],
[ 1.7],
[ 2.1],
[ 2.3]])
dipy.tracking.streamline.
cluster_confidence
(streamlines, max_mdf=5, subsample=12, power=1, override=False)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.
References
[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.
dipy.tracking.streamline.
compress_streamlines
()Compress streamlines by linearization as in [Presseau15].
The compression consists in merging consecutive segments that are nearly collinear. The merging is achieved by removing the point the two segments have in common.
The linearization process [Presseau15] ensures that every point being removed are within a certain margin (in mm) of the resulting streamline. Recommendations for setting this margin can be found in [Presseau15] (in which they called it tolerance error).
The compression also ensures that two consecutive points won’t be too far from each other (precisely less or equal than `max_segment_length`mm). This is a tradeoff to speed up the linearization process [Rheault15]. A low value will result in a faster linearization but low compression, whereas a high value will result in a slower linearization but high compression.
Array representing x,y,z of N points in a streamline.
Tolerance error in mm (default: 0.01). A rule of thumb is to set it to 0.01mm for deterministic streamlines and 0.1mm for probabilitic streamlines.
Maximum length in mm of any given segment produced by the compression. The default is 10mm. (In [Presseau15], they used a value of np.inf).
Results of the linearization process.
Notes
Be aware that compressed streamlines have variable step sizes. One needs to be careful when computing streamlinesbased metrics [Houde15].
References
Presseau C. et al., A new compression format for fiber tracking datasets, NeuroImage, no 109, 7383, 2015.
Rheault F. et al., Real Time Interaction with Millions of Streamlines, ISMRM, 2015.
Houde J.C. et al. How to Avoid Biased StreamlinesBased Metrics for Streamlines with Variable Step Sizes, ISMRM, 2015.
Examples
>>> from dipy.tracking.streamline import compress_streamlines
>>> import numpy as np
>>> # One streamline: a wiggling line
>>> rng = np.random.RandomState(42)
>>> streamline = np.linspace(0, 10, 100*3).reshape((100, 3))
>>> streamline += 0.2 * rng.rand(100, 3)
>>> c_streamline = compress_streamlines(streamline, tol_error=0.2)
>>> len(streamline)
100
>>> len(c_streamline)
10
>>> # Multiple streamlines
>>> streamlines = [streamline, streamline[::2]]
>>> c_streamlines = compress_streamlines(streamlines, tol_error=0.2)
>>> [len(s) for s in streamlines]
[100, 50]
>>> [len(s) for s in c_streamlines]
[10, 7]
dipy.tracking.streamline.
deform_streamlines
(streamlines, deform_field, stream_to_current_grid, current_grid_to_world, stream_to_ref_grid, ref_grid_to_world)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
dipy.tracking.streamline.
dist_to_corner
(affine)Calculate the maximal distance from the center to a corner of a voxel, given an affine
The spatial transformation from the measurement to the scanner space.
The maximal distance to the corner of a voxel, given voxel size encoded in the affine.
dipy.tracking.streamline.
interpolate_scalar_3d
()Trilinear interpolation of a 3D scalar image
Interpolates the 3D image at the given locations. This function is a wrapper for _interpolate_scalar_3d for testing purposes, it is equivalent to scipy.ndimage.interpolation.map_coordinates with trilinear interpolation
the 3D image to be interpolated
(locations[i,0], locations[i,1], locations[i,2), 0<=i<n must contain the coordinates to interpolate the image at
out[i], 0<=i<n will be the interpolated scalar at coordinates locations[i,:], or 0 if locations[i,:] is outside the image
if locations[i,:] is inside the image then inside[i]=1, else inside[i]=0
dipy.tracking.streamline.
interpolate_vector_3d
()Trilinear interpolation of a 3D vector field
Interpolates the 3D vector field at the given locations. This function is a wrapper for _interpolate_vector_3d for testing purposes, it is equivalent to using scipy.ndimage.interpolation.map_coordinates with trilinear interpolation at each vector component
the 3D vector field to be interpolated
(locations[i,0], locations[i,1], locations[i,2), 0<=i<n must contain the coordinates to interpolate the vector field at
out[i,:], 0<=i<n will be the interpolated vector at coordinates locations[i,:], or (0,0,0) if locations[i,:] is outside the field
if locations[i,:] is inside the vector field then inside[i]=1, else inside[i]=0
dipy.tracking.streamline.
length
()Euclidean length of streamlines
Length is in mm only if streamlines are expressed in world coordinates.
dipy.tracking.Streamlines
If ndarray, must have shape (N,3) where N is the number of points
of the streamline.
If list, each item must be ndarray shape (Ni,3) where Ni is the number
of points of streamline i.
If dipy.tracking.Streamlines
, its common_shape must be 3.
If there is only one streamline, a scalar representing the length of the streamline. If there are several streamlines, ndarray containing the length of every streamline.
Examples
>>> from dipy.tracking.streamline import length
>>> import numpy as np
>>> streamline = np.array([[1, 1, 1], [2, 3, 4], [0, 0, 0]])
>>> expected_length = np.sqrt([1+2**2+3**2, 2**2+3**2+4**2]).sum()
>>> length(streamline) == expected_length
True
>>> streamlines = [streamline, np.vstack([streamline, streamline[::1]])]
>>> expected_lengths = [expected_length, 2*expected_length]
>>> lengths = [length(streamlines[0]), length(streamlines[1])]
>>> np.allclose(lengths, expected_lengths)
True
>>> length([])
0.0
>>> length(np.array([[1, 2, 3]]))
0.0
dipy.tracking.streamline.
orient_by_rois
(streamlines, affine, roi1, roi2, in_place=False, as_generator=False)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
Examples
>>> 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.]])]
dipy.tracking.streamline.
orient_by_streamline
(streamlines, standard, n_points=12, in_place=False, as_generator=False)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.
dipy.tracking.streamline.
select_by_rois
(streamlines, affine, rois, include, mode=None, tol=None)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.
Generates the streamlines to be included based on these criteria.
Notes
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.
Examples
>>> 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.]])]
dipy.tracking.streamline.
select_random_set_of_streamlines
(streamlines, select, rng=None)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.
Notes
The same streamline will not be selected twice.
dipy.tracking.streamline.
set_number_of_points
()(either by downsampling or upsampling)
Change the number of points of streamlines in order to obtain nb_points1 segments of equal length. Points of streamlines will be modified along the curve.
dipy.tracking.Streamlines
If ndarray, must have shape (N,3) where N is the number of points
of the streamline.
If list, each item must be ndarray shape (Ni,3) where Ni is the number
of points of streamline i.
If dipy.tracking.Streamlines
, its common_shape must be 3.
integer representing number of points wanted along the curve.
dipy.tracking.Streamlines
Results of the downsampling or upsampling process.
Examples
>>> from dipy.tracking.streamline import set_number_of_points
>>> import numpy as np
One streamline, a semicircle:
>>> theta = np.pi*np.linspace(0, 1, 100)
>>> x = np.cos(theta)
>>> y = np.sin(theta)
>>> z = 0 * x
>>> streamline = np.vstack((x, y, z)).T
>>> modified_streamline = set_number_of_points(streamline, 3)
>>> len(modified_streamline)
3
Multiple streamlines:
>>> streamlines = [streamline, streamline[::2]]
>>> new_streamlines = set_number_of_points(streamlines, 10)
>>> [len(s) for s in streamlines]
[100, 50]
>>> [len(s) for s in new_streamlines]
[10, 10]
dipy.tracking.streamline.
transform_streamlines
(streamlines, mat, in_place=False)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
dipy.tracking.streamline.
values_from_volume
(data, streamlines, affine)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.
Notes
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.
dipy.tracking.streamlinespeed.
compress_streamlines
()Compress streamlines by linearization as in [Presseau15].
The compression consists in merging consecutive segments that are nearly collinear. The merging is achieved by removing the point the two segments have in common.
The linearization process [Presseau15] ensures that every point being removed are within a certain margin (in mm) of the resulting streamline. Recommendations for setting this margin can be found in [Presseau15] (in which they called it tolerance error).
The compression also ensures that two consecutive points won’t be too far from each other (precisely less or equal than `max_segment_length`mm). This is a tradeoff to speed up the linearization process [Rheault15]. A low value will result in a faster linearization but low compression, whereas a high value will result in a slower linearization but high compression.
Array representing x,y,z of N points in a streamline.
Tolerance error in mm (default: 0.01). A rule of thumb is to set it to 0.01mm for deterministic streamlines and 0.1mm for probabilitic streamlines.
Maximum length in mm of any given segment produced by the compression. The default is 10mm. (In [Presseau15], they used a value of np.inf).
Results of the linearization process.
Notes
Be aware that compressed streamlines have variable step sizes. One needs to be careful when computing streamlinesbased metrics [Houde15].
References
Presseau C. et al., A new compression format for fiber tracking datasets, NeuroImage, no 109, 7383, 2015.
Rheault F. et al., Real Time Interaction with Millions of Streamlines, ISMRM, 2015.
Houde J.C. et al. How to Avoid Biased StreamlinesBased Metrics for Streamlines with Variable Step Sizes, ISMRM, 2015.
Examples
>>> from dipy.tracking.streamline import compress_streamlines
>>> import numpy as np
>>> # One streamline: a wiggling line
>>> rng = np.random.RandomState(42)
>>> streamline = np.linspace(0, 10, 100*3).reshape((100, 3))
>>> streamline += 0.2 * rng.rand(100, 3)
>>> c_streamline = compress_streamlines(streamline, tol_error=0.2)
>>> len(streamline)
100
>>> len(c_streamline)
10
>>> # Multiple streamlines
>>> streamlines = [streamline, streamline[::2]]
>>> c_streamlines = compress_streamlines(streamlines, tol_error=0.2)
>>> [len(s) for s in streamlines]
[100, 50]
>>> [len(s) for s in c_streamlines]
[10, 7]
dipy.tracking.streamlinespeed.
length
()Euclidean length of streamlines
Length is in mm only if streamlines are expressed in world coordinates.
dipy.tracking.Streamlines
If ndarray, must have shape (N,3) where N is the number of points
of the streamline.
If list, each item must be ndarray shape (Ni,3) where Ni is the number
of points of streamline i.
If dipy.tracking.Streamlines
, its common_shape must be 3.
If there is only one streamline, a scalar representing the length of the streamline. If there are several streamlines, ndarray containing the length of every streamline.
Examples
>>> from dipy.tracking.streamline import length
>>> import numpy as np
>>> streamline = np.array([[1, 1, 1], [2, 3, 4], [0, 0, 0]])
>>> expected_length = np.sqrt([1+2**2+3**2, 2**2+3**2+4**2]).sum()
>>> length(streamline) == expected_length
True
>>> streamlines = [streamline, np.vstack([streamline, streamline[::1]])]
>>> expected_lengths = [expected_length, 2*expected_length]
>>> lengths = [length(streamlines[0]), length(streamlines[1])]
>>> np.allclose(lengths, expected_lengths)
True
>>> length([])
0.0
>>> length(np.array([[1, 2, 3]]))
0.0
dipy.tracking.streamlinespeed.
set_number_of_points
()(either by downsampling or upsampling)
Change the number of points of streamlines in order to obtain nb_points1 segments of equal length. Points of streamlines will be modified along the curve.
dipy.tracking.Streamlines
If ndarray, must have shape (N,3) where N is the number of points
of the streamline.
If list, each item must be ndarray shape (Ni,3) where Ni is the number
of points of streamline i.
If dipy.tracking.Streamlines
, its common_shape must be 3.
integer representing number of points wanted along the curve.
dipy.tracking.Streamlines
Results of the downsampling or upsampling process.
Examples
>>> from dipy.tracking.streamline import set_number_of_points
>>> import numpy as np
One streamline, a semicircle:
>>> theta = np.pi*np.linspace(0, 1, 100)
>>> x = np.cos(theta)
>>> y = np.sin(theta)
>>> z = 0 * x
>>> streamline = np.vstack((x, y, z)).T
>>> modified_streamline = set_number_of_points(streamline, 3)
>>> len(modified_streamline)
3
Multiple streamlines:
>>> streamlines = [streamline, streamline[::2]]
>>> new_streamlines = set_number_of_points(streamlines, 10)
>>> [len(s) for s in streamlines]
[100, 50]
>>> [len(s) for s in new_streamlines]
[10, 10]
OrderedDict
dipy.tracking.utils.
OrderedDict
Bases: dict
Dictionary that remembers insertion order
Methods





Create a new ordered dictionary with keys from iterable and values set to value. 

Return the value for key if key is in the dictionary, else default. 





Move an existing element to the end (or beginning if last is false). 

value. 

Remove and return a (key, value) pair from the dictionary. 

Insert key with a value of default if key is not in the dictionary. 

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k] 

fromkeys
(/, iterable, value=None)Create a new ordered dictionary with keys from iterable and values set to value.
move_to_end
(/, key, last=True)Move an existing element to the end (or beginning if last is false).
Raise KeyError if the element does not exist.
pop
(k[, d]) → v, remove specified key and return the correspondingvalue. If key is not found, d is returned if given, otherwise KeyError is raised.
popitem
(/, last=True)Remove and return a (key, value) pair from the dictionary.
Pairs are returned in LIFO order if last is true or FIFO order if false.
setdefault
(/, key, default=None)Insert key with a value of default if key is not in the dictionary.
Return the value for key if key is in the dictionary, else default.
combinations
dipy.tracking.utils.
combinations
Bases: object
combinations(iterable, r) –> combinations object
Return successive rlength combinations of elements in the iterable.
combinations(range(4), 3) –> (0,1,2), (0,1,3), (0,2,3), (1,2,3)
defaultdict
dipy.tracking.utils.
defaultdict
Bases: dict
defaultdict(default_factory[, …]) –> dict with default factory
The default factory is called without arguments to produce a new value when a key is not present, in __getitem__ only. A defaultdict compares equal to a dict with the same items. All remaining arguments are treated the same as if they were passed to the dict constructor, including keyword arguments.
default_factory
Factory for default value called by __missing__().
Methods





Create a new dictionary with keys from iterable and values set to value. 

Return the value for key if key is in the dictionary, else default. 





If key is not found, d is returned if given, otherwise KeyError is raised 

2tuple; but raise KeyError if D is empty. 

Insert key with a value of default if key is not in the dictionary. 

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k] 

groupby
dipy.tracking.utils.
groupby
(iterable, key=None) → make an iterator that returns consecutiveBases: object
keys and groups from the iterable. If the key function is not specified or is None, the element itself is used for grouping.
dipy.tracking.utils.
apply_affine
(aff, pts)Apply affine matrix aff to points pts
Returns result of application of aff to the right of pts. The coordinate dimension of pts should be the last.
For the 3D case, aff will be shape (4,4) and pts will have final axis length 3  maybe it will just be N by 3. The return value is the transformed points, in this case:
res = np.dot(aff[:3,:3], pts.T) + aff[:3,3:4]
transformed_pts = res.T
This routine is more general than 3D, in that aff can have any shape (N,N), and pts can have any shape, as long as the last dimension is for the coordinates, and is therefore length N1.
Homogenous affine, for 3D points, will be 4 by 4. Contrary to first appearance, the affine will be applied on the left of pts.
Points, where the last dimension contains the coordinates of each point. For 3D, the last dimension will be length 3.
transformed points
Examples
>>> aff = np.array([[0,2,0,10],[3,0,0,11],[0,0,4,12],[0,0,0,1]])
>>> pts = np.array([[1,2,3],[2,3,4],[4,5,6],[6,7,8]])
>>> apply_affine(aff, pts)
array([[14, 14, 24],
[16, 17, 28],
[20, 23, 36],
[24, 29, 44]]...)
Just to show that in the simple 3D case, it is equivalent to:
>>> (np.dot(aff[:3,:3], pts.T) + aff[:3,3:4]).T
array([[14, 14, 24],
[16, 17, 28],
[20, 23, 36],
[24, 29, 44]]...)
But pts can be a more complicated shape:
>>> pts = pts.reshape((2,2,3))
>>> apply_affine(aff, pts)
array([[[14, 14, 24],
[16, 17, 28]],
[[20, 23, 36],
[24, 29, 44]]]...)
dipy.tracking.utils.
asarray
(a, dtype=None, order=None, *, like=None)Convert the input to an array.
Input data, in any form that can be converted to an array. This includes lists, lists of tuples, tuples, tuples of tuples, tuples of lists and ndarrays.
By default, the datatype is inferred from the input data.
Memory layout. ‘A’ and ‘K’ depend on the order of input array a. ‘C’ rowmajor (Cstyle), ‘F’ columnmajor (Fortranstyle) memory representation. ‘A’ (any) means ‘F’ if a is Fortran contiguous, ‘C’ otherwise ‘K’ (keep) preserve input order Defaults to ‘C’.
Reference object to allow the creation of arrays which are not
NumPy arrays. If an arraylike passed in as like
supports
the __array_function__
protocol, the result will be defined
by it. In this case, it ensures the creation of an array object
compatible with that passed in via this argument.
Note
The like
keyword is an experimental feature pending on
acceptance of NEP 35.
New in version 1.20.0.
Array interpretation of a. No copy is performed if the input is already an ndarray with matching dtype and order. If a is a subclass of ndarray, a base class ndarray is returned.
See also
asanyarray
Similar function which passes through subclasses.
ascontiguousarray
Convert input to a contiguous array.
asfarray
Convert input to a floating point ndarray.
asfortranarray
Convert input to an ndarray with columnmajor memory order.
asarray_chkfinite
Similar function which checks input for NaNs and Infs.
fromiter
Create an array from an iterator.
fromfunction
Construct an array by executing a function on grid positions.
Examples
Convert a list into an array:
>>> a = [1, 2]
>>> np.asarray(a)
array([1, 2])
Existing arrays are not copied:
>>> a = np.array([1, 2])
>>> np.asarray(a) is a
True
If dtype is set, array is copied only if dtype does not match:
>>> a = np.array([1, 2], dtype=np.float32)
>>> np.asarray(a, dtype=np.float32) is a
True
>>> np.asarray(a, dtype=np.float64) is a
False
Contrary to asanyarray, ndarray subclasses are not passed through:
>>> issubclass(np.recarray, np.ndarray)
True
>>> a = np.array([(1.0, 2), (3.0, 4)], dtype='f4,i4').view(np.recarray)
>>> np.asarray(a) is a
False
>>> np.asanyarray(a) is a
True
dipy.tracking.utils.
cdist
(XA, XB, metric='euclidean', *args, **kwargs)Compute distance between each pair of the two collections of inputs.
See Notes for common calling conventions.
An \(m_A\) by \(n\) array of \(m_A\) original observations in an \(n\)dimensional space. Inputs are converted to float type.
An \(m_B\) by \(n\) array of \(m_B\) original observations in an \(n\)dimensional space. Inputs are converted to float type.
The distance metric to use. If a string, the distance function can be ‘braycurtis’, ‘canberra’, ‘chebyshev’, ‘cityblock’, ‘correlation’, ‘cosine’, ‘dice’, ‘euclidean’, ‘hamming’, ‘jaccard’, ‘jensenshannon’, ‘kulsinski’, ‘mahalanobis’, ‘matching’, ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’, ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, ‘wminkowski’, ‘yule’.
Additional arguments should be passed as keyword arguments
Extra arguments to metric: refer to each metric documentation for a list of all possible arguments.
Some possible arguments:
p : scalar The pnorm to apply for Minkowski, weighted and unweighted. Default: 2.
w : ndarray The weight vector for metrics that support weights (e.g., Minkowski).
V : ndarray The variance vector for standardized Euclidean. Default: var(vstack([XA, XB]), axis=0, ddof=1)
VI : ndarray The inverse of the covariance matrix for Mahalanobis. Default: inv(cov(vstack([XA, XB].T))).T
out : ndarray The output array If not None, the distance matrix Y is stored in this array. Note: metric independent, it will become a regular keyword arg in a future scipy version
A \(m_A\) by \(m_B\) distance matrix is returned.
For each \(i\) and \(j\), the metric
dist(u=XA[i], v=XB[j])
is computed and stored in the
\(ij\) th entry.
An exception is thrown if XA and XB do not have the same number of columns.
Notes
The following are common calling conventions:
Y = cdist(XA, XB, 'euclidean')
Computes the distance between \(m\) points using Euclidean distance (2norm) as the distance metric between the points. The points are arranged as \(m\) \(n\)dimensional row vectors in the matrix X.
Y = cdist(XA, XB, 'minkowski', p=2.)
Computes the distances using the Minkowski distance \(uv_p\) (\(p\)norm) where \(p \geq 1\).
Y = cdist(XA, XB, 'cityblock')
Computes the city block or Manhattan distance between the points.
Y = cdist(XA, XB, 'seuclidean', V=None)
Computes the standardized Euclidean distance. The standardized
Euclidean distance between two nvectors u
and v
is
V is the variance vector; V[i] is the variance computed over all the i’th components of the points. If not passed, it is automatically computed.
Y = cdist(XA, XB, 'sqeuclidean')
Computes the squared Euclidean distance \(uv_2^2\) between the vectors.
Y = cdist(XA, XB, 'cosine')
Computes the cosine distance between vectors u and v,
where \(*_2\) is the 2norm of its argument *
, and
\(u \cdot v\) is the dot product of \(u\) and \(v\).
Y = cdist(XA, XB, 'correlation')
Computes the correlation distance between vectors u and v. This is
where \(\bar{v}\) is the mean of the elements of vector v, and \(x \cdot y\) is the dot product of \(x\) and \(y\).
Y = cdist(XA, XB, 'hamming')
Computes the normalized Hamming distance, or the proportion of
those vector elements between two nvectors u
and v
which disagree. To save memory, the matrix X
can be of type
boolean.
Y = cdist(XA, XB, 'jaccard')
Computes the Jaccard distance between the points. Given two
vectors, u
and v
, the Jaccard distance is the
proportion of those elements u[i]
and v[i]
that
disagree where at least one of them is nonzero.
Y = cdist(XA, XB, 'chebyshev')
Computes the Chebyshev distance between the points. The Chebyshev distance between two nvectors
u
andv
is the maximum norm1 distance between their respective elements. More precisely, the distance is given by\[d(u,v) = \max_i {u_iv_i}.\]
Y = cdist(XA, XB, 'canberra')
Computes the Canberra distance between the points. The Canberra distance between two points
u
andv
is\[d(u,v) = \sum_i \frac{u_iv_i} {u_i+v_i}.\]
Y = cdist(XA, XB, 'braycurtis')
Computes the BrayCurtis distance between the points. The BrayCurtis distance between two points
u
andv
is\[d(u,v) = \frac{\sum_i (u_iv_i)} {\sum_i (u_i+v_i)}\]
Y = cdist(XA, XB, 'mahalanobis', VI=None)
Computes the Mahalanobis distance between the points. The Mahalanobis distance between two points
u
andv
is \(\sqrt{(uv)(1/V)(uv)^T}\) where \((1/V)\) (theVI
variable) is the inverse covariance. IfVI
is not None,VI
will be used as the inverse covariance matrix.
Y = cdist(XA, XB, 'yule')
Computes the Yule distance between the boolean vectors. (see yule function documentation)
Y = cdist(XA, XB, 'matching')
Synonym for ‘hamming’.
Y = cdist(XA, XB, 'dice')
Computes the Dice distance between the boolean vectors. (see dice function documentation)
Y = cdist(XA, XB, 'kulsinski')
Computes the Kulsinski distance between the boolean vectors. (see kulsinski function documentation)
Y = cdist(XA, XB, 'rogerstanimoto')
Computes the RogersTanimoto distance between the boolean vectors. (see rogerstanimoto function documentation)
Y = cdist(XA, XB, 'russellrao')
Computes the RussellRao distance between the boolean vectors. (see russellrao function documentation)
Y = cdist(XA, XB, 'sokalmichener')
Computes the SokalMichener distance between the boolean vectors. (see sokalmichener function documentation)
Y = cdist(XA, XB, 'sokalsneath')
Computes the SokalSneath distance between the vectors. (see sokalsneath function documentation)
Y = cdist(XA, XB, 'wminkowski', p=2., w=w)
Computes the weighted Minkowski distance between the vectors. (see wminkowski function documentation)
Y = cdist(XA, XB, f)
Computes the distance between all pairs of vectors in X using the user supplied 2arity function f. For example, Euclidean distance between the vectors could be computed as follows:
dm = cdist(XA, XB, lambda u, v: np.sqrt(((uv)**2).sum()))Note that you should avoid passing a reference to one of the distance functions defined in this library. For example,:
dm = cdist(XA, XB, sokalsneath)would calculate the pairwise distances between the vectors in X using the Python function sokalsneath. This would result in sokalsneath being called \({n \choose 2}\) times, which is inefficient. Instead, the optimized C version is more efficient, and we call it using the following syntax:
dm = cdist(XA, XB, 'sokalsneath')
Examples
Find the Euclidean distances between four 2D coordinates:
>>> from scipy.spatial import distance
>>> coords = [(35.0456, 85.2672),
... (35.1174, 89.9711),
... (35.9728, 83.9422),
... (36.1667, 86.7833)]
>>> distance.cdist(coords, coords, 'euclidean')
array([[ 0. , 4.7044, 1.6172, 1.8856],
[ 4.7044, 0. , 6.0893, 3.3561],
[ 1.6172, 6.0893, 0. , 2.8477],
[ 1.8856, 3.3561, 2.8477, 0. ]])
Find the Manhattan distance from a 3D point to the corners of the unit cube:
>>> a = np.array([[0, 0, 0],
... [0, 0, 1],
... [0, 1, 0],
... [0, 1, 1],
... [1, 0, 0],
... [1, 0, 1],
... [1, 1, 0],
... [1, 1, 1]])
>>> b = np.array([[ 0.1, 0.2, 0.4]])
>>> distance.cdist(a, b, 'cityblock')
array([[ 0.7],
[ 0.9],
[ 1.3],
[ 1.5],
[ 1.5],
[ 1.7],
[ 2.1],
[ 2.3]])
dipy.tracking.utils.
connectivity_matrix
(streamlines, affine, label_volume, inclusive=False, symmetric=True, return_mapping=False, mapping_as_streamlines=False)Counts 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)
.
dipy.tracking.utils.
density_map
(streamlines, affine, vol_dims)Counts 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.
Notes
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.
dipy.tracking.utils.
dist_to_corner
(affine)Calculate the maximal distance from the center to a corner of a voxel, given an affine
The spatial transformation from the measurement to the scanner space.
The maximal distance to the corner of a voxel, given voxel size encoded in the affine.
dipy.tracking.utils.
empty
(shape, dtype=float, order='C', *, like=None)Return a new array of given shape and type, without initializing entries.
Shape of the empty array, e.g., (2, 3)
or 2
.
Desired output datatype for the array, e.g, numpy.int8. Default is numpy.float64.
Whether to store multidimensional data in rowmajor (Cstyle) or columnmajor (Fortranstyle) order in memory.
Reference object to allow the creation of arrays which are not
NumPy arrays. If an arraylike passed in as like
supports
the __array_function__
protocol, the result will be defined
by it. In this case, it ensures the creation of an array object
compatible with that passed in via this argument.
Note
The like
keyword is an experimental feature pending on
acceptance of NEP 35.
New in version 1.20.0.
Array of uninitialized (arbitrary) data of the given shape, dtype, and order. Object arrays will be initialized to None.
See also
empty_like
Return an empty array with shape and type of input.
ones
Return a new array setting values to one.
zeros
Return a new array setting values to zero.
full
Return a new array of given shape filled with value.
Notes
empty, unlike zeros, does not set the array values to zero, and may therefore be marginally faster. On the other hand, it requires the user to manually set all the values in the array, and should be used with caution.
Examples
>>> np.empty([2, 2])
array([[ 9.74499359e+001, 6.69583040e309],
[ 2.13182611e314, 3.06959433e309]]) #uninitialized
>>> np.empty([2, 2], dtype=int)
array([[1073741821, 1067949133],
[ 496041986, 19249760]]) #uninitialized
dipy.tracking.utils.
minimum_at
(a, indices, b=None, /)Performs unbuffered in place operation on operand ‘a’ for elements
specified by ‘indices’. For addition ufunc, this method is equivalent to
a[indices] += b
, except that results are accumulated for elements that
are indexed more than once. For example, a[[0,0]] += 1
will only
increment the first element once because of buffering, whereas
add.at(a, [0,0], 1)
will increment the first element twice.
New in version 1.8.0.
The array to perform in place operation on.
Array like index object or slice object for indexing into first operand. If first operand has multiple dimensions, indices can be a tuple of array like index objects or slice objects.
Second operand for ufuncs requiring two operands. Operand must be broadcastable over first operand after indexing or slicing.
Examples
Set items 0 and 1 to their negative values:
>>> a = np.array([1, 2, 3, 4])
>>> np.negative.at(a, [0, 1])
>>> a
array([1, 2, 3, 4])
Increment items 0 and 1, and increment item 2 twice:
>>> a = np.array([1, 2, 3, 4])
>>> np.add.at(a, [0, 1, 2, 2], 1)
>>> a
array([2, 3, 5, 4])
Add items 0 and 1 in first array to second array, and store results in first array:
>>> a = np.array([1, 2, 3, 4])
>>> b = np.array([1, 2])
>>> np.add.at(a, [0, 1], b)
>>> a
array([2, 4, 3, 4])
dipy.tracking.utils.
near_roi
(streamlines, affine, region_of_interest, tol=None, mode='any')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.
dipy.tracking.utils.
path_length
(streamlines, affine, aoi, fill_value=1)Computes 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.
dipy.tracking.utils.
random_seeds_from_mask
(mask, affine, seeds_count=1, seed_count_per_voxel=True, random_seed=None)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).
When mask
is not a threedimensional array
See also
Examples
>>> 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]])
dipy.tracking.utils.
ravel_multi_index
(multi_index, dims, mode='raise', order='C')Converts a tuple of index arrays into an array of flat indices, applying boundary modes to the multiindex.
A tuple of integer arrays, one array for each dimension.
The shape of array into which the indices from multi_index
apply.
Specifies how outofbounds indices are handled. Can specify either one mode or a tuple of modes, one mode per index.
‘raise’ – raise an error (default)
‘wrap’ – wrap around
‘clip’ – clip to the range
In ‘clip’ mode, a negative index which would normally wrap will clip to 0 instead.
Determines whether the multiindex should be viewed as indexing in rowmajor (Cstyle) or columnmajor (Fortranstyle) order.
An array of indices into the flattened version of an array
of dimensions dims
.
See also
unravel_index
Notes
New in version 1.6.0.
Examples
>>> arr = np.array([[3,6,6],[4,5,1]])
>>> np.ravel_multi_index(arr, (7,6))
array([22, 41, 37])
>>> np.ravel_multi_index(arr, (7,6), order='F')
array([31, 41, 13])
>>> np.ravel_multi_index(arr, (4,6), mode='clip')
array([22, 23, 19])
>>> np.ravel_multi_index(arr, (4,4), mode=('clip','wrap'))
array([12, 13, 13])
>>> np.ravel_multi_index((3,1,4,1), (6,7,8,9))
1621
dipy.tracking.utils.
reduce_labels
(label_volume)Reduces an array of labels to the integers from 0 to n with smallest possible n.
Examples
>>> 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
dipy.tracking.utils.
reduce_rois
(rois, include)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
Notes
The include_roi and exclude_roi can be used to perfom the operation: “(A or B or …) and not (X or Y or …)”, where A, B are inclusion regions and X, Y are exclusion regions.
dipy.tracking.utils.
seeds_from_mask
(mask, affine, density=[1, 1, 1])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.
When mask
is not a threedimensional array
See also
Examples
>>> 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.]])
dipy.tracking.utils.
streamline_near_roi
(streamline, roi_coords, tol, mode='any')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.
dipy.tracking.utils.
subsegment
(streamlines, max_segment_length)Splits 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.
Notes
Segments of 0 length are removed. If unchanged
Examples
>>> 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. ]])]
dipy.tracking.utils.
target
(streamlines, affine, target_mask, include=True)Filters 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.
See also
dipy.tracking.utils.
target_line_based
(streamlines, affine, target_mask, include=True)Filters 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.
References
digital plotter”, IBM Systems Journal, vol 4, no. 1, 1965.
streamlines with variable step sizes, ISMRM 2015.
dipy.tracking.utils.
transform_tracking_output
(tracking_output, affine, save_seeds=False)Applies a linear transformation, given by affine, to streamlines. Parameters ——— streamlines : Streamlines generator
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.
dipy.tracking.utils.
unique_rows
(in_array, dtype='f4')This (quickly) finds 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.
dipy.tracking.utils.
wraps
(wrapped, assigned=('__module__', '__name__', '__qualname__', '__doc__', '__annotations__'), updated=('__dict__', ))Decorator factory to apply update_wrapper() to a wrapper function
Returns a decorator that invokes update_wrapper() with the decorated function as the wrapper argument and the arguments to wraps() as the remaining arguments. Default arguments are as for update_wrapper(). This is a convenience function to simplify applying partial() to update_wrapper().
dipy.tracking.vox2track.
streamline_mapping
()Creates a mapping from voxel indices to streamlines.
Returns a dictionary where each key is a 3d voxel index and the associated value is a list of the streamlines that pass through that voxel.
A sequence of streamlines.
The mapping from voxel coordinates to streamline coordinates.
The streamline values are assumed to be in voxel coordinates.
IE [0, 0, 0]
is the center of the first voxel and the voxel size
is [1, 1, 1]
.
If True voxel indices map to lists of streamline objects. Otherwise voxel indices map to lists of integers.
A mapping from voxel indices to the streamlines that pass through that voxel.
Examples
>>> streamlines = [np.array([[0., 0., 0.],
... [1., 1., 1.],
... [2., 3., 4.]]),
... np.array([[0., 0., 0.],
... [1., 2., 3.]])]
>>> mapping = streamline_mapping(streamlines, affine=np.eye(4))
>>> mapping[0, 0, 0]
[0, 1]
>>> mapping[1, 1, 1]
[0]
>>> mapping[1, 2, 3]
[1]
>>> mapping.get((3, 2, 1), 'no streamlines')
'no streamlines'
>>> mapping = streamline_mapping(streamlines, affine=np.eye(4),
... mapping_as_streamlines=True)
>>> mapping[1, 2, 3][0] is streamlines[1]
True
dipy.tracking.vox2track.
track_counts
()Counts of points in tracks that pass through voxels in volume
We find whether a point passed through a track by rounding the mm point values to voxels. For a track that passes through a voxel more than once, we only record counts and elements for the first point in the line that enters the voxel.
sequence of T tracks. One track is an ndarray of shape (N, 3), where N
is the number of points in that track, and tracks[t][n]
is the nth
point in the tth track. Points are of form x, y, z in voxel mm
coordinates. That is, if i, j, k
is the possibly noninteger voxel
coordinate of the track point, and vox_sizes are 3 floats giving voxel
sizes of dimensions 0, 1, 2 respectively, then the voxel mm coordinates
x, y, z
are simply i * vox_sizes[0], j * vox_sizes[1], k *
vox_sizes[2]
. This convention derives from trackviz. To pass in
tracks as voxel coordinates, just pass vox_sizes=(1, 1, 1)
(see
below).
volume dimensions in voxels, x, y, z.
voxel sizes in mm. Default is (1,1,1)
If True, also return object array with one list per voxel giving track indices and point indices passing through the voxel (see below)
An array where entry tcs[x, y, z]
is the number of tracks
that passed through voxel at voxel coordinate x, y, z
If return_elements is True, we also return an object array with one object per voxel. The objects at each voxel are a list of integers, where the integers are the indices of the track that passed through the voxel.
Examples
Imagine you have a volume (voxel) space of dimension (10,20,30)
.
Imagine you had voxel coordinate tracks in vs
. To just fill an array
with the counts of how many tracks pass through each voxel:
>>> vox_track0 = np.array([[0, 0, 0], [1.1, 2.2, 3.3], [2.2, 4.4, 6.6]])
>>> vox_track1 = np.array([[0, 0, 0], [0, 0, 1], [0, 0, 2]])
>>> vs = (vox_track0, vox_track1)
>>> vox_dim = (10, 20, 30) # original voxel array size
>>> tcs = track_counts(vs, vox_dim, (1, 1, 1), False)
>>> tcs.shape
(10, 20, 30)
>>> tcs[0, 0, 0:4]
array([2, 1, 1, 0])
>>> tcs[1, 2, 3], tcs[2, 4, 7]
(1, 1)
You can also use the routine to count into largerthanvoxel boxes. To do
this, increase the voxel size and decrease the vox_dim
accordingly:
>>> tcs=track_counts(vs, (10/2., 20/2., 30/2.), (2,2,2), False)
>>> tcs.shape
(5, 10, 15)
>>> tcs[1,1,2], tcs[1,2,3]
(1, 1)