tracking

Important Note:

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 A-D represent the following points in “real world coordinates”:

A = [-.5, -1.]
B = [ .5,  1.]
C = [ 0.,  0.]
D = [ 2.5,  5.]

Streamlines

dipy.tracking.Streamlines

alias of nibabel.streamlines.array_sequence.ArraySequence

bench

dipy.tracking.bench(label='fast', verbose=1, extra_argv=None)

Run benchmarks for module using nose.

Parameters:

label : {‘fast’, ‘full’, ‘’, attribute identifier}, optional 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’. verbose : int, optional Verbosity value for benchmark outputs, in the range 1-10. Default is 1. extra_argv : list, optional List with any extra arguments to pass to nosetests.

Returns:

success : bool 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” sub-directory 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

test

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.

Parameters:

label : {‘fast’, ‘full’, ‘’, attribute identifier}, optional 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’. verbose : int, optional Verbosity value for test outputs, in the range 1-10. Default is 1. extra_argv : list, optional List with any extra arguments to pass to nosetests. doctests : bool, optional If True, run doctests in module. Default is False. coverage : bool, optional If True, report coverage of NumPy code. Default is False. (This requires the `coverage module: <http://nedbatchelder.com/code/modules/coverage.html>`_). raise_warnings : None, str or sequence of warnings, optional 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 (), don’t raise on any warnings. The default is to use the class initialization value. timer : bool or int, optional Timing of individual tests with nose-timer (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:

result : object 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 
[]

warn

dipy.tracking._utils.warn()

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

Streamlines

dipy.tracking.benchmarks.bench_streamline.Streamlines

alias of nibabel.streamlines.array_sequence.ArraySequence

assert_array_almost_equal

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(desired-actual) < 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.

Parameters:	x : array_like The actual object to check. y : array_like The desired, expected object. decimal : int, optional Desired precision, default is 6. err_msg : str, optional The error message to be printed in case of failure. verbose : bool, optional If True, the conflicting values are appended to the error message.
Raises:	AssertionError 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)
...
<type 'exceptions.AssertionError'>:
AssertionError:
Arrays are not almost equal

(mismatch 50.0%)
 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)
<type 'exceptions.ValueError'>:
ValueError:
Arrays are not almost equal
 x: array([ 1.     ,  2.33333,      NaN])
 y: array([ 1.     ,  2.33333,  5.     ])

assert_array_equal

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

Parameters:	x : array_like The actual object to check. y : array_like The desired, expected object. err_msg : str, optional The error message to be printed in case of failure. verbose : bool, optional If True, the conflicting values are appended to the error message.
Raises:	AssertionError 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

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 inprecision with floats:

>>> np.testing.assert_array_equal([1.0,np.pi,np.nan],
...                               [1, np.sqrt(np.pi)**2, np.nan])
...
<type 'exceptions.ValueError'>:
AssertionError:
Arrays are not equal

(mismatch 50.0%)
 x: array([ 1.        ,  3.14159265,         NaN])
 y: array([ 1.        ,  3.14159265,         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=1e-10, atol=0)

bench_compress_streamlines

dipy.tracking.benchmarks.bench_streamline.bench_compress_streamlines()

bench_length

dipy.tracking.benchmarks.bench_streamline.bench_length()

bench_set_number_of_points

dipy.tracking.benchmarks.bench_streamline.bench_set_number_of_points()

compress_streamlines

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.

Parameters:

streamlines : one or a list of array-like of shape (N,3) Array representing x,y,z of N points in a streamline. tol_error : float (optional) 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. max_segment_length : float (optional) 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).

Returns:

compressed_streamlines : one or a list of array-like Results of the linearization process.

Notes

Be aware that compressed streamlines have variable step sizes. One needs to be careful when computing streamlines-based metrics [Houde15].

References

[Presseau15]

(1, 2, 3, 4, 5, 6) Presseau C. et al., A new compression format for fiber tracking datasets, NeuroImage, no 109, 73-83, 2015.

[Rheault15]

(1, 2) Rheault F. et al., Real Time Interaction with Millions of Streamlines, ISMRM, 2015.

[Houde15]

(1, 2) Houde J.-C. et al. How to Avoid Biased Streamlines-Based 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]

compress_streamlines_python

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.

generate_streamlines

dipy.tracking.benchmarks.bench_streamline.generate_streamlines(nb_streamlines, min_nb_points, max_nb_points, rng)

get_fnames

dipy.tracking.benchmarks.bench_streamline.get_fnames(name='small_64D')

provides filenames of some test datasets or other useful parametrisations

Parameters:

name : str 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

Returns:

fnames : tuple filenames for dataset

Examples

>>> import numpy as np
>>> from dipy.data import get_fnames
>>> fimg,fbvals,fbvecs=get_fnames('small_101D')
>>> bvals=np.loadtxt(fbvals)
>>> bvecs=np.loadtxt(fbvecs).T
>>> import nibabel as nib
>>> img=nib.load(fimg)
>>> data=img.get_data()
>>> data.shape == (6, 10, 10, 102)
True
>>> bvals.shape == (102,)
True
>>> bvecs.shape == (102, 3)
True

length

dipy.tracking.benchmarks.bench_streamline.length()

Euclidean length of streamlines

Length is in mm only if streamlines are expressed in world coordinates.

Parameters:	streamlines : ndarray or a list or 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.
Returns:	lengths : scalar or ndarray shape (N,) 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

length_python

dipy.tracking.benchmarks.bench_streamline.length_python(xyz, along=False)

measure

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 milli-seconds. If the code will execute fast on this timescale, it can be executed many times to get reasonable timing accuracy.

Parameters:	code_str : str The code to be timed. times : int, optional The number of times the code is executed. Default is 1. The code is only compiled once. label : str, optional A label to identify code_str with. This is passed into compile as the second argument (for run-time error messages).
Returns:	elapsed : float Total elapsed time in seconds for executing code_str times times.

Examples

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

set_number_of_points

dipy.tracking.benchmarks.bench_streamline.set_number_of_points()

Change the number of points of streamlines

(either by downsampling or upsampling)

Change the number of points of streamlines in order to obtain nb_points-1 segments of equal length. Points of streamlines will be modified along the curve.

Parameters:	streamlines : ndarray or a list or 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. nb_points : int integer representing number of points wanted along the curve.
Returns:	new_streamlines : ndarray or a list or 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 semi-circle:

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

set_number_of_points_python

dipy.tracking.benchmarks.bench_streamline.set_number_of_points_python(xyz, n_pols=3)

setup

dipy.tracking.benchmarks.bench_streamline.setup()

EuDX

class dipy.tracking.eudx.EuDX(a, ind, seeds, odf_vertices, a_low=0.0239, step_sz=0.5, ang_thr=60.0, length_thr=0.0, total_weight=0.5, max_points=1000, affine=None)

Bases: object

Euler Delta Crossings

Generates tracks with termination criteria defined by a delta function [1] and it has similarities with FACT algorithm [2] and Basser’s method but uses trilinear interpolation.

Can be used with any reconstruction method as DTI, DSI, QBI, GQI which can calculate an orientation distribution function and find the local peaks of that function. For example a single tensor model can give you only one peak a dual tensor model 2 peaks and quantitative anisotropy method as used in GQI can give you 3,4,5 or even more peaks.

The parameters of the delta function are checking thresholds for the direction propagation magnitude and the angle of propagation.

A specific number of seeds is defined randomly and then the tracks are generated for that seed if the delta function returns true.

Trilinear interpolation is being used for defining the weights of the propagation.

Notes

The coordinate system of the tractography is that of native space of image coordinates not native space world coordinates therefore voxel size is always considered as having size (1,1,1). Therefore, the origin is at the center of the center of the first voxel of the volume and all i,j,k coordinates start from the center of the voxel they represent.

References

[1]	(1, 2) Garyfallidis, Towards an accurate brain tractography, PhD thesis, University of Cambridge, 2012.

[2]	(1, 2) Mori et al. Three-dimensional tracking of axonal projections in the brain by magnetic resonance imaging. Ann. Neurol. 1999.

__init__(a, ind, seeds, odf_vertices, a_low=0.0239, step_sz=0.5, ang_thr=60.0, length_thr=0.0, total_weight=0.5, max_points=1000, affine=None)

Euler integration with multiple stopping criteria and supporting multiple multiple fibres in crossings [1].

Parameters:

a : array, Shape (I, J, K, Np), magnitude of the peak of a scalar anisotropic function e.g. QA (quantitative anisotropy) where Np is the number of peaks or a different function of shape (I, J, K) e.g FA or GFA. ind : array, shape(x, y, z, Np) indices of orientations of the scalar anisotropic peaks found on the resampling sphere seeds : int or ndarray If an int is specified then that number of random seeds is generated in the volume. If an (N, 3) array of points is given, each of the N points is used as a seed. Seed points should be given in the point space of the track (see affine). The latter is useful when you need to track from specific regions e.g. the white/gray matter interface or a specific ROI e.g. in the corpus callosum. odf_vertices : ndarray, shape (N, 3) sphere points which define a discrete representation of orientations for the peaks, the same for all voxels. Usually the same sphere is used as an input for a reconstruction algorithm e.g. DSI. a_low : float, optional low threshold for QA(typical 0.023) or FA(typical 0.2) or any other anisotropic function step_sz : float, optional euler propagation step size ang_thr : float, optional if turning angle is bigger than this threshold then tracking stops. total_weight : float, optional total weighting threshold max_points : int, optional maximum number of points in a track. Used to stop tracks from looping forever. affine : array (4, 4) optional An affine mapping from the voxel indices of the input data to the point space of the streamlines. That is if [x, y, z, 1] == point_space * [i, j, k, 1], then the streamline with point [x, y, z] passes though the center of voxel [i, j, k]. If no point_space is given, the point space will be in voxel coordinates.

Returns:

generator : obj By iterating this generator you can obtain all the streamlines.

Notes

This works as an iterator class because otherwise it could fill your entire memory if you generate many tracks. Something very common as you can easily generate millions of tracks if you have many seeds.

References

[1]	(1, 2) E. Garyfallidis (2012), “Towards an accurate brain tractography”, PhD thesis, University of Cambridge, UK.

Examples

>>> import nibabel as nib
>>> from dipy.reconst.dti import TensorModel, quantize_evecs
>>> from dipy.data import get_fnames, get_sphere
>>> from dipy.core.gradients import gradient_table
>>> fimg,fbvals,fbvecs = get_fnames('small_101D')
>>> img = nib.load(fimg)
>>> affine = img.affine
>>> data = img.get_data()
>>> gtab = gradient_table(fbvals, fbvecs)
>>> model = TensorModel(gtab)
>>> ten = model.fit(data)
>>> sphere = get_sphere('symmetric724')
>>> ind = quantize_evecs(ten.evecs, sphere.vertices)
>>> eu = EuDX(a=ten.fa, ind=ind, seeds=100, odf_vertices=sphere.vertices, a_low=.2)
>>> tracks = [e for e in eu]

eudx_both_directions

dipy.tracking.eudx.eudx_both_directions()

Parameters:

seed : array, float64 shape (3,) Point where the tracking starts. ref : cnp.npy_intp int Index of peak to follow first. qa : array, float64 shape (X, Y, Z, Np) Anisotropy matrix, where Np is the number of maximum allowed peaks. ind : array, float64 shape(x, y, z, Np) Index of the track orientation. odf_vertices : double array shape (N, 3) Sampling directions on the sphere. qa_thr : float Threshold for QA, we want everything higher than this threshold. ang_thr : float Angle threshold, we only select fiber orientation within this range. step_sz : double total_weight : double max_points : cnp.npy_intp

Returns:

track : array, shape (N,3)

get_sphere

dipy.tracking.eudx.get_sphere(name='symmetric362')

provide triangulated spheres

Parameters:	name : str which sphere - one of: * ‘symmetric362’ * ‘symmetric642’ * ‘symmetric724’ * ‘repulsion724’ * ‘repulsion100’ * ‘repulsion200’
Returns:	sphere : a dipy.core.sphere.Sphere class instance

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"

detect_corresponding_tracks

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

Parameters:	indices : sequence of indices of tracks1 that are to be detected in tracks2 tracks1 : sequence of tracks as arrays, shape (N1,3) .. (Nm,3) tracks2 : sequence of tracks as arrays, shape (M1,3) .. (Mm,3)
Returns:	track2track : array (N,2) where N is len(indices) of int 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)

detect_corresponding_tracks_plus

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

Parameters:	indices : sequence of indices of tracks1 that are to be detected in tracks2 tracks1 : sequence of tracks as arrays, shape (N1,3) .. (Nm,3) indices2 : sequence of indices of tracks2 in the initial brain tracks2 : sequence of tracks as arrays, shape (M1,3) .. (Mm,3)
Returns:	track2track : array (N,2) where N is len(indices) 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

class 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([gtab, S0])

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)

Parameters:	fiber_model : A FiberModel class instance params : the parameters derived from a fit of the model to the data.

predict(gtab=None, S0=None)

Predict the signal

Parameters:	gtab : GradientTable Default: use self.gtab S0 : float or array The non-diffusion-weighted signal in the voxels for which a prediction is made. Default: use self.b0_signal
Returns:	prediction : ndarray of shape (voxels, bvecs) An array with a prediction of the signal in each voxel/direction

FiberModel

class 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]_

[1] Pestilli, F., Yeatman, J, Rokem, A. Kay, K. and Wandell

B.A. (2014). Validation and statistical inference in living connectomes. Nature Methods.

Methods

fit(data, streamline[, affine, evals, sphere])	Fit the LiFE FiberModel for data and a set of streamlines associated with this data
setup(streamline, affine[, evals, sphere])	Set up the necessary components for the LiFE model: the matrix of fiber-contributions to the DWI signal, and the coordinates of voxels for which the equations will be solved

__init__(gtab)

Parameters:	gtab : a GradientTable class instance

fit(data, streamline, affine=None, evals=[0.001, 0, 0], sphere=None)

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

Parameters:

data : 4D array Diffusion-weighted data streamline : list A bunch of streamlines affine: 4 by 4 array (optional) The affine to go from the streamline coordinates to the data coordinates. Defaults to use np.eye(4) evals : list (optional) The eigenvalues of the tensor response function used in constructing the model signal. Default: [0.001, 0, 0] sphere: `dipy.core.Sphere` instance, or False Whether to approximate (and cache) the signal on a discrete sphere. This may confer a significant speed-up 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.

Returns:

FiberFit class instance

setup(streamline, affine, evals=[0.001, 0, 0], sphere=None)

Set up the necessary components for the LiFE model: the matrix of fiber-contributions to the DWI signal, and the coordinates of voxels for which the equations will be solved

Parameters:

streamline : list Streamlines, each is an array of shape (n, 3) affine : 4 by 4 array Mapping from the streamline coordinates to the data evals : list (3 items, optional) The eigenvalues of the canonical tensor used as a response function. Default:[0.001, 0, 0]. sphere: `dipy.core.Sphere` instance. Whether to approximate (and cache) the signal on a discrete sphere. This may confer a significant speed-up 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 724-vertex symmetric sphere from dipy.data

LifeSignalMaker

class 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

streamline_signal(streamline)

Approximate the signal for a given streamline

calc_signal

__init__(gtab, evals=[0.001, 0, 0], sphere=None)

Initialize a signal maker

Parameters:

gtab : GradientTable class instance The gradient table on which the signal is calculated. evals : list of 3 items The eigenvalues of the canonical tensor to use in calculating the signal. n_points : dipy.core.Sphere class instance 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

calc_signal(xyz)

streamline_signal(streamline)

Approximate the signal for a given streamline

ReconstFit

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

__init__(model, data)

Initialize self. See help(type(self)) for accurate signature.

ReconstModel

class dipy.tracking.life.ReconstModel(gtab)

Bases: object

Abstract class for signal reconstruction models

Methods

fit

__init__(gtab)

Initialization of the abstract class for signal reconstruction models

Parameters:	gtab : GradientTable class instance

fit(data, mask=None, **kwargs)

range

class dipy.tracking.life.range(stop) → range object

Bases: object

range(start, stop[, step]) -> range object

Return an object that produces a sequence of integers from start (inclusive) to stop (exclusive) by step. range(i, j) produces i, i+1, i+2, …, j-1. start defaults to 0, and stop is omitted! range(4) produces 0, 1, 2, 3. These are exactly the valid indices for a list of 4 elements. When step is given, it specifies the increment (or decrement).

Attributes:	start step stop

Methods

count(value)
index(value, [start, [stop]])	Raise ValueError if the value is not present.

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

count(value) → integer -- return number of occurrences of value

index(value[, start[, stop]]) → integer -- return index of value.

Raise ValueError if the value is not present.

start

step

stop

grad_tensor

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]

Parameters:	grad : 1d array of shape (3,) The spatial gradient (e.g between two nodes of a streamline). evals: 1d array of shape (3,) The eigenvalues of a canonical tensor to be used as a response function.

gradient

dipy.tracking.life.gradient(f)

Return the gradient of an N-dimensional 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.

Parameters:	f : array_like An N-dimensional array containing samples of a scalar function.
Returns:	gradient : ndarray N arrays of the same shape as f giving the derivative of f with respect to each dimension.

Examples

>>> x = np.array([1, 2, 4, 7, 11, 16], dtype=np.float)
>>> gradient(x)
array([ 1. ,  1.5,  2.5,  3.5,  4.5,  5. ])

>>> gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=np.float))
[array([[ 2.,  2., -1.],
       [ 2.,  2., -1.]]), array([[ 1. ,  2.5,  4. ],
       [ 1. ,  1. ,  1. ]])]

streamline_gradients

dipy.tracking.life.streamline_gradients(streamline)

Calculate the gradients of the streamline along the spatial dimension

Parameters:	streamline : array-like of shape (n, 3) The 3d coordinates of a single streamline
Returns:	Array of shape (3, n): Spatial gradients along the length of the streamline.

streamline_signal

dipy.tracking.life.streamline_signal(streamline, gtab, evals=[0.001, 0, 0])

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

Parameters:	streamline : a single streamline gtab : GradientTable class instance evals : list of length 3 (optional. Default: [0.001, 0, 0]) The eigenvalues of the canonical tensor used as an estimate of the signal generated by each node of the streamline.

streamline_tensors

dipy.tracking.life.streamline_tensors(streamline, evals=[0.001, 0, 0])

The tensors generated by this fiber.

Parameters:	streamline : array-like of shape (n, 3) The 3d coordinates of a single streamline evals : iterable with three entries The estimated eigenvalues of a single fiber tensor. (default: [0.001, 0, 0]).
Returns:	An n_nodes by 3 by 3 array with the tensor for each node in the fiber.

transform_streamlines

dipy.tracking.life.transform_streamlines(streamlines, mat, in_place=False)

Apply affine transformation to streamlines

Parameters:	streamlines : Streamlines Streamlines object mat : array, (4, 4) transformation matrix in_place : bool If True then change data in place. Be careful changes input streamlines.
Returns:	new_streamlines : Streamlines Sequence transformed 2D ndarrays of shape[-1]==3

unique_rows

dipy.tracking.life.unique_rows(in_array, dtype='f4')

This (quickly) finds the unique rows in an array

Parameters:	in_array: ndarray The array for which the unique rows should be found dtype: str, optional This determines the intermediate representation used for the values. Should at least preserve the values of the input array.
Returns:	u_return: ndarray Array with the unique rows of the original array.

voxel2streamline

dipy.tracking.life.voxel2streamline(streamline, transformed=False, affine=None, unique_idx=None)

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

Parameters:

streamline : list A collection of streamlines, each n by 3, with n being the number of nodes in the fiber. affine : 4 by 4 array (optional) Defines the spatial transformation from streamline to data. Default: np.eye(4) transformed : bool (optional) Whether the streamlines have been already transformed (in which case they don’t need to be transformed in here). unique_idx : array (optional). The unique indices in the streamlines

Returns:

v2f, v2fn : tuple of dicts The first dict in the tuple answers the question: Given a voxel (from the unique indices in this model), which fibers pass through it? The second answers the question: Given a streamline, for each voxel that this streamline passes through, which nodes of that streamline are in that voxel?

ActTissueClassifier

class dipy.tracking.local.ActTissueClassifier

Bases: dipy.tracking.local.tissue_classifier.ConstrainedTissueClassifier

Anatomically-Constrained Tractography (ACT) stopping criteria 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

[1]	(1, 2, 3) Smith, R. E., Tournier, J.-D., Calamante, F., & Connelly, A.

“Anatomically-constrained tractography: Improved diffusion MRI streamlines tractography through effective use of anatomical information.” NeuroImage, 63(3), 1924-1938, 2012.

Methods

from_pve

ConstrainedTissueClassifier from partial volume fraction (PVE) maps.

check_point
get_exclude
get_include

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

BinaryTissueClassifier

class dipy.tracking.local.BinaryTissueClassifier

Bases: dipy.tracking.local.tissue_classifier.TissueClassifier

cdef:

unsigned char[:, :, :] mask

Methods

check_point

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

CmcTissueClassifier

class dipy.tracking.local.CmcTissueClassifier

Bases: dipy.tracking.local.tissue_classifier.ConstrainedTissueClassifier

Continuous map criterion (CMC) stopping criteria from [1]. This implements the use of partial volume fraction (PVE) maps to determine when the tracking stops.

cdef:

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

[1]	(1, 2, 3) Girard, G., Whittingstall, K., Deriche, R., & Descoteaux, M.

“Towards quantitative connectivity analysis: reducing tractography biases.” NeuroImage, 98, 266-278, 2014.

Methods

from_pve

ConstrainedTissueClassifier from partial volume fraction (PVE) maps.

check_point
get_exclude
get_include

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

ConstrainedTissueClassifier

class dipy.tracking.local.ConstrainedTissueClassifier

Bases: dipy.tracking.local.tissue_classifier.TissueClassifier

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

cdef:

double interp_out_double[1] double[:] interp_out_view = interp_out_view double[:, :, :] include_map, exclude_map

Methods

from_pve

ConstrainedTissueClassifier from partial volume fraction (PVE) maps.

check_point
get_exclude
get_include

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

from_pve()

ConstrainedTissueClassifier from partial volume fraction (PVE) maps.

Parameters:	wm_map : array The partial volume fraction of white matter at each voxel. gm_map : array The partial volume fraction of gray matter at each voxel. csf_map : array The partial volume fraction of corticospinal fluid at each voxel.

get_exclude()

get_include()

DirectionGetter

class dipy.tracking.local.DirectionGetter

Bases: object

Methods

get_direction
initial_direction

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

get_direction()

initial_direction()

LocalTracking

class dipy.tracking.local.LocalTracking(direction_getter, tissue_classifier, seeds, affine, step_size, max_cross=None, maxlen=500, fixedstep=True, return_all=True, random_seed=None)

Bases: object

__init__(direction_getter, tissue_classifier, seeds, affine, step_size, max_cross=None, maxlen=500, fixedstep=True, return_all=True, random_seed=None)

Creates streamlines by using local fiber-tracking.

Parameters:

direction_getter : instance of DirectionGetter Used to get directions for fiber tracking. tissue_classifier : instance of TissueClassifier Identifies endpoints and invalid points to inform tracking. seeds : array (N, 3) Points to seed the tracking. Seed points should be given in point space of the track (see affine). affine : array (4, 4) 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 : float Step size used for tracking. max_cross : int or None The maximum number of direction to track from each seed in crossing voxels. By default all initial directions are tracked. maxlen : int Maximum number of steps to track from seed. Used to prevent infinite loops. fixedstep : bool If true, a fixed stepsize is used, otherwise a variable step size is used. return_all : bool If true, return all generated streamlines, otherwise only streamlines reaching end points or exiting the image. random_seed : int The seed for the random seed generator (numpy.random.seed and random.seed).

ParticleFilteringTracking

class dipy.tracking.local.ParticleFilteringTracking(direction_getter, tissue_classifier, 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)

Bases: dipy.tracking.local.localtracking.LocalTracking

__init__(direction_getter, tissue_classifier, 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)

A streamline generator using the particle filtering tractography method [1].

Parameters:

direction_getter : instance of ProbabilisticDirectionGetter Used to get directions for fiber tracking. tissue_classifier : instance of ConstrainedTissueClassifier Identifies endpoints and invalid points to inform tracking. seeds : array (N, 3) Points to seed the tracking. Seed points should be given in point space of the track (see affine). affine : array (4, 4) 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 : float Step size used for tracking. max_cross : int or None The maximum number of direction to track from each seed in crossing voxels. By default all initial directions are tracked. maxlen : int Maximum number of steps to track from seed. Used to prevent infinite loops. pft_back_tracking_dist : float 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. pft_front_tracking_dist : float 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. pft_max_trial : int Maximum number of trial for the particle filtering tractography (Prevents infinite loops). particle_count : int Number of particles to use in the particle filter. return_all : bool If true, return all generated streamlines, otherwise only streamlines reaching end points or exiting the image. random_seed : int The seed for the random seed generator (numpy.random.seed and random.seed).

References

[1]	(1, 2) Girard, G., Whittingstall, K., Deriche, R., & Descoteaux, M. Towards quantitative connectivity analysis: reducing tractography biases. NeuroImage, 98, 266-278, 2014.

ThresholdTissueClassifier

class dipy.tracking.local.ThresholdTissueClassifier

Bases: dipy.tracking.local.tissue_classifier.TissueClassifier

# Declarations from tissue_classifier.pxd bellow cdef:

double threshold, interp_out_double[1] double[:] interp_out_view = interp_out_view double[:, :, :] metric_map

Methods

check_point

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

TissueClassifier

class dipy.tracking.local.TissueClassifier

Bases: object

Methods

check_point

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

check_point()

Bunch

class dipy.tracking.local.localtracking.Bunch(**kwds)

Bases: object

__init__(**kwds)

A ‘bunch’ of values (a replacement of Enum)

This is a temporary replacement of Enum, which is not available on all versions of Python 2

ConstrainedTissueClassifier

class dipy.tracking.local.localtracking.ConstrainedTissueClassifier

Bases: dipy.tracking.local.tissue_classifier.TissueClassifier

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

cdef:

double interp_out_double[1] double[:] interp_out_view = interp_out_view double[:, :, :] include_map, exclude_map

Methods

from_pve

ConstrainedTissueClassifier from partial volume fraction (PVE) maps.

check_point
get_exclude
get_include

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

from_pve()

ConstrainedTissueClassifier from partial volume fraction (PVE) maps.

Parameters:	wm_map : array The partial volume fraction of white matter at each voxel. gm_map : array The partial volume fraction of gray matter at each voxel. csf_map : array The partial volume fraction of corticospinal fluid at each voxel.

get_exclude()

get_include()

LocalTracking

class dipy.tracking.local.localtracking.LocalTracking(direction_getter, tissue_classifier, seeds, affine, step_size, max_cross=None, maxlen=500, fixedstep=True, return_all=True, random_seed=None)

Bases: object

__init__(direction_getter, tissue_classifier, seeds, affine, step_size, max_cross=None, maxlen=500, fixedstep=True, return_all=True, random_seed=None)

Creates streamlines by using local fiber-tracking.

Parameters:

direction_getter : instance of DirectionGetter Used to get directions for fiber tracking. tissue_classifier : instance of TissueClassifier Identifies endpoints and invalid points to inform tracking. seeds : array (N, 3) Points to seed the tracking. Seed points should be given in point space of the track (see affine). affine : array (4, 4) 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 : float Step size used for tracking. max_cross : int or None The maximum number of direction to track from each seed in crossing voxels. By default all initial directions are tracked. maxlen : int Maximum number of steps to track from seed. Used to prevent infinite loops. fixedstep : bool If true, a fixed stepsize is used, otherwise a variable step size is used. return_all : bool If true, return all generated streamlines, otherwise only streamlines reaching end points or exiting the image. random_seed : int The seed for the random seed generator (numpy.random.seed and random.seed).

ParticleFilteringTracking

class dipy.tracking.local.localtracking.ParticleFilteringTracking(direction_getter, tissue_classifier, 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)

Bases: dipy.tracking.local.localtracking.LocalTracking

__init__(direction_getter, tissue_classifier, 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)

A streamline generator using the particle filtering tractography method [1].

Parameters:

direction_getter : instance of ProbabilisticDirectionGetter Used to get directions for fiber tracking. tissue_classifier : instance of ConstrainedTissueClassifier Identifies endpoints and invalid points to inform tracking. seeds : array (N, 3) Points to seed the tracking. Seed points should be given in point space of the track (see affine). affine : array (4, 4) 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 : float Step size used for tracking. max_cross : int or None The maximum number of direction to track from each seed in crossing voxels. By default all initial directions are tracked. maxlen : int Maximum number of steps to track from seed. Used to prevent infinite loops. pft_back_tracking_dist : float 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. pft_front_tracking_dist : float 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. pft_max_trial : int Maximum number of trial for the particle filtering tractography (Prevents infinite loops). particle_count : int Number of particles to use in the particle filter. return_all : bool If true, return all generated streamlines, otherwise only streamlines reaching end points or exiting the image. random_seed : int The seed for the random seed generator (numpy.random.seed and random.seed).

References

[1]	(1, 2) Girard, G., Whittingstall, K., Deriche, R., & Descoteaux, M. Towards quantitative connectivity analysis: reducing tractography biases. NeuroImage, 98, 266-278, 2014.

local_tracker

dipy.tracking.local.localtracking.local_tracker()

Tracks one direction from a seed.

This function is the main workhorse of the LocalTracking class defined in dipy.tracking.local.localtracking.

Parameters:

dg : DirectionGetter Used to choosing tracking directions. tc : TissueClassifier Used to check tissue type along path. seed_pos : array, float, 1d, (3,) First point of the (partial) streamline. first_step : array, float, 1d, (3,) Initial seeding direction. Used as prev_dir for selecting the step direction from the seed point. voxel_size : array, float, 1d, (3,) Size of voxels in the data set. streamline : array, float, 2d, (N, 3) Output of tracking will be put into this array. The length of this array, N, will set the maximum allowable length of the streamline. step_size : float Size of tracking steps in mm if fixed_step. fixedstep : bool If true, a fixed step_size is used, otherwise a variable step size is used.

Returns:

end : int Length of the tracked streamline tissue_class : TissueClass Ending state of the streamlines as determined by the TissueClassifier.

pft_tracker

dipy.tracking.local.localtracking.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.localtracking.

Parameters:

dg : DirectionGetter Used to choosing tracking directions. tc : TissueClassifier Used to check tissue type along path. seed_pos : array, float, 1d, (3,) First point of the (partial) streamline. first_step : array, float, 1d, (3,) Initial seeding direction. Used as prev_dir for selecting the step direction from the seed point. voxel_size : array, float, 1d, (3,) Size of voxels in the data set. streamline : array, float, 2d, (N, 3) Output of tracking will be put into this array. The length of this array, N, will set the maximum allowable length of the streamline. directions : array, float, 2d, (N, 3) 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. step_size : float Size of tracking steps in mm if fixed_step. pft_max_nbr_back_steps : int Number of tracking steps to back track before starting the particle filtering tractography. pft_max_nbr_front_steps : int Number of additional tracking steps to track. pft_max_trials : int Maximum number of trials for the particle filtering tractography (Prevents infinite loops). particle_count : int Number of particles to use in the particle filter. particle_paths : array, float, 4d, (2, particle_count, pft_max_steps, 3) Temporary array for paths followed by all particles. particle_dirs : array, float, 4d, (2, particle_count, pft_max_steps, 3) Temporary array for directions followed by particles. particle_weights : array, float, 1d (particle_count) Temporary array for the weights of particles. particle_steps : array, float, (2, particle_count) Temporary array for the number of steps of particles. particle_tissue_classes : array, float, (2, particle_count) Temporary array for the tissue classes of particles.

Returns:

end : int Length of the tracked streamline tissue_class : TissueClass Ending state of the streamlines as determined by the TissueClassifier.

xrange

dipy.tracking.metrics.xrange

alias of builtins.range

arbitrarypoint

dipy.tracking.metrics.arbitrarypoint(xyz, distance)

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

Parameters:	xyz : array-like shape (N,3) array representing x,y,z of N points in a track distance : float float representing distance travelled from the xyz[0] point of the curve along the curve.
Returns:	ap : array shape (3,) 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)

bytes

dipy.tracking.metrics.bytes(xyz)

Size of track in bytes.

Parameters:	xyz : array-like shape (N,3) Array representing x,y,z of N points in a track.
Returns:	b : int Number of bytes.

center_of_mass

dipy.tracking.metrics.center_of_mass(xyz)

Center of mass of streamline

Parameters:	xyz : array-like shape (N,3) array representing x,y,z of N points in a track
Returns:	com : array shape (3,) 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.])

downsample

dipy.tracking.metrics.downsample(xyz, n_pols=3)

downsample for a specific number of points along the curve/track

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

Parameters:	xyz : array-like shape (N,3) array representing x,y,z of N points in a track n_pol : int integer representing number of points (poles) we need along the curve.
Returns:	xyz2 : array shape (M,3) array representing x,y,z of M points that where extrapolated. M should be equal to n_pols

Examples

>>> import numpy as np
>>> # a semi-circle
>>> 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
>>> xyz2=downsample(xyz,3)
>>> # a cosine
>>> x=np.pi*np.linspace(0,1,100)
>>> y=np.cos(theta)
>>> z=0*y
>>> xyz=np.vstack((x,y,z)).T
>>> _= downsample(xyz,3)
>>> len(xyz2)
3
>>> xyz3=downsample(xyz,10)
>>> len(xyz3)
10

endpoint

dipy.tracking.metrics.endpoint(xyz)

Parameters:	xyz : array, shape(N,3) Track.
Returns:	ep : array, shape(3,) 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

frenet_serret

dipy.tracking.metrics.frenet_serret(xyz)

Frenet-Serret Space Curve Invariants

Calculates the 3 vector and 2 scalar invariants of a space curve defined by vectors r = (x,y,z). If z is omitted (i.e. the array xyz has shape (N,2)), then the curve is only 2D (planar), but the equations are still valid.

Similar to http://www.mathworks.com/matlabcentral/fileexchange/11169

In the following equations the prime (\('\)) indicates differentiation with respect to the parameter \(s\) of a parametrised curve \(\mathbf{r}(s)\).

• \(\mathbf{T}=\mathbf{r'}/|\mathbf{r'}|\qquad\) (Tangent vector)}
• \(\mathbf{N}=\mathbf{T'}/|\mathbf{T'}|\qquad\) (Normal vector)
• \(\mathbf{B}=\mathbf{T}\times\mathbf{N}\qquad\) (Binormal vector)
• \(\kappa=|\mathbf{T'}|\qquad\) (Curvature)
• \(\mathrm{\tau}=-\mathbf{B'}\cdot\mathbf{N}\) (Torsion)

Parameters:	xyz : array-like shape (N,3) array representing x,y,z of N points in a track
Returns:	T : array shape (N,3) array representing the tangent of the curve xyz N : array shape (N,3) array representing the normal of the curve xyz B : array shape (N,3) array representing the binormal of the curve xyz k : array shape (N,1) array representing the curvature of the curve xyz t : array shape (N,1) array representing the torsion of the curve xyz

Examples

Create a helix and calculate its tangent, normal, binormal, curvature and torsion

>>> from dipy.tracking import metrics as tm
>>> import numpy as np
>>> theta = 2*np.pi*np.linspace(0,2,100)
>>> x=np.cos(theta)
>>> y=np.sin(theta)
>>> z=theta/(2*np.pi)
>>> xyz=np.vstack((x,y,z)).T
>>> T,N,B,k,t=tm.frenet_serret(xyz)

generate_combinations

dipy.tracking.metrics.generate_combinations(items, n)

Combine sets of size n from items

Parameters:	items : sequence n : int
Returns:	ic : iterator

Examples

>>> from dipy.tracking.metrics import generate_combinations
>>> ic=generate_combinations(range(3),2)
>>> for i in ic: print(i)
[0, 1]
[0, 2]
[1, 2]

inside_sphere

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 \(|x-c|\le r\) where \(x\) a point \(c\) the center of the sphere and \(r\) the radius of the sphere.

Parameters:	xyz : array, shape (N,3) representing x,y,z of the N points of the track center : array, shape (3,) center of the sphere radius : float radius of the sphere
Returns:	tf : {True,False} Whether point is inside sphere.

Examples

>>> from dipy.tracking.metrics import inside_sphere
>>> line=np.array(([0,0,0],[1,1,1],[2,2,2]))
>>> sph_cent=np.array([1,1,1])
>>> sph_radius = 1
>>> inside_sphere(line,sph_cent,sph_radius)
True

inside_sphere_points

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 \(|x-c| \le r\) where \(x\) a point \(c\) the center of the sphere and \(r\) the radius of the sphere.

Parameters:	xyz : array, shape (N,3) representing x,y,z of the N points of the track center : array, shape (3,) center of the sphere radius : float radius of the sphere
Returns:	xyzn : array, shape(M,3) array representing x,y,z of the M points inside the sphere

Examples

>>> from dipy.tracking.metrics import inside_sphere_points
>>> line=np.array(([0,0,0],[1,1,1],[2,2,2]))
>>> sph_cent=np.array([1,1,1])
>>> sph_radius = 1
>>> inside_sphere_points(line,sph_cent,sph_radius)
array([[1, 1, 1]])

intersect_sphere

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

Parameters:	xyz : array, shape (N,3) representing x,y,z of the N points of the track center : array, shape (3,) center of the sphere radius : float radius of the sphere
Returns:	tf : {True, False} True if track xyz intersects sphere >>> from dipy.tracking.metrics import intersect_sphere >>> line=np.array(([0,0,0],[1,1,1],[2,2,2])) >>> sph_cent=np.array([1,1,1]) >>> sph_radius = 1 >>> intersect_sphere(line,sph_cent,sph_radius) True

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

length

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.

Parameters:	xyz : array-like shape (N,3) array representing x,y,z of N points in a track along : bool, optional If True, return array giving cumulative length along track, otherwise (default) return scalar giving total length.
Returns:	L : scalar or array shape (N-1,) 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])

longest_track_bundle

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.

Parameters:	bundle : sequence of tracks as arrays, shape (N1,3) … (Nm,3) sort : bool, optional If False (default) return longest track. If True, return length sorted indices for tracks in bundle
Returns:	longest_or_indices : array 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]...)