# tracking

Tracking objects

 Streamlines alias of nibabel.streamlines.array_sequence.ArraySequence bench Run benchmarks for module using nose. test Run tests for module using nose.

## Module: tracking._utils

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

## Module: 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
 Streamlines alias of nibabel.streamlines.array_sequence.ArraySequence assert_array_almost_equal(x, y[, decimal, …]) Raises an AssertionError if two objects are not equal up to desired precision. assert_array_equal(x, y[, err_msg, verbose]) Raises an AssertionError if two array_like objects are not equal. bench_compress_streamlines() bench_length() bench_set_number_of_points() compress_streamlines Compress streamlines by linearization as in [Presseau15]. compress_streamlines_python(streamline[, …]) Python version of the FiberCompression found on https://github.com/scilus/FiberCompression. generate_streamlines(nb_streamlines, …) get_fnames([name]) provides filenames of some test datasets or other useful parametrisations length Euclidean length of streamlines length_python(xyz[, along]) measure(code_str[, times, label]) Return elapsed time for executing code in the namespace of the caller. set_number_of_points Change the number of points of streamlines set_number_of_points_python(xyz[, n_pols]) setup()

## Module: tracking.eudx

EuDX(a, ind, seeds, odf_vertices[, a_low, …]) Euler Delta Crossings
eudx_both_directions
get_sphere([name]) provide triangulated spheres

## Module: tracking.learning

Learning algorithms for tractography

 detect_corresponding_tracks(indices, …) Detect corresponding tracks from list tracks1 to list tracks2 where tracks1 & tracks2 are lists of tracks detect_corresponding_tracks_plus(indices, …) Detect corresponding tracks from 1 to 2 where tracks1 & tracks2 are sequences of tracks

## Module: 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: 1058-1063. doi:10.1038/nmeth.3098

 FiberFit(fiber_model, life_matrix, …) A fit of the LiFE model to diffusion data FiberModel(gtab) A class for representing and solving predictive models based on tractography solutions. LifeSignalMaker(gtab[, evals, sphere]) A class for generating signals from streamlines in an efficient and speedy manner. ReconstFit(model, data) Abstract class which holds the fit result of ReconstModel ReconstModel(gtab) Abstract class for signal reconstruction models range(stop) range(start, stop[, step]) -> range object 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] gradient(f) Return the gradient of an N-dimensional array. streamline_gradients(streamline) Calculate the gradients of the streamline along the spatial dimension streamline_signal(streamline, gtab[, evals]) The signal from a single streamline estimate along each of its nodes. streamline_tensors(streamline[, evals]) The tensors generated by this fiber. transform_streamlines(streamlines, mat[, …]) Apply affine transformation to streamlines unique_rows(in_array[, dtype]) This (quickly) finds the unique rows in an array voxel2streamline(streamline[, transformed, …]) Maps voxels to streamlines and streamlines to voxels, for setting up the LiFE equations matrix

## Module: tracking.local

 ActTissueClassifier Anatomically-Constrained Tractography (ACT) stopping criteria from [1]. BinaryTissueClassifier cdef: CmcTissueClassifier Continuous map criterion (CMC) stopping criteria from [1]. ConstrainedTissueClassifier Abstract class that takes as input included and excluded tissue maps. DirectionGetter Methods LocalTracking(direction_getter, …[, …]) ParticleFilteringTracking(direction_getter, …) ThresholdTissueClassifier # Declarations from tissue_classifier.pxd bellow cdef: double threshold, interp_out_double[1] double[:] interp_out_view = interp_out_view double[:, :, :] metric_map TissueClassifier Methods

## Module: tracking.local.localtracking

 Bunch(**kwds) ConstrainedTissueClassifier Abstract class that takes as input included and excluded tissue maps. LocalTracking(direction_getter, …[, …]) ParticleFilteringTracking(direction_getter, …) local_tracker Tracks one direction from a seed. pft_tracker Tracks one direction from a seed using the particle filtering algorithm.

## Module: tracking.metrics

Metrics for tracks, where tracks are arrays of points

xrange alias of builtins.range
arbitrarypoint(xyz, distance) Select an arbitrary point along distance on the track (curve)
bytes(xyz) Size of track in bytes.
center_of_mass(xyz) Center of mass of streamline
downsample(xyz[, n_pols]) downsample for a specific number of points along the curve/track
endpoint(xyz)
frenet_serret(xyz) Frenet-Serret Space Curve Invariants
generate_combinations(items, n) Combine sets of size n from items
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.
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.
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
length(xyz[, along]) Euclidean length of track line
longest_track_bundle(bundle[, sort]) Return longest track or length sorted track indices in bundle
magn(xyz[, n]) magnitude of vector
mean_curvature(xyz) Calculates the mean curvature of a curve
mean_orientation(xyz) Calculates the mean orientation of a curve
midpoint(xyz) Midpoint of track
midpoint2point(xyz, p) Calculate distance from midpoint of a curve to arbitrary point p
principal_components(xyz) We use PCA to calculate the 3 principal directions for a track
splev(x, tck[, der, ext]) Evaluate a B-spline or its derivatives.
spline(xyz[, s, k, nest]) Generate B-splines as documented in http://www.scipy.org/Cookbook/Interpolation
splprep(x[, w, u, ub, ue, k, task, s, t, …]) Find the B-spline representation of an N-dimensional curve.
startpoint(xyz) First point of the track
winding(xyz) Total turning angle projected.

## Module: tracking.streamline

 LooseVersion([vstring]) Version numbering for anarchists and software realists. Streamlines alias of nibabel.streamlines.array_sequence.ArraySequence apply_affine(aff, pts) Apply affine matrix aff to points pts bundles_distances_mdf Calculate distances between list of tracks A and list of tracks B cdist(XA, XB[, metric]) Compute distance between each pair of the two collections of inputs. center_streamlines(streamlines) Move streamlines to the origin cluster_confidence(streamlines[, max_mdf, …]) Computes the cluster confidence index (cci), which is an estimation of the support a set of streamlines gives to a particular pathway. compress_streamlines Compress streamlines by linearization as in [Presseau15]. deepcopy(x[, memo, _nil]) Deep copy operation on arbitrary Python objects. deform_streamlines(streamlines, …) Apply deformation field to streamlines dist_to_corner(affine) Calculate the maximal distance from the center to a corner of a voxel, given an affine length Euclidean length of streamlines nbytes(streamlines) orient_by_rois(streamlines, roi1, roi2[, …]) Orient a set of streamlines according to a pair of ROIs orient_by_streamline(streamlines, standard) Orient a bundle of streamlines to a standard streamline. relist_streamlines(points, offsets) 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_by_rois(streamlines, rois, include[, …]) Select streamlines based on logical relations with several regions of interest (ROIs). select_random_set_of_streamlines(…[, rng]) Select a random set of streamlines set_number_of_points Change the number of points of streamlines streamline_near_roi(streamline, roi_coords, tol) Is a streamline near an ROI. transform_streamlines(streamlines, mat[, …]) Apply affine transformation to streamlines unlist_streamlines(streamlines) Return the streamlines not as a list but as an array and an offset values_from_volume(data, streamlines[, affine]) Extract values of a scalar/vector along each streamline from a volume. warn Issue a warning, or maybe ignore it or raise an exception.

## Module: 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.

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

 defaultdict defaultdict(default_factory[, …]) –> dict with default factory map map(func, *iterables) –> map object xrange alias of builtins.range affine_for_trackvis(voxel_size[, …]) Returns an affine which maps points for voxel indices to trackvis space. affine_from_fsl_mat_file(mat_affine, …) Converts an affine matrix from flirt (FSLdot) and a given voxel size for input and output images and returns an adjusted affine matrix for trackvis. apply_affine(aff, pts) Apply affine matrix aff to points pts asarray(a[, dtype, order]) Convert the input to an array. cdist(XA, XB[, metric]) Compute distance between each pair of the two collections of inputs. connectivity_matrix(streamlines, label_volume) Counts the streamlines that start and end at each label pair. density_map(streamlines, vol_dims[, …]) Counts the number of unique streamlines that pass through each voxel. dist_to_corner(affine) Calculate the maximal distance from the center to a corner of a voxel, given an affine dot(a, b[, out]) Dot product of two arrays. empty(shape[, dtype, order]) Return a new array of given shape and type, without initializing entries. eye(N[, M, k, dtype, order]) Return a 2-D array with ones on the diagonal and zeros elsewhere. flexi_tvis_affine(sl_vox_order, grid_affine, …) Computes the mapping from voxel indices to streamline points, get_flexi_tvis_affine(tvis_hdr, nii_aff) Computes the mapping from voxel indices to streamline points, length(streamlines[, affine]) Calculate the lengths of many streamlines in a bundle. minimum_at(a, indices[, b]) Performs unbuffered in place operation on operand ‘a’ for elements specified by ‘indices’. move_streamlines(streamlines, output_space) Applies a linear transformation, given by affine, to streamlines. ndbincount(x[, weights, shape]) Like bincount, but for nd-indicies. near_roi(streamlines, region_of_interest[, …]) Provide filtering criteria for a set of streamlines based on whether they fall within a tolerance distance from an ROI orientation_from_string(string_ornt) Returns an array representation of an ornt string ornt_mapping(ornt1, ornt2) Calculates the mapping needing to get from orn1 to orn2 path_length(streamlines, aoi, affine[, …]) Computes the shortest path, along any streamline, between aoi and each voxel. random_seeds_from_mask(mask[, seeds_count, …]) Creates randomly placed seeds for fiber tracking from a binary mask. ravel_multi_index(multi_index, dims[, mode, …]) Converts a tuple of index arrays into an array of flat indices, applying boundary modes to the multi-index. reduce_labels(label_volume) Reduces an array of labels to the integers from 0 to n with smallest possible n. reduce_rois(rois, include) Reduce multiple ROIs to one inclusion and one exclusion ROI reorder_voxels_affine(input_ornt, …) Calculates a linear transformation equivalent to changing voxel order. seeds_from_mask(mask[, density, voxel_size, …]) Creates seeds for fiber tracking from a binary mask. streamline_near_roi(streamline, roi_coords, tol) Is a streamline near an ROI. subsegment(streamlines, max_segment_length) Splits the segments of the streamlines into small segments. target(streamlines, target_mask, affine[, …]) Filters streamlines based on whether or not they pass through an ROI. target_line_based(streamlines, target_mask) Filters streamlines based on whether or not they pass through a ROI, using a line-based algorithm. unique_rows(in_array[, dtype]) This (quickly) finds the unique rows in an array warn Issue a warning, or maybe ignore it or raise an exception. wraps(wrapped[, assigned, updated]) Decorator factory to apply update_wrapper() to a wrapper function

### 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. 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: 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. 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. AssertionError If actual and desired are not equal up to specified precision.

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. AssertionError If actual and desired objects are not equal.

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_lengthmm). 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). 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 fnames : tuple filenames for dataset

Examples

>>> import numpy as np
>>> from dipy.data import get_fnames
>>> fimg,fbvals,fbvecs=get_fnames('small_101D')
>>> import nibabel as nib
>>> 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. 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). 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. 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. 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
>>> fimg,fbvals,fbvecs = get_fnames('small_101D')
>>> affine = img.affine
>>> data = img.get_data()
>>> 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 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’ 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) 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) 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

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)

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

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

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)
__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. copy() → a shallow copy of D. default_factory Factory for default value called by __missing__(). ### map class dipy.tracking.utils.map Bases: object map(func, *iterables) –> map object Make an iterator that computes the function using arguments from each of the iterables. Stops when the shortest iterable is exhausted. __init__($self, /, *args, **kwargs)

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

### xrange

dipy.tracking.utils.xrange

alias of builtins.range

### affine_for_trackvis

dipy.tracking.utils.affine_for_trackvis(voxel_size, voxel_order=None, dim=None, ref_img_voxel_order=None)

Returns an affine which maps points for voxel indices to trackvis space.

Parameters: voxel_size : array (3,) The sizes of the voxels in the reference image. affine : array (4, 4) Mapping from the voxel indices of the reference image to trackvis space.

### affine_from_fsl_mat_file

dipy.tracking.utils.affine_from_fsl_mat_file(mat_affine, input_voxsz, output_voxsz)

Converts an affine matrix from flirt (FSLdot) and a given voxel size for input and output images and returns an adjusted affine matrix for trackvis.

Parameters: mat_affine : array of shape (4, 4) An FSL flirt affine. input_voxsz : array of shape (3,) The input image voxel dimensions. output_voxsz : array of shape (3,) affine : array of shape (4, 4) A trackvis-compatible affine.

### apply_affine

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

Parameters: aff : (N, N) array-like Homogenous affine, for 3D points, will be 4 by 4. Contrary to first appearance, the affine will be applied on the left of pts. pts : (…, N-1) array-like Points, where the last dimension contains the coordinates of each point. For 3D, the last dimension will be length 3. transformed_pts : (…, N-1) array 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]]]...)


### asarray

dipy.tracking.utils.asarray(a, dtype=None, order=None)

Convert the input to an array.

Parameters: a : array_like 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. dtype : data-type, optional By default, the data-type is inferred from the input data. order : {‘C’, ‘F’}, optional Whether to use row-major (C-style) or column-major (Fortran-style) memory representation. Defaults to ‘C’. out : ndarray 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.

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


### cdist

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.

Parameters: XA : ndarray An $$m_A$$ by $$n$$ array of $$m_A$$ original observations in an $$n$$-dimensional space. Inputs are converted to float type. XB : ndarray An $$m_B$$ by $$n$$ array of $$m_B$$ original observations in an $$n$$-dimensional space. Inputs are converted to float type. metric : str or callable, optional The distance metric to use. If a string, the distance function can be ‘braycurtis’, ‘canberra’, ‘chebyshev’, ‘cityblock’, ‘correlation’, ‘cosine’, ‘dice’, ‘euclidean’, ‘hamming’, ‘jaccard’, ‘kulsinski’, ‘mahalanobis’, ‘matching’, ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’, ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, ‘wminkowski’, ‘yule’. *args : tuple. Deprecated. Additional arguments should be passed as keyword arguments **kwargs : dict, optional Extra arguments to metric: refer to each metric documentation for a list of all possible arguments. Some possible arguments: p : scalar The p-norm 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 Y : ndarray 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. ValueError An exception is thrown if XA and XB do not have the same number of columns.

Notes

The following are common calling conventions:

1. Y = cdist(XA, XB, 'euclidean')

Computes the distance between $$m$$ points using Euclidean distance (2-norm) as the distance metric between the points. The points are arranged as $$m$$ $$n$$-dimensional row vectors in the matrix X.

2. Y = cdist(XA, XB, 'minkowski', p=2.)

Computes the distances using the Minkowski distance $$||u-v||_p$$ ($$p$$-norm) where $$p \geq 1$$.

3. Y = cdist(XA, XB, 'cityblock')

Computes the city block or Manhattan distance between the points.

4. Y = cdist(XA, XB, 'seuclidean', V=None)

Computes the standardized Euclidean distance. The standardized Euclidean distance between two n-vectors u and v is

$\sqrt{\sum {(u_i-v_i)^2 / V[x_i]}}.$

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.

5. Y = cdist(XA, XB, 'sqeuclidean')

Computes the squared Euclidean distance $$||u-v||_2^2$$ between the vectors.

6. Y = cdist(XA, XB, 'cosine')

Computes the cosine distance between vectors u and v,

$1 - \frac{u \cdot v} {{||u||}_2 {||v||}_2}$

where $$||*||_2$$ is the 2-norm of its argument *, and $$u \cdot v$$ is the dot product of $$u$$ and $$v$$.

7. Y = cdist(XA, XB, 'correlation')

Computes the correlation distance between vectors u and v. This is

$1 - \frac{(u - \bar{u}) \cdot (v - \bar{v})} {{||(u - \bar{u})||}_2 {||(v - \bar{v})||}_2}$

where $$\bar{v}$$ is the mean of the elements of vector v, and $$x \cdot y$$ is the dot product of $$x$$ and $$y$$.

8. Y = cdist(XA, XB, 'hamming')

Computes the normalized Hamming distance, or the proportion of those vector elements between two n-vectors u and v which disagree. To save memory, the matrix X can be of type boolean.

9. 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 non-zero.

10. Y = cdist(XA, XB, 'chebyshev')

Computes the Chebyshev distance between the points. The Chebyshev distance between two n-vectors u and v is the maximum norm-1 distance between their respective elements. More precisely, the distance is given by

$d(u,v) = \max_i {|u_i-v_i|}.$
1. Y = cdist(XA, XB, 'canberra')

Computes the Canberra distance between the points. The Canberra distance between two points u and v is

$d(u,v) = \sum_i \frac{|u_i-v_i|} {|u_i|+|v_i|}.$
1. Y = cdist(XA, XB, 'braycurtis')

Computes the Bray-Curtis distance between the points. The Bray-Curtis distance between two points u and v is

$d(u,v) = \frac{\sum_i (|u_i-v_i|)} {\sum_i (|u_i+v_i|)}$
1. Y = cdist(XA, XB, 'mahalanobis', VI=None)
Computes the Mahalanobis distance between the points. The Mahalanobis distance between two points u and v is $$\sqrt{(u-v)(1/V)(u-v)^T}$$ where $$(1/V)$$ (the VI variable) is the inverse covariance. If VI is not None, VI will be used as the inverse covariance matrix.
1. Y = cdist(XA, XB, 'yule')
Computes the Yule distance between the boolean vectors. (see yule function documentation)
1. Y = cdist(XA, XB, 'matching')
Synonym for ‘hamming’.
1. Y = cdist(XA, XB, 'dice')
Computes the Dice distance between the boolean vectors. (see dice function documentation)
1. Y = cdist(XA, XB, 'kulsinski')
Computes the Kulsinski distance between the boolean vectors. (see kulsinski function documentation)
1. Y = cdist(XA, XB, 'rogerstanimoto')
Computes the Rogers-Tanimoto distance between the boolean vectors. (see rogerstanimoto function documentation)
1. Y = cdist(XA, XB, 'russellrao')
Computes the Russell-Rao distance between the boolean vectors. (see russellrao function documentation)
1. Y = cdist(XA, XB, 'sokalmichener')
Computes the Sokal-Michener distance between the boolean vectors. (see sokalmichener function documentation)
1. Y = cdist(XA, XB, 'sokalsneath')
Computes the Sokal-Sneath distance between the vectors. (see sokalsneath function documentation)
1. Y = cdist(XA, XB, 'wminkowski', p=2., w=w)
Computes the weighted Minkowski distance between the vectors. (see wminkowski function documentation)
1. Y = cdist(XA, XB, f)

Computes the distance between all pairs of vectors in X using the user supplied 2-arity function f. For example, Euclidean distance between the vectors could be computed as follows:

dm = cdist(XA, XB, lambda u, v: np.sqrt(((u-v)**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 pair-wise 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 2-D 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 3-D 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]])


### connectivity_matrix

dipy.tracking.utils.connectivity_matrix(streamlines, label_volume, voxel_size=None, affine=None, symmetric=True, return_mapping=False, mapping_as_streamlines=False)

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

Parameters: streamlines : sequence A sequence of streamlines. label_volume : ndarray An image volume with an integer data type, where the intensities in the volume map to anatomical structures. voxel_size : This argument is deprecated. affine : array_like (4, 4) The mapping from voxel coordinates to streamline coordinates. symmetric : bool, True by default Symmetric means we don’t distinguish between start and end points. If symmetric is True, matrix[i, j] == matrix[j, i]. return_mapping : bool, False by default If True, a mapping is returned which maps matrix indices to streamlines. mapping_as_streamlines : bool, False by default If True voxel indices map to lists of streamline objects. Otherwise voxel indices map to lists of integers. matrix : ndarray The number of connection between each pair of regions in label_volume. mapping : defaultdict(list) 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).

### density_map

dipy.tracking.utils.density_map(streamlines, vol_dims, voxel_size=None, affine=None)

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

Parameters: streamlines : iterable A sequence of streamlines. vol_dims : 3 ints The shape of the volume to be returned containing the streamlines counts voxel_size : This argument is deprecated. affine : array_like (4, 4) The mapping from voxel coordinates to streamline points. image_volume : ndarray, shape=vol_dims The number of streamline points in each voxel of volume. IndexError 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.

### dist_to_corner

dipy.tracking.utils.dist_to_corner(affine)

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

Parameters: affine : 4 by 4 array. The spatial transformation from the measurement to the scanner space. dist: float The maximal distance to the corner of a voxel, given voxel size encoded in the affine.

### dot

dipy.tracking.utils.dot(a, b, out=None)

Dot product of two arrays. Specifically,

• If both a and b are 1-D arrays, it is inner product of vectors (without complex conjugation).

• If both a and b are 2-D arrays, it is matrix multiplication, but using matmul() or a @ b is preferred.

• If either a or b is 0-D (scalar), it is equivalent to multiply() and using numpy.multiply(a, b) or a * b is preferred.

• If a is an N-D array and b is a 1-D array, it is a sum product over the last axis of a and b.

• If a is an N-D array and b is an M-D array (where M>=2), it is a sum product over the last axis of a and the second-to-last axis of b:

dot(a, b)[i,j,k,m] = sum(a[i,j,:] * b[k,:,m])

Parameters: a : array_like First argument. b : array_like Second argument. out : ndarray, optional Output argument. This must have the exact kind that would be returned if it was not used. In particular, it must have the right type, must be C-contiguous, and its dtype must be the dtype that would be returned for dot(a,b). This is a performance feature. Therefore, if these conditions are not met, an exception is raised, instead of attempting to be flexible. output : ndarray Returns the dot product of a and b. If a and b are both scalars or both 1-D arrays then a scalar is returned; otherwise an array is returned. If out is given, then it is returned. ValueError If the last dimension of a is not the same size as the second-to-last dimension of b.

vdot
Complex-conjugating dot product.
tensordot
Sum products over arbitrary axes.
einsum
Einstein summation convention.
matmul
‘@’ operator as method with out parameter.

Examples

>>> np.dot(3, 4)
12


Neither argument is complex-conjugated:

>>> np.dot([2j, 3j], [2j, 3j])
(-13+0j)


For 2-D arrays it is the matrix product:

>>> a = [[1, 0], [0, 1]]
>>> b = [[4, 1], [2, 2]]
>>> np.dot(a, b)
array([[4, 1],
[2, 2]])

>>> a = np.arange(3*4*5*6).reshape((3,4,5,6))
>>> b = np.arange(3*4*5*6)[::-1].reshape((5,4,6,3))
>>> np.dot(a, b)[2,3,2,1,2,2]
499128
>>> sum(a[2,3,2,:] * b[1,2,:,2])
499128


### empty

dipy.tracking.utils.empty(shape, dtype=float, order='C')

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

Parameters: shape : int or tuple of int Shape of the empty array, e.g., (2, 3) or 2. dtype : data-type, optional Desired output data-type for the array, e.g, numpy.int8. Default is numpy.float64. order : {‘C’, ‘F’}, optional, default: ‘C’ Whether to store multi-dimensional data in row-major (C-style) or column-major (Fortran-style) order in memory. out : ndarray Array of uninitialized (arbitrary) data of the given shape, dtype, and order. Object arrays will be initialized to None.

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.69583040e-309],
[  2.13182611e-314,   3.06959433e-309]])         #random

>>> np.empty([2, 2], dtype=int)
array([[-1073741821, -1067949133],
[  496041986,    19249760]])                     #random


### eye

dipy.tracking.utils.eye(N, M=None, k=0, dtype=<class 'float'>, order='C')

Return a 2-D array with ones on the diagonal and zeros elsewhere.

Parameters: N : int Number of rows in the output. M : int, optional Number of columns in the output. If None, defaults to N. k : int, optional Index of the diagonal: 0 (the default) refers to the main diagonal, a positive value refers to an upper diagonal, and a negative value to a lower diagonal. dtype : data-type, optional Data-type of the returned array. order : {‘C’, ‘F’}, optional Whether the output should be stored in row-major (C-style) or column-major (Fortran-style) order in memory. New in version 1.14.0. I : ndarray of shape (N,M) An array where all elements are equal to zero, except for the k-th diagonal, whose values are equal to one.

identity
(almost) equivalent function
diag
diagonal 2-D array from a 1-D array specified by the user.

Examples

>>> np.eye(2, dtype=int)
array([[1, 0],
[0, 1]])
>>> np.eye(3, k=1)
array([[ 0.,  1.,  0.],
[ 0.,  0.,  1.],
[ 0.,  0.,  0.]])


### flexi_tvis_affine

dipy.tracking.utils.flexi_tvis_affine(sl_vox_order, grid_affine, dim, voxel_size)
Computes the mapping from voxel indices to streamline points,
reconciling streamlines and grids with different voxel orders
Parameters: sl_vox_order : string of length 3 a string that describes the voxel order of the streamlines (ex: LPS) grid_affine : array (4, 4), An affine matrix describing the current space of the grid in relation to RAS+ scanner space dim : tuple of length 3 dimension of the grid voxel_size : array (3,0) voxel size of the grid flexi_tvis_aff : this affine maps between a grid and a trackvis space

### get_flexi_tvis_affine

dipy.tracking.utils.get_flexi_tvis_affine(tvis_hdr, nii_aff)
Computes the mapping from voxel indices to streamline points,
reconciling streamlines and grids with different voxel orders
Parameters: tvis_hdr : header from a trackvis file nii_aff : array (4, 4), An affine matrix describing the current space of the grid in relation to RAS+ scanner space nii_data : nd array 3D array, each with shape (x, y, z) corresponding to the shape of the brain volume. flexi_tvis_aff : array (4,4) this affine maps between a grid and a trackvis space

### length

dipy.tracking.utils.length(streamlines, affine=None)

Calculate the lengths of many streamlines in a bundle.

Parameters: streamlines : list Each item in the list is an array with 3D coordinates of a streamline. affine : 4 x 4 array An affine transformation to move the fibers by, before computing their lengths. Iterator object which then computes the length of each streamline in the bundle, upon iteration.

### minimum_at

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.

Parameters: a : array_like The array to perform in place operation on. indices : array_like or tuple 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. b : array_like 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])
>>> print(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)
>>> print(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])
>>> print(a)
array([2, 4, 3, 4])


### move_streamlines

dipy.tracking.utils.move_streamlines(streamlines, output_space, input_space=None)

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

Parameters: streamlines : sequence A set of streamlines to be transformed. output_space : array (4, 4) An affine matrix describing the target space to which the streamlines will be transformed. input_space : array (4, 4), optional An affine matrix describing the current space of the streamlines, if no input_space is specified, it’s assumed the streamlines are in the reference space. The reference space is the same as the space associated with the affine matrix np.eye(4). streamlines : generator A sequence of transformed streamlines.

### ndbincount

dipy.tracking.utils.ndbincount(x, weights=None, shape=None)

Like bincount, but for nd-indicies.

Parameters: x : array_like (N, M) M indices to a an Nd-array weights : array_like (M,), optional Weights associated with indices shape : optional the shape of the output

### near_roi

dipy.tracking.utils.near_roi(streamlines, region_of_interest, affine=None, tol=None, mode='any')

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

Parameters: streamlines : list or generator A sequence of streamlines. Each streamline should be a (N, 3) array, where N is the length of the streamline. region_of_interest : ndarray A mask used as a target. Non-zero values are considered to be within the target region. affine : ndarray Affine transformation from voxels to streamlines. Default: identity. tol : float 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. mode : string, optional 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 end-points is within tol from ROI “both_end” : both end points are within tol from ROI. 1D array of boolean dtype, shape (len(streamlines), ) This contains True for indices corresponding to each streamline that passes within a tolerance distance from the target ROI, False otherwise.

### orientation_from_string

dipy.tracking.utils.orientation_from_string(string_ornt)

Returns an array representation of an ornt string

### ornt_mapping

dipy.tracking.utils.ornt_mapping(ornt1, ornt2)

Calculates the mapping needing to get from orn1 to orn2

### path_length

dipy.tracking.utils.path_length(streamlines, aoi, affine, fill_value=-1)

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

Parameters: streamlines : seq of (N, 3) arrays A sequence of streamlines, path length is given in mm along the curve of the streamline. aoi : array, 3d A mask (binary array) of voxels from which to start computing distance. affine : array (4, 4) The mapping from voxel indices to streamline points. fill_value : float The value of voxel in the path length map that are not connected to the aoi. plm : array 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, seeds_count=1, seed_count_per_voxel=True, affine=None, random_seed=None)

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

Parameters: mask : binary 3d array_like A binary array specifying where to place the seeds for fiber tracking. seeds_count : int 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. seed_count_per_voxel: bool If True, seeds_count is per voxel, else seeds_count is the total number of seeds. affine : array, (4, 4) The mapping between voxel indices and the point space for seeds. 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]). random_seed : int The seed for the random seed generator (numpy.random.seed). ValueError When mask is not a three-dimensional array

Examples

>>> mask = np.zeros((3,3,3), 'bool')
... random_seed=1)
array([[-0.0640051 , -0.47407377,  0.04966248]])
... 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]])
... 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]])


### ravel_multi_index

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

Parameters: multi_index : tuple of array_like A tuple of integer arrays, one array for each dimension. dims : tuple of ints The shape of array into which the indices from multi_index apply. mode : {‘raise’, ‘wrap’, ‘clip’}, optional Specifies how out-of-bounds 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. order : {‘C’, ‘F’}, optional Determines whether the multi-index should be viewed as indexing in row-major (C-style) or column-major (Fortran-style) order. raveled_indices : ndarray An array of indices into the flattened version of an array of dimensions dims.

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


### reduce_labels

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


### reduce_rois

dipy.tracking.utils.reduce_rois(rois, include)

Reduce multiple ROIs to one inclusion and one exclusion ROI

Parameters: rois : list or ndarray 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). Non-zeros in each volume are considered to be within the region. include : array or list A list or 1D array of boolean marking inclusion or exclusion criteria. include_roi : boolean 3D array An array marking the inclusion mask. exclude_roi : boolean 3D array An array marking the exclusion mask

### reorder_voxels_affine

dipy.tracking.utils.reorder_voxels_affine(input_ornt, output_ornt, shape, voxel_size)

Calculates a linear transformation equivalent to changing voxel order.

Calculates a linear tranformation A such that [a, b, c, 1] = A[x, y, z, 1]. where [x, y, z] is a point in the coordinate system defined by input_ornt and [a, b, c] is the same point in the coordinate system defined by output_ornt.

Parameters: input_ornt : array (n, 2) A description of the orientation of a point in n-space. See nibabel.orientation or dipy.io.bvectxt for more information. output_ornt : array (n, 2) A description of the orientation of a point in n-space. shape : tuple of int Shape of the image in the input orientation. map = ornt_mapping(input_ornt, output_ornt) voxel_size : int Voxel size of the image in the input orientation. A : array (n+1, n+1) Affine matrix of the transformation between input_ornt and output_ornt.

dipy.tracking.utils.seeds_from_mask(mask, density=[1, 1, 1], voxel_size=None, affine=None)

Creates seeds for fiber tracking from a binary mask.

Seeds points are placed evenly distributed in all voxels of mask which are True.

Parameters: mask : binary 3d array_like A binary array specifying where to place the seeds for fiber tracking. density : int or array_like (3,) 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. voxel_size : This argument is deprecated. affine : array, (4, 4) The mapping between voxel indices and the point space for seeds. 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]). ValueError When mask is not a three-dimensional array

Examples

>>> mask = np.zeros((3,3,3), 'bool')
array([[ 0.5,  0.5,  0.5]])
array([[ 0.5       ,  0.25      ,  0.16666667],
[ 0.5       ,  0.75      ,  0.16666667],
[ 0.5       ,  0.25      ,  0.5       ],
[ 0.5       ,  0.75      ,  0.5       ],
[ 0.5       ,  0.25      ,  0.83333333],
[ 0.5       ,  0.75      ,  0.83333333]])
array([[ 0.55 ,  0.55 ,  0.625],
[ 0.55 ,  0.55 ,  1.875],
[ 0.55 ,  1.65 ,  5.625],
[ 0.55 ,  1.65 ,  6.875]])


### streamline_near_roi

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.

Parameters: streamline : array, shape (N, 3) A single streamline roi_coords : array, shape (M, 3) ROI coordinates transformed to the streamline coordinate frame. tol : float 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. mode : string 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 end-points is within tol from ROI “both_end” : both end points are within tol from ROI. out : boolean

### subsegment

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.

Parameters: streamlines : sequence of ndarrays The streamlines to be subsegmented. max_segment_length : float The longest allowable segment length. output_streamlines : generator 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. ]])]


### target

dipy.tracking.utils.target(streamlines, target_mask, affine, include=True)

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

Parameters: streamlines : iterable A sequence of streamlines. Each streamline should be a (N, 3) array, where N is the length of the streamline. target_mask : array-like A mask used as a target. Non-zero values are considered to be within the target region. affine : array (4, 4) The affine transform from voxel indices to streamline points. include : bool, default True If True, streamlines passing through target_mask are kept. If False, the streamlines not passing through target_mask are kept. streamlines : generator A sequence of streamlines that pass through target_mask. ValueError When the points of the streamlines lie outside of the target_mask.

### target_line_based

dipy.tracking.utils.target_line_based(streamlines, target_mask, affine=None, include=True)

Filters streamlines based on whether or not they pass through a ROI, using a line-based algorithm. Mostly used as a replacement of target for compressed streamlines.

This function never returns single-point streamlines, whatever the value of include.

Parameters: streamlines : iterable A sequence of streamlines. Each streamline should be a (N, 3) array, where N is the length of the streamline. target_mask : array-like A mask used as a target. Non-zero values are considered to be within the target region. affine : array (4, 4) The affine transform from voxel indices to streamline points. include : bool, default True If True, streamlines passing through target_mask are kept. If False, the streamlines not passing through target_mask are kept. streamlines : generator A sequence of streamlines that pass through target_mask.

References

[Bresenham5] Bresenham, Jack Elton. “Algorithm for computer control of a
digital plotter”, IBM Systems Journal, vol 4, no. 1, 1965.
[Houde15] Houde et al. How to avoid biased streamlines-based metrics for
streamlines with variable step sizes, ISMRM 2015.

### unique_rows

dipy.tracking.utils.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. u_return: ndarray Array with the unique rows of the original array.

### warn

dipy.tracking.utils.warn()

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

### wraps

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