tracking
¶
Tracking objects
Streamlines 
alias of ArraySequence 
bench 
Run benchmarks for module using nose. 
test 
Run tests for module using nose. 
Module: tracking.benchmarks
¶
Module: tracking.benchmarks.bench_streamline
¶
Benchmarks for functions related to streamline
Run all benchmarks with:
import dipy.tracking as dipytracking
dipytracking.bench()
If you have doctests enabled by default in nose (with a noserc file or environment variable), and you have a numpy version <= 1.6.1, this will also run the doctests, let’s hope they pass.
Run this benchmark with:
nosetests s –match ‘(?:^[b_.//])[Bb]ench’ bench_streamline.py
Streamlines 
alias of 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_data ([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 
detect_corresponding_tracks_plus (indices, ...) 
Detect corresponding tracks from 1 to 2 where tracks1 & tracks2 are 
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: 10581063. 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 object) 
range(start, stop[, step]) > range object 
grad_tensor (grad, evals) 
Calculate the 3 by 3 tensor for a given spatial gradient, given a canonical 
gradient (f) 
Return the gradient of an Ndimensional array. 
setup_test () 
Set numpy print options to “legacy” for new versions of numpy 
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 
Module: tracking.local
¶
ActTissueClassifier 
AnatomicallyConstrained Tractography (ACT) stopping criteria from [R480]. 
BinaryTissueClassifier 
cdef: 
CmcTissueClassifier 
Continuous map criterion (CMC) stopping criteria from [R481]. 
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 
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 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) 
FrenetSerret 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  
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  
setup_test () 
Set numpy print options to “legacy” for new versions of numpy  
splev (x, tck[, der, ext]) 
Evaluate a Bspline or its derivatives.  
spline (xyz[, s, k, nest]) 
Generate Bsplines as documented in  
splprep (x[, w, u, ub, ue, k, task, s, t, ...]) 
Find the Bspline representation of an Ndimensional curve.  
startpoint (xyz) 
First point of the track  
winding (xyz) 
Total turning angle projected. 
Module: tracking.streamline
¶
ArraySequence ([iterable, buffer_size]) 
Sequence of ndarrays having variable first dimension sizes. 
LooseVersion ([vstring]) 
Version numbering for anarchists and software realists. 
Streamlines (*args, **kwargs) 
Attributes 
apply_affine (aff, pts) 
Apply affine matrix aff to points pts 
cdist (XA, XB[, metric, p, V, VI, w]) 
Computes distance between each pair of the two collections of inputs. 
center_streamlines (streamlines) 
Move streamlines to the origin 
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, 
length 
Euclidean length of streamlines 
mul 
mul(a, b) – Same as a * b. 
nbytes (streamlines) 

orient_by_rois (streamlines, roi1, roi2[, ...]) 
Orient a set of streamlines according to a pair of ROIs 
reduce ((function, sequence[, initial]) > value) 
Apply a function of two arguments cumulatively to the items of a sequence, from left to right, so as to reduce the sequence to a single value. 
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 (...) 
Select a random set of streamlines 
set_number_of_points 
Change the number of points of streamlines 
setup_test () 
Set numpy print options to “legacy” for new versions of numpy 
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 AD 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 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, p, V, VI, w]) 
Computes 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, 
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]) 
Return a 2D 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 ndindicies. 
near_roi (streamlines, region_of_interest[, ...]) 
Provide filtering criteria for a set of streamlines based on whether 
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 multiindex. 
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. 
setup_test () 
Set numpy print options to “legacy” for new versions of numpy 
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 linebased 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
ArraySequence
bench¶

dipy.tracking.
bench
(self, 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 110. Default is 1.
extra_argv : list, optional
List with any extra arguments to pass to nosetests.
Returns: success : bool
Returns True if running the benchmarks works, False if an error occurred.
Notes
Benchmarks are like tests, but have names starting with “bench” instead of “test”, and can be found under the “benchmarks” subdirectory of the module.
Each NumPy module exposes bench in its namespace to run all benchmarks for it.
Examples
>>> success = np.lib.bench() Running benchmarks for numpy.lib ... using 562341 items: unique: 0.11 unique1d: 0.11 ratio: 1.0 nUnique: 56230 == 56230 ... OK
>>> success True
test¶

dipy.tracking.
test
(self, label='fast', verbose=1, extra_argv=None, doctests=False, coverage=False, raise_warnings=None)¶ 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 110. 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.
Returns: result : object
Returns the result of running the tests as a
nose.result.TextTestResult
object.Notes
Each NumPy module exposes test in its namespace to run all tests for it. For example, to run all tests for numpy.lib:
>>> np.lib.test()
Examples
>>> result = np.lib.test() Running unit tests for numpy.lib ... Ran 976 tests in 3.933s
OK
>>> result.errors [] >>> result.knownfail []
Streamlines
¶

dipy.tracking.benchmarks.bench_streamline.
Streamlines
¶ alias of
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
anddesired
satisfy.abs(desiredactual) < 1.5 * 10**(decimal)
That is a looser test than originally documented, but agrees with what the actual implementation did up to rounding vagaries. An exception is raised at shape mismatch or conflicting values. In contrast to the standard usage in numpy, NaNs are compared like numbers, no assertion is raised if both objects have NaNs in the same positions.
Parameters: x : array_like
The actual object to check.
y : array_like
The desired, expected object.
decimal : int, optional
Desired precision, default is 6.
err_msg : str, optional
The error message to be printed in case of failure.
verbose : bool, optional
If True, the conflicting values are appended to the error message.
Raises: AssertionError
If actual and desired are not equal up to specified precision.
See also
assert_allclose
 Compare two array_like objects for equality with desired relative and/or absolute precision.
assert_array_almost_equal_nulp
,assert_array_max_ulp
,assert_equal
Examples
the first assert does not raise an exception
>>> np.testing.assert_array_almost_equal([1.0,2.333,np.nan], [1.0,2.333,np.nan])
>>> np.testing.assert_array_almost_equal([1.0,2.33333,np.nan], ... [1.0,2.33339,np.nan], decimal=5) ... <type 'exceptions.AssertionError'>: AssertionError: Arrays are not almost equal (mismatch 50.0%) x: array([ 1. , 2.33333, NaN]) y: array([ 1. , 2.33339, NaN])
>>> np.testing.assert_array_almost_equal([1.0,2.33333,np.nan], ... [1.0,2.33333, 5], decimal=5) <type 'exceptions.ValueError'>: ValueError: Arrays are not almost equal x: array([ 1. , 2.33333, NaN]) y: array([ 1. , 2.33333, 5. ])
assert_array_equal¶

dipy.tracking.benchmarks.bench_streamline.
assert_array_equal
(x, y, err_msg='', verbose=True)¶ Raises an AssertionError if two array_like objects are not equal.
Given two array_like objects, check that the shape is equal and all elements of these objects are equal. An exception is raised at shape mismatch or conflicting values. In contrast to the standard usage in numpy, NaNs are compared like numbers, no assertion is raised if both objects have NaNs in the same positions.
The usual caution for verifying equality with floating point numbers is advised.
Parameters: x : array_like
The actual object to check.
y : array_like
The desired, expected object.
err_msg : str, optional
The error message to be printed in case of failure.
verbose : bool, optional
If True, the conflicting values are appended to the error message.
Raises: AssertionError
If actual and desired objects are not equal.
See also
assert_allclose
 Compare two array_like objects for equality with desired relative and/or absolute precision.
assert_array_almost_equal_nulp
,assert_array_max_ulp
,assert_equal
Examples
The first assert does not raise an exception:
>>> np.testing.assert_array_equal([1.0,2.33333,np.nan], ... [np.exp(0),2.33333, np.nan])
Assert fails with numerical inprecision with floats:
>>> np.testing.assert_array_equal([1.0,np.pi,np.nan], ... [1, np.sqrt(np.pi)**2, np.nan]) ... <type 'exceptions.ValueError'>: AssertionError: Arrays are not equal (mismatch 50.0%) x: array([ 1. , 3.14159265, NaN]) y: array([ 1. , 3.14159265, NaN])
Use assert_allclose or one of the nulp (number of floating point values) functions for these cases instead:
>>> np.testing.assert_allclose([1.0,np.pi,np.nan], ... [1, np.sqrt(np.pi)**2, np.nan], ... rtol=1e10, atol=0)
compress_streamlines¶

dipy.tracking.benchmarks.bench_streamline.
compress_streamlines
()¶ Compress streamlines by linearization as in [Presseau15].
The compression consists in merging consecutive segments that are nearly collinear. The merging is achieved by removing the point the two segments have in common.
The linearization process [Presseau15] ensures that every point being removed are within a certain margin (in mm) of the resulting streamline. Recommendations for setting this margin can be found in [Presseau15] (in which they called it tolerance error).
The compression also ensures that two consecutive points won’t be too far from each other (precisely less or equal than `max_segment_length`mm). This is a tradeoff to speed up the linearization process [Rheault15]. A low value will result in a faster linearization but low compression, whereas a high value will result in a slower linearization but high compression.
Parameters: streamlines : one or a list of arraylike of shape (N,3)
Array representing x,y,z of N points in a streamline.
tol_error : float (optional)
Tolerance error in mm (default: 0.01). A rule of thumb is to set it to 0.01mm for deterministic streamlines and 0.1mm for probabilitic streamlines.
max_segment_length : float (optional)
Maximum length in mm of any given segment produced by the compression. The default is 10mm. (In [Presseau15], they used a value of np.inf).
Returns: compressed_streamlines : one or a list of arraylike
Results of the linearization process.
Notes
Be aware that compressed streamlines have variable step sizes. One needs to be careful when computing streamlinesbased metrics [Houde15].
References
[Presseau15] Presseau C. et al., A new compression format for fiber tracking datasets, NeuroImage, no 109, 7383, 2015. [Rheault15] Rheault F. et al., Real Time Interaction with Millions of Streamlines, ISMRM, 2015. [Houde15] Houde J.C. et al. How to Avoid Biased StreamlinesBased Metrics for Streamlines with Variable Step Sizes, ISMRM, 2015. Examples
>>> from dipy.tracking.streamline import compress_streamlines >>> import numpy as np >>> # One streamline: a wiggling line >>> rng = np.random.RandomState(42) >>> streamline = np.linspace(0, 10, 100*3).reshape((100, 3)) >>> streamline += 0.2 * rng.rand(100, 3) >>> c_streamline = compress_streamlines(streamline, tol_error=0.2) >>> len(streamline) 100 >>> len(c_streamline) 10 >>> # Multiple streamlines >>> streamlines = [streamline, streamline[::2]] >>> c_streamlines = compress_streamlines(streamlines, tol_error=0.2) >>> [len(s) for s in streamlines] [100, 50] >>> [len(s) for s in c_streamlines] [10, 7]
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_data¶

dipy.tracking.benchmarks.bench_streamline.
get_data
(name='small_64D')¶ provides filenames of some test datasets or other useful parametrisations
Parameters: name : str
the filename/s of which dataset to return, one of: ‘small_64D’ small region of interest nifti,bvecs,bvals 64 directions ‘small_101D’ small region of interest nifti,bvecs,bvals 101 directions ‘aniso_vox’ volume with anisotropic voxel size as Nifti ‘fornix’ 300 tracks in Trackvis format (from Pittsburgh
Brain Competition)
 ‘gqi_vectors’ the scanner wave vectors needed for a GQI acquisitions
of 101 directions tested on Siemens 3T Trio
‘small_25’ small ROI (10x8x2) DTI data (b value 2000, 25 directions) ‘test_piesno’ slice of N=8, K=14 diffusion data ‘reg_c’ small 2D image used for validating registration ‘reg_o’ small 2D image used for validation registration ‘cb_2’ two vectorized cingulum bundles
Returns: fnames : tuple
filenames for dataset
Examples
>>> import numpy as np >>> from dipy.data import get_data >>> fimg,fbvals,fbvecs=get_data('small_101D') >>> bvals=np.loadtxt(fbvals) >>> bvecs=np.loadtxt(fbvecs).T >>> import nibabel as nib >>> img=nib.load(fimg) >>> data=img.get_data() >>> data.shape == (6, 10, 10, 102) True >>> bvals.shape == (102,) True >>> bvecs.shape == (102, 3) True
length¶

dipy.tracking.benchmarks.bench_streamline.
length
()¶ Euclidean length of streamlines
Length is in mm only if streamlines are expressed in world coordinates.
Parameters: streamlines : ndarray or a list or
dipy.tracking.Streamlines
If ndarray, must have shape (N,3) where N is the number of points of the streamline. If list, each item must be ndarray shape (Ni,3) where Ni is the number of points of streamline i. If
dipy.tracking.Streamlines
, its common_shape must be 3.Returns: lengths : scalar or ndarray shape (N,)
If there is only one streamline, a scalar representing the length of the streamline. If there are several streamlines, ndarray containing the length of every streamline.
Examples
>>> from dipy.tracking.streamline import length >>> import numpy as np >>> streamline = np.array([[1, 1, 1], [2, 3, 4], [0, 0, 0]]) >>> expected_length = np.sqrt([1+2**2+3**2, 2**2+3**2+4**2]).sum() >>> length(streamline) == expected_length True >>> streamlines = [streamline, np.vstack([streamline, streamline[::1]])] >>> expected_lengths = [expected_length, 2*expected_length] >>> lengths = [length(streamlines[0]), length(streamlines[1])] >>> np.allclose(lengths, expected_lengths) True >>> length([]) 0.0 >>> length(np.array([[1, 2, 3]])) 0.0
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 milliseconds. 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 runtime error messages).Returns: elapsed : float
Total elapsed time in seconds for executing code_str times times.
Examples
>>> etime = np.testing.measure('for i in range(1000): np.sqrt(i**2)', ... times=times) >>> print("Time for a single execution : ", etime / times, "s") Time for a single execution : 0.005 s
set_number_of_points¶

dipy.tracking.benchmarks.bench_streamline.
set_number_of_points
()¶  Change the number of points of streamlines
 (either by downsampling or upsampling)
Change the number of points of streamlines in order to obtain nb_points1 segments of equal length. Points of streamlines will be modified along the curve.
Parameters: streamlines : ndarray or a list or
dipy.tracking.Streamlines
If ndarray, must have shape (N,3) where N is the number of points of the streamline. If list, each item must be ndarray shape (Ni,3) where Ni is the number of points of streamline i. If
dipy.tracking.Streamlines
, its common_shape must be 3.nb_points : int
integer representing number of points wanted along the curve.
Returns: new_streamlines : ndarray or a list or
dipy.tracking.Streamlines
Results of the downsampling or upsampling process.
Examples
>>> from dipy.tracking.streamline import set_number_of_points >>> import numpy as np
One streamline, a semicircle:
>>> theta = np.pi*np.linspace(0, 1, 100) >>> x = np.cos(theta) >>> y = np.sin(theta) >>> z = 0 * x >>> streamline = np.vstack((x, y, z)).T >>> modified_streamline = set_number_of_points(streamline, 3) >>> len(modified_streamline) 3
Multiple streamlines:
>>> streamlines = [streamline, streamline[::2]] >>> new_streamlines = set_number_of_points(streamlines, 10) >>> [len(s) for s in streamlines] [100, 50] >>> [len(s) for s in new_streamlines] [10, 10]
set_number_of_points_python¶

dipy.tracking.benchmarks.bench_streamline.
set_number_of_points_python
(xyz, n_pols=3)¶
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 [R488] and it has similarities with FACT algorithm [R489] 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
[R488] (1, 2) Garyfallidis, Towards an accurate brain tractography, PhD thesis, University of Cambridge, 2012. [R489] (1, 2) Mori et al. Threedimensional 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 [R490].
Parameters: a : array,
Shape (I, J, K, Np), magnitude of the peak of a scalar anisotropic function e.g. QA (quantitative anisotropy) where Np is the number of peaks or a different function of shape (I, J, K) e.g FA or GFA.
ind : array, shape(x, y, z, Np)
indices of orientations of the scalar anisotropic peaks found on the resampling sphere
seeds : int or ndarray
If an int is specified then that number of random seeds is generated in the volume. If an (N, 3) array of points is given, each of the N points is used as a seed. Seed points should be given in the point space of the track (see
affine
). The latter is useful when you need to track from specific regions e.g. the white/gray matter interface or a specific ROI e.g. in the corpus callosum.odf_vertices : ndarray, shape (N, 3)
sphere points which define a discrete representation of orientations for the peaks, the same for all voxels. Usually the same sphere is used as an input for a reconstruction algorithm e.g. DSI.
a_low : float, optional
low threshold for QA(typical 0.023) or FA(typical 0.2) or any other anisotropic function
step_sz : float, optional
euler propagation step size
ang_thr : float, optional
if turning angle is bigger than this threshold then tracking stops.
total_weight : float, optional
total weighting threshold
max_points : int, optional
maximum number of points in a track. Used to stop tracks from looping forever.
affine : array (4, 4) optional
An affine mapping from the voxel indices of the input data to the point space of the streamlines. That is if
[x, y, z, 1] == point_space * [i, j, k, 1]
, then the streamline with point[x, y, z]
passes though the center of voxel[i, j, k]
. If no point_space is given, the point space will be in voxel coordinates.Returns: generator : obj
By iterating this generator you can obtain all the streamlines.
Notes
This works as an iterator class because otherwise it could fill your entire memory if you generate many tracks. Something very common as you can easily generate millions of tracks if you have many seeds.
References
[R490] (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_data, get_sphere >>> from dipy.core.gradients import gradient_table >>> fimg,fbvals,fbvecs = get_data('small_101D') >>> img = nib.load(fimg) >>> affine = img.affine >>> data = img.get_data() >>> gtab = gradient_table(fbvals, fbvecs) >>> model = TensorModel(gtab) >>> ten = model.fit(data) >>> sphere = get_sphere('symmetric724') >>> ind = quantize_evecs(ten.evecs, sphere.vertices) >>> eu = EuDX(a=ten.fa, ind=ind, seeds=100, odf_vertices=sphere.vertices, a_low=.2) >>> tracks = [e for e in eu]

eudx_both_directions¶

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

dipy.tracking.eudx.
get_sphere
(name='symmetric362')¶ provide triangulated spheres
Parameters: name : str
which sphere  one of: * ‘symmetric362’ * ‘symmetric642’ * ‘symmetric724’ * ‘repulsion724’ * ‘repulsion100’ * ‘repulsion200’
Returns: sphere : a dipy.core.sphere.Sphere class instance
Examples
>>> import numpy as np >>> from dipy.data import get_sphere >>> sphere = get_sphere('symmetric362') >>> verts, faces = sphere.vertices, sphere.faces >>> verts.shape == (362, 3) True >>> faces.shape == (720, 3) True >>> verts, faces = get_sphere('not a sphere name') Traceback (most recent call last): ... DataError: No sphere called "not a sphere name"
detect_corresponding_tracks¶

dipy.tracking.learning.
detect_corresponding_tracks
(indices, tracks1, tracks2)¶ Detect corresponding tracks from list tracks1 to list tracks2 where tracks1 & tracks2 are lists of tracks
Parameters: indices : sequence
of indices of tracks1 that are to be detected in tracks2
tracks1 : sequence
of tracks as arrays, shape (N1,3) .. (Nm,3)
tracks2 : sequence
of tracks as arrays, shape (M1,3) .. (Mm,3)
Returns: track2track : array (N,2) where N is len(indices) of int
it shows the correspondance in the following way: the first column is the current index in tracks1 the second column is the corresponding index in tracks2
Notes
To find the corresponding tracks we use mam_distances with ‘avg’ option. Then we calculate the argmin of all the calculated distances and return it for every index. (See 3rd column of arr in the example given below.)
Examples
>>> import numpy as np >>> import dipy.tracking.learning as tl >>> A = np.array([[0, 0, 0], [1, 1, 1], [2, 2, 2]]) >>> B = np.array([[1, 0, 0], [2, 0, 0], [3, 0, 0]]) >>> C = np.array([[0, 0, 1], [0, 0, 2], [0, 0, 3]]) >>> bundle1 = [A, B, C] >>> bundle2 = [B, A] >>> indices = [0, 1] >>> arr = tl.detect_corresponding_tracks(indices, bundle1, bundle2)
detect_corresponding_tracks_plus¶

dipy.tracking.learning.
detect_corresponding_tracks_plus
(indices, tracks1, indices2, tracks2)¶ Detect corresponding tracks from 1 to 2 where tracks1 & tracks2 are sequences of tracks
Parameters: indices : sequence
of indices of tracks1 that are to be detected in tracks2
tracks1 : sequence
of tracks as arrays, shape (N1,3) .. (Nm,3)
indices2 : sequence
of indices of tracks2 in the initial brain
tracks2 : sequence
of tracks as arrays, shape (M1,3) .. (Mm,3)
Returns: track2track : array (N,2) where N is len(indices)
of int showing the correspondance in th following way the first colum is the current index of tracks1 the second column is the corresponding index in tracks2
See also
distances.mam_distances
Notes
To find the corresponding tracks we use mam_distances with ‘avg’ option. Then we calculate the argmin of all the calculated distances and return it for every index. (See 3rd column of arr in the example given below.)
Examples
>>> import numpy as np >>> import dipy.tracking.learning as tl >>> A = np.array([[0, 0, 0], [1, 1, 1], [2, 2, 2]]) >>> B = np.array([[1, 0, 0], [2, 0, 0], [3, 0, 0]]) >>> C = np.array([[0, 0, 1], [0, 0, 2], [0, 0, 3]]) >>> bundle1 = [A, B, C] >>> bundle2 = [B, A] >>> indices = [0, 1] >>> indices2 = indices >>> arr = tl.detect_corresponding_tracks_plus(indices, bundle1, indices2, bundle2)
FiberFit
¶

class
dipy.tracking.life.
FiberFit
(fiber_model, life_matrix, vox_coords, to_fit, beta, weighted_signal, b0_signal, relative_signal, mean_sig, vox_data, streamline, affine, evals)¶ Bases:
dipy.reconst.base.ReconstFit
A fit of the LiFE model to diffusion data
Methods
predict
([gtab, S0])Predict the signal 
__init__
(fiber_model, life_matrix, vox_coords, to_fit, beta, weighted_signal, b0_signal, relative_signal, mean_sig, vox_data, streamline, affine, evals)¶ Parameters: fiber_model : A FiberModel class instance
params : the parameters derived from a fit of the model to the data.

predict
(gtab=None, S0=None)¶ Predict the signal
Parameters: gtab : GradientTable
Default: use self.gtab
S0 : float or array
The nondiffusionweighted signal in the voxels for which a prediction is made. Default: use self.b0_signal
Returns: prediction : ndarray of shape (voxels, bvecs)
An array with a prediction of the signal in each voxel/direction

FiberModel
¶

class
dipy.tracking.life.
FiberModel
(gtab)¶ Bases:
dipy.reconst.base.ReconstModel
A class for representing and solving predictive models based on tractography solutions.
Notes
This is an implementation of the LiFE model described in [1]_
 [1] Pestilli, F., Yeatman, J, Rokem, A. Kay, K. and Wandell
 B.A. (2014). Validation and statistical inference in living connectomes. Nature Methods.
Methods
fit
(data, streamline[, affine, evals, sphere])Fit the LiFE FiberModel for data and a set of streamlines associated setup
(streamline, affine[, evals, sphere])Set up the necessary components for the LiFE model: the matrix of 
__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
Diffusionweighted 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 speedup in setting up the problem, but is not as accurate. If False, we use the exact gradients along the streamlines to calculate the matrix, instead of an approximation.
Returns: FiberFit class instance

setup
(streamline, affine, evals=[0.001, 0, 0], sphere=None)¶ Set up the necessary components for the LiFE model: the matrix of fibercontributions 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 speedup in setting up the problem, but is not as accurate. If False, we use the exact gradients along the streamlines to calculate the matrix, instead of an approximation. Defaults to use the 724vertex symmetric sphere from
dipy.data
LifeSignalMaker
¶

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
calc_signal
(xyz)streamline_signal
(streamline)Approximate the signal for a given streamline 
__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

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, ..., j1. 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).
Methods
count
(...)index
((value, [start, ...)Raise ValueError if the value is not present. 
__init__
()¶ 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 Ndimensional array.
The gradient is computed using central differences in the interior and first differences at the boundaries. The returned gradient hence has the same shape as the input array.
Parameters: f : array_like
An Ndimensional array containing samples of a scalar function.
Returns: gradient : ndarray
N arrays of the same shape as f giving the derivative of f with respect to each dimension.
Examples
>>> x = np.array([1, 2, 4, 7, 11, 16], dtype=np.float) >>> gradient(x) array([ 1. , 1.5, 2.5, 3.5, 4.5, 5. ])
>>> gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=np.float)) [array([[ 2., 2., 1.], [ 2., 2., 1.]]), array([[ 1. , 2.5, 4. ], [ 1. , 1. , 1. ]])]
setup_test¶

dipy.tracking.life.
setup_test
()¶ Set numpy print options to “legacy” for new versions of numpy
If imported into a file, nosetest will run this before any doctests.
References
https://github.com/numpy/numpy/commit/710e0327687b9f7653e5ac02d222ba62c657a718 https://github.com/numpy/numpy/commit/734b907fc2f7af6e40ec989ca49ee6d87e21c495 https://github.com/nipy/nibabel/pull/556
streamline_gradients¶

dipy.tracking.life.
streamline_gradients
(streamline)¶ Calculate the gradients of the streamline along the spatial dimension
Parameters: streamline : arraylike of shape (n, 3)
The 3d coordinates of a single streamline
Returns: Array of shape (3, n): Spatial gradients along the length of the
streamline.
streamline_signal¶

dipy.tracking.life.
streamline_signal
(streamline, gtab, evals=[0.001, 0, 0])¶ The signal from a single streamline estimate along each of its nodes.
Parameters: streamline : a single streamline
gtab : GradientTable class instance
evals : list of length 3 (optional. Default: [0.001, 0, 0])
The eigenvalues of the canonical tensor used as an estimate of the signal generated by each node of the streamline.
streamline_tensors¶

dipy.tracking.life.
streamline_tensors
(streamline, evals=[0.001, 0, 0])¶ The tensors generated by this fiber.
Parameters: streamline : arraylike of shape (n, 3)
The 3d coordinates of a single streamline
evals : iterable with three entries
The estimated eigenvalues of a single fiber tensor. (default: [0.001, 0, 0]).
Returns: An n_nodes by 3 by 3 array with the tensor for each node in the fiber.
transform_streamlines¶

dipy.tracking.life.
transform_streamlines
(streamlines, mat)¶ Apply affine transformation to streamlines
Parameters: streamlines : list
List of 2D ndarrays of shape[1]==3
mat : array, (4, 4)
transformation matrix
Returns: new_streamlines : list
List of the transformed 2D ndarrays of shape[1]==3
unique_rows¶

dipy.tracking.life.
unique_rows
(in_array, dtype='f4')¶ This (quickly) finds the unique rows in an array
Parameters: in_array: ndarray
The array for which the unique rows should be found
dtype: str, optional
This determines the intermediate representation used for the values. Should at least preserve the values of the input array.
Returns: u_return: ndarray
Array with the unique rows of the original array.
voxel2streamline¶

dipy.tracking.life.
voxel2streamline
(streamline, transformed=False, affine=None, unique_idx=None)¶ Maps voxels to streamlines and streamlines to voxels, for setting up the LiFE equations matrix
Parameters: streamline : list
A collection of streamlines, each n by 3, with n being the number of nodes in the fiber.
affine : 4 by 4 array (optional)
Defines the spatial transformation from streamline to data. Default: np.eye(4)
transformed : bool (optional)
Whether the streamlines have been already transformed (in which case they don’t need to be transformed in here).
unique_idx : array (optional).
The unique indices in the streamlines
Returns: v2f, v2fn : tuple of dicts
The first dict in the tuple answers the question: Given a voxel (from
the unique indices in this model), which fibers pass through it?
The second answers the question: Given a streamline, for each voxel that
this streamline passes through, which nodes of that streamline are in that
voxel?
ActTissueClassifier
¶

class
dipy.tracking.local.
ActTissueClassifier
¶ Bases:
dipy.tracking.local.tissue_classifier.ConstrainedTissueClassifier
AnatomicallyConstrained Tractography (ACT) stopping criteria from [R491]. This implements the use of partial volume fraction (PVE) maps to determine when the tracking stops. The proposed ([R491]) 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[R491] (1, 2) Smith, R. E., Tournier, J.D., Calamante, F., & Connelly, A. “Anatomicallyconstrained tractography: Improved diffusion MRI streamlines tractography through effective use of anatomical information.” NeuroImage, 63(3), 19241938, 2012.
Methods
check_point
from_pve
ConstrainedTissueClassifier from partial volume fraction (PVE) maps. get_exclude
get_include

__init__
()¶ 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 [R492]. 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
[R492] (1, 2) Girard, G., Whittingstall, K., Deriche, R., & Descoteaux, M. “Towards quantitative connectivity analysis: reducing tractography biases.” NeuroImage, 98, 266278, 2014.
Methods
check_point
from_pve
ConstrainedTissueClassifier from partial volume fraction (PVE) maps. get_exclude
get_include

__init__
()¶ 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
check_point
from_pve
ConstrainedTissueClassifier from partial volume fraction (PVE) maps. get_exclude
get_include

__init__
()¶ 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__
()¶ 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)¶ Bases:
object

__init__
(direction_getter, tissue_classifier, seeds, affine, step_size, max_cross=None, maxlen=500, fixedstep=True, return_all=True)¶ Creates streamlines by using local fibertracking.
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.

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)¶ Bases:
dipy.tracking.local.localtracking.LocalTracking

__init__
(direction_getter, tissue_classifier, seeds, affine, step_size, max_cross=None, maxlen=500, pft_back_tracking_dist=2, pft_front_tracking_dist=1, pft_max_trial=20, particle_count=15, return_all=True)¶ A streamline generator using the particle filtering tractography method [R493].
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.
References
[R493] (1, 2) Girard, G., Whittingstall, K., Deriche, R., & Descoteaux, M. Towards quantitative connectivity analysis: reducing tractography biases. NeuroImage, 98, 266278, 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_mapMethods
check_point

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

TissueClassifier
¶

class
dipy.tracking.local.
TissueClassifier
¶ Bases:
object
Methods
check_point

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

check_point
()¶

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
check_point
from_pve
ConstrainedTissueClassifier from partial volume fraction (PVE) maps. get_exclude
get_include

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

from_pve
()¶ ConstrainedTissueClassifier from partial volume fraction (PVE) maps.
Parameters: wm_map : array
The partial volume fraction of white matter at each voxel.
gm_map : array
The partial volume fraction of gray matter at each voxel.
csf_map : array
The partial volume fraction of corticospinal fluid at each voxel.

get_exclude
()¶

get_include
()¶
LocalTracking
¶

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

__init__
(direction_getter, tissue_classifier, seeds, affine, step_size, max_cross=None, maxlen=500, fixedstep=True, return_all=True)¶ Creates streamlines by using local fibertracking.
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.

ParticleFilteringTracking
¶

class
dipy.tracking.local.localtracking.
ParticleFilteringTracking
(direction_getter, tissue_classifier, seeds, affine, step_size, max_cross=None, maxlen=500, pft_back_tracking_dist=2, pft_front_tracking_dist=1, pft_max_trial=20, particle_count=15, return_all=True)¶ Bases:
dipy.tracking.local.localtracking.LocalTracking

__init__
(direction_getter, tissue_classifier, seeds, affine, step_size, max_cross=None, maxlen=500, pft_back_tracking_dist=2, pft_front_tracking_dist=1, pft_max_trial=20, particle_count=15, return_all=True)¶ A streamline generator using the particle filtering tractography method [R494].
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.
References
[R494] (1, 2) Girard, G., Whittingstall, K., Deriche, R., & Descoteaux, M. Towards quantitative connectivity analysis: reducing tractography biases. NeuroImage, 98, 266278, 2014.

local_tracker¶

dipy.tracking.local.localtracking.
local_tracker
()¶ Tracks one direction from a seed.
This function is the main workhorse of the
LocalTracking
class defined indipy.tracking.local.localtracking
.Parameters: dg : DirectionGetter
Used to choosing tracking directions.
tc : TissueClassifier
Used to check tissue type along path.
seed_pos : array, float, 1d, (3,)
First point of the (partial) streamline.
first_step : array, float, 1d, (3,)
Initial seeding direction. Used as
prev_dir
for selecting the step direction from the seed point.voxel_size : array, float, 1d, (3,)
Size of voxels in the data set.
streamline : array, float, 2d, (N, 3)
Output of tracking will be put into this array. The length of this array,
N
, will set the maximum allowable length of the streamline.step_size : float
Size of tracking steps in mm if
fixed_step
.fixedstep : bool
If true, a fixed step_size is used, otherwise a variable step size is used.
Returns: end : int
Length of the tracked streamline
tissue_class : TissueClass
Ending state of the streamlines as determined by the TissueClassifier.
pft_tracker¶

dipy.tracking.local.localtracking.
pft_tracker
()¶ Tracks one direction from a seed using the particle filtering algorithm.
This function is the main workhorse of the
ParticleFilteringTracking
class defined indipy.tracking.local.localtracking
.Parameters: dg : DirectionGetter
Used to choosing tracking directions.
tc : TissueClassifier
Used to check tissue type along path.
seed_pos : array, float, 1d, (3,)
First point of the (partial) streamline.
first_step : array, float, 1d, (3,)
Initial seeding direction. Used as
prev_dir
for selecting the step direction from the seed point.voxel_size : array, float, 1d, (3,)
Size of voxels in the data set.
streamline : array, float, 2d, (N, 3)
Output of tracking will be put into this array. The length of this array,
N
, will set the maximum allowable length of the streamline.directions : array, float, 2d, (N, 3)
Output of tracking directions will be put into this array. The length of this array,
N
, will set the maximum allowable length of the streamline.step_size : float
Size of tracking steps in mm if
fixed_step
.pft_max_nbr_back_steps : int
Number of tracking steps to back track before starting the particle filtering tractography.
pft_max_nbr_front_steps : int
Number of additional tracking steps to track.
pft_max_trials : int
Maximum number of trials for the particle filtering tractography (Prevents infinite loops).
particle_count : int
Number of particles to use in the particle filter.
particle_paths : array, float, 4d, (2, particle_count, pft_max_steps, 3)
Temporary array for paths followed by all particles.
particle_dirs : array, float, 4d, (2, particle_count, pft_max_steps, 3)
Temporary array for directions followed by particles.
particle_weights : array, float, 1d (particle_count)
Temporary array for the weights of particles.
particle_steps : array, float, (2, particle_count)
Temporary array for the number of steps of particles.
particle_tissue_classes : array, float, (2, particle_count)
Temporary array for the tissue classes of particles.
Returns: end : int
Length of the tracked streamline
tissue_class : TissueClass
Ending state of the streamlines as determined by the TissueClassifier.
arbitrarypoint¶

dipy.tracking.metrics.
arbitrarypoint
(xyz, distance)¶ Select an arbitrary point along distance on the track (curve)
Parameters: xyz : arraylike shape (N,3)
array representing x,y,z of N points in a track
distance : float
float representing distance travelled from the xyz[0] point of the curve along the curve.
Returns: ap : array shape (3,)
Arbitrary point of line, such that, if the arbitrary point is not a point in xyz, then we take the interpolation between the two nearest xyz points. If xyz is empty, return a ValueError
Examples
>>> import numpy as np >>> from dipy.tracking.metrics import arbitrarypoint, length >>> theta=np.pi*np.linspace(0,1,100) >>> x=np.cos(theta) >>> y=np.sin(theta) >>> z=0*x >>> xyz=np.vstack((x,y,z)).T >>> ap=arbitrarypoint(xyz,length(xyz)/3)
bytes¶

dipy.tracking.metrics.
bytes
(xyz)¶ Size of track in bytes.
Parameters: xyz : arraylike shape (N,3)
Array representing x,y,z of N points in a track.
Returns: b : int
Number of bytes.
center_of_mass¶

dipy.tracking.metrics.
center_of_mass
(xyz)¶ Center of mass of streamline
Parameters: xyz : arraylike shape (N,3)
array representing x,y,z of N points in a track
Returns: com : array shape (3,)
center of mass of streamline
Examples
>>> from dipy.tracking.metrics import center_of_mass >>> center_of_mass([]) Traceback (most recent call last): ... ValueError: xyz array cannot be empty >>> center_of_mass([[1,1,1]]) array([ 1., 1., 1.]) >>> xyz = np.array([[0,0,0],[1,1,1],[2,2,2]]) >>> center_of_mass(xyz) array([ 1., 1., 1.])
downsample¶

dipy.tracking.metrics.
downsample
(xyz, n_pols=3)¶ downsample for a specific number of points along the curve/track
Uses the length of the curve. It works in a similar fashion to midpoint and arbitrarypoint but it also reduces the number of segments of a track.
Parameters: xyz : arraylike shape (N,3)
array representing x,y,z of N points in a track
n_pol : int
integer representing number of points (poles) we need along the curve.
Returns: xyz2 : array shape (M,3)
array representing x,y,z of M points that where extrapolated. M should be equal to n_pols
Examples
>>> import numpy as np >>> # a semicircle >>> theta=np.pi*np.linspace(0,1,100) >>> x=np.cos(theta) >>> y=np.sin(theta) >>> z=0*x >>> xyz=np.vstack((x,y,z)).T >>> xyz2=downsample(xyz,3) >>> # a cosine >>> x=np.pi*np.linspace(0,1,100) >>> y=np.cos(theta) >>> z=0*y >>> xyz=np.vstack((x,y,z)).T >>> _= downsample(xyz,3) >>> len(xyz2) 3 >>> xyz3=downsample(xyz,10) >>> len(xyz3) 10
endpoint¶

dipy.tracking.metrics.
endpoint
(xyz)¶ Parameters: xyz : array, shape(N,3)
Track.
Returns: ep : array, shape(3,)
First track point.
Examples
>>> from dipy.tracking.metrics import endpoint >>> import numpy as np >>> theta=np.pi*np.linspace(0,1,100) >>> x=np.cos(theta) >>> y=np.sin(theta) >>> z=0*x >>> xyz=np.vstack((x,y,z)).T >>> ep=endpoint(xyz) >>> ep.any()==xyz[1].any() True
frenet_serret¶

dipy.tracking.metrics.
frenet_serret
(xyz)¶ FrenetSerret Space Curve Invariants
Calculates the 3 vector and 2 scalar invariants of a space curve defined by vectors r = (x,y,z). If z is omitted (i.e. the array xyz has shape (N,2)), then the curve is only 2D (planar), but the equations are still valid.
Similar to http://www.mathworks.com/matlabcentral/fileexchange/11169
In the following equations the prime (\('\)) indicates differentiation with respect to the parameter \(s\) of a parametrised curve \(\mathbf{r}(s)\).
 \(\mathbf{T}=\mathbf{r'}/\mathbf{r'}\qquad\) (Tangent vector)}
 \(\mathbf{N}=\mathbf{T'}/\mathbf{T'}\qquad\) (Normal vector)
 \(\mathbf{B}=\mathbf{T}\times\mathbf{N}\qquad\) (Binormal vector)
 \(\kappa=\mathbf{T'}\qquad\) (Curvature)
 \(\mathrm{\tau}=\mathbf{B'}\cdot\mathbf{N}\) (Torsion)
Parameters: xyz : arraylike shape (N,3)
array representing x,y,z of N points in a track
Returns: T : array shape (N,3)
array representing the tangent of the curve xyz
N : array shape (N,3)
array representing the normal of the curve xyz
B : array shape (N,3)
array representing the binormal of the curve xyz
k : array shape (N,1)
array representing the curvature of the curve xyz
t : array shape (N,1)
array representing the torsion of the curve xyz
Examples
Create a helix and calculate its tangent, normal, binormal, curvature and torsion
>>> from dipy.tracking import metrics as tm >>> import numpy as np >>> theta = 2*np.pi*np.linspace(0,2,100) >>> x=np.cos(theta) >>> y=np.sin(theta) >>> z=theta/(2*np.pi) >>> xyz=np.vstack((x,y,z)).T >>> T,N,B,k,t=tm.frenet_serret(xyz)
generate_combinations¶

dipy.tracking.metrics.
generate_combinations
(items, n)¶ Combine sets of size n from items
Parameters: items : sequence
n : int
Returns: ic : iterator
Examples
>>> from dipy.tracking.metrics import generate_combinations >>> ic=generate_combinations(range(3),2) >>> for i in ic: print(i) [0, 1] [0, 2] [1, 2]
inside_sphere¶

dipy.tracking.metrics.
inside_sphere
(xyz, center, radius)¶ If any point of the track is inside a sphere of a specified center and radius return True otherwise False. Mathematicaly this can be simply described by \(xc\le r\) where \(x\) a point \(c\) the center of the sphere and \(r\) the radius of the sphere.
Parameters: xyz : array, shape (N,3)
representing x,y,z of the N points of the track
center : array, shape (3,)
center of the sphere
radius : float
radius of the sphere
Returns: tf : {True,False}
Whether point is inside sphere.
Examples
>>> from dipy.tracking.metrics import inside_sphere >>> line=np.array(([0,0,0],[1,1,1],[2,2,2])) >>> sph_cent=np.array([1,1,1]) >>> sph_radius = 1 >>> inside_sphere(line,sph_cent,sph_radius) True
inside_sphere_points¶

dipy.tracking.metrics.
inside_sphere_points
(xyz, center, radius)¶ If a track intersects with a sphere of a specified center and radius return the points that are inside the sphere otherwise False. Mathematicaly this can be simply described by \(xc \le r\) where \(x\) a point \(c\) the center of the sphere and \(r\) the radius of the sphere.
Parameters: xyz : array, shape (N,3)
representing x,y,z of the N points of the track
center : array, shape (3,)
center of the sphere
radius : float
radius of the sphere
Returns: xyzn : array, shape(M,3)
array representing x,y,z of the M points inside the sphere
Examples
>>> from dipy.tracking.metrics import inside_sphere_points >>> line=np.array(([0,0,0],[1,1,1],[2,2,2])) >>> sph_cent=np.array([1,1,1]) >>> sph_radius = 1 >>> inside_sphere_points(line,sph_cent,sph_radius) array([[1, 1, 1]])
intersect_sphere¶

dipy.tracking.metrics.
intersect_sphere
(xyz, center, radius)¶ If any segment of the track is intersecting with a sphere of specific center and radius return True otherwise False
Parameters: xyz : array, shape (N,3)
representing x,y,z of the N points of the track
center : array, shape (3,)
center of the sphere
radius : float
radius of the sphere
Returns: tf : {True, False}
True if track xyz intersects sphere
>>> from dipy.tracking.metrics import intersect_sphere
>>> line=np.array(([0,0,0],[1,1,1],[2,2,2]))
>>> sph_cent=np.array([1,1,1])
>>> sph_radius = 1
>>> intersect_sphere(line,sph_cent,sph_radius)
True
Notes
The ray to sphere intersection method used here is similar with http://local.wasp.uwa.edu.au/~pbourke/geometry/sphereline/ http://local.wasp.uwa.edu.au/~pbourke/geometry/sphereline/source.cpp we just applied it for every segment neglecting the intersections where the intersecting points are not inside the segment
length¶

dipy.tracking.metrics.
length
(xyz, along=False)¶ Euclidean length of track line
This will give length in mm if tracks are expressed in world coordinates.
Parameters: xyz : arraylike shape (N,3)
array representing x,y,z of N points in a track
along : bool, optional
If True, return array giving cumulative length along track, otherwise (default) return scalar giving total length.
Returns: L : scalar or array shape (N1,)
scalar in case of along == False, giving total length, array if along == True, giving cumulative lengths.
Examples
>>> from dipy.tracking.metrics import length >>> xyz = np.array([[1,1,1],[2,3,4],[0,0,0]]) >>> expected_lens = np.sqrt([1+2**2+3**2, 2**2+3**2+4**2]) >>> length(xyz) == expected_lens.sum() True >>> len_along = length(xyz, along=True) >>> np.allclose(len_along, expected_lens.cumsum()) True >>> length([]) 0 >>> length([[1, 2, 3]]) 0 >>> length([], along=True) array([0])
longest_track_bundle¶

dipy.tracking.metrics.
longest_track_bundle
(bundle, sort=False)¶ Return longest track or length sorted track indices in bundle
If sort == True, return the indices of the sorted tracks in the bundle, otherwise return the longest track.
Parameters: bundle : sequence
of tracks as arrays, shape (N1,3) ... (Nm,3)
sort : bool, optional
If False (default) return longest track. If True, return length sorted indices for tracks in bundle
Returns: longest_or_indices : array
longest track  shape (N,3)  (if sort is False), or indices of length sorted tracks (if sort is True)
Examples
>>> from dipy.tracking.metrics import longest_track_bundle >>> import numpy as np >>> bundle = [np.array([[0,0,0],[2,2,2]]),np.array([[0,0,0],[4,4,4]])] >>> longest_track_bundle(bundle) array([[0, 0, 0], [4, 4, 4]]) >>> longest_track_bundle(bundle, True) array([0, 1]...)
mean_curvature¶

dipy.tracking.metrics.
mean_curvature
(xyz)¶ Calculates the mean curvature of a curve
Parameters: xyz : arraylike shape (N,3)
array representing x,y,z of N points in a curve
Returns: m : float
Mean curvature.
Examples
Create a straight line and a semicircle and print their mean curvatures
>>> from dipy.tracking import metrics as tm >>> import numpy as np >>> x=np.linspace(0,1,100) >>> y=0*x >>> z=0*x >>> xyz=np.vstack((x,y,z)).T >>> m=tm.mean_curvature(xyz) #mean curvature straight line >>> theta=np.pi*np.linspace(0,1,100) >>> x=np.cos(theta) >>> y=np.sin(theta) >>> z=0*x >>> xyz=np.vstack((x,y,z)).T >>> _= tm.mean_curvature(xyz) #mean curvature for semicircle
mean_orientation¶

dipy.tracking.metrics.
mean_orientation
(xyz)¶ Calculates the mean orientation of a curve
Parameters: xyz : arraylike shape (N,3)
array representing x,y,z of N points in a curve
Returns: m : float
Mean orientation.
midpoint¶

dipy.tracking.metrics.
midpoint
(xyz)¶ Midpoint of track
Parameters: xyz : arraylike shape (N,3)
array representing x,y,z of N points in a track
Returns: mp : array shape (3,)
Middle point of line, such that, if L is the line length then np is the point such that the length xyz[0] to mp and from mp to xyz[1] is L/2. If the middle point is not a point in xyz, then we take the interpolation between the two nearest xyz points. If xyz is empty, return a ValueError
Examples
>>> from dipy.tracking.metrics import midpoint >>> midpoint([]) Traceback (most recent call last): ... ValueError: xyz array cannot be empty >>> midpoint([[1, 2, 3]]) array([1, 2, 3]) >>> xyz = np.array([[1,1,1],[2,3,4]]) >>> midpoint(xyz) array([ 1.5, 2. , 2.5]) >>> xyz = np.array([[0,0,0],[1,1,1],[2,2,2]]) >>> midpoint(xyz) array([ 1., 1., 1.]) >>> xyz = np.array([[0,0,0],[1,0,0],[3,0,0]]) >>> midpoint(xyz) array([ 1.5, 0. , 0. ]) >>> xyz = np.array([[0,9,7],[1,9,7],[3,9,7]]) >>> midpoint(xyz) array([ 1.5, 9. , 7. ])
midpoint2point¶

dipy.tracking.metrics.
midpoint2point
(xyz, p)¶ Calculate distance from midpoint of a curve to arbitrary point p
Parameters: xyz : arraylike shape (N,3)
array representing x,y,z of N points in a track
p : array shape (3,)
array representing an arbitrary point with x,y,z coordinates in space.
Returns: d : float
a float number representing Euclidean distance
Examples
>>> import numpy as np >>> from dipy.tracking.metrics import midpoint2point, midpoint >>> theta=np.pi*np.linspace(0,1,100) >>> x=np.cos(theta) >>> y=np.sin(theta) >>> z=0*x >>> xyz=np.vstack((x,y,z)).T >>> dist=midpoint2point(xyz,np.array([0,0,0]))
principal_components¶

dipy.tracking.metrics.
principal_components
(xyz)¶ We use PCA to calculate the 3 principal directions for a track
Parameters: xyz : arraylike shape (N,3)
array representing x,y,z of N points in a track
Returns: va : array_like
eigenvalues
ve : array_like
eigenvectors
Examples
>>> import numpy as np >>> from dipy.tracking.metrics import principal_components >>> theta=np.pi*np.linspace(0,1,100) >>> x=np.cos(theta) >>> y=np.sin(theta) >>> z=0*x >>> xyz=np.vstack((x,y,z)).T >>> va, ve = principal_components(xyz) >>> np.allclose(va, [0.51010101, 0.09883545, 0]) True
setup_test¶

dipy.tracking.metrics.
setup_test
()¶ Set numpy print options to “legacy” for new versions of numpy
If imported into a file, nosetest will run this before any doctests.
References
https://github.com/numpy/numpy/commit/710e0327687b9f7653e5ac02d222ba62c657a718 https://github.com/numpy/numpy/commit/734b907fc2f7af6e40ec989ca49ee6d87e21c495 https://github.com/nipy/nibabel/pull/556
splev¶

dipy.tracking.metrics.
splev
(x, tck, der=0, ext=0)¶ Evaluate a Bspline or its derivatives.
Given the knots and coefficients of a Bspline representation, evaluate the value of the smoothing polynomial and its derivatives. This is a wrapper around the FORTRAN routines splev and splder of FITPACK.
Parameters: x : array_like
An array of points at which to return the value of the smoothed spline or its derivatives. If tck was returned from splprep, then the parameter values, u should be given.
tck : 3tuple or a BSpline object
If a tuple, then it should be a sequence of length 3 returned by splrep or splprep containing the knots, coefficients, and degree of the spline. (Also see Notes.)
der : int, optional
The order of derivative of the spline to compute (must be less than or equal to k).
ext : int, optional
Controls the value returned for elements of
x
not in the interval defined by the knot sequence. if ext=0, return the extrapolated value.
 if ext=1, return 0
 if ext=2, raise a ValueError
 if ext=3, return the boundary value.
The default value is 0.
Returns: y : ndarray or list of ndarrays
An array of values representing the spline function evaluated at the points in x. If tck was returned from splprep, then this is a list of arrays representing the curve in Ndimensional space.
See also
splprep
,splrep
,sproot
,spalde
,splint
,bisplrep
,bisplev
,BSpline
Notes
Manipulating the tcktuples directly is not recommended. In new code, prefer using BSpline objects.
References
[R495] C. de Boor, “On calculating with bsplines”, J. Approximation Theory, 6, p.5062, 1972. [R496] M. G. Cox, “The numerical evaluation of bsplines”, J. Inst. Maths Applics, 10, p.134149, 1972. [R497] P. Dierckx, “Curve and surface fitting with splines”, Monographs on Numerical Analysis, Oxford University Press, 1993.
spline¶

dipy.tracking.metrics.
spline
(xyz, s=3, k=2, nest=1)¶ Generate Bsplines as documented in http://www.scipy.org/Cookbook/Interpolation
The scipy.interpolate packages wraps the netlib FITPACK routines (Dierckx) for calculating smoothing splines for various kinds of data and geometries. Although the data is evenly spaced in this example, it need not be so to use this routine.
Parameters: xyz : array, shape (N,3)
array representing x,y,z of N points in 3d space
s : float, optional
A smoothing condition. The amount of smoothness is determined by satisfying the conditions: sum((w * (y  g))**2,axis=0) <= s where g(x) is the smoothed interpolation of (x,y). The user can use s to control the tradeoff between closeness and smoothness of fit. Larger satisfying the conditions: sum((w * (y  g))**2,axis=0) <= s where g(x) is the smoothed interpolation of (x,y). The user can use s to control the tradeoff between closeness and smoothness of fit. Larger s means more smoothing while smaller values of s indicate less smoothing. Recommended values of s depend on the weights, w. If the weights represent the inverse of the standarddeviation of y, then a: good s value should be found in the range (msqrt(2*m),m+sqrt(2*m)) where m is the number of datapoints in x, y, and w.
k : int, optional
Degree of the spline. Cubic splines are recommended. Even values of k should be avoided especially with a small svalue. for the same set of data. If task=1 find the weighted least square spline for a given set of knots, t.
nest : None or int, optional
An overestimate of the total number of knots of the spline to help in determining the storage space. None results in value m+2*k. 1 results in m+k+1. Always large enough is nest=m+k+1. Default is 1.
Returns: xyzn : array, shape (M,3)
array representing x,y,z of the M points inside the sphere
See also
scipy.interpolate.splprep
,scipy.interpolate.splev
Examples
>>> import numpy as np >>> t=np.linspace(0,1.75*2*np.pi,100)# make ascending spiral in 3space >>> x = np.sin(t) >>> y = np.cos(t) >>> z = t >>> x+= np.random.normal(scale=0.1, size=x.shape) # add noise >>> y+= np.random.normal(scale=0.1, size=y.shape) >>> z+= np.random.normal(scale=0.1, size=z.shape) >>> xyz=np.vstack((x,y,z)).T >>> xyzn=spline(xyz,3,2,1) >>> len(xyzn) > len(xyz) True
splprep¶

dipy.tracking.metrics.
splprep
(x, w=None, u=None, ub=None, ue=None, k=3, task=0, s=None, t=None, full_output=0, nest=None, per=0, quiet=1)¶ Find the Bspline representation of an Ndimensional curve.
Given a list of N rank1 arrays, x, which represent a curve in Ndimensional space parametrized by u, find a smooth approximating spline curve g(u). Uses the FORTRAN routine parcur from FITPACK.
Parameters: x : array_like
A list of sample vector arrays representing the curve.
w : array_like, optional
Strictly positive rank1 array of weights the same length as x[0]. The weights are used in computing the weighted leastsquares spline fit. If the errors in the x values have standarddeviation given by the vector d, then w should be 1/d. Default is
ones(len(x[0]))
.u : array_like, optional
An array of parameter values. If not given, these values are calculated automatically as
M = len(x[0])
, wherev[0] = 0
v[i] = v[i1] + distance(x[i], x[i1])
u[i] = v[i] / v[M1]
ub, ue : int, optional
The endpoints of the parameters interval. Defaults to u[0] and u[1].
k : int, optional
Degree of the spline. Cubic splines are recommended. Even values of k should be avoided especially with a small svalue.
1 <= k <= 5
, default is 3.task : int, optional
If task==0 (default), find t and c for a given smoothing factor, s. If task==1, find t and c for another value of the smoothing factor, s. There must have been a previous call with task=0 or task=1 for the same set of data. If task=1 find the weighted least square spline for a given set of knots, t.
s : float, optional
A smoothing condition. The amount of smoothness is determined by satisfying the conditions:
sum((w * (y  g))**2,axis=0) <= s
, where g(x) is the smoothed interpolation of (x,y). The user can use s to control the tradeoff between closeness and smoothness of fit. Larger s means more smoothing while smaller values of s indicate less smoothing. Recommended values of s depend on the weights, w. If the weights represent the inverse of the standarddeviation of y, then a good s value should be found in the range(msqrt(2*m),m+sqrt(2*m))
, where m is the number of data points in x, y, and w.t : int, optional
The knots needed for task=1.
full_output : int, optional
If nonzero, then return optional outputs.
nest : int, optional
An overestimate of the total number of knots of the spline to help in determining the storage space. By default nest=m/2. Always large enough is nest=m+k+1.
per : int, optional
If nonzero, data points are considered periodic with period
x[m1]  x[0]
and a smooth periodic spline approximation is returned. Values ofy[m1]
andw[m1]
are not used.quiet : int, optional
Nonzero to suppress messages. This parameter is deprecated; use standard Python warning filters instead.
Returns: tck : tuple
(t,c,k) a tuple containing the vector of knots, the Bspline coefficients, and the degree of the spline.
u : array
An array of the values of the parameter.
fp : float
The weighted sum of squared residuals of the spline approximation.
ier : int
An integer flag about splrep success. Success is indicated if ier<=0. If ier in [1,2,3] an error occurred but was not raised. Otherwise an error is raised.
msg : str
A message corresponding to the integer flag, ier.
See also
splrep
,splev
,sproot
,spalde
,splint
,bisplrep
,bisplev
,UnivariateSpline
,BivariateSpline
,BSpline
,make_interp_spline
Notes
See splev for evaluation of the spline and its derivatives. The number of dimensions N must be smaller than 11.
References
[R498] P. Dierckx, “Algorithms for smoothing data with periodic and parametric splines, Computer Graphics and Image Processing”, 20 (1982) 171184. [R499] P. Dierckx, “Algorithms for smoothing data with periodic and parametric splines”, report tw55, Dept. Computer Science, K.U.Leuven, 1981. [R500] P. Dierckx, “Curve and surface fitting with splines”, Monographs on Numerical Analysis, Oxford University Press, 1993. Examples
Generate a discretization of a limacon curve in the polar coordinates:
>>> phi = np.linspace(0, 2.*np.pi, 40) >>> r = 0.5 + np.cos(phi) # polar coords >>> x, y = r * np.cos(phi), r * np.sin(phi) # convert to cartesian
And interpolate:
>>> from scipy.interpolate import splprep, splev >>> tck, u = splprep([x, y], s=0) >>> new_points = splev(u, tck)
Notice that (i) we force interpolation by using s=0, (ii) the parameterization,
u
, is generated automatically. Now plot the result:>>> import matplotlib.pyplot as plt >>> fig, ax = plt.subplots() >>> ax.plot(x, y, 'ro') >>> ax.plot(new_points[0], new_points[1], 'r') >>> plt.show()
startpoint¶

dipy.tracking.metrics.
startpoint
(xyz)¶ First point of the track
Parameters: xyz : array, shape(N,3)
Track.
Returns: sp : array, shape(3,)
First track point.
Examples
>>> from dipy.tracking.metrics import startpoint >>> import numpy as np >>> theta=np.pi*np.linspace(0,1,100) >>> x=np.cos(theta) >>> y=np.sin(theta) >>> z=0*x >>> xyz=np.vstack((x,y,z)).T >>> sp=startpoint(xyz) >>> sp.any()==xyz[0].any() True
winding¶

dipy.tracking.metrics.
winding
(xyz)¶ Total turning angle projected.
Project space curve to best fitting plane. Calculate the cumulative signed angle between each line segment and the previous one.
Parameters: xyz : arraylike shape (N,3)
Array representing x,y,z of N points in a track.
Returns: a : scalar
Total turning angle in degrees.
ArraySequence
¶

class
dipy.tracking.streamline.
ArraySequence
(iterable=None, buffer_size=4)¶ Bases:
object
Sequence of ndarrays having variable first dimension sizes.
This is a container that can store multiple ndarrays where each ndarray might have a different first dimension size but a common size for the remaining dimensions.
More generally, an instance of
ArraySequence
of length \(N\) is composed of \(N\) ndarrays of shape \((d_1, d_2, ... d_D)\) where \(d_1\) can vary in length between arrays but \((d_2, ..., d_D)\) have to be the same for every ndarray.Attributes
common_shape
Matching shape of the elements in this array sequence. data
Elements in this array sequence. is_array_sequence
total_nb_rows
Total number of rows in this array sequence. Methods
append
(element[, cache_build])Appends element to this array sequence. copy
()Creates a copy of this ArraySequence
object.extend
(elements)Appends all elements to this array sequence. finalize_append
()Finalize process of appending several elements to self load
(filename)Loads a ArraySequence
object from a .npz file.save
(filename)Saves this ArraySequence
object to a .npz file.shrink_data
()
__init__
(iterable=None, buffer_size=4)¶ Initialize array sequence instance
Parameters: iterable : None or iterable or
ArraySequence
, optionalIf None, create an empty
ArraySequence
object. If iterable, create aArraySequence
object initialized from arraylike objects yielded by the iterable. IfArraySequence
, create a view (no memory is allocated). For an actual copy usecopy()
instead.buffer_size : float, optional
Size (in Mb) for memory allocation when iterable is a generator.

append
(element, cache_build=False)¶ Appends element to this array sequence.
Append can be a lot faster if it knows that it is appending several elements instead of a single element. In that case it can cache the parameters it uses between append operations, in a “build cache”. To tell append to do this, use
cache_build=True
. If you usecache_build=True
, you need to finalize the append operations withfinalize_append()
.Parameters: element : ndarray
Element to append. The shape must match already inserted elements shape except for the first dimension.
cache_build : {False, True}
Whether to save the build cache from this append routine. If True, append can assume it is the only player updating self, and the caller must finalize self after all append operations, with
self.finalize_append()
.Returns: None
Notes
If you need to add multiple elements you should consider ArraySequence.extend.

common_shape
¶ Matching shape of the elements in this array sequence.

copy
()¶ Creates a copy of this
ArraySequence
object.Returns: seq_copy :
ArraySequence
instanceCopy of self.
Notes
We do not simply deepcopy this object because we have a chance to use less memory. For example, if the array sequence being copied is the result of a slicing operation on an array sequence.

data
¶ Elements in this array sequence.

extend
(elements)¶ Appends all elements to this array sequence.
Parameters: elements : iterable of ndarrays or
ArraySequence
objectIf iterable of ndarrays, each ndarray will be concatenated along the first dimension then appended to the data of this ArraySequence. If
ArraySequence
object, its data are simply appended to the data of this ArraySequence.Returns: None
Notes
The shape of the elements to be added must match the one of the data of this
ArraySequence
except for the first dimension.

finalize_append
()¶ Finalize process of appending several elements to self
append()
can be a lot faster if it knows that it is appending several elements instead of a single element. To tell the append method this is the case, usecache_build=True
. This method finalizes the series of append operations after a call toappend()
withcache_build=True
.

is_array_sequence
¶

classmethod
load
(filename)¶ Loads a
ArraySequence
object from a .npz file.

save
(filename)¶ Saves this
ArraySequence
object to a .npz file.

shrink_data
()¶

total_nb_rows
¶ Total number of rows in this array sequence.

LooseVersion
¶

class
dipy.tracking.streamline.
LooseVersion
(vstring=None)¶ Bases:
distutils.version.Version
Version numbering for anarchists and software realists. Implements the standard interface for version number classes as described above. A version number consists of a series of numbers, separated by either periods or strings of letters. When comparing version numbers, the numeric components will be compared numerically, and the alphabetic components lexically. The following are all valid version numbers, in no particular order:
1.5.1 1.5.2b2 161 3.10a 8.02 3.4j 1996.07.12 3.2.pl0 3.1.1.6 2g6 11g 0.960923 2.2beta29 1.13++ 5.5.kw 2.0b1pl0In fact, there is no such thing as an invalid version number under this scheme; the rules for comparison are simple and predictable, but may not always give the results you want (for some definition of “want”).
Methods
parse
(vstring)
__init__
(vstring=None)¶

component_re
= re.compile('(\\d+  [az]+  \\.)', re.VERBOSE)¶

parse
(vstring)¶

Streamlines
¶

class
dipy.tracking.streamline.
Streamlines
(*args, **kwargs)¶ Bases:
nibabel.streamlines.array_sequence.ArraySequence
Attributes
common_shape
Matching shape of the elements in this array sequence. data
Elements in this array sequence. is_array_sequence
total_nb_rows
Total number of rows in this array sequence. Methods
append
(element[, cache_build])Appends element to this array sequence. copy
()Creates a copy of this ArraySequence
object.extend
(elements)Appends all elements to this array sequence. finalize_append
()Finalize process of appending several elements to self append()
can be a lot faster if it knows that it is appending several elements instead of a single element.load
(filename)Loads a ArraySequence
object from a .npz file.save
(filename)Saves this ArraySequence
object to a .npz file.shrink_data
()
__init__
(*args, **kwargs)¶

append
(element, cache_build=False)¶ Appends element to this array sequence. Append can be a lot faster if it knows that it is appending several elements instead of a single element. In that case it can cache the parameters it uses between append operations, in a “build cache”. To tell append to do this, use
cache_build=True
. If you usecache_build=True
, you need to finalize the append operations withfinalize_append()
. Parameters ——— element : ndarrayElement to append. The shape must match already inserted elements shape except for the first dimension. cache_build : {False, True}
 Whether to save the build cache from this append routine. If True,
append can assume it is the only player updating self, and the
caller must finalize self after all append operations, with
self.finalize_append()
.
None Notes —– If you need to add multiple elements you should consider ArraySequence.extend.

extend
(elements)¶ Appends all elements to this array sequence. Parameters ——— elements : iterable of ndarrays or
ArraySequence
objectIf iterable of ndarrays, each ndarray will be concatenated along the first dimension then appended to the data of this ArraySequence. IfArraySequence
object, its data are simply appended to the data of this ArraySequence.None Notes —– The shape of the elements to be added must match the one of the data of this
ArraySequence
except for the first dimension.

finalize_append
()¶ Finalize process of appending several elements to self
append()
can be a lot faster if it knows that it is appending several elements instead of a single element. To tell the append method this is the case, usecache_build=True
. This method finalizes the series of append operations after a call toappend()
withcache_build=True
.

apply_affine¶

dipy.tracking.streamline.
apply_affine
(aff, pts)¶ Apply affine matrix aff to points pts
Returns result of application of aff to the right of pts. The coordinate dimension of pts should be the last.
For the 3D case, aff will be shape (4,4) and pts will have final axis length 3  maybe it will just be N by 3. The return value is the transformed points, in this case:
res = np.dot(aff[:3,:3], pts.T) + aff[:3,3:4] transformed_pts = res.T
This routine is more general than 3D, in that aff can have any shape (N,N), and pts can have any shape, as long as the last dimension is for the coordinates, and is therefore length N1.
Parameters: aff : (N, N) arraylike
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 : (..., N1) arraylike
Points, where the last dimension contains the coordinates of each point. For 3D, the last dimension will be length 3.
Returns: transformed_pts : (..., N1) 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]]]...)
cdist¶

dipy.tracking.streamline.
cdist
(XA, XB, metric='euclidean', p=None, V=None, VI=None, w=None)¶ Computes 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’.
p : double, optional
The pnorm to apply Only for Minkowski, weighted and unweighted. Default: 2.
w : ndarray, optional
The weight vector. Only for weighted Minkowski. Mandatory
V : ndarray, optional
The variance vector Only for standardized Euclidean. Default: var(vstack([XA, XB]), axis=0, ddof=1)
VI : ndarray, optional
The inverse of the covariance matrix Only for Mahalanobis. Default: inv(cov(vstack([XA, XB]).T)).T
Returns: 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.Raises: ValueError
An exception is thrown if XA and XB do not have the same number of columns.
Notes
The following are common calling conventions:
Y = cdist(XA, XB, 'euclidean')
Computes the distance between \(m\) points using Euclidean distance (2norm) as the distance metric between the points. The points are arranged as \(m\) \(n\)dimensional row vectors in the matrix X.
Y = cdist(XA, XB, 'minkowski', p)
Computes the distances using the Minkowski distance \(uv_p\) (\(p\)norm) where \(p \geq 1\).
Y = cdist(XA, XB, 'cityblock')
Computes the city block or Manhattan distance between the points.
Y = cdist(XA, XB, 'seuclidean', V=None)
Computes the standardized Euclidean distance. The standardized Euclidean distance between two nvectors
u
andv
is\[\sqrt{\sum {(u_iv_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.
Y = cdist(XA, XB, 'sqeuclidean')
Computes the squared Euclidean distance \(uv_2^2\) between the vectors.
Y = cdist(XA, XB, 'cosine')
Computes the cosine distance between vectors u and v,
\[1  \frac{u \cdot v} {{u}_2 {v}_2}\]where \(*_2\) is the 2norm of its argument
*
, and \(u \cdot v\) is the dot product of \(u\) and \(v\).Y = cdist(XA, XB, 'correlation')
Computes the correlation distance between vectors u and v. This is
\[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\).
Y = cdist(XA, XB, 'hamming')
Computes the normalized Hamming distance, or the proportion of those vector elements between two nvectors
u
andv
which disagree. To save memory, the matrixX
can be of type boolean.Y = cdist(XA, XB, 'jaccard')
Computes the Jaccard distance between the points. Given two vectors,
u
andv
, the Jaccard distance is the proportion of those elementsu[i]
andv[i]
that disagree where at least one of them is nonzero.Y = cdist(XA, XB, 'chebyshev')
Computes the Chebyshev distance between the points. The Chebyshev distance between two nvectors
u
andv
is the maximum norm1 distance between their respective elements. More precisely, the distance is given by\[d(u,v) = \max_i {u_iv_i}.\]Y = cdist(XA, XB, 'canberra')
Computes the Canberra distance between the points. The Canberra distance between two points
u
andv
is\[d(u,v) = \sum_i \frac{u_iv_i} {u_i+v_i}.\]Y = cdist(XA, XB, 'braycurtis')
Computes the BrayCurtis distance between the points. The BrayCurtis distance between two points
u
andv
is\[d(u,v) = \frac{\sum_i (u_iv_i)} {\sum_i (u_i+v_i)}\]Y = cdist(XA, XB, 'mahalanobis', VI=None)
Computes the Mahalanobis distance between the points. The Mahalanobis distance between two pointsu
andv
is \(\sqrt{(uv)(1/V)(uv)^T}\) where \((1/V)\) (theVI
variable) is the inverse covariance. IfVI
is not None,VI
will be used as the inverse covariance matrix.Y = cdist(XA, XB, 'yule')
Computes the Yule distance between the boolean vectors. (see yule function documentation)Y = cdist(XA, XB, 'matching')
Synonym for ‘hamming’.Y = cdist(XA, XB, 'dice')
Computes the Dice distance between the boolean vectors. (see dice function documentation)Y = cdist(XA, XB, 'kulsinski')
Computes the Kulsinski distance between the boolean vectors. (see kulsinski function documentation)Y = cdist(XA, XB, 'rogerstanimoto')
Computes the RogersTanimoto distance between the boolean vectors. (see rogerstanimoto function documentation)Y = cdist(XA, XB, 'russellrao')
Computes the RussellRao distance between the boolean vectors. (see russellrao function documentation)Y = cdist(XA, XB, 'sokalmichener')
Computes the SokalMichener distance between the boolean vectors. (see sokalmichener function documentation)Y = cdist(XA, XB, 'sokalsneath')
Computes the SokalSneath distance between the vectors. (see sokalsneath function documentation)Y = cdist(XA, XB, 'wminkowski')
Computes the weighted Minkowski distance between the vectors. (see wminkowski function documentation)Y = cdist(XA, XB, f)
Computes the distance between all pairs of vectors in X using the user supplied 2arity function f. For example, Euclidean distance between the vectors could be computed as follows:
dm = cdist(XA, XB, lambda u, v: np.sqrt(((uv)**2).sum()))
Note that you should avoid passing a reference to one of the distance functions defined in this library. For example,:
dm = cdist(XA, XB, sokalsneath)
would calculate the pairwise distances between the vectors in X using the Python function sokalsneath. This would result in sokalsneath being called \({n \choose 2}\) times, which is inefficient. Instead, the optimized C version is more efficient, and we call it using the following syntax:
dm = cdist(XA, XB, 'sokalsneath')
Examples
Find the Euclidean distances between four 2D coordinates:
>>> from scipy.spatial import distance >>> coords = [(35.0456, 85.2672), ... (35.1174, 89.9711), ... (35.9728, 83.9422), ... (36.1667, 86.7833)] >>> distance.cdist(coords, coords, 'euclidean') array([[ 0. , 4.7044, 1.6172, 1.8856], [ 4.7044, 0. , 6.0893, 3.3561], [ 1.6172, 6.0893, 0. , 2.8477], [ 1.8856, 3.3561, 2.8477, 0. ]])
Find the Manhattan distance from a 3D point to the corners of the unit cube:
>>> a = np.array([[0, 0, 0], ... [0, 0, 1], ... [0, 1, 0], ... [0, 1, 1], ... [1, 0, 0], ... [1, 0, 1], ... [1, 1, 0], ... [1, 1, 1]]) >>> b = np.array([[ 0.1, 0.2, 0.4]]) >>> distance.cdist(a, b, 'cityblock') array([[ 0.7], [ 0.9], [ 1.3], [ 1.5], [ 1.5], [ 1.7], [ 2.1], [ 2.3]])
center_streamlines¶

dipy.tracking.streamline.
center_streamlines
(streamlines)¶ Move streamlines to the origin
Parameters: streamlines : list
List of 2D ndarrays of shape[1]==3
Returns: new_streamlines : list
List of 2D ndarrays of shape[1]==3
inv_shift : ndarray
Translation in x,y,z to go back in the initial position
compress_streamlines¶

dipy.tracking.streamline.
compress_streamlines
()¶ Compress streamlines by linearization as in [Presseau15].
The compression consists in merging consecutive segments that are nearly collinear. The merging is achieved by removing the point the two segments have in common.
The linearization process [Presseau15] ensures that every point being removed are within a certain margin (in mm) of the resulting streamline. Recommendations for setting this margin can be found in [Presseau15] (in which they called it tolerance error).
The compression also ensures that two consecutive points won’t be too far from each other (precisely less or equal than `max_segment_length`mm). This is a tradeoff to speed up the linearization process [Rheault15]. A low value will result in a faster linearization but low compression, whereas a high value will result in a slower linearization but high compression.
Parameters: streamlines : one or a list of arraylike of shape (N,3)
Array representing x,y,z of N points in a streamline.
tol_error : float (optional)
Tolerance error in mm (default: 0.01). A rule of thumb is to set it to 0.01mm for deterministic streamlines and 0.1mm for probabilitic streamlines.
max_segment_length : float (optional)
Maximum length in mm of any given segment produced by the compression. The default is 10mm. (In [Presseau15], they used a value of np.inf).
Returns: compressed_streamlines : one or a list of arraylike
Results of the linearization process.
Notes
Be aware that compressed streamlines have variable step sizes. One needs to be careful when computing streamlinesbased metrics [Houde15].
References
[Presseau15] Presseau C. et al., A new compression format for fiber tracking datasets, NeuroImage, no 109, 7383, 2015. [Rheault15] Rheault F. et al., Real Time Interaction with Millions of Streamlines, ISMRM, 2015. [Houde15] Houde J.C. et al. How to Avoid Biased StreamlinesBased Metrics for Streamlines with Variable Step Sizes, ISMRM, 2015. Examples
>>> from dipy.tracking.streamline import compress_streamlines >>> import numpy as np >>> # One streamline: a wiggling line >>> rng = np.random.RandomState(42) >>> streamline = np.linspace(0, 10, 100*3).reshape((100, 3)) >>> streamline += 0.2 * rng.rand(100, 3) >>> c_streamline = compress_streamlines(streamline, tol_error=0.2) >>> len(streamline) 100 >>> len(c_streamline) 10 >>> # Multiple streamlines >>> streamlines = [streamline, streamline[::2]] >>> c_streamlines = compress_streamlines(streamlines, tol_error=0.2) >>> [len(s) for s in streamlines] [100, 50] >>> [len(s) for s in c_streamlines] [10, 7]
deepcopy¶

dipy.tracking.streamline.
deepcopy
(x, memo=None, _nil=[])¶ Deep copy operation on arbitrary Python objects.
See the module’s __doc__ string for more info.
deform_streamlines¶

dipy.tracking.streamline.
deform_streamlines
(streamlines, deform_field, stream_to_current_grid, current_grid_to_world, stream_to_ref_grid, ref_grid_to_world)¶ Apply deformation field to streamlines
Parameters: streamlines : list
List of 2D ndarrays of shape[1]==3
deform_field : 4D numpy array
x,y,z displacements stored in volume, shape[1]==3
stream_to_current_grid : array, (4, 4)
transform matrix voxmm space to original grid space
current_grid_to_world : array (4, 4)
transform matrix original grid space to world coordinates
stream_to_ref_grid : array (4, 4)
transform matrix voxmm space to new grid space
ref_grid_to_world : array(4, 4)
transform matrix new grid space to world coordinates
Returns: new_streamlines : list
List of the transformed 2D ndarrays of shape[1]==3
dist_to_corner¶

dipy.tracking.streamline.
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.
Returns: dist: float
The maximal distance to the corner of a voxel, given voxel size encoded in the affine.
length¶

dipy.tracking.streamline.
length
()¶ Euclidean length of streamlines
Length is in mm only if streamlines are expressed in world coordinates.
Parameters: streamlines : ndarray or a list or
dipy.tracking.Streamlines
If ndarray, must have shape (N,3) where N is the number of points of the streamline. If list, each item must be ndarray shape (Ni,3) where Ni is the number of points of streamline i. If
dipy.tracking.Streamlines
, its common_shape must be 3.Returns: lengths : scalar or ndarray shape (N,)
If there is only one streamline, a scalar representing the length of the streamline. If there are several streamlines, ndarray containing the length of every streamline.
Examples
>>> from dipy.tracking.streamline import length >>> import numpy as np >>> streamline = np.array([[1, 1, 1], [2, 3, 4], [0, 0, 0]]) >>> expected_length = np.sqrt([1+2**2+3**2, 2**2+3**2+4**2]).sum() >>> length(streamline) == expected_length True >>> streamlines = [streamline, np.vstack([streamline, streamline[::1]])] >>> expected_lengths = [expected_length, 2*expected_length] >>> lengths = [length(streamlines[0]), length(streamlines[1])] >>> np.allclose(lengths, expected_lengths) True >>> length([]) 0.0 >>> length(np.array([[1, 2, 3]])) 0.0
orient_by_rois¶

dipy.tracking.streamline.
orient_by_rois
(streamlines, roi1, roi2, in_place=False, as_generator=False, affine=None)¶ Orient a set of streamlines according to a pair of ROIs
Parameters: streamlines : list or generator
List or generator of 2d arrays of 3d coordinates. Each array contains the xyz coordinates of a single streamline.
roi1, roi2 : ndarray
Binary masks designating the location of the regions of interest, or coordinate arrays (nby3 array with ROI coordinate in each row).
in_place : bool
Whether to make the change inplace in the original list (and return a reference to the list), or to make a copy of the list and return this copy, with the relevant streamlines reoriented. Default: False.
as_generator : bool
Whether to return a generator as output. Default: False
affine : ndarray
Affine transformation from voxels to streamlines. Default: identity.
Returns: streamlines : list or generator
The same 3D arrays as a list or generator, but reoriented with respect to the ROIs
Examples
>>> streamlines = [np.array([[0, 0., 0], ... [1, 0., 0.], ... [2, 0., 0.]]), ... np.array([[2, 0., 0.], ... [1, 0., 0], ... [0, 0, 0.]])] >>> roi1 = np.zeros((4, 4, 4), dtype=bool) >>> roi2 = np.zeros_like(roi1) >>> roi1[0, 0, 0] = True >>> roi2[1, 0, 0] = True >>> orient_by_rois(streamlines, roi1, roi2) [array([[ 0., 0., 0.], [ 1., 0., 0.], [ 2., 0., 0.]]), array([[ 0., 0., 0.], [ 1., 0., 0.], [ 2., 0., 0.]])]
reduce¶

dipy.tracking.streamline.
reduce
(function, sequence[, initial]) → value¶ Apply a function of two arguments cumulatively to the items of a sequence, from left to right, so as to reduce the sequence to a single value. For example, reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) calculates ((((1+2)+3)+4)+5). If initial is present, it is placed before the items of the sequence in the calculation, and serves as a default when the sequence is empty.
relist_streamlines¶

dipy.tracking.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.
Parameters: points : array
offsets : array
Returns: streamlines: sequence
select_by_rois¶

dipy.tracking.streamline.
select_by_rois
(streamlines, rois, include, mode=None, affine=None, tol=None)¶ Select streamlines based on logical relations with several regions of interest (ROIs). For example, select streamlines that pass near ROI1, but only if they do not pass near ROI2.
Parameters: streamlines : list
A list of candidate streamlines for selection
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). Nonzeros in each volume are considered to be within the region
include : array or list
A list or 1D array of boolean values marking inclusion or exclusion criteria. If a streamline is near any of the inclusion ROIs, it should evaluate to True, unless it is also near any of the exclusion ROIs.
mode : string, optional
One of {“any”, “all”, “either_end”, “both_end”}, where a streamline is associated with an ROI if:
“any” : any point is within tol from ROI. Default.
“all” : all points are within tol from ROI.
“either_end” : either of the endpoints is within tol from ROI
“both_end” : both end points are within tol from ROI.
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.
Returns: generator
Generates the streamlines to be included based on these criteria.
Notes
The only operation currently possible is “(A or B or ...) and not (X or Y or ...)”, where A, B are inclusion regions and X, Y are exclusion regions.
Examples
>>> streamlines = [np.array([[0, 0., 0.9], ... [1.9, 0., 0.]]), ... np.array([[0., 0., 0], ... [0, 1., 1.], ... [0, 2., 2.]]), ... np.array([[2, 2, 2], ... [3, 3, 3]])] >>> mask1 = np.zeros((4, 4, 4), dtype=bool) >>> mask2 = np.zeros_like(mask1) >>> mask1[0, 0, 0] = True >>> mask2[1, 0, 0] = True >>> selection = select_by_rois(streamlines, [mask1, mask2], ... [True, True], ... tol=1) >>> list(selection) # The result is a generator [array([[ 0. , 0. , 0.9], [ 1.9, 0. , 0. ]]), array([[ 0., 0., 0.], [ 0., 1., 1.], [ 0., 2., 2.]])] >>> selection = select_by_rois(streamlines, [mask1, mask2], ... [True, False], ... tol=0.87) >>> list(selection) [array([[ 0., 0., 0.], [ 0., 1., 1.], [ 0., 2., 2.]])] >>> selection = select_by_rois(streamlines, [mask1, mask2], ... [True, True], ... mode="both_end", ... tol=1.0) >>> list(selection) [array([[ 0. , 0. , 0.9], [ 1.9, 0. , 0. ]])] >>> mask2[0, 2, 2] = True >>> selection = select_by_rois(streamlines, [mask1, mask2], ... [True, True], ... mode="both_end", ... tol=1.0) >>> list(selection) [array([[ 0. , 0. , 0.9], [ 1.9, 0. , 0. ]]), array([[ 0., 0., 0.], [ 0., 1., 1.], [ 0., 2., 2.]])]
select_random_set_of_streamlines¶

dipy.tracking.streamline.
select_random_set_of_streamlines
(streamlines, select)¶ Select a random set of streamlines
Parameters: streamlines : list
List of 2D ndarrays of shape[1]==3
select : int
Number of streamlines to select. If there are less streamlines than
select
thenselect=len(streamlines)
.Returns: selected_streamlines : list
Notes
The same streamline will not be selected twice.
set_number_of_points¶

dipy.tracking.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_points1 segments of equal length. Points of streamlines will be modified along the curve.
Parameters: streamlines : ndarray or a list or
dipy.tracking.Streamlines
If ndarray, must have shape (N,3) where N is the number of points of the streamline. If list, each item must be ndarray shape (Ni,3) where Ni is the number of points of streamline i. If
dipy.tracking.Streamlines
, its common_shape must be 3.nb_points : int
integer representing number of points wanted along the curve.
Returns: new_streamlines : ndarray or a list or
dipy.tracking.Streamlines
Results of the downsampling or upsampling process.
Examples
>>> from dipy.tracking.streamline import set_number_of_points >>> import numpy as np
One streamline, a semicircle:
>>> theta = np.pi*np.linspace(0, 1, 100) >>> x = np.cos(theta) >>> y = np.sin(theta) >>> z = 0 * x >>> streamline = np.vstack((x, y, z)).T >>> modified_streamline = set_number_of_points(streamline, 3) >>> len(modified_streamline) 3
Multiple streamlines:
>>> streamlines = [streamline, streamline[::2]] >>> new_streamlines = set_number_of_points(streamlines, 10) >>> [len(s) for s in streamlines] [100, 50] >>> [len(s) for s in new_streamlines] [10, 10]
setup_test¶

dipy.tracking.streamline.
setup_test
()¶ Set numpy print options to “legacy” for new versions of numpy
If imported into a file, nosetest will run this before any doctests.
References
https://github.com/numpy/numpy/commit/710e0327687b9f7653e5ac02d222ba62c657a718 https://github.com/numpy/numpy/commit/734b907fc2f7af6e40ec989ca49ee6d87e21c495 https://github.com/nipy/nibabel/pull/556
streamline_near_roi¶

dipy.tracking.streamline.
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 endpoints is within tol from ROI
“both_end” : both end points are within tol from ROI.
Returns: out : boolean
transform_streamlines¶

dipy.tracking.streamline.
transform_streamlines
(streamlines, mat)¶ Apply affine transformation to streamlines
Parameters: streamlines : list
List of 2D ndarrays of shape[1]==3
mat : array, (4, 4)
transformation matrix
Returns: new_streamlines : list
List of the transformed 2D ndarrays of shape[1]==3
unlist_streamlines¶

dipy.tracking.streamline.
unlist_streamlines
(streamlines)¶ Return the streamlines not as a list but as an array and an offset
Parameters: streamlines: sequence
Returns: points : array
offsets : array
values_from_volume¶

dipy.tracking.streamline.
values_from_volume
(data, streamlines, affine=None)¶ Extract values of a scalar/vector along each streamline from a volume.
Parameters: data : 3D or 4D array
Scalar (for 3D) and vector (for 4D) values to be extracted. For 4D data, interpolation will be done on the 3 spatial dimensions in each volume.
streamlines : ndarray or list
If array, of shape (n_streamlines, n_nodes, 3) If list, len(n_streamlines) with (n_nodes, 3) array in each element of the list.
affine : ndarray, shape (4, 4)
Affine transformation from voxels (image coordinates) to streamlines. Default: identity. For example, if no affine is provided and the first coordinate of the first streamline is
[1, 0, 0]
, data[1, 0, 0] would be returned as the value for that streamline coordinateNotes
Values are extracted from the image based on the 3D coordinates of the nodes that comprise the points in the streamline, without any interpolation into segments between the nodes. Using this function with streamlines that have been resampled into a very small number of nodes will result in very few values.
defaultdict
¶

class
dipy.tracking.utils.
defaultdict
¶ Bases:
dict
defaultdict(default_factory[, ...]) –> dict with default factory
The default factory is called without arguments to produce a new value when a key is not present, in __getitem__ only. A defaultdict compares equal to a dict with the same items. All remaining arguments are treated the same as if they were passed to the dict constructor, including keyword arguments.
Methods
clear
(() > None. Remove all items from D.)copy
(() > a shallow copy of D.)fromkeys
Returns a new dict with keys from iterable and values equal to value. get
((k[,d]) > D[k] if k in D, ...)items
(...)keys
(...)pop
((k[,d]) > v, ...)If key is not found, d is returned if given, otherwise KeyError is raised popitem
(() > (k, v), ...)2tuple; but raise KeyError if D is empty. setdefault
((k[,d]) > D.get(k,d), ...)update
(([E, ...)If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] values
(...)
__init__
()¶ Initialize self. See help(type(self)) for accurate signature.

copy
() → a shallow copy of D.¶

default_factory
¶ Factory for default value called by __missing__().

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.
Returns: 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,)
Returns: affine : array of shape (4, 4)
A trackviscompatible 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 N1.
Parameters: aff : (N, N) arraylike
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 : (..., N1) arraylike
Points, where the last dimension contains the coordinates of each point. For 3D, the last dimension will be length 3.
Returns: transformed_pts : (..., N1) 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 : datatype, optional
By default, the datatype is inferred from the input data.
order : {‘C’, ‘F’}, optional
Whether to use rowmajor (Cstyle) or columnmajor (Fortranstyle) memory representation. Defaults to ‘C’.
Returns: 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.
See also
asanyarray
 Similar function which passes through subclasses.
ascontiguousarray
 Convert input to a contiguous array.
asfarray
 Convert input to a floating point ndarray.
asfortranarray
 Convert input to an ndarray with columnmajor memory order.
asarray_chkfinite
 Similar function which checks input for NaNs and Infs.
fromiter
 Create an array from an iterator.
fromfunction
 Construct an array by executing a function on grid positions.
Examples
Convert a list into an array:
>>> a = [1, 2] >>> np.asarray(a) array([1, 2])
Existing arrays are not copied:
>>> a = np.array([1, 2]) >>> np.asarray(a) is a True
If dtype is set, array is copied only if dtype does not match:
>>> a = np.array([1, 2], dtype=np.float32) >>> np.asarray(a, dtype=np.float32) is a True >>> np.asarray(a, dtype=np.float64) is a False
Contrary to asanyarray, ndarray subclasses are not passed through:
>>> issubclass(np.matrix, np.ndarray) True >>> a = np.matrix([[1, 2]]) >>> np.asarray(a) is a False >>> np.asanyarray(a) is a True
cdist¶

dipy.tracking.utils.
cdist
(XA, XB, metric='euclidean', p=None, V=None, VI=None, w=None)¶ Computes 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’.
p : double, optional
The pnorm to apply Only for Minkowski, weighted and unweighted. Default: 2.
w : ndarray, optional
The weight vector. Only for weighted Minkowski. Mandatory
V : ndarray, optional
The variance vector Only for standardized Euclidean. Default: var(vstack([XA, XB]), axis=0, ddof=1)
VI : ndarray, optional
The inverse of the covariance matrix Only for Mahalanobis. Default: inv(cov(vstack([XA, XB]).T)).T
Returns: 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.Raises: ValueError
An exception is thrown if XA and XB do not have the same number of columns.
Notes
The following are common calling conventions:
Y = cdist(XA, XB, 'euclidean')
Computes the distance between \(m\) points using Euclidean distance (2norm) as the distance metric between the points. The points are arranged as \(m\) \(n\)dimensional row vectors in the matrix X.
Y = cdist(XA, XB, 'minkowski', p)
Computes the distances using the Minkowski distance \(uv_p\) (\(p\)norm) where \(p \geq 1\).
Y = cdist(XA, XB, 'cityblock')
Computes the city block or Manhattan distance between the points.
Y = cdist(XA, XB, 'seuclidean', V=None)
Computes the standardized Euclidean distance. The standardized Euclidean distance between two nvectors
u
andv
is\[\sqrt{\sum {(u_iv_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.
Y = cdist(XA, XB, 'sqeuclidean')
Computes the squared Euclidean distance \(uv_2^2\) between the vectors.
Y = cdist(XA, XB, 'cosine')
Computes the cosine distance between vectors u and v,
\[1  \frac{u \cdot v} {{u}_2 {v}_2}\]where \(*_2\) is the 2norm of its argument
*
, and \(u \cdot v\) is the dot product of \(u\) and \(v\).Y = cdist(XA, XB, 'correlation')
Computes the correlation distance between vectors u and v. This is
\[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\).
Y = cdist(XA, XB, 'hamming')
Computes the normalized Hamming distance, or the proportion of those vector elements between two nvectors
u
andv
which disagree. To save memory, the matrixX
can be of type boolean.Y = cdist(XA, XB, 'jaccard')
Computes the Jaccard distance between the points. Given two vectors,
u
andv
, the Jaccard distance is the proportion of those elementsu[i]
andv[i]
that disagree where at least one of them is nonzero.Y = cdist(XA, XB, 'chebyshev')
Computes the Chebyshev distance between the points. The Chebyshev distance between two nvectors
u
andv
is the maximum norm1 distance between their respective elements. More precisely, the distance is given by\[d(u,v) = \max_i {u_iv_i}.\]Y = cdist(XA, XB, 'canberra')
Computes the Canberra distance between the points. The Canberra distance between two points
u
andv
is\[d(u,v) = \sum_i \frac{u_iv_i} {u_i+v_i}.\]Y = cdist(XA, XB, 'braycurtis')
Computes the BrayCurtis distance between the points. The BrayCurtis distance between two points
u
andv
is\[d(u,v) = \frac{\sum_i (u_iv_i)} {\sum_i (u_i+v_i)}\]Y = cdist(XA, XB, 'mahalanobis', VI=None)
Computes the Mahalanobis distance between the points. The Mahalanobis distance between two pointsu
andv
is \(\sqrt{(uv)(1/V)(uv)^T}\) where \((1/V)\) (theVI
variable) is the inverse covariance. IfVI
is not None,VI
will be used as the inverse covariance matrix.Y = cdist(XA, XB, 'yule')
Computes the Yule distance between the boolean vectors. (see yule function documentation)Y = cdist(XA, XB, 'matching')
Synonym for ‘hamming’.Y = cdist(XA, XB, 'dice')
Computes the Dice distance between the boolean vectors. (see dice function documentation)Y = cdist(XA, XB, 'kulsinski')
Computes the Kulsinski distance between the boolean vectors. (see kulsinski function documentation)Y = cdist(XA, XB, 'rogerstanimoto')
Computes the RogersTanimoto distance between the boolean vectors. (see rogerstanimoto function documentation)Y = cdist(XA, XB, 'russellrao')
Computes the RussellRao distance between the boolean vectors. (see russellrao function documentation)Y = cdist(XA, XB, 'sokalmichener')
Computes the SokalMichener distance between the boolean vectors. (see sokalmichener function documentation)Y = cdist(XA, XB, 'sokalsneath')
Computes the SokalSneath distance between the vectors. (see sokalsneath function documentation)Y = cdist(XA, XB, 'wminkowski')
Computes the weighted Minkowski distance between the vectors. (see wminkowski function documentation)Y = cdist(XA, XB, f)
Computes the distance between all pairs of vectors in X using the user supplied 2arity function f. For example, Euclidean distance between the vectors could be computed as follows:
dm = cdist(XA, XB, lambda u, v: np.sqrt(((uv)**2).sum()))
Note that you should avoid passing a reference to one of the distance functions defined in this library. For example,:
dm = cdist(XA, XB, sokalsneath)
would calculate the pairwise distances between the vectors in X using the Python function sokalsneath. This would result in sokalsneath being called \({n \choose 2}\) times, which is inefficient. Instead, the optimized C version is more efficient, and we call it using the following syntax:
dm = cdist(XA, XB, 'sokalsneath')
Examples
Find the Euclidean distances between four 2D coordinates:
>>> from scipy.spatial import distance >>> coords = [(35.0456, 85.2672), ... (35.1174, 89.9711), ... (35.9728, 83.9422), ... (36.1667, 86.7833)] >>> distance.cdist(coords, coords, 'euclidean') array([[ 0. , 4.7044, 1.6172, 1.8856], [ 4.7044, 0. , 6.0893, 3.3561], [ 1.6172, 6.0893, 0. , 2.8477], [ 1.8856, 3.3561, 2.8477, 0. ]])
Find the Manhattan distance from a 3D point to the corners of the unit cube:
>>> a = np.array([[0, 0, 0], ... [0, 0, 1], ... [0, 1, 0], ... [0, 1, 1], ... [1, 0, 0], ... [1, 0, 1], ... [1, 1, 0], ... [1, 1, 1]]) >>> b = np.array([[ 0.1, 0.2, 0.4]]) >>> distance.cdist(a, b, 'cityblock') array([[ 0.7], [ 0.9], [ 1.3], [ 1.5], [ 1.5], [ 1.7], [ 2.1], [ 2.3]])
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, False 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.
Returns: 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 ifi < 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.
Returns: image_volume : ndarray, shape=vol_dims
The number of streamline points in each voxel of volume.
Raises: 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.
Returns: 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.
For 2D arrays it is equivalent to matrix multiplication, and for 1D arrays to inner product of vectors (without complex conjugation). For N dimensions it is a sum product over the last axis of a and the secondtolast 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 Ccontiguous, 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.
Returns: output : ndarray
Returns the dot product of a and b. If a and b are both scalars or both 1D arrays then a scalar is returned; otherwise an array is returned. If out is given, then it is returned.
Raises: ValueError
If the last dimension of a is not the same size as the secondtolast dimension of b.
See also
vdot
 Complexconjugating 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 complexconjugated:
>>> np.dot([2j, 3j], [2j, 3j]) (13+0j)
For 2D 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
dtype : datatype, optional
Desired output datatype.
order : {‘C’, ‘F’}, optional
Whether to store multidimensional data in rowmajor (Cstyle) or columnmajor (Fortranstyle) order in memory.
Returns: out : ndarray
Array of uninitialized (arbitrary) data of the given shape, dtype, and order. Object arrays will be initialized to None.
See also
empty_like
,zeros
,ones
Notes
empty, unlike zeros, does not set the array values to zero, and may therefore be marginally faster. On the other hand, it requires the user to manually set all the values in the array, and should be used with caution.
Examples
>>> np.empty([2, 2]) array([[ 9.74499359e+001, 6.69583040e309], [ 2.13182611e314, 3.06959433e309]]) #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'>)¶ Return a 2D 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 : datatype, optional
Datatype of the returned array.
Returns: I : ndarray of shape (N,M)
An array where all elements are equal to zero, except for the kth diagonal, whose values are equal to one.
See also
identity
 (almost) equivalent function
diag
 diagonal 2D array from a 1D 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
Returns: 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.
Returns: 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.
Returns: 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]) >>> np.add.at(a, [0, 1], b) >>> 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 matrixnp.eye(4)
.Returns: streamlines : generator
A sequence of transformed streamlines.
ndbincount¶

dipy.tracking.utils.
ndbincount
(x, weights=None, shape=None)¶ Like bincount, but for ndindicies.
Parameters: x : array_like (N, M)
M indices to a an Ndarray
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. Nonzero 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 endpoints is within tol from ROI
“both_end” : both end points are within tol from ROI.
Returns: 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.
Returns: plm : array
Same shape as aoi. The minimum distance between every point and aoi along the path of a streamline.
random_seeds_from_mask¶

dipy.tracking.utils.
random_seeds_from_mask
(mask, seeds_count=1, seed_count_per_voxel=True, affine=None)¶ Creates randomly placed seeds for fiber tracking from a binary mask.
Seeds points are placed randomly distributed in voxels of
mask
which areTrue
. Ifseed_count_per_voxel
isTrue
, this function is similar toseeds_from_mask()
, with the difference that instead of evenly distributing the seeds, it randomly places the seeds within the voxels specified by themask
. The initial random conditions can be set usingnumpy.random.seed(...)
, prior to calling this function.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])
.Raises: ValueError
When
mask
is not a threedimensional arraySee also
Examples
>>> mask = np.zeros((3,3,3), 'bool') >>> mask[0,0,0] = 1 >>> np.random.seed(1) >>> random_seeds_from_mask(mask, seeds_count=1, seed_count_per_voxel=True) array([[0.082978 , 0.22032449, 0.49988563]]) >>> random_seeds_from_mask(mask, seeds_count=6, seed_count_per_voxel=True) array([[0.19766743, 0.35324411, 0.40766141], [0.31373979, 0.15443927, 0.10323253], [ 0.03881673, 0.08080549, 0.1852195 ], [0.29554775, 0.37811744, 0.47261241], [ 0.17046751, 0.0826952 , 0.05868983], [0.35961306, 0.30189851, 0.30074457]]) >>> mask[0,1,2] = 1 >>> random_seeds_from_mask(mask, seeds_count=2, seed_count_per_voxel=True) array([[ 0.46826158, 0.18657582, 0.19232262], [ 0.37638915, 0.39460666, 0.41495579], [0.46094522, 0.66983042, 2.3781425 ], [0.40165317, 0.92110763, 2.45788953]])
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 multiindex.
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 outofbounds indices are handled. Can specify either one mode or a tuple of modes, one mode per index.
 ‘raise’ – raise an error (default)
 ‘wrap’ – wrap around
 ‘clip’ – clip to the range
In ‘clip’ mode, a negative index which would normally wrap will clip to 0 instead.
order : {‘C’, ‘F’}, optional
Determines whether the multiindex should be viewed as indexing in rowmajor (Cstyle) or columnmajor (Fortranstyle) order.
Returns: raveled_indices : ndarray
An array of indices into the flattened version of an array of dimensions
dims
.See also
unravel_index
Notes
New in version 1.6.0.
Examples
>>> arr = np.array([[3,6,6],[4,5,1]]) >>> np.ravel_multi_index(arr, (7,6)) array([22, 41, 37]) >>> np.ravel_multi_index(arr, (7,6), order='F') array([31, 41, 13]) >>> np.ravel_multi_index(arr, (4,6), mode='clip') array([22, 23, 19]) >>> np.ravel_multi_index(arr, (4,4), mode=('clip','wrap')) array([12, 13, 13])
>>> np.ravel_multi_index((3,1,4,1), (6,7,8,9)) 1621
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). Nonzeros 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.
Returns: 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 nspace. See
nibabel.orientation
ordipy.io.bvectxt
for more information.output_ornt : array (n, 2)
A description of the orientation of a point in nspace.
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.
Returns: A : array (n+1, n+1)
Affine matrix of the transformation between input_ornt and output_ornt.
See also
nibabel.orientation
,dipy.io.bvectxt.orientation_to_string
,dipy.io.bvectxt.orientation_from_string
seeds_from_mask¶

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 areTrue
.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])
.Raises: ValueError
When
mask
is not a threedimensional arraySee also
Examples
>>> mask = np.zeros((3,3,3), 'bool') >>> mask[0,0,0] = 1 >>> seeds_from_mask(mask, [1,1,1], [1,1,1]) array([[ 0.5, 0.5, 0.5]]) >>> seeds_from_mask(mask, [1,2,3], [1,1,1]) 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]]) >>> mask[0,1,2] = 1 >>> seeds_from_mask(mask, [1,1,2], [1.1,1.1,2.5]) 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]])
setup_test¶

dipy.tracking.utils.
setup_test
()¶ Set numpy print options to “legacy” for new versions of numpy
If imported into a file, nosetest will run this before any doctests.
References
https://github.com/numpy/numpy/commit/710e0327687b9f7653e5ac02d222ba62c657a718 https://github.com/numpy/numpy/commit/734b907fc2f7af6e40ec989ca49ee6d87e21c495 https://github.com/nipy/nibabel/pull/556
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 endpoints is within tol from ROI
“both_end” : both end points are within tol from ROI.
Returns: 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.
Returns: 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 : arraylike
A mask used as a target. Nonzero 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.
Returns: streamlines : generator
A sequence of streamlines that pass through target_mask.
Raises: ValueError
When the points of the streamlines lie outside of the target_mask.
See also
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 linebased algorithm. Mostly used as a replacement of target for compressed streamlines.
This function never returns singlepoint 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 : arraylike
A mask used as a target. Nonzero 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.
Returns: 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 streamlinesbased 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.
Returns: u_return: ndarray
Array with the unique rows of the original array.
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().