tracking

Tracking objects

Streamlines

alias of nibabel.streamlines.array_sequence.ArraySequence

bench([label, verbose, extra_argv])

Run benchmarks for module using nose.

test([label, verbose, extra_argv, doctests, …])

Run tests for module using nose.

Module: tracking._utils

This is a helper module for dipy.tracking.utils.

warn(/, message[, category, stacklevel, source])

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

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

With Pytest, Run this benchmark with:

pytest -svv -c bench.ini /path/to/bench_streamline.py

Streamlines

alias of nibabel.streamlines.array_sequence.ArraySequence

assert_array_almost_equal(x, y[, decimal, …])

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

assert_array_equal(x, y[, err_msg, verbose])

Raises an AssertionError if two array_like objects are not equal.

bench_compress_streamlines()

bench_length()

bench_set_number_of_points()

compress_streamlines

Compress streamlines by linearization as in [Presseau15].

compress_streamlines_python(streamline[, …])

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

generate_streamlines(nb_streamlines, …)

get_fnames([name])

Provide full paths to example or test datasets.

length

Euclidean length of streamlines

length_python(xyz[, along])

load_tractogram(filename, reference[, …])

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

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

DirectionGetter

Methods

Module: tracking.distances

Optimized track distances, similarities and distanch clustering algorithms

add_3vecs

approx_polygon_track

Fast and simple trajectory approximation algorithm by Eleftherios and Ian

approximate_mdl_trajectory

Implementation of Lee et al Approximate Trajectory Partitioning Algorithm

bundles_distances_mam

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

bundles_distances_mdf

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

cut_plane

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

inner_3vecs

intersect_segment_cylinder

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

larch_3merge

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

larch_3split

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

lee_angle_distance

Calculates angle distance metric for the distance between two line segments

lee_perpendicular_distance

Calculates perpendicular distance metric for the distance between two line segments

local_skeleton_clustering

Efficient tractography clustering

local_skeleton_clustering_3pts

Does a first pass clustering

mam_distances

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

minimum_closest_distance

Find the minimum distance between two curves xyz1, xyz2

most_similar_track_mam

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

mul_3vec

mul_3vecs

norm_3vec

Euclidean (L2) norm of length 3 vector

normalized_3vec

Return normalized 3D vector

point_segment_sq_distance

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

point_track_sq_distance_check

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

sub_3vecs

track_dist_3pts

Calculate the euclidean distance between two 3pt tracks

track_roi_intersection_check

Check if a track is intersecting a region of interest

warn(/, message[, category, stacklevel, source])

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

Module: tracking.fbcmeasures

EnhancementKernel

Methods

FBCMeasures

Methods

KDTree(data[, leafsize])

kd-tree for quick nearest-neighbor lookup

interp1d(x, y[, kind, axis, copy, …])

Interpolate a 1-D function.

compute_rfbc

Compute the relative fiber to bundle coherence (RFBC)

cpu_count

Return number of cpus as determined by omp_get_num_procs.

determine_num_threads

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

get_sphere([name])

provide triangulated spheres

log(x, [base=math.e])

Return the logarithm of x to the given base.

min_moving_average

Return the lowest cumulative sum for the score of a streamline segment

ndindex(shape)

An N-dimensional iterator object to index arrays.

sqrt(x, /)

Return the square root of x.

Module: tracking.learning

Learning algorithms for tractography

detect_corresponding_tracks(indices, …)

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

detect_corresponding_tracks_plus(indices, …)

Detect corresponding tracks from 1 to 2 where tracks1 & tracks2 are sequences of tracks

Module: tracking.life

This is an implementation of the Linear Fascicle Evaluation (LiFE) algorithm described in:

Pestilli, F., Yeatman, J, Rokem, A. Kay, K. and Wandell B.A. (2014). Validation and statistical inference in living connectomes. Nature Methods 11: 1058-1063. doi:10.1038/nmeth.3098

FiberFit(fiber_model, life_matrix, …)

A fit of the LiFE model to diffusion data

FiberModel(gtab)

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

LifeSignalMaker(gtab[, evals, sphere])

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

ReconstFit(model, data)

Abstract class which holds the fit result of ReconstModel

ReconstModel(gtab)

Abstract class for signal reconstruction models

grad_tensor(grad, evals)

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

gradient(f)

Return the gradient of an N-dimensional array.

streamline_gradients(streamline)

Calculate the gradients of the streamline along the spatial dimension

streamline_signal(streamline, gtab[, evals])

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

streamline_tensors(streamline[, evals])

The tensors generated by this fiber.

transform_streamlines(streamlines, mat[, …])

Apply affine transformation to streamlines

unique_rows(in_array[, dtype])

This (quickly) finds the unique rows in an array

voxel2streamline(streamline, affine[, …])

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

Module: tracking.local_tracking

AnatomicalStoppingCriterion

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

Iterable

LocalTracking(direction_getter, …[, …])

ParticleFilteringTracking(direction_getter, …)

StreamlineStatus

An enumeration.

local_tracker

Tracks one direction from a seed.

pft_tracker

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

Module: tracking.localtrack

local_tracker

Tracks one direction from a seed.

pft_tracker

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

random()

Module: tracking.mesh

random_coordinates_from_surface(…[, …])

Generate random triangles_indices and trilinear_coord

seeds_from_surface_coordinates(triangles, …)

Compute points from triangles_indices and trilinear_coord

triangles_area(triangles, vts)

Compute the local area of each triangle

vertices_to_triangles_values(triangles, …)

Change from values per vertex to values per triangle

Module: tracking.metrics

Metrics for tracks, where tracks are arrays of points

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

deprecate_with_version(message[, since, …])

Return decorator function function for deprecation warning / error.

downsample(xyz[, n_pols])

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

endpoint(xyz)

Parameters

frenet_serret(xyz)

Frenet-Serret Space Curve Invariants

generate_combinations(items, n)

Combine sets of size n from items

inside_sphere(xyz, center, radius)

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

inside_sphere_points(xyz, center, radius)

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

intersect_sphere(xyz, center, radius)

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

length(xyz[, along])

Euclidean length of track line

longest_track_bundle(bundle[, sort])

Return longest track or length sorted track indices in bundle

magn(xyz[, n])

magnitude of vector

mean_curvature(xyz)

Calculates the mean curvature of a curve

mean_orientation(xyz)

Calculates the mean orientation of a curve

midpoint(xyz)

Midpoint of track

midpoint2point(xyz, p)

Calculate distance from midpoint of a curve to arbitrary point p

principal_components(xyz)

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

set_number_of_points

Change the number of points of streamlines

splev(x, tck[, der, ext])

Evaluate a B-spline or its derivatives.

spline(xyz[, s, k, nest])

Generate B-splines as documented in http://www.scipy.org/Cookbook/Interpolation

splprep(x[, w, u, ub, ue, k, task, s, t, …])

Find the B-spline representation of an N-D curve.

startpoint(xyz)

First point of the track

winding(xyz)

Total turning angle projected.

Module: tracking.propspeed

Track propagation performance functions

eudx_both_directions

Parameters

ndarray_offset

Find offset in an N-dimensional ndarray using strides

Module: tracking.stopping_criterion

ActStoppingCriterion

Anatomically-Constrained Tractography (ACT) stopping criterion from [1].

AnatomicalStoppingCriterion

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

BinaryStoppingCriterion

cdef:

CmcStoppingCriterion

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

StoppingCriterion

Methods

StreamlineStatus

An enumeration.

ThresholdStoppingCriterion

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

Module: tracking.streamline

Streamlines

alias of nibabel.streamlines.array_sequence.ArraySequence

apply_affine(aff, pts)

Apply affine matrix aff to points pts

bundles_distances_mdf

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

cdist(XA, XB[, metric])

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

center_streamlines(streamlines)

Move streamlines to the origin

cluster_confidence(streamlines[, max_mdf, …])

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

compress_streamlines

Compress streamlines by linearization as in [Presseau15].

deepcopy(x[, memo, _nil])

Deep copy operation on arbitrary Python objects.

deform_streamlines(streamlines, …)

Apply deformation field to streamlines

dist_to_corner(affine)

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

interpolate_scalar_3d

Trilinear interpolation of a 3D scalar image

interpolate_vector_3d

Trilinear interpolation of a 3D vector field

length

Euclidean length of streamlines

nbytes(streamlines)

orient_by_rois(streamlines, affine, roi1, roi2)

Orient a set of streamlines according to a pair of ROIs

orient_by_streamline(streamlines, standard)

Orient a bundle of streamlines to a standard streamline.

relist_streamlines(points, offsets)

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

select_by_rois(streamlines, affine, rois, …)

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

select_random_set_of_streamlines(…[, rng])

Select a random set of streamlines

set_number_of_points

Change the number of points of streamlines

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(/, message[, category, stacklevel, source])

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

Module: tracking.streamlinespeed

Streamlines

alias of nibabel.streamlines.array_sequence.ArraySequence

compress_streamlines

Compress streamlines by linearization as in [Presseau15].

length

Euclidean length of streamlines

set_number_of_points

Change the number of points of streamlines

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 Notes

Dipy uses affine matrices to represent the relationship between streamline points, which are defined as points in a continuous 3d space, and image voxels, which are typically arranged in a discrete 3d grid. Dipy uses a convention similar to nifti files to interpret these affine matrices. This convention is that the point at the center of voxel [i, j, k] is represented by the point [x, y, z] where [x, y, z, 1] = affine * [i, j, k, 1]. Also when the phrase “voxel coordinates” is used, it is understood to be the same as affine = eye(4).

As an example, lets take a 2d image where the affine is:

[[1., 0., 0.],
 [0., 2., 0.],
 [0., 0., 1.]]

The pixels of an image with this affine would look something like:

A------------
|   |   |   |
| C |   |   |
|   |   |   |
----B--------
|   |   |   |
|   |   |   |
|   |   |   |
-------------
|   |   |   |
|   |   |   |
|   |   |   |
------------D

And the letters A-D represent the following points in “real world coordinates”:

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

OrderedDict

Dictionary that remembers insertion order

combinations

combinations(iterable, r) –> combinations object

defaultdict

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

groupby(iterable[, key])

keys and groups from the iterable.

apply_affine(aff, pts)

Apply affine matrix aff to points pts

asarray(a[, dtype, order, like])

Convert the input to an array.

cdist(XA, XB[, metric])

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

connectivity_matrix(streamlines, affine, …)

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

density_map(streamlines, affine, vol_dims)

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

dist_to_corner(affine)

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

empty(shape[, dtype, order, like])

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

length(streamlines)

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

ndbincount(x[, weights, shape])

Like bincount, but for nd-indices.

near_roi(streamlines, affine, region_of_interest)

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

path_length(streamlines, affine, aoi[, …])

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

random_seeds_from_mask(mask, affine[, …])

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

ravel_multi_index(multi_index, dims[, mode, …])

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

reduce_labels(label_volume)

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

reduce_rois(rois, include)

Reduce multiple ROIs to one inclusion and one exclusion ROI.

seeds_from_mask(mask, affine[, density])

Create seeds for fiber tracking from a binary mask.

streamline_near_roi(streamline, roi_coords, tol)

Is a streamline near an ROI.

subsegment(streamlines, max_segment_length)

Splits the segments of the streamlines into small segments.

target(streamlines, affine, target_mask[, …])

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

target_line_based(streamlines, affine, …)

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

transform_tracking_output(tracking_output, …)

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

unique_rows(in_array[, dtype])

This (quickly) finds the unique rows in an array

warn(/, message[, category, stacklevel, source])

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

Module: tracking.vox2track

This module contains the parts of dipy.tracking.utils that need to be implemented in cython.

streamline_mapping

Creates a mapping from voxel indices to streamlines.

track_counts

Counts of points in tracks that pass through voxels in volume

Streamlines

dipy.tracking.Streamlines

alias of nibabel.streamlines.array_sequence.ArraySequence

bench

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

Run benchmarks for module using nose.

Parameters
label{‘fast’, ‘full’, ‘’, attribute identifier}, optional

Identifies the benchmarks to run. This can be a string to pass to the nosetests executable with the ‘-A’ option, or one of several special values. Special values are:

  • ‘fast’ - the default - which corresponds to the nosetests -A option of ‘not slow’.

  • ‘full’ - fast (as above) and slow benchmarks as in the ‘no -A’ option to nosetests - this is the same as ‘’.

  • None or ‘’ - run all tests.

  • attribute_identifier - string passed directly to nosetests as ‘-A’.

verboseint, optional

Verbosity value for benchmark outputs, in the range 1-10. Default is 1.

extra_argvlist, optional

List with any extra arguments to pass to nosetests.

Returns
successbool

Returns True if running the benchmarks works, False if an error occurred.

Notes

Benchmarks are like tests, but have names starting with “bench” instead of “test”, and can be found under the “benchmarks” sub-directory of the module.

Each NumPy module exposes bench in its namespace to run all benchmarks for it.

Examples

>>> success = np.lib.bench() 
Running benchmarks for numpy.lib
...
using 562341 items:
unique:
0.11
unique1d:
0.11
ratio: 1.0
nUnique: 56230 == 56230
...
OK
>>> success 
True

test

dipy.tracking.test(label='fast', verbose=1, extra_argv=None, doctests=False, coverage=False, raise_warnings=None, timer=False)

Run tests for module using nose.

Parameters
label{‘fast’, ‘full’, ‘’, attribute identifier}, optional

Identifies the tests to run. This can be a string to pass to the nosetests executable with the ‘-A’ option, or one of several special values. Special values are:

  • ‘fast’ - the default - which corresponds to the nosetests -A option of ‘not slow’.

  • ‘full’ - fast (as above) and slow tests as in the ‘no -A’ option to nosetests - this is the same as ‘’.

  • None or ‘’ - run all tests.

  • attribute_identifier - string passed directly to nosetests as ‘-A’.

verboseint, optional

Verbosity value for test outputs, in the range 1-10. Default is 1.

extra_argvlist, optional

List with any extra arguments to pass to nosetests.

doctestsbool, optional

If True, run doctests in module. Default is False.

coveragebool, optional

If True, report coverage of NumPy code. Default is False. (This requires the coverage module).

raise_warningsNone, 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 (), do not raise on any warnings.

timerbool or int, optional

Timing of individual tests with nose-timer (which needs to be installed). If True, time tests and report on all of them. If an integer (say N), report timing results for N slowest tests.

Returns
resultobject

Returns the result of running the tests as a nose.result.TextTestResult object.

Notes

Each NumPy module exposes test in its namespace to run all tests for it. For example, to run all tests for numpy.lib:

>>> np.lib.test() 

Examples

>>> result = np.lib.test() 
Running unit tests for numpy.lib
...
Ran 976 tests in 3.933s

OK

>>> result.errors 
[]
>>> result.knownfail 
[]

warn

dipy.tracking._utils.warn(/, message, category=None, stacklevel=1, source=None)

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

Streamlines

dipy.tracking.benchmarks.bench_streamline.Streamlines

alias of nibabel.streamlines.array_sequence.ArraySequence

assert_array_almost_equal

dipy.tracking.benchmarks.bench_streamline.assert_array_almost_equal(x, y, decimal=6, err_msg='', verbose=True)

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

Note

It is recommended to use one of assert_allclose, assert_array_almost_equal_nulp or assert_array_max_ulp instead of this function for more consistent floating point comparisons.

The test verifies identical shapes and that the elements of actual and desired satisfy.

abs(desired-actual) < 1.5 * 10**(-decimal)

That is a looser test than originally documented, but agrees with what the actual implementation did up to rounding vagaries. An exception is raised at shape mismatch or conflicting values. In contrast to the standard usage in numpy, NaNs are compared like numbers, no assertion is raised if both objects have NaNs in the same positions.

Parameters
xarray_like

The actual object to check.

yarray_like

The desired, expected object.

decimalint, optional

Desired precision, default is 6.

err_msgstr, optional

The error message to be printed in case of failure.

verbosebool, 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)
Traceback (most recent call last):
    ...
AssertionError:
Arrays are not almost equal to 5 decimals

Mismatched elements: 1 / 3 (33.3%)
Max absolute difference: 6.e-05
Max relative difference: 2.57136612e-05
 x: array([1.     , 2.33333,     nan])
 y: array([1.     , 2.33339,     nan])
>>> np.testing.assert_array_almost_equal([1.0,2.33333,np.nan],
...                                      [1.0,2.33333, 5], decimal=5)
Traceback (most recent call last):
    ...
AssertionError:
Arrays are not almost equal to 5 decimals

x and y nan location mismatch:
 x: array([1.     , 2.33333,     nan])
 y: array([1.     , 2.33333, 5.     ])

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 (but see the Notes for the special handling of a scalar). An exception is raised at shape mismatch or conflicting values. In contrast to the standard usage in numpy, NaNs are compared like numbers, no assertion is raised if both objects have NaNs in the same positions.

The usual caution for verifying equality with floating point numbers is advised.

Parameters
xarray_like

The actual object to check.

yarray_like

The desired, expected object.

err_msgstr, optional

The error message to be printed in case of failure.

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

Notes

When one of x and y is a scalar and the other is array_like, the function checks that each element of the array_like object is equal to the scalar.

Examples

The first assert does not raise an exception:

>>> np.testing.assert_array_equal([1.0,2.33333,np.nan],
...                               [np.exp(0),2.33333, np.nan])

Assert fails with numerical imprecision with floats:

>>> np.testing.assert_array_equal([1.0,np.pi,np.nan],
...                               [1, np.sqrt(np.pi)**2, np.nan])
Traceback (most recent call last):
    ...
AssertionError:
Arrays are not equal

Mismatched elements: 1 / 3 (33.3%)
Max absolute difference: 4.4408921e-16
Max relative difference: 1.41357986e-16
 x: array([1.      , 3.141593,      nan])
 y: array([1.      , 3.141593,      nan])

Use assert_allclose or one of the nulp (number of floating point values) functions for these cases instead:

>>> np.testing.assert_allclose([1.0,np.pi,np.nan],
...                            [1, np.sqrt(np.pi)**2, np.nan],
...                            rtol=1e-10, atol=0)

As mentioned in the Notes section, assert_array_equal has special handling for scalars. Here the test checks that each value in x is 3:

>>> x = np.full((2, 5), fill_value=3)
>>> np.testing.assert_array_equal(x, 3)

bench_compress_streamlines

dipy.tracking.benchmarks.bench_streamline.bench_compress_streamlines()

bench_length

dipy.tracking.benchmarks.bench_streamline.bench_length()

bench_set_number_of_points

dipy.tracking.benchmarks.bench_streamline.bench_set_number_of_points()

compress_streamlines

dipy.tracking.benchmarks.bench_streamline.compress_streamlines()

Compress streamlines by linearization as in [Presseau15].

The compression consists in merging consecutive segments that are nearly collinear. The merging is achieved by removing the point the two segments have in common.

The linearization process [Presseau15] ensures that every point being removed are within a certain margin (in mm) of the resulting streamline. Recommendations for setting this margin can be found in [Presseau15] (in which they called it tolerance error).

The compression also ensures that two consecutive points won’t be too far from each other (precisely less or equal than `max_segment_length`mm). This is a tradeoff to speed up the linearization process [Rheault15]. A low value will result in a faster linearization but low compression, whereas a high value will result in a slower linearization but high compression.

Parameters
streamlinesone or a list of array-like of shape (N,3)

Array representing x,y,z of N points in a streamline.

tol_errorfloat (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_lengthfloat (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_streamlinesone or a list of array-like

Results of the linearization process.

Notes

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

References

Presseau15(1,2,3,4,5)

Presseau C. et al., A new compression format for fiber tracking datasets, NeuroImage, no 109, 73-83, 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 Streamlines-Based Metrics for Streamlines with Variable Step Sizes, ISMRM, 2015.

Examples

>>> from dipy.tracking.streamline import compress_streamlines
>>> import numpy as np
>>> # One streamline: a wiggling line
>>> rng = np.random.RandomState(42)
>>> streamline = np.linspace(0, 10, 100*3).reshape((100, 3))
>>> streamline += 0.2 * rng.rand(100, 3)
>>> c_streamline = compress_streamlines(streamline, tol_error=0.2)
>>> len(streamline)
100
>>> len(c_streamline)
10
>>> # Multiple streamlines
>>> streamlines = [streamline, streamline[::2]]
>>> c_streamlines = compress_streamlines(streamlines, tol_error=0.2)
>>> [len(s) for s in streamlines]
[100, 50]
>>> [len(s) for s in c_streamlines]
[10, 7]

compress_streamlines_python

dipy.tracking.benchmarks.bench_streamline.compress_streamlines_python(streamline, tol_error=0.01, max_segment_length=10)

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

generate_streamlines

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

get_fnames

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

Provide full paths to example or test datasets.

Parameters
namestr

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
fnamestuple

filenames for dataset

Examples

>>> import numpy as np
>>> from dipy.io.image import load_nifti
>>> from dipy.data import get_fnames
>>> fimg, fbvals, fbvecs = get_fnames('small_101D')
>>> bvals=np.loadtxt(fbvals)
>>> bvecs=np.loadtxt(fbvecs).T
>>> data, affine = load_nifti(fimg)
>>> data.shape == (6, 10, 10, 102)
True
>>> bvals.shape == (102,)
True
>>> bvecs.shape == (102, 3)
True

length

dipy.tracking.benchmarks.bench_streamline.length()

Euclidean length of streamlines

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

Parameters
streamlinesndarray 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
lengthsscalar or ndarray shape (N,)

If there is only one streamline, a scalar representing the length of the streamline. If there are several streamlines, ndarray containing the length of every streamline.

Examples

>>> from dipy.tracking.streamline import length
>>> import numpy as np
>>> streamline = np.array([[1, 1, 1], [2, 3, 4], [0, 0, 0]])
>>> expected_length = np.sqrt([1+2**2+3**2, 2**2+3**2+4**2]).sum()
>>> length(streamline) == expected_length
True
>>> streamlines = [streamline, np.vstack([streamline, streamline[::-1]])]
>>> expected_lengths = [expected_length, 2*expected_length]
>>> lengths = [length(streamlines[0]), length(streamlines[1])]
>>> np.allclose(lengths, expected_lengths)
True
>>> length([])
0.0
>>> length(np.array([[1, 2, 3]]))
0.0

length_python

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

load_tractogram

dipy.tracking.benchmarks.bench_streamline.load_tractogram(filename, reference, to_space=<Space.RASMM: 'rasmm'>, to_origin=<Origin.NIFTI: 'center'>, bbox_valid_check=True, trk_header_check=True)

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

Parameters
filenamestring

Filename with valid extension

referenceNifti or Trk filename, Nifti1Image or TrkFile, Nifti1Header or

trk.header (dict), or ‘same’ if the input is a trk file. Reference that provides the spatial attribute. Typically a nifti-related object from the native diffusion used for streamlines generation

to_spaceEnum (dipy.io.stateful_tractogram.Space)

Space to which the streamlines will be transformed after loading

to_originEnum (dipy.io.stateful_tractogram.Origin)
Origin to which the streamlines will be transformed after loading

NIFTI standard, default (center of the voxel) TRACKVIS standard (corner of the voxel)

bbox_valid_checkbool

Verification for negative voxel coordinates or values above the volume dimensions. Default is True, to enforce valid file.

trk_header_checkbool

Verification that the reference has the same header as the spatial attributes as the input tractogram when a Trk is loaded

Returns
outputStatefulTractogram

The tractogram to load (must have been saved properly)

measure

dipy.tracking.benchmarks.bench_streamline.measure(code_str, times=1, label=None)

Return elapsed time for executing code in the namespace of the caller.

The supplied code string is compiled with the Python builtin compile. The precision of the timing is 10 milli-seconds. If the code will execute fast on this timescale, it can be executed many times to get reasonable timing accuracy.

Parameters
code_strstr

The code to be timed.

timesint, optional

The number of times the code is executed. Default is 1. The code is only compiled once.

labelstr, optional

A label to identify code_str with. This is passed into compile as the second argument (for run-time error messages).

Returns
elapsedfloat

Total elapsed time in seconds for executing code_str times times.

Examples

>>> times = 10
>>> etime = np.testing.measure('for i in range(1000): np.sqrt(i**2)', times=times)
>>> print("Time for a single execution : ", etime / times, "s")  
Time for a single execution :  0.005 s

set_number_of_points

dipy.tracking.benchmarks.bench_streamline.set_number_of_points()
Change the number of points of streamlines

(either by downsampling or upsampling)

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

Parameters
streamlinesndarray 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_pointsint

integer representing number of points wanted along the curve.

Returns
new_streamlinesndarray or a list or dipy.tracking.Streamlines

Results of the downsampling or upsampling process.

Examples

>>> from dipy.tracking.streamline import set_number_of_points
>>> import numpy as np

One streamline, a semi-circle:

>>> theta = np.pi*np.linspace(0, 1, 100)
>>> x = np.cos(theta)
>>> y = np.sin(theta)
>>> z = 0 * x
>>> streamline = np.vstack((x, y, z)).T
>>> modified_streamline = set_number_of_points(streamline, 3)
>>> len(modified_streamline)
3

Multiple streamlines:

>>> streamlines = [streamline, streamline[::2]]
>>> new_streamlines = set_number_of_points(streamlines, 10)
>>> [len(s) for s in streamlines]
[100, 50]
>>> [len(s) for s in new_streamlines]
[10, 10]

set_number_of_points_python

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

setup

dipy.tracking.benchmarks.bench_streamline.setup()

DirectionGetter

class dipy.tracking.direction_getter.DirectionGetter

Bases: object

Methods

get_direction

initial_direction

__init__(*args, **kwargs)

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

get_direction()
initial_direction()

add_3vecs

dipy.tracking.distances.add_3vecs()

approx_polygon_track

dipy.tracking.distances.approx_polygon_track()

Fast and simple trajectory approximation algorithm by Eleftherios and Ian

It will reduce the number of points of the track by keeping intact the start and endpoints of the track and trying to remove as many points as possible without distorting much the shape of the track

Parameters
xyzarray(N,3)

initial trajectory

alphafloat

smoothing parameter (<0.392 smoother, >0.392 rougher) if the trajectory was a smooth circle then with alpha =0.393 ~=pi/8. the circle would be approximated with an decahexagon if alpha = 0.7853 ~=pi/4. with an octagon.

Returns
characteristic_points: list of M array(3,) points

Notes

Assuming that a good approximation for a circle is an octagon then that means that the points of the octagon will have angle alpha = 2*pi/8 = pi/4 . We calculate the angle between every two neighbour segments of a trajectory and if the angle is higher than pi/4 we choose that point as a characteristic point otherwise we move at the next point.

Examples

Approximating a helix:

>>> t=np.linspace(0,1.75*2*np.pi,100)
>>> x = np.sin(t)
>>> y = np.cos(t)
>>> z = t
>>> xyz=np.vstack((x,y,z)).T
>>> xyza = approx_polygon_track(xyz)
>>> len(xyza) < len(xyz)
True

approximate_mdl_trajectory

dipy.tracking.distances.approximate_mdl_trajectory()

Implementation of Lee et al Approximate Trajectory Partitioning Algorithm

This is base on the minimum description length principle

Parameters
xyzarray(N,3)

initial trajectory

alphafloat

smoothing parameter (>1 smoother, <1 rougher)

Returns
characteristic_pointslist of M array(3,) points

bundles_distances_mam

dipy.tracking.distances.bundles_distances_mam()

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

Parameters
tracksAsequence

of tracks as arrays, shape (N1,3) .. (Nm,3)

tracksBsequence

of tracks as arrays, shape (N1,3) .. (Nm,3)

metricstr

‘avg’, ‘min’, ‘max’

Returns
DMarray, shape (len(tracksA), len(tracksB))

distances between tracksA and tracksB according to metric

bundles_distances_mdf

dipy.tracking.distances.bundles_distances_mdf()

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

All tracks need to have the same number of points

Parameters
tracksAsequence

of tracks as arrays, [(N,3) .. (N,3)]

tracksBsequence

of tracks as arrays, [(N,3) .. (N,3)]

Returns
DMarray, shape (len(tracksA), len(tracksB))

distances between tracksA and tracksB according to metric

cut_plane

dipy.tracking.distances.cut_plane()

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

Parameters
trackssequence

of tracks as arrays, shape (N1,3) .. (Nm,3)

refarray, shape (N,3)

reference track

Returns
hitssequence

list of points and rcds (radial coefficient of divergence)

Notes

The orthogonality relationship np.inner(hits[p][q][0:3]-ref[p+1],ref[p+2]-ref[r][p+1]) will hold throughout for every point q in the hits plane at point (p+1) on the reference track.

Examples

>>> refx = np.array([[0,0,0],[1,0,0],[2,0,0],[3,0,0]],dtype='float32')
>>> bundlex = [np.array([[0.5,1,0],[1.5,2,0],[2.5,3,0]],dtype='float32')]
>>> res = cut_plane(bundlex,refx)
>>> len(res)
2
>>> print(res[0])
[[ 1.          1.5         0.          0.70710683  0.        ]]
>>> print(res[1])
[[ 2.          2.5         0.          0.70710677  0.        ]]

inner_3vecs

dipy.tracking.distances.inner_3vecs()

intersect_segment_cylinder

dipy.tracking.distances.intersect_segment_cylinder()

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

See p.197 from Real Time Collision Detection by C. Ericson

Examples

Define cylinder using a segment defined by

>>> p=np.array([0,0,0],dtype=np.float32)
>>> q=np.array([1,0,0],dtype=np.float32)
>>> r=0.5

Define segment

>>> sa=np.array([0.5,1 ,0],dtype=np.float32)
>>> sb=np.array([0.5,-1,0],dtype=np.float32)

Intersection

>>> intersect_segment_cylinder(sa, sb, p, q, r)
(1.0, 0.25, 0.75)

larch_3merge

dipy.tracking.distances.larch_3merge()

Reassign tracks to existing clusters by merging clusters that their representative tracks are not very distant i.e. less than sqd_thr. Using tracks consisting of 3 points (first, mid and last). This is necessary after running larch_fast_split after multiple split in different levels (squared thresholds) as some of them have created independent clusters.

Parameters
Cgraph with clusters

of indices 3tracks (tracks consisting of 3 points only)

sqd_trh: float

squared euclidean distance threshold

Returns
Cdict

a tree graph containing the clusters

larch_3split

dipy.tracking.distances.larch_3split()

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

Parameters
trackssequence

of tracks as arrays, shape (N1,3) .. (Nm,3), where 3 points are (first, mid and last)

indicesNone or sequence, optional

Sequence of integer indices of tracks

trhfloat, optional

squared euclidean distance threshold

Returns
Cdict

A tree graph containing the clusters.

Notes

If a 3 point track (3track) is far away from all clusters then add a new cluster and assign this 3track as the rep(representative) track for the new cluster. Otherwise the rep 3track of each cluster is the average track of the cluster.

Examples

>>> tracks=[np.array([[0,0,0],[1,0,0,],[2,0,0]],dtype=np.float32),
...         np.array([[3,0,0],[3.5,1,0],[4,2,0]],dtype=np.float32),
...         np.array([[3.2,0,0],[3.7,1,0],[4.4,2,0]],dtype=np.float32),
...         np.array([[3.4,0,0],[3.9,1,0],[4.6,2,0]],dtype=np.float32),
...         np.array([[0,0.2,0],[1,0.2,0],[2,0.2,0]],dtype=np.float32),
...         np.array([[2,0.2,0],[1,0.2,0],[0,0.2,0]],dtype=np.float32),
...         np.array([[0,0,0],[0,1,0],[0,2,0]],dtype=np.float32),
...         np.array([[0.2,0,0],[0.2,1,0],[0.2,2,0]],dtype=np.float32),
...         np.array([[-0.2,0,0],[-0.2,1,0],[-0.2,2,0]],dtype=np.float32)]
>>> C = larch_3split(tracks, None, 0.5)

Here is an example of how to visualize the clustering above:

from dipy.viz import window, actor
scene = window.Scene()
scene.add(actor.line(tracks,window.colors.red))
window.show(scene)
for c in C:
    color=np.random.rand(3)
    for i in C[c]['indices']:
        scene.add(actor.line(tracks[i],color))
window.show(scene)
for c in C:
    scene.add(actor.line(C[c]['rep3']/C[c]['N'],
                         window.colors.white))
window.show(scene)

lee_angle_distance

dipy.tracking.distances.lee_angle_distance()

Calculates angle distance metric for the distance between two line segments

Based on Lee , Han & Whang SIGMOD07.

This function assumes that norm(end0-start0)>norm(end1-start1) i.e. that the first segment will be bigger than the second one.

Parameters
start0float array(3,)
end0float array(3,)
start1float array(3,)
end1float array(3,)
Returns
angle_distancefloat

Notes

l_0 = np.inner(end0-start0,end0-start0) l_1 = np.inner(end1-start1,end1-start1)

cos_theta_squared = np.inner(end0-start0,end1-start1)**2/ (l_0*l_1) return np.sqrt((1-cos_theta_squared)*l_1)

Examples

>>> lee_angle_distance([0,0,0],[1,0,0],[3,4,5],[5,4,3])
2.0

lee_perpendicular_distance

dipy.tracking.distances.lee_perpendicular_distance()

Calculates perpendicular distance metric for the distance between two line segments

Based on Lee , Han & Whang SIGMOD07.

This function assumes that norm(end0-start0)>norm(end1-start1) i.e. that the first segment will be bigger than the second one.

Parameters
start0float array(3,)
end0float array(3,)
start1float array(3,)
end1float array(3,)
Returns
perpendicular_distance: float

Notes

l0 = np.inner(end0-start0,end0-start0) l1 = np.inner(end1-start1,end1-start1)

k0=end0-start0

u1 = np.inner(start1-start0,k0)/l0 u2 = np.inner(end1-start0,k0)/l0

ps = start0+u1*k0 pe = start0+u2*k0

lperp1 = np.sqrt(np.inner(ps-start1,ps-start1)) lperp2 = np.sqrt(np.inner(pe-end1,pe-end1))

if lperp1+lperp2 > 0.:

return (lperp1**2+lperp2**2)/(lperp1+lperp2)

else:

return 0.

Examples

>>> d = lee_perpendicular_distance([0,0,0],[1,0,0],[3,4,5],[5,4,3])
>>> print('%.6f' % d)
5.787888

local_skeleton_clustering

dipy.tracking.distances.local_skeleton_clustering()

Efficient tractography clustering

Every track can needs to have the same number of points. Use dipy.tracking.metrics.downsample to restrict the number of points

Parameters
trackssequence

of tracks as arrays, shape (N,3) .. (N,3) where N=points

d_thrfloat

average euclidean distance threshold

Returns
Cdict

Clusters.

Notes

The distance calculated between two tracks:

t_1       t_2

0*   a    *0
  \       |
   \      |
   1*     |
    |  b  *1
    |      \
    2*      \
        c    *2

is equal to \((a+b+c)/3\) where \(a\) the euclidean distance between t_1[0] and t_2[0], \(b\) between t_1[1] and t_2[1] and \(c\) between t_1[2] and t_2[2]. Also the same with t2 flipped (so t_1[0] compared to t_2[2] etc).

Visualization:

It is possible to visualize the clustering C from the example above using the dipy.viz module:

from dipy.viz import window, actor
scene = window.Scene()
for c in C:
    color=np.random.rand(3)
    for i in C[c]['indices']:
        scene.add(actor.line(tracks[i],color))
window.show(scene)

Examples

>>> tracks=[np.array([[0,0,0],[1,0,0,],[2,0,0]]),
...         np.array([[3,0,0],[3.5,1,0],[4,2,0]]),
...         np.array([[3.2,0,0],[3.7,1,0],[4.4,2,0]]),
...         np.array([[3.4,0,0],[3.9,1,0],[4.6,2,0]]),
...         np.array([[0,0.2,0],[1,0.2,0],[2,0.2,0]]),
...         np.array([[2,0.2,0],[1,0.2,0],[0,0.2,0]]),
...         np.array([[0,0,0],[0,1,0],[0,2,0]])]
>>> C = local_skeleton_clustering(tracks, d_thr=0.5)

local_skeleton_clustering_3pts

dipy.tracking.distances.local_skeleton_clustering_3pts()

Does a first pass clustering

Every track can only have 3 pts neither less or more. Use dipy.tracking.metrics.downsample to restrict the number of points

Parameters
trackssequence

of tracks as arrays, shape (N,3) .. (N,3) where N=3

d_thrfloat

Average euclidean distance threshold

Returns
Cdict

Clusters.

Notes

It is possible to visualize the clustering C from the example above using the fvtk module:

r=fvtk.ren()
for c in C:
    color=np.random.rand(3)
    for i in C[c]['indices']:
        fvtk.add(r,fos.line(tracks[i],color))
fvtk.show(r)

Examples

>>> tracks=[np.array([[0,0,0],[1,0,0,],[2,0,0]]),
...         np.array([[3,0,0],[3.5,1,0],[4,2,0]]),
...         np.array([[3.2,0,0],[3.7,1,0],[4.4,2,0]]),
...         np.array([[3.4,0,0],[3.9,1,0],[4.6,2,0]]),
...         np.array([[0,0.2,0],[1,0.2,0],[2,0.2,0]]),
...         np.array([[2,0.2,0],[1,0.2,0],[0,0.2,0]]),
...         np.array([[0,0,0],[0,1,0],[0,2,0]])]
>>> C=local_skeleton_clustering_3pts(tracks,d_thr=0.5)

mam_distances

dipy.tracking.distances.mam_distances()

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

Based on the metrics in Zhang, Correia, Laidlaw 2008 http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=4479455 which in turn are based on those of Corouge et al. 2004

Parameters
xyz1array, shape (N1,3), dtype float32
xyz2array, shape (N2,3), dtype float32

arrays representing x,y,z of the N1 and N2 points of two tracks

metrics{‘avg’,’min’,’max’,’all’}

Metric to calculate. {‘avg’,’min’,’max’} return a scalar. ‘all’ returns a tuple

Returns
avg_mcdfloat

average_mean_closest_distance

min_mcdfloat

minimum_mean_closest_distance

max_mcdfloat

maximum_mean_closest_distance

Notes

Algorithmic description

Lets say we have curves A and B.

For every point in A calculate the minimum distance from every point in B stored in minAB

For every point in B calculate the minimum distance from every point in A stored in minBA

find average of minAB stored as avg_minAB find average of minBA stored as avg_minBA

if metric is ‘avg’ then return (avg_minAB + avg_minBA)/2.0 if metric is ‘min’ then return min(avg_minAB,avg_minBA) if metric is ‘max’ then return max(avg_minAB,avg_minBA)

minimum_closest_distance

dipy.tracking.distances.minimum_closest_distance()

Find the minimum distance between two curves xyz1, xyz2

Parameters
xyz1array, shape (N1,3), dtype float32
xyz2array, shape (N2,3), dtype float32

arrays representing x,y,z of the N1 and N2 points of two tracks

Returns
mdminimum distance

Notes

Algorithmic description

Lets say we have curves A and B

for every point in A calculate the minimum distance from every point in B stored in minAB for every point in B calculate the minimum distance from every point in A stored in minBA find min of minAB stored in min_minAB find min of minBA stored in min_minBA

Then return (min_minAB + min_minBA)/2.0

most_similar_track_mam

dipy.tracking.distances.most_similar_track_mam()

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

Parameters
trackssequence

of tracks as arrays, shape (N1,3) .. (Nm,3)

metricstr

‘avg’, ‘min’, ‘max’

Returns
siint

index of the most similar track in tracks. This can be used as a reference track for a bundle.

sarray, shape (len(tracks),)

similarities between tracks[si] and the rest of the tracks in the bundle

Notes

A vague description of this function is given below:

for (i,j) in tracks_combinations_of_2:

calculate the mean_closest_distance from i to j (mcd_i) calculate the mean_closest_distance from j to i (mcd_j)

if ‘avg’:

s holds the average similarities

if ‘min’:

s holds the minimum similarities

if ‘max’:

s holds the maximum similarities

si holds the index of the track with min {avg,min,max} average metric

mul_3vec

dipy.tracking.distances.mul_3vec()

mul_3vecs

dipy.tracking.distances.mul_3vecs()

norm_3vec

dipy.tracking.distances.norm_3vec()

Euclidean (L2) norm of length 3 vector

Parameters
vecarray-like shape (3,)
Returns
normfloat

Euclidean norm

normalized_3vec

dipy.tracking.distances.normalized_3vec()

Return normalized 3D vector

Vector divided by Euclidean (L2) norm

Parameters
vecarray-like shape (3,)
Returns
vec_outarray shape (3,)

point_segment_sq_distance

dipy.tracking.distances.point_segment_sq_distance()

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

Examples

>>> a=np.array([0,0,0], dtype=np.float32)
>>> b=np.array([1,0,0], dtype=np.float32)
>>> c=np.array([0,1,0], dtype=np.float32)
>>> point_segment_sq_distance(a, b, c)
1.0
>>> c = np.array([0,3,0], dtype=np.float32)
>>> point_segment_sq_distance(a,b,c)
9.0
>>> c = np.array([-1,1,0], dtype=np.float32)
>>> point_segment_sq_distance(a, b, c)
2.0

point_track_sq_distance_check

dipy.tracking.distances.point_track_sq_distance_check()

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

Parameters
track: array,float32, shape (N,3)
point: array,float32, shape (3,)
sq_dist_thr: double, threshold
Returns
bool: True, if sq_distance <= sq_dist_thr, otherwise False.

Examples

>>> t=np.random.rand(10,3).astype(np.float32)
>>> p=np.array([0.5,0.5,0.5],dtype=np.float32)
>>> point_track_sq_distance_check(t,p,2**2)
True
>>> t=np.array([[0,0,0],[1,1,1],[2,2,2]],dtype='f4')
>>> p=np.array([-1,-1.,-1],dtype='f4')
>>> point_track_sq_distance_check(t,p,.2**2)
False
>>> point_track_sq_distance_check(t,p,2**2)
True

sub_3vecs

dipy.tracking.distances.sub_3vecs()

track_dist_3pts

dipy.tracking.distances.track_dist_3pts()

Calculate the euclidean distance between two 3pt tracks

Both direct and flip distances are calculated but only the smallest is returned

Parameters
aarray, shape (3,3)
a three point track
barray, shape (3,3)
a three point track
Returns
dist :float

Examples

>>> a = np.array([[0,0,0],[1,0,0,],[2,0,0]])
>>> b = np.array([[3,0,0],[3.5,1,0],[4,2,0]])
>>> c = track_dist_3pts(a, b)
>>> print('%.6f' % c)
2.721573

track_roi_intersection_check

dipy.tracking.distances.track_roi_intersection_check()

Check if a track is intersecting a region of interest

Parameters
track: array,float32, shape (N,3)
roi: array,float32, shape (M,3)
sq_dist_thr: double, threshold, check squared euclidean distance from every roi point
Returns
bool: True, if sq_distance <= sq_dist_thr, otherwise False.

Examples

>>> roi=np.array([[0,0,0],[1,0,0],[2,0,0]],dtype='f4')
>>> t=np.array([[0,0,0],[1,1,1],[2,2,2]],dtype='f4')
>>> track_roi_intersection_check(t,roi,1)
True
>>> track_roi_intersection_check(t,np.array([[10,0,0]],dtype='f4'),1)
False

warn

dipy.tracking.distances.warn(/, message, category=None, stacklevel=1, source=None)

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

EnhancementKernel

class dipy.tracking.fbcmeasures.EnhancementKernel

Bases: object

Methods

evaluate_kernel

Evaluate the kernel at position x relative to position y, with orientation r relative to orientation v.

get_lookup_table

Return the computed look-up table.

get_orientations

Return the orientations.

get_sphere

Get the sphere corresponding with the orientations

__init__()

Compute a look-up table for the contextual enhancement kernel

Parameters
D33float

Spatial diffusion

D44float

Angular diffusion

tfloat

Diffusion time

force_recomputeboolean

Always compute the look-up table even if it is available in cache. Default is False.

orientationsinteger or Sphere object

Specify the number of orientations to be used with electrostatic repulsion, or provide a Sphere object. The default sphere is ‘repulsion100’.

verboseboolean

Enable verbose mode.

References

[Meesters2016_ISMRM] S. Meesters, G. Sanguinetti, E. Garyfallidis,

J. Portegies, R. Duits. (2016) Fast implementations of contextual PDE’s for HARDI data processing in DIPY. ISMRM 2016 conference.

[DuitsAndFranken_IJCV] R. Duits and E. Franken (2011) Left-invariant diffusions

on the space of positions and orientations and their application to crossing-preserving smoothing of HARDI images. International Journal of Computer Vision, 92:231-264.

[Portegies2015] J. Portegies, G. Sanguinetti, S. Meesters, and R. Duits.

(2015) New Approximation of a Scale Space Kernel on SE(3) and Applications in Neuroimaging. Fifth International Conference on Scale Space and Variational Methods in Computer Vision

[Portegies2015b] J. Portegies, R. Fick, G. Sanguinetti, S. Meesters,

G. Girard, and R. Duits. (2015) Improving Fiber Alignment in HARDI by Combining Contextual PDE flow with Constrained Spherical Deconvolution. PLoS One.

evaluate_kernel()

Evaluate the kernel at position x relative to position y, with orientation r relative to orientation v.

Parameters
x1D ndarray

Position x

y1D ndarray

Position y

r1D ndarray

Orientation r

v1D ndarray

Orientation v

Returns
kernel_valuedouble
get_lookup_table()

Return the computed look-up table.

get_orientations()

Return the orientations.

get_sphere()

Get the sphere corresponding with the orientations

FBCMeasures

class dipy.tracking.fbcmeasures.FBCMeasures

Bases: object

Methods

get_points_rfbc_thresholded

Set a threshold on the RFBC to remove spurious fibers.

__init__()

Compute the fiber to bundle coherence measures for a set of streamlines.

Parameters
streamlineslist

A collection of streamlines, each n by 3, with n being the number of nodes in the fiber.

kernelKernel object

A diffusion kernel object created from EnhancementKernel.

min_fiberlengthint

Fibers with fewer points than minimum_length are excluded from FBC computation.

max_windowsizeint

The maximal window size used to calculate the average LFBC region

num_threadsint, optional

Number of threads to be used for OpenMP parallelization. If None (default) the value of OMP_NUM_THREADS environment variable is used if it is set, otherwise all available threads are used. If < 0 the maximal number of threads minus |num_threads + 1| is used (enter -1 to use as many threads as possible). 0 raises an error.

verboseboolean

Enable verbose mode.

References

[Meesters2016_HBM] S. Meesters, G. Sanguinetti, E. Garyfallidis,

J. Portegies, P. Ossenblok, R. Duits. (2016) Cleaning output of tractography via fiber to bundle coherence, a new open source implementation. Human Brain Mapping conference 2016.

[Portegies2015b] J. Portegies, R. Fick, G. Sanguinetti, S. Meesters,

G.Girard, and R. Duits. (2015) Improving Fiber Alignment in HARDI by Combining Contextual PDE flow with Constrained Spherical Deconvolution. PLoS One.

get_points_rfbc_thresholded()

Set a threshold on the RFBC to remove spurious fibers.

Parameters
thresholdfloat

The threshold to set on the RFBC, should be within 0 and 1.

emphasisfloat

Enhances the coloring of the fibers by LFBC. Increasing emphasis will stress spurious fibers by logarithmic weighting.

verboseboolean

Prints info about the found RFBC for the set of fibers such as median, mean, min and max values.

Returns
outputtuple with 3 elements

The output contains: 1) a collection of streamlines, each n by 3, with n being the number of nodes in the fiber that remain after filtering 2) the r,g,b values of the local fiber to bundle coherence (LFBC) 3) the relative fiber to bundle coherence (RFBC)

KDTree

class dipy.tracking.fbcmeasures.KDTree(data, leafsize=10)

Bases: object

kd-tree for quick nearest-neighbor lookup

This class provides an index into a set of k-D points which can be used to rapidly look up the nearest neighbors of any point.

Parameters
data(N,K) array_like

The data points to be indexed. This array is not copied, and so modifying this data will result in bogus results.

leafsizeint, optional

The number of points at which the algorithm switches over to brute-force. Has to be positive.

Raises
RuntimeError

The maximum recursion limit can be exceeded for large data sets. If this happens, either increase the value for the leafsize parameter or increase the recursion limit by:

>>> import sys
>>> sys.setrecursionlimit(10000)

See also

cKDTree

Implementation of KDTree in Cython

Notes

The algorithm used is described in Maneewongvatana and Mount 1999. The general idea is that the kd-tree is a binary tree, each of whose nodes represents an axis-aligned hyperrectangle. Each node specifies an axis and splits the set of points based on whether their coordinate along that axis is greater than or less than a particular value.

During construction, the axis and splitting point are chosen by the “sliding midpoint” rule, which ensures that the cells do not all become long and thin.

The tree can be queried for the r closest neighbors of any given point (optionally returning only those within some maximum distance of the point). It can also be queried, with a substantial gain in efficiency, for the r approximate closest neighbors.

For large dimensions (20 is already large) do not expect this to run significantly faster than brute force. High-dimensional nearest-neighbor queries are a substantial open problem in computer science.

The tree also supports all-neighbors queries, both with arrays of points and with other kd-trees. These do use a reasonably efficient algorithm, but the kd-tree is not necessarily the best data structure for this sort of calculation.

Methods

count_neighbors(other, r[, p])

Count how many nearby pairs can be formed.

query(x[, k, eps, p, distance_upper_bound])

Query the kd-tree for nearest neighbors

query_ball_point(x, r[, p, eps])

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

query_ball_tree(other, r[, p, eps])

Find all pairs of points whose distance is at most r

query_pairs(r[, p, eps])

Find all pairs of points within a distance.

sparse_distance_matrix(other, max_distance)

Compute a sparse distance matrix

innernode

leafnode

node

__init__(data, leafsize=10)

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

count_neighbors(other, r, p=2.0)

Count how many nearby pairs can be formed.

Count the number of pairs (x1,x2) can be formed, with x1 drawn from self and x2 drawn from other, and where distance(x1, x2, p) <= r. This is the “two-point correlation” described in Gray and Moore 2000, “N-body problems in statistical learning”, and the code here is based on their algorithm.

Parameters
otherKDTree instance

The other tree to draw points from.

rfloat or one-dimensional array of floats

The radius to produce a count for. Multiple radii are searched with a single tree traversal.

pfloat, 1<=p<=infinity, optional

Which Minkowski p-norm to use

Returns
resultint or 1-D array of ints

The number of pairs. Note that this is internally stored in a numpy int, and so may overflow if very large (2e9).

class innernode(split_dim, split, less, greater)

Bases: scipy.spatial.kdtree.node

class leafnode(idx)

Bases: scipy.spatial.kdtree.node

class node

Bases: object

query(x, k=1, eps=0, p=2, distance_upper_bound=inf)

Query the kd-tree for nearest neighbors

Parameters
xarray_like, last dimension self.m

An array of points to query.

kint, optional

The number of nearest neighbors to return.

epsnonnegative float, optional

Return approximate nearest neighbors; the kth returned value is guaranteed to be no further than (1+eps) times the distance to the real kth nearest neighbor.

pfloat, 1<=p<=infinity, optional

Which Minkowski p-norm to use. 1 is the sum-of-absolute-values “Manhattan” distance 2 is the usual Euclidean distance infinity is the maximum-coordinate-difference distance

distance_upper_boundnonnegative float, optional

Return only neighbors within this distance. This is used to prune tree searches, so if you are doing a series of nearest-neighbor queries, it may help to supply the distance to the nearest neighbor of the most recent point.

Returns
dfloat or array of floats

The distances to the nearest neighbors. If x has shape tuple+(self.m,), then d has shape tuple if k is one, or tuple+(k,) if k is larger than one. Missing neighbors (e.g. when k > n or distance_upper_bound is given) are indicated with infinite distances. If k is None, then d is an object array of shape tuple, containing lists of distances. In either case the hits are sorted by distance (nearest first).

iinteger or array of integers

The locations of the neighbors in self.data. i is the same shape as d.

Examples

>>> from scipy import spatial
>>> x, y = np.mgrid[0:5, 2:8]
>>> tree = spatial.KDTree(list(zip(x.ravel(), y.ravel())))
>>> tree.data
array([[0, 2],
       [0, 3],
       [0, 4],
       [0, 5],
       [0, 6],
       [0, 7],
       [1, 2],
       [1, 3],
       [1, 4],
       [1, 5],
       [1, 6],
       [1, 7],
       [2, 2],
       [2, 3],
       [2, 4],
       [2, 5],
       [2, 6],
       [2, 7],
       [3, 2],
       [3, 3],
       [3, 4],
       [3, 5],
       [3, 6],
       [3, 7],
       [4, 2],
       [4, 3],
       [4, 4],
       [4, 5],
       [4, 6],
       [4, 7]])
>>> pts = np.array([[0, 0], [2.1, 2.9]])
>>> tree.query(pts)
(array([ 2.        ,  0.14142136]), array([ 0, 13]))
>>> tree.query(pts[0])
(2.0, 0)
query_ball_point(x, r, p=2.0, eps=0)

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

Parameters
xarray_like, shape tuple + (self.m,)

The point or points to search for neighbors of.

rpositive float

The radius of points to return.

pfloat, optional

Which Minkowski p-norm to use. Should be in the range [1, inf].

epsnonnegative float, optional

Approximate search. Branches of the tree are not explored if their nearest points are further than r / (1 + eps), and branches are added in bulk if their furthest points are nearer than r * (1 + eps).

Returns
resultslist or array of lists

If x is a single point, returns a list of the indices of the neighbors of x. If x is an array of points, returns an object array of shape tuple containing lists of neighbors.

Notes

If you have many points whose neighbors you want to find, you may save substantial amounts of time by putting them in a KDTree and using query_ball_tree.

Examples

>>> from scipy import spatial
>>> x, y = np.mgrid[0:5, 0:5]
>>> points = np.c_[x.ravel(), y.ravel()]
>>> tree = spatial.KDTree(points)
>>> tree.query_ball_point([2, 0], 1)
[5, 10, 11, 15]

Query multiple points and plot the results:

>>> import matplotlib.pyplot as plt
>>> points = np.asarray(points)
>>> plt.plot(points[:,0], points[:,1], '.')
>>> for results in tree.query_ball_point(([2, 0], [3, 3]), 1):
...     nearby_points = points[results]
...     plt.plot(nearby_points[:,0], nearby_points[:,1], 'o')
>>> plt.margins(0.1, 0.1)
>>> plt.show()
query_ball_tree(other, r, p=2.0, eps=0)

Find all pairs of points whose distance is at most r

Parameters
otherKDTree instance

The tree containing points to search against.

rfloat

The maximum distance, has to be positive.

pfloat, optional

Which Minkowski norm to use. p has to meet the condition 1 <= p <= infinity.

epsfloat, optional

Approximate search. Branches of the tree are not explored if their nearest points are further than r/(1+eps), and branches are added in bulk if their furthest points are nearer than r * (1+eps). eps has to be non-negative.

Returns
resultslist of lists

For each element self.data[i] of this tree, results[i] is a list of the indices of its neighbors in other.data.

query_pairs(r, p=2.0, eps=0)

Find all pairs of points within a distance.

Parameters
rpositive float

The maximum distance.

pfloat, optional

Which Minkowski norm to use. p has to meet the condition 1 <= p <= infinity.

epsfloat, optional

Approximate search. Branches of the tree are not explored if their nearest points are further than r/(1+eps), and branches are added in bulk if their furthest points are nearer than r * (1+eps). eps has to be non-negative.

Returns
resultsset

Set of pairs (i,j), with i < j, for which the corresponding positions are close.

sparse_distance_matrix(other, max_distance, p=2.0)

Compute a sparse distance matrix

Computes a distance matrix between two KDTrees, leaving as zero any distance greater than max_distance.

Parameters
otherKDTree
max_distancepositive float
pfloat, optional
Returns
resultdok_matrix

Sparse matrix representing the results in “dictionary of keys” format.

interp1d

class dipy.tracking.fbcmeasures.interp1d(x, y, kind='linear', axis=-1, copy=True, bounds_error=None, fill_value=nan, assume_sorted=False)

Bases: scipy.interpolate.polyint._Interpolator1D

Interpolate a 1-D function.

x and y are arrays of values used to approximate some function f: y = f(x). This class returns a function whose call method uses interpolation to find the value of new points.

Note that calling interp1d with NaNs present in input values results in undefined behaviour.

Parameters
x(N,) array_like

A 1-D array of real values.

y(…,N,…) array_like

A N-D array of real values. The length of y along the interpolation axis must be equal to the length of x.

kindstr or int, optional

Specifies the kind of interpolation as a string (‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’, ‘previous’, ‘next’, where ‘zero’, ‘slinear’, ‘quadratic’ and ‘cubic’ refer to a spline interpolation of zeroth, first, second or third order; ‘previous’ and ‘next’ simply return the previous or next value of the point) or as an integer specifying the order of the spline interpolator to use. Default is ‘linear’.

axisint, optional

Specifies the axis of y along which to interpolate. Interpolation defaults to the last axis of y.

copybool, optional

If True, the class makes internal copies of x and y. If False, references to x and y are used. The default is to copy.

bounds_errorbool, optional

If True, a ValueError is raised any time interpolation is attempted on a value outside of the range of x (where extrapolation is necessary). If False, out of bounds values are assigned fill_value. By default, an error is raised unless fill_value="extrapolate".

fill_valuearray-like or (array-like, array_like) or “extrapolate”, optional
  • if a ndarray (or float), this value will be used to fill in for requested points outside of the data range. If not provided, then the default is NaN. The array-like must broadcast properly to the dimensions of the non-interpolation axes.

  • If a two-element tuple, then the first element is used as a fill value for x_new < x[0] and the second element is used for x_new > x[-1]. Anything that is not a 2-element tuple (e.g., list or ndarray, regardless of shape) is taken to be a single array-like argument meant to be used for both bounds as below, above = fill_value, fill_value.

    New in version 0.17.0.

  • If “extrapolate”, then points outside the data range will be extrapolated.

    New in version 0.17.0.

assume_sortedbool, optional

If False, values of x can be in any order and they are sorted first. If True, x has to be an array of monotonically increasing values.

See also

splrep, splev

Spline interpolation/smoothing based on FITPACK.

UnivariateSpline

An object-oriented wrapper of the FITPACK routines.

interp2d

2-D interpolation

Examples

>>> import matplotlib.pyplot as plt
>>> from scipy import interpolate
>>> x = np.arange(0, 10)
>>> y = np.exp(-x/3.0)
>>> f = interpolate.interp1d(x, y)
>>> xnew = np.arange(0, 9, 0.1)
>>> ynew = f(xnew)   # use interpolation function returned by `interp1d`
>>> plt.plot(x, y, 'o', xnew, ynew, '-')
>>> plt.show()
Attributes
fill_value

The fill value.

Methods

__call__(x)

Evaluate the interpolant

__init__(x, y, kind='linear', axis=-1, copy=True, bounds_error=None, fill_value=nan, assume_sorted=False)

Initialize a 1-D linear interpolation class.

dtype
property fill_value

The fill value.

compute_rfbc

dipy.tracking.fbcmeasures.compute_rfbc()

Compute the relative fiber to bundle coherence (RFBC)

Parameters
streamlines_length1D int array

Contains the length of each streamline

streamlines_scores2D double array

Contains the local fiber to bundle coherence (LFBC) for each streamline element.

max_windowsizeint

The maximal window size used to calculate the average LFBC region

Returns
output: normalized lowest average LFBC region along the fiber

cpu_count

dipy.tracking.fbcmeasures.cpu_count()

Return number of cpus as determined by omp_get_num_procs.

determine_num_threads

dipy.tracking.fbcmeasures.determine_num_threads()

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

  • For num_threads = None, - if the OMP_NUM_THREADS environment variable is set, return that value - otherwise, return the maximum number of cores retrieved by openmp.opm_get_num_procs().

  • For num_threads > 0, return this value.

  • For num_threads < 0, return the maximal number of threads minus |num_threads + 1|. In particular num_threads = -1 will use as many threads as there are available cores on the machine.

  • For num_threads = 0 a ValueError is raised.

Parameters
num_threadsint or None

Desired number of threads to be used.

get_sphere

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

provide triangulated spheres

Parameters
namestr

which sphere - one of: * ‘symmetric362’ * ‘symmetric642’ * ‘symmetric724’ * ‘repulsion724’ * ‘repulsion100’ * ‘repulsion200’

Returns
spherea 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"

log

dipy.tracking.fbcmeasures.log(x[, base=math.e])

Return the logarithm of x to the given base.

If the base not specified, returns the natural logarithm (base e) of x.

min_moving_average

dipy.tracking.fbcmeasures.min_moving_average()

Return the lowest cumulative sum for the score of a streamline segment

Parameters
aarray

Input array

nint

Length of the segment

Returns
output: normalized lowest average LFBC region along the fiber

ndindex

dipy.tracking.fbcmeasures.ndindex(shape)

An N-dimensional iterator object to index arrays.

Given the shape of an array, an ndindex instance iterates over the N-dimensional index of the array. At each iteration a tuple of indices is returned; the last dimension is iterated over first.

Parameters
shapetuple of ints

The dimensions of the array.

Examples

>>> from dipy.core.ndindex import ndindex
>>> shape = (3, 2, 1)
>>> for index in ndindex(shape):
...     print(index)
(0, 0, 0)
(0, 1, 0)
(1, 0, 0)
(1, 1, 0)
(2, 0, 0)
(2, 1, 0)

sqrt

dipy.tracking.fbcmeasures.sqrt(x, /)

Return the square root of x.

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
indicessequence

of indices of tracks1 that are to be detected in tracks2

tracks1sequence

of tracks as arrays, shape (N1,3) .. (Nm,3)

tracks2sequence

of tracks as arrays, shape (M1,3) .. (Mm,3)

Returns
track2trackarray (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
indicessequence

of indices of tracks1 that are to be detected in tracks2

tracks1sequence

of tracks as arrays, shape (N1,3) .. (Nm,3)

indices2sequence

of indices of tracks2 in the initial brain

tracks2sequence

of tracks as arrays, shape (M1,3) .. (Mm,3)

Returns
track2trackarray (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_modelA FiberModel class instance
paramsthe parameters derived from a fit of the model to the data.
predict(gtab=None, S0=None)

Predict the signal

Parameters
gtabGradientTable

Default: use self.gtab

S0float or array

The non-diffusion-weighted signal in the voxels for which a prediction is made. Default: use self.b0_signal

Returns
predictionndarray of shape (voxels, bvecs)

An array with a prediction of the signal in each voxel/direction

FiberModel

class dipy.tracking.life.FiberModel(gtab)

Bases: dipy.reconst.base.ReconstModel

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

Notes

This is an implementation of the LiFE model described in [1]_

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

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

Methods

fit(data, streamline, affine[, evals, sphere])

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

setup(streamline, affine[, evals, sphere])

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

__init__(gtab)
Parameters
gtaba GradientTable class instance
fit(data, streamline, affine, evals=[0.001, 0, 0], sphere=None)

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

Parameters
data4D array

Diffusion-weighted data

streamlinelist

A bunch of streamlines

affinearray_like (4, 4)

The mapping from voxel coordinates to streamline points. The voxel_to_rasmm matrix, typically from a NIFTI file.

evalslist (optional)

The eigenvalues of the tensor response function used in constructing the model signal. Default: [0.001, 0, 0]

sphere: `dipy.core.Sphere` instance, or False

Whether to approximate (and cache) the signal on a discrete sphere. This may confer a significant speed-up in setting up the problem, but is not as accurate. If False, we use the exact gradients along the streamlines to calculate the matrix, instead of an approximation.

Returns
FiberFit class instance
setup(streamline, affine, evals=[0.001, 0, 0], sphere=None)

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

Parameters
streamlinelist

Streamlines, each is an array of shape (n, 3)

affinearray_like (4, 4)

The mapping from voxel coordinates to streamline points. The voxel_to_rasmm matrix, typically from a NIFTI file.

evalslist (3 items, optional)

The eigenvalues of the canonical tensor used as a response function. Default:[0.001, 0, 0].

sphere: `dipy.core.Sphere` instance.

Whether to approximate (and cache) the signal on a discrete sphere. This may confer a significant speed-up in setting up the problem, but is not as accurate. If False, we use the exact gradients along the streamlines to calculate the matrix, instead of an approximation. Defaults to use the 724-vertex symmetric sphere from dipy.data

LifeSignalMaker

class dipy.tracking.life.LifeSignalMaker(gtab, evals=[0.001, 0, 0], sphere=None)

Bases: object

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

Methods

streamline_signal(streamline)

Approximate the signal for a given streamline

calc_signal

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

Initialize a signal maker

Parameters
gtabGradientTable class instance

The gradient table on which the signal is calculated.

evalslist of 3 items

The eigenvalues of the canonical tensor to use in calculating the signal.

spheredipy.core.Sphere class instance

The discrete sphere to use as an approximation for the continuous sphere on which the signal is represented. If integer - we will use an instance of one of the symmetric spheres cached in dps.get_sphere. If a ‘dipy.core.Sphere’ class instance is provided, we will use this object. Default: the dipy.data symmetric sphere with 724 vertices

calc_signal(xyz)
streamline_signal(streamline)

Approximate the signal for a given streamline

ReconstFit

class dipy.tracking.life.ReconstFit(model, data)

Bases: object

Abstract class which holds the fit result of ReconstModel

For example that could be holding FA or GFA etc.

__init__(model, data)

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

ReconstModel

class dipy.tracking.life.ReconstModel(gtab)

Bases: object

Abstract class for signal reconstruction models

Methods

fit

__init__(gtab)

Initialization of the abstract class for signal reconstruction models

Parameters
gtabGradientTable class instance
fit(data, mask=None, **kwargs)

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
grad1d array of shape (3,)

The spatial gradient (e.g between two nodes of a streamline).

evals: 1d array of shape (3,)

The eigenvalues of a canonical tensor to be used as a response function.

gradient

dipy.tracking.life.gradient(f)

Return the gradient of an N-dimensional array.

The gradient is computed using central differences in the interior and first differences at the boundaries. The returned gradient hence has the same shape as the input array.

Parameters
farray_like

An N-dimensional array containing samples of a scalar function.

Returns
gradientndarray

N arrays of the same shape as f giving the derivative of f with respect to each dimension.

Notes

This is a simplified implementation of gradient that is part of numpy 1.8. In order to mitigate the effects of changes added to this implementation in version 1.9 of numpy, we include this implementation here.

Examples

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

streamline_gradients

dipy.tracking.life.streamline_gradients(streamline)

Calculate the gradients of the streamline along the spatial dimension

Parameters
streamlinearray-like of shape (n, 3)

The 3d coordinates of a single streamline

Returns
Array of shape (3, n): Spatial gradients along the length of the
streamline.

streamline_signal

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

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

Parameters
streamlinea single streamline
gtabGradientTable class instance
evalslist 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
streamlinearray-like of shape (n, 3)

The 3d coordinates of a single streamline

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

Notes

Estimates of the radial/axial diffusivities may rely on empirical measurements (for example, the AD in the Corpus Callosum), or may be based on a biophysical model of some kind.

transform_streamlines

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

Apply affine transformation to streamlines

Parameters
streamlinesStreamlines

Streamlines object

matarray, (4, 4)

transformation matrix

in_placebool

If True then change data in place. Be careful changes input streamlines.

Returns
new_streamlinesStreamlines

Sequence transformed 2D ndarrays of shape[-1]==3

unique_rows

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

This (quickly) finds the unique rows in an array

Parameters
in_array: ndarray

The array for which the unique rows should be found

dtype: str, optional

This determines the intermediate representation used for the values. Should at least preserve the values of the input array.

Returns
u_return: ndarray

Array with the unique rows of the original array.

voxel2streamline

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

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

Parameters
streamlinelist

A collection of streamlines, each n by 3, with n being the number of nodes in the fiber.

affinearray_like (4, 4)

The mapping from voxel coordinates to streamline points. The voxel_to_rasmm matrix, typically from a NIFTI file.

unique_idxarray (optional).

The unique indices in the streamlines

Returns
v2f, v2fntuple 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?

AnatomicalStoppingCriterion

class dipy.tracking.local_tracking.AnatomicalStoppingCriterion

Bases: dipy.tracking.stopping_criterion.StoppingCriterion

Abstract class that takes as input included and excluded tissue maps. The ‘include_map’ defines when the streamline reached a ‘valid’ stopping region (e.g. gray matter partial volume estimation (PVE) map) and the ‘exclude_map’ defines when the streamline reached an ‘invalid’ stopping region (e.g. corticospinal fluid PVE map). The background of the anatomical image should be added to the ‘include_map’ to keep streamlines exiting the brain (e.g. through the brain stem).

cdef:

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

Methods

from_pve

AnatomicalStoppingCriterion from partial volume fraction (PVE) maps.

check_point

get_exclude

get_include

__init__(*args, **kwargs)

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

from_pve()

AnatomicalStoppingCriterion from partial volume fraction (PVE) maps.

Parameters
wm_maparray

The partial volume fraction of white matter at each voxel.

gm_maparray

The partial volume fraction of gray matter at each voxel.

csf_maparray

The partial volume fraction of corticospinal fluid at each voxel.

get_exclude()
get_include()

Iterable

class dipy.tracking.local_tracking.Iterable

Bases: object

__init__(*args, **kwargs)

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

LocalTracking

class dipy.tracking.local_tracking.LocalTracking(direction_getter, stopping_criterion, seeds, affine, step_size, max_cross=None, maxlen=500, fixedstep=True, return_all=True, random_seed=None, save_seeds=False)

Bases: object

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

Creates streamlines by using local fiber-tracking.

Parameters
direction_getterinstance of DirectionGetter

Used to get directions for fiber tracking.

stopping_criterioninstance of StoppingCriterion

Identifies endpoints and invalid points to inform tracking.

seedsarray (N, 3)

Points to seed the tracking. Seed points should be given in point space of the track (see affine).

affinearray (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_sizefloat

Step size used for tracking.

max_crossint or None

The maximum number of direction to track from each seed in crossing voxels. By default all initial directions are tracked.

maxlenint

Maximum number of steps to track from seed. Used to prevent infinite loops.

fixedstepbool

If true, a fixed stepsize is used, otherwise a variable step size is used.

return_allbool

If true, return all generated streamlines, otherwise only streamlines reaching end points or exiting the image.

random_seedint

The seed for the random seed generator (numpy.random.seed and random.seed).

save_seedsbool

If True, return seeds alongside streamlines

ParticleFilteringTracking

class dipy.tracking.local_tracking.ParticleFilteringTracking(direction_getter, stopping_criterion, seeds, affine, step_size, max_cross=None, maxlen=500, pft_back_tracking_dist=2, pft_front_tracking_dist=1, pft_max_trial=20, particle_count=15, return_all=True, random_seed=None, save_seeds=False)

Bases: dipy.tracking.local_tracking.LocalTracking

__init__(direction_getter, stopping_criterion, seeds, affine, step_size, max_cross=None, maxlen=500, pft_back_tracking_dist=2, pft_front_tracking_dist=1, pft_max_trial=20, particle_count=15, return_all=True, random_seed=None, save_seeds=False)

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

Parameters
direction_getterinstance of ProbabilisticDirectionGetter

Used to get directions for fiber tracking.

stopping_criterioninstance of AnatomicalStoppingCriterion

Identifies endpoints and invalid points to inform tracking.

seedsarray (N, 3)

Points to seed the tracking. Seed points should be given in point space of the track (see affine).

affinearray (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_sizefloat

Step size used for tracking.

max_crossint or None

The maximum number of direction to track from each seed in crossing voxels. By default all initial directions are tracked.

maxlenint

Maximum number of steps to track from seed. Used to prevent infinite loops.

pft_back_tracking_distfloat

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_distfloat

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_trialint

Maximum number of trial for the particle filtering tractography (Prevents infinite loops).

particle_countint

Number of particles to use in the particle filter.

return_allbool

If true, return all generated streamlines, otherwise only streamlines reaching end points or exiting the image.

random_seedint

The seed for the random seed generator (numpy.random.seed and random.seed).

save_seedsbool

If True, return seeds alongside streamlines

References

1

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

StreamlineStatus

class dipy.tracking.local_tracking.StreamlineStatus

Bases: enum.IntEnum

An enumeration.

__init__(*args, **kwargs)

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

ENDPOINT = 2
INVALIDPOINT = 0
OUTSIDEIMAGE = -1
PYERROR = -2
TRACKPOINT = 1

local_tracker

dipy.tracking.local_tracking.local_tracker()

Tracks one direction from a seed.

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

Parameters
dgDirectionGetter

Used to choosing tracking directions.

scStoppingCriterion

Used to check the streamline status (e.g. endpoint) along path.

seed_posarray, float, 1d, (3,)

First point of the (partial) streamline.

first_steparray, float, 1d, (3,)

Initial seeding direction. Used as prev_dir for selecting the step direction from the seed point.

voxel_sizearray, float, 1d, (3,)

Size of voxels in the data set.

streamlinearray, 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_sizefloat

Size of tracking steps in mm if fixed_step.

fixedstepbool

If true, a fixed step_size is used, otherwise a variable step size is used.

Returns
endint

Length of the tracked streamline

stream_statusStreamlineStatus

Ending state of the streamlines as determined by the StoppingCriterion.

pft_tracker

dipy.tracking.local_tracking.pft_tracker()

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

This function is the main workhorse of the ParticleFilteringTracking class defined in dipy.tracking.local_tracking.

Parameters
dgDirectionGetter

Used to choosing tracking directions.

scAnatomicalStoppingCriterion

Used to check the streamline status (e.g. endpoint) along path.

seed_posarray, float, 1d, (3,)

First point of the (partial) streamline.

first_steparray, float, 1d, (3,)

Initial seeding direction. Used as prev_dir for selecting the step direction from the seed point.

voxel_sizearray, float, 1d, (3,)

Size of voxels in the data set.

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

directionsarray, 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_sizefloat

Size of tracking steps in mm if fixed_step.

pft_max_nbr_back_stepsint

Number of tracking steps to back track before starting the particle filtering tractography.

pft_max_nbr_front_stepsint

Number of additional tracking steps to track.

pft_max_trialsint

Maximum number of trials for the particle filtering tractography (Prevents infinite loops).

particle_countint

Number of particles to use in the particle filter.

particle_pathsarray, float, 4d, (2, particle_count, pft_max_steps, 3)

Temporary array for paths followed by all particles.

particle_dirsarray, float, 4d, (2, particle_count, pft_max_steps, 3)

Temporary array for directions followed by particles.

particle_weightsarray, float, 1d (particle_count)

Temporary array for the weights of particles.

particle_stepsarray, float, (2, particle_count)

Temporary array for the number of steps of particles.

particle_stream_statusesarray, float, (2, particle_count)

Temporary array for the stream status of particles.

Returns
endint

Length of the tracked streamline

stream_statusStreamlineStatus

Ending state of the streamlines as determined by the StoppingCriterion.

local_tracker

dipy.tracking.localtrack.local_tracker()

Tracks one direction from a seed.

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

Parameters
dgDirectionGetter

Used to choosing tracking directions.

scStoppingCriterion

Used to check the streamline status (e.g. endpoint) along path.

seed_posarray, float, 1d, (3,)

First point of the (partial) streamline.

first_steparray, float, 1d, (3,)

Initial seeding direction. Used as prev_dir for selecting the step direction from the seed point.

voxel_sizearray, float, 1d, (3,)

Size of voxels in the data set.

streamlinearray, 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_sizefloat

Size of tracking steps in mm if fixed_step.

fixedstepbool

If true, a fixed step_size is used, otherwise a variable step size is used.

Returns
endint

Length of the tracked streamline

stream_statusStreamlineStatus

Ending state of the streamlines as determined by the StoppingCriterion.

pft_tracker

dipy.tracking.localtrack.pft_tracker()

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

This function is the main workhorse of the ParticleFilteringTracking class defined in dipy.tracking.local_tracking.

Parameters
dgDirectionGetter

Used to choosing tracking directions.

scAnatomicalStoppingCriterion

Used to check the streamline status (e.g. endpoint) along path.

seed_posarray, float, 1d, (3,)

First point of the (partial) streamline.

first_steparray, float, 1d, (3,)

Initial seeding direction. Used as prev_dir for selecting the step direction from the seed point.

voxel_sizearray, float, 1d, (3,)

Size of voxels in the data set.

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

directionsarray, 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_sizefloat

Size of tracking steps in mm if fixed_step.

pft_max_nbr_back_stepsint

Number of tracking steps to back track before starting the particle filtering tractography.

pft_max_nbr_front_stepsint

Number of additional tracking steps to track.

pft_max_trialsint

Maximum number of trials for the particle filtering tractography (Prevents infinite loops).

particle_countint

Number of particles to use in the particle filter.

particle_pathsarray, float, 4d, (2, particle_count, pft_max_steps, 3)

Temporary array for paths followed by all particles.

particle_dirsarray, float, 4d, (2, particle_count, pft_max_steps, 3)

Temporary array for directions followed by particles.

particle_weightsarray, float, 1d (particle_count)

Temporary array for the weights of particles.

particle_stepsarray, float, (2, particle_count)

Temporary array for the number of steps of particles.

particle_stream_statusesarray, float, (2, particle_count)

Temporary array for the stream status of particles.

Returns
endint

Length of the tracked streamline

stream_statusStreamlineStatus

Ending state of the streamlines as determined by the StoppingCriterion.

random

dipy.tracking.localtrack.random() → x in the interval [0, 1).

random_coordinates_from_surface

dipy.tracking.mesh.random_coordinates_from_surface(nb_triangles, nb_seed, triangles_mask=None, triangles_weight=None, rand_gen=None)

Generate random triangles_indices and trilinear_coord

Triangles_indices probability are weighted by triangles_weight,

for each triangles inside the given triangles_mask

Parameters
nb_trianglesint (n)

The amount of triangles in the mesh

nb_seedint

The number of random indices and coordinates generated.

triangles_mask[n] numpy array

Specifies which triangles should be chosen (or not)

triangles_weight[n] numpy array

Specifies the weight/probability of choosing each triangle

random_seedint

The seed for the random seed generator (numpy.random.seed).

Returns
triangles_idx: [s] array

Randomly chosen triangles_indices

trilin_coord: [s,3] array

Randomly chosen trilinear_coordinates

See also

seeds_from_surface_coordinates, random_seeds_from_mask

seeds_from_surface_coordinates

dipy.tracking.mesh.seeds_from_surface_coordinates(triangles, vts_values, triangles_idx, trilinear_coord)

Compute points from triangles_indices and trilinear_coord

Parameters
triangles[n, 3] -> m array

A list of triangles from a mesh

vts_values[m, .] array

List of values to interpolates from coordinates along vertices, (vertices, vertices_normal, vertices_colors …)

triangles_idx[s] array

Specifies which triangles should be chosen (or not)

trilinear_coord[s, 3] array

Specifies the weight/probability of choosing each triangle

Returns
pts[s, …] array

Interpolated values of vertices with triangles_idx and trilinear_coord

triangles_area

dipy.tracking.mesh.triangles_area(triangles, vts)

Compute the local area of each triangle

Parameters
triangles[n, 3] -> m array

A list of triangles from a mesh

vts[m, .] array

List of vertices

Returns
triangles_area[m] array

List of area for each triangle in the mesh

vertices_to_triangles_values

dipy.tracking.mesh.vertices_to_triangles_values(triangles, vts_values)

Change from values per vertex to values per triangle

Parameters
triangles[n, 3] -> m array

A list of triangles from a mesh

vts_values[m, .] array

List of values to interpolates from coordinates along vertices, (vertices, vertices_normal, vertices_colors …)

Returns
triangles_values[m] array

List of values for each triangle in the mesh

arbitrarypoint

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

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

Parameters
xyzarray-like shape (N,3)

array representing x,y,z of N points in a track

distancefloat

float representing distance travelled from the xyz[0] point of the curve along the curve.

Returns
aparray 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
xyzarray-like shape (N,3)

Array representing x,y,z of N points in a track.

Returns
bint

Number of bytes.

center_of_mass

dipy.tracking.metrics.center_of_mass(xyz)

Center of mass of streamline

Parameters
xyzarray-like shape (N,3)

array representing x,y,z of N points in a track

Returns
comarray 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.])

deprecate_with_version

dipy.tracking.metrics.deprecate_with_version(message, since='', until='', version_comparator=<function cmp_pkg_version>, warn_class=<class 'DeprecationWarning'>, error_class=<class 'dipy.utils.deprecator.ExpiredDeprecationError'>)

Return decorator function function for deprecation warning / error.

The decorated function / method will:

  • Raise the given warning_class warning when the function / method gets called, up to (and including) version until (if specified);

  • Raise the given error_class error when the function / method gets called, when the package version is greater than version until (if specified).

Parameters
messagestr

Message explaining deprecation, giving possible alternatives.

sincestr, optional

Released version at which object was first deprecated.

untilstr, optional

Last released version at which this function will still raise a deprecation warning. Versions higher than this will raise an error.

version_comparatorcallable

Callable accepting string as argument, and return 1 if string represents a higher version than encoded in the version_comparator, 0 if the version is equal, and -1 if the version is lower. For example, the version_comparator may compare the input version string to the current package version string.

warn_classclass, optional

Class of warning to generate for deprecation.

error_classclass, optional

Class of error to generate when version_comparator returns 1 for a given argument of until.

Returns
deprecatorfunc

Function returning a decorator.

downsample

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

downsample for a specific number of points along the streamline Uses the length of the curve. It works in a similar fashion to midpoint and arbitrarypoint but it also reduces the number of segments of a streamline.

dipy.tracking.metrics.downsample is deprecated, Please use dipy.tracking.streamline.set_number_of_points instead

  • deprecated from version: 1.2

  • Raises <class ‘dipy.utils.deprecator.ExpiredDeprecationError’> as of version: 1.4

Parameters
xyzarray-like shape (N,3)

array representing x,y,z of N points in a streamlines

n_polint

integer representing number of points (poles) we need along the curve.

Returns
xyz2array shape (M,3)

array representing x,y,z of M points that where extrapolated. M should be equal to n_pols

endpoint

dipy.tracking.metrics.endpoint(xyz)
Parameters
xyzarray, shape(N,3)

Track.

Returns
eparray, shape(3,)

First track point.

Examples

>>> from dipy.tracking.metrics import endpoint
>>> import numpy as np
>>> theta=np.pi*np.linspace(0,1,100)
>>> x=np.cos(theta)
>>> y=np.sin(theta)
>>> z=0*x
>>> xyz=np.vstack((x,y,z)).T
>>> ep=endpoint(xyz)
>>> ep.any()==xyz[-1].any()
True

frenet_serret

dipy.tracking.metrics.frenet_serret(xyz)

Frenet-Serret Space Curve Invariants

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

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

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

  • \(\mathbf{T}=\mathbf{r'}/|\mathbf{r'}|\qquad\) (Tangent vector)}

  • \(\mathbf{N}=\mathbf{T'}/|\mathbf{T'}|\qquad\) (Normal vector)

  • \(\mathbf{B}=\mathbf{T}\times\mathbf{N}\qquad\) (Binormal vector)

  • \(\kappa=|\mathbf{T'}|\qquad\) (Curvature)

  • \(\mathrm{\tau}=-\mathbf{B'}\cdot\mathbf{N}\) (Torsion)

Parameters
xyzarray-like shape (N,3)

array representing x,y,z of N points in a track

Returns
Tarray shape (N,3)

array representing the tangent of the curve xyz

Narray shape (N,3)

array representing the normal of the curve xyz

Barray shape (N,3)

array representing the binormal of the curve xyz

karray shape (N,1)

array representing the curvature of the curve xyz

tarray 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
itemssequence
nint
Returns
iciterator

Examples

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

inside_sphere

dipy.tracking.metrics.inside_sphere(xyz, center, radius)

If any point of the track is inside a sphere of a specified center and radius return True otherwise False. Mathematicaly this can be simply described by \(|x-c|\le r\) where \(x\) a point \(c\) the center of the sphere and \(r\) the radius of the sphere.

Parameters
xyzarray, shape (N,3)

representing x,y,z of the N points of the track

centerarray, shape (3,)

center of the sphere

radiusfloat

radius of the sphere

Returns
tf{True,False}

Whether point is inside sphere.

Examples

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

inside_sphere_points

dipy.tracking.metrics.inside_sphere_points(xyz, center, radius)

If a track intersects with a sphere of a specified center and radius return the points that are inside the sphere otherwise False. Mathematicaly this can be simply described by \(|x-c| \le r\) where \(x\) a point \(c\) the center of the sphere and \(r\) the radius of the sphere.

Parameters
xyzarray, shape (N,3)

representing x,y,z of the N points of the track

centerarray, shape (3,)

center of the sphere

radiusfloat

radius of the sphere

Returns
xyznarray, 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
xyzarray, shape (N,3)

representing x,y,z of the N points of the track

centerarray, shape (3,)

center of the sphere

radiusfloat

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
xyzarray-like shape (N,3)

array representing x,y,z of N points in a track

alongbool, optional

If True, return array giving cumulative length along track, otherwise (default) return scalar giving total length.

Returns
Lscalar or array shape (N-1,)

scalar in case of along == False, giving total length, array if along == True, giving cumulative lengths.

Examples

>>> from dipy.tracking.metrics import length
>>> xyz = np.array([[1,1,1],[2,3,4],[0,0,0]])
>>> expected_lens = np.sqrt([1+2**2+3**2, 2**2+3**2+4**2])
>>> length(xyz) == expected_lens.sum()
True
>>> len_along = length(xyz, along=True)
>>> np.allclose(len_along, expected_lens.cumsum())
True
>>> length([])
0
>>> length([[1, 2, 3]])
0
>>> length([], along=True)
array([0])

longest_track_bundle

dipy.tracking.metrics.longest_track_bundle(bundle, sort=False)

Return longest track or length sorted track indices in bundle

If sort == True, return the indices of the sorted tracks in the bundle, otherwise return the longest track.

Parameters
bundlesequence

of tracks as arrays, shape (N1,3) … (Nm,3)

sortbool, optional

If False (default) return longest track. If True, return length sorted indices for tracks in bundle

Returns
longest_or_indicesarray

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

magn

dipy.tracking.metrics.magn(xyz, n=1)

magnitude of vector

mean_curvature

dipy.tracking.metrics.mean_curvature(xyz)

Calculates the mean curvature of a curve

Parameters
xyzarray-like shape (N,3)

array representing x,y,z of N points in a curve

Returns
mfloat

Mean curvature.

Examples

Create a straight line and a semi-circle 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 semi-circle

mean_orientation

dipy.tracking.metrics.mean_orientation(xyz)

Calculates the mean orientation of a curve

Parameters
xyzarray-like shape (N,3)

array representing x,y,z of N points in a curve

Returns
mfloat

Mean orientation.

midpoint

dipy.tracking.metrics.midpoint(xyz)

Midpoint of track

Parameters
xyzarray-like shape (N,3)

array representing x,y,z of N points in a track

Returns
mparray 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
xyzarray-like shape (N,3)

array representing x,y,z of N points in a track

parray shape (3,)

array representing an arbitrary point with x,y,z coordinates in space.

Returns
dfloat

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
xyzarray-like shape (N,3)

array representing x,y,z of N points in a track

Returns
vaarray_like

eigenvalues

vearray_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

set_number_of_points

dipy.tracking.metrics.set_number_of_points()
Change the number of points of streamlines

(either by downsampling or upsampling)

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

Parameters
streamlinesndarray 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_pointsint

integer representing number of points wanted along the curve.

Returns
new_streamlinesndarray or a list or dipy.tracking.Streamlines

Results of the downsampling or upsampling process.

Examples

>>> from dipy.tracking.streamline import set_number_of_points
>>> import numpy as np

One streamline, a semi-circle:

>>> theta = np.pi*np.linspace(0, 1, 100)
>>> x = np.cos(theta)
>>> y = np.sin(theta)
>>> z = 0 * x
>>> streamline = np.vstack((x, y, z)).T
>>> modified_streamline = set_number_of_points(streamline, 3)
>>> len(modified_streamline)
3

Multiple streamlines:

>>> streamlines = [streamline, streamline[::2]]
>>> new_streamlines = set_number_of_points(streamlines, 10)
>>> [len(s) for s in streamlines]
[100, 50]
>>> [len(s) for s in new_streamlines]
[10, 10]

splev

dipy.tracking.metrics.splev(x, tck, der=0, ext=0)

Evaluate a B-spline or its derivatives.

Given the knots and coefficients of a B-spline 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
xarray_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.

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

derint, optional

The order of derivative of the spline to compute (must be less than or equal to k, the degree of the spline).

extint, 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
yndarray 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 an N-D space.

See also

splprep, splrep, sproot, spalde, splint
bisplrep, bisplev
BSpline

Notes

Manipulating the tck-tuples directly is not recommended. In new code, prefer using BSpline objects.

References

1

C. de Boor, “On calculating with b-splines”, J. Approximation Theory, 6, p.50-62, 1972.

2

M. G. Cox, “The numerical evaluation of b-splines”, J. Inst. Maths Applics, 10, p.134-149, 1972.

3

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 B-splines 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
xyzarray, shape (N,3)

array representing x,y,z of N points in 3d space

sfloat, 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 standard-deviation of y, then a: good s value should be found in the range (m-sqrt(2*m),m+sqrt(2*m)) where m is the number of datapoints in x, y, and w.

kint, optional

Degree of the spline. Cubic splines are recommended. Even values of k should be avoided especially with a small s-value. for the same set of data. If task=-1 find the weighted least square spline for a given set of knots, t.

nestNone or int, optional

An over-estimate 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
xyznarray, 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 3-space
>>> 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 B-spline representation of an N-D curve.

Given a list of N rank-1 arrays, x, which represent a curve in N-D space parametrized by u, find a smooth approximating spline curve g(u). Uses the FORTRAN routine parcur from FITPACK.

Parameters
xarray_like

A list of sample vector arrays representing the curve.

warray_like, optional

Strictly positive rank-1 array of weights the same length as x[0]. The weights are used in computing the weighted least-squares spline fit. If the errors in the x values have standard-deviation given by the vector d, then w should be 1/d. Default is ones(len(x[0])).

uarray_like, optional

An array of parameter values. If not given, these values are calculated automatically as M = len(x[0]), where

v[0] = 0

v[i] = v[i-1] + distance(x[i], x[i-1])

u[i] = v[i] / v[M-1]

ub, ueint, optional

The end-points of the parameters interval. Defaults to u[0] and u[-1].

kint, optional

Degree of the spline. Cubic splines are recommended. Even values of k should be avoided especially with a small s-value. 1 <= k <= 5, default is 3.

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

sfloat, 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 trade-off 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 standard-deviation of y, then a good s value should be found in the range (m-sqrt(2*m),m+sqrt(2*m)), where m is the number of data points in x, y, and w.

tint, optional

The knots needed for task=-1.

full_outputint, optional

If non-zero, then return optional outputs.

nestint, optional

An over-estimate 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.

perint, optional

If non-zero, data points are considered periodic with period x[m-1] - x[0] and a smooth periodic spline approximation is returned. Values of y[m-1] and w[m-1] are not used.

quietint, optional

Non-zero to suppress messages. This parameter is deprecated; use standard Python warning filters instead.

Returns
tcktuple

(t,c,k) a tuple containing the vector of knots, the B-spline coefficients, and the degree of the spline.

uarray

An array of the values of the parameter.

fpfloat

The weighted sum of squared residuals of the spline approximation.

ierint

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.

msgstr

A message corresponding to the integer flag, ier.

See also

splrep, splev, sproot, spalde, splint
bisplrep, bisplev
UnivariateSpline, BivariateSpline
BSpline
make_interp_spline

Notes

See splev for evaluation of the spline and its derivatives. The number of dimensions N must be smaller than 11.

The number of coefficients in the c array is k+1 less then the number of knots, len(t). This is in contrast with splrep, which zero-pads the array of coefficients to have the same length as the array of knots. These additional coefficients are ignored by evaluation routines, splev and BSpline.

References

1

P. Dierckx, “Algorithms for smoothing data with periodic and parametric splines, Computer Graphics and Image Processing”, 20 (1982) 171-184.

2

P. Dierckx, “Algorithms for smoothing data with periodic and parametric splines”, report tw55, Dept. Computer Science, K.U.Leuven, 1981.

3

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
xyzarray, shape(N,3)

Track.

Returns
sparray, 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
xyzarray-like shape (N,3)

Array representing x,y,z of N points in a track.

Returns
ascalar

Total turning angle in degrees.

eudx_both_directions

dipy.tracking.propspeed.eudx_both_directions()
Parameters
seedarray, float64 shape (3,)

Point where the tracking starts.

refcnp.npy_intp int

Index of peak to follow first.

qaarray, float64 shape (X, Y, Z, Np)

Anisotropy matrix, where Np is the number of maximum allowed peaks.

indarray, float64 shape(x, y, z, Np)

Index of the track orientation.

odf_verticesdouble array shape (N, 3)

Sampling directions on the sphere.

qa_thrfloat

Threshold for QA, we want everything higher than this threshold.

ang_thrfloat

Angle threshold, we only select fiber orientation within this range.

step_szdouble
total_weightdouble
max_pointscnp.npy_intp
Returns
trackarray, shape (N,3)

ndarray_offset

dipy.tracking.propspeed.ndarray_offset()

Find offset in an N-dimensional ndarray using strides

Parameters
indicesarray, npy_intp shape (N,)

Indices of the array which we want to find the offset.

stridesarray, shape (N,)

Strides of array.

lenindint

len of the indices array.

typesizeint

Number of bytes for data type e.g. if 8 for double, 4 for int32

Returns
offsetinteger

Index position in flattened array

Examples

>>> import numpy as np
>>> from dipy.tracking.propspeed import ndarray_offset
>>> I=np.array([1,1])
>>> A=np.array([[1,0,0],[0,2,0],[0,0,3]])
>>> S=np.array(A.strides)
>>> ndarray_offset(I,S,2,A.dtype.itemsize)
4
>>> A.ravel()[4]==A[1,1]
True

ActStoppingCriterion

class dipy.tracking.stopping_criterion.ActStoppingCriterion

Bases: dipy.tracking.stopping_criterion.AnatomicalStoppingCriterion

Anatomically-Constrained Tractography (ACT) stopping criterion from [1]. This implements the use of partial volume fraction (PVE) maps to determine when the tracking stops. The proposed ([1]) method that cuts streamlines going through subcortical gray matter regions is not implemented here. The backtracking technique for streamlines reaching INVALIDPOINT is not implemented either. cdef:

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

1(1,2,3)

Smith, R. E., Tournier, J.-D., Calamante, F., & Connelly, A.

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

Methods

from_pve

AnatomicalStoppingCriterion from partial volume fraction (PVE) maps.

check_point

get_exclude

get_include

__init__(*args, **kwargs)

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

AnatomicalStoppingCriterion

class dipy.tracking.stopping_criterion.AnatomicalStoppingCriterion

Bases: dipy.tracking.stopping_criterion.StoppingCriterion

Abstract class that takes as input included and excluded tissue maps. The ‘include_map’ defines when the streamline reached a ‘valid’ stopping region (e.g. gray matter partial volume estimation (PVE) map) and the ‘exclude_map’ defines when the streamline reached an ‘invalid’ stopping region (e.g. corticospinal fluid PVE map). The background of the anatomical image should be added to the ‘include_map’ to keep streamlines exiting the brain (e.g. through the brain stem).

cdef:

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

Methods

from_pve

AnatomicalStoppingCriterion from partial volume fraction (PVE) maps.

check_point

get_exclude

get_include

__init__(*args, **kwargs)

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

from_pve()

AnatomicalStoppingCriterion from partial volume fraction (PVE) maps.

Parameters
wm_maparray

The partial volume fraction of white matter at each voxel.

gm_maparray

The partial volume fraction of gray matter at each voxel.

csf_maparray

The partial volume fraction of corticospinal fluid at each voxel.

get_exclude()
get_include()

BinaryStoppingCriterion

class dipy.tracking.stopping_criterion.BinaryStoppingCriterion

Bases: dipy.tracking.stopping_criterion.StoppingCriterion

cdef:

unsigned char[:, :, :] mask

Methods

check_point

__init__(*args, **kwargs)

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

CmcStoppingCriterion

class dipy.tracking.stopping_criterion.CmcStoppingCriterion

Bases: dipy.tracking.stopping_criterion.AnatomicalStoppingCriterion

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

cdef:

double interp_out_double[1] double[:] interp_out_view = interp_out_view double[:, :, :] include_map, exclude_map double step_size double average_voxel_size double correction_factor

References

1(1,2)

Girard, G., Whittingstall, K., Deriche, R., & Descoteaux, M.

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

Methods

from_pve

AnatomicalStoppingCriterion from partial volume fraction (PVE) maps.

check_point

get_exclude

get_include

__init__(*args, **kwargs)

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

StoppingCriterion

class dipy.tracking.stopping_criterion.StoppingCriterion

Bases: object

Methods

check_point

__init__(*args, **kwargs)

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

check_point()

StreamlineStatus

class dipy.tracking.stopping_criterion.StreamlineStatus

Bases: enum.IntEnum

An enumeration.

__init__(*args, **kwargs)

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

ENDPOINT = 2
INVALIDPOINT = 0
OUTSIDEIMAGE = -1
PYERROR = -2
TRACKPOINT = 1

ThresholdStoppingCriterion

class dipy.tracking.stopping_criterion.ThresholdStoppingCriterion

Bases: dipy.tracking.stopping_criterion.StoppingCriterion

# Declarations from stopping_criterion.pxd bellow cdef:

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

Methods

check_point

__init__(*args, **kwargs)

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

Streamlines

dipy.tracking.streamline.Streamlines

alias of nibabel.streamlines.array_sequence.ArraySequence

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

Parameters
aff(N, N) array-like

Homogenous affine, for 3D points, will be 4 by 4. Contrary to first appearance, the affine will be applied on the left of pts.

pts(…, N-1) array-like

Points, where the last dimension contains the coordinates of each point. For 3D, the last dimension will be length 3.

Returns
transformed_pts(…, N-1) array

transformed points

Examples

>>> aff = np.array([[0,2,0,10],[3,0,0,11],[0,0,4,12],[0,0,0,1]])
>>> pts = np.array([[1,2,3],[2,3,4],[4,5,6],[6,7,8]])
>>> apply_affine(aff, pts) 
array([[14, 14, 24],
       [16, 17, 28],
       [20, 23, 36],
       [24, 29, 44]]...)

Just to show that in the simple 3D case, it is equivalent to:

>>> (np.dot(aff[:3,:3], pts.T) + aff[:3,3:4]).T 
array([[14, 14, 24],
       [16, 17, 28],
       [20, 23, 36],
       [24, 29, 44]]...)

But pts can be a more complicated shape:

>>> pts = pts.reshape((2,2,3))
>>> apply_affine(aff, pts) 
array([[[14, 14, 24],
        [16, 17, 28]],

       [[20, 23, 36],
        [24, 29, 44]]]...)

bundles_distances_mdf

dipy.tracking.streamline.bundles_distances_mdf()

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

All tracks need to have the same number of points

Parameters
tracksAsequence

of tracks as arrays, [(N,3) .. (N,3)]

tracksBsequence

of tracks as arrays, [(N,3) .. (N,3)]

Returns
DMarray, shape (len(tracksA), len(tracksB))

distances between tracksA and tracksB according to metric

cdist

dipy.tracking.streamline.cdist(XA, XB, metric='euclidean', *args, **kwargs)

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

See Notes for common calling conventions.

Parameters
XAndarray

An \(m_A\) by \(n\) array of \(m_A\) original observations in an \(n\)-dimensional space. Inputs are converted to float type.

XBndarray

An \(m_B\) by \(n\) array of \(m_B\) original observations in an \(n\)-dimensional space. Inputs are converted to float type.

metricstr 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’, ‘jensenshannon’, ‘kulsinski’, ‘mahalanobis’, ‘matching’, ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’, ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, ‘wminkowski’, ‘yule’.

*argstuple. Deprecated.

Additional arguments should be passed as keyword arguments

**kwargsdict, optional

Extra arguments to metric: refer to each metric documentation for a list of all possible arguments.

Some possible arguments:

p : scalar The p-norm to apply for Minkowski, weighted and unweighted. Default: 2.

w : ndarray The weight vector for metrics that support weights (e.g., Minkowski).

V : ndarray The variance vector for standardized Euclidean. Default: var(vstack([XA, XB]), axis=0, ddof=1)

VI : ndarray The inverse of the covariance matrix for Mahalanobis. Default: inv(cov(vstack([XA, XB].T))).T

out : ndarray The output array If not None, the distance matrix Y is stored in this array. Note: metric independent, it will become a regular keyword arg in a future scipy version

Returns
Yndarray

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:

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

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

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

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

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

    Computes the city block or Manhattan distance between the points.

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

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

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

    V is the variance vector; V[i] is the variance computed over all the i’th components of the points. If not passed, it is automatically computed.

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

    Computes the squared Euclidean distance \(||u-v||_2^2\) between the vectors.

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

    Computes the cosine distance between vectors u and v,

    \[1 - \frac{u \cdot v} {{||u||}_2 {||v||}_2}\]

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

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

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

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

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

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

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

  9. Y = cdist(XA, XB, 'jaccard')

    Computes the Jaccard distance between the points. Given two vectors, u and v, the Jaccard distance is the proportion of those elements u[i] and v[i] that disagree where at least one of them is non-zero.

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

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

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

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

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

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

\[d(u,v) = \frac{\sum_i (|u_i-v_i|)} {\sum_i (|u_i+v_i|)}\]
  1. Y = cdist(XA, XB, 'mahalanobis', VI=None)

Computes the Mahalanobis distance between the points. The Mahalanobis distance between two points u and v is \(\sqrt{(u-v)(1/V)(u-v)^T}\) where \((1/V)\) (the VI variable) is the inverse covariance. If VI is not None, VI will be used as the inverse covariance matrix.

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

Computes the Yule distance between the boolean vectors. (see yule function documentation)

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

Synonym for ‘hamming’.

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

Computes the Dice distance between the boolean vectors. (see dice function documentation)

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

Computes the Kulsinski distance between the boolean vectors. (see kulsinski function documentation)

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

Computes the Rogers-Tanimoto distance between the boolean vectors. (see rogerstanimoto function documentation)

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

Computes the Russell-Rao distance between the boolean vectors. (see russellrao function documentation)

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

Computes the Sokal-Michener distance between the boolean vectors. (see sokalmichener function documentation)

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

Computes the Sokal-Sneath distance between the vectors. (see sokalsneath function documentation)

  1. Y = cdist(XA, XB, 'wminkowski', p=2., w=w)

Computes the weighted Minkowski distance between the vectors. (see wminkowski function documentation)

  1. Y = cdist(XA, XB, f)

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

dm = cdist(XA, XB, lambda u, v: np.sqrt(((u-v)**2).sum()))

Note that you should avoid passing a reference to one of the distance functions defined in this library. For example,:

dm = cdist(XA, XB, sokalsneath)

would calculate the pair-wise distances between the vectors in X using the Python function sokalsneath. This would result in sokalsneath being called \({n \choose 2}\) times, which is inefficient. Instead, the optimized C version is more efficient, and we call it using the following syntax:

dm = cdist(XA, XB, 'sokalsneath')

Examples

Find the Euclidean distances between four 2-D coordinates:

>>> from scipy.spatial import distance
>>> coords = [(35.0456, -85.2672),
...           (35.1174, -89.9711),
...           (35.9728, -83.9422),
...           (36.1667, -86.7833)]
>>> distance.cdist(coords, coords, 'euclidean')
array([[ 0.    ,  4.7044,  1.6172,  1.8856],
       [ 4.7044,  0.    ,  6.0893,  3.3561],
       [ 1.6172,  6.0893,  0.    ,  2.8477],
       [ 1.8856,  3.3561,  2.8477,  0.    ]])

Find the Manhattan distance from a 3-D point to the corners of the unit cube:

>>> a = np.array([[0, 0, 0],
...               [0, 0, 1],
...               [0, 1, 0],
...               [0, 1, 1],
...               [1, 0, 0],
...               [1, 0, 1],
...               [1, 1, 0],
...               [1, 1, 1]])
>>> b = np.array([[ 0.1,  0.2,  0.4]])
>>> distance.cdist(a, b, 'cityblock')
array([[ 0.7],
       [ 0.9],
       [ 1.3],
       [ 1.5],
       [ 1.5],
       [ 1.7],
       [ 2.1],
       [ 2.3]])

center_streamlines

dipy.tracking.streamline.center_streamlines(streamlines)

Move streamlines to the origin

Parameters
streamlineslist

List of 2D ndarrays of shape[-1]==3

Returns
new_streamlineslist

List of 2D ndarrays of shape[-1]==3

inv_shiftndarray

Translation in x,y,z to go back in the initial position

cluster_confidence

dipy.tracking.streamline.cluster_confidence(streamlines, max_mdf=5, subsample=12, power=1, override=False)

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

Ex: A single streamline with no others in the dataset following a similar pathway has a low cci. A streamline in a bundle of 100 streamlines that follow similar pathways has a high cci.

See: Jordan et al. 2017 (Based on streamline MDF distance from Garyfallidis et al. 2012)

Parameters
streamlineslist of 2D (N, 3) arrays

A sequence of streamlines of length N (# streamlines)

max_mdfint

The maximum MDF distance (mm) that will be considered a “supporting” streamline and included in cci calculation

subsample: int

The number of points that are considered for each streamline in the calculation. To save on calculation time, each streamline is subsampled to subsampleN points.

power: int

The power to which the MDF distance for each streamline will be raised to determine how much it contributes to the cci. High values of power make the contribution value degrade much faster. E.g., a streamline with 5mm MDF similarity contributes 1/5 to the cci if power is 1, but only contributes 1/5^2 = 1/25 if power is 2.

override: bool, False by default

override means that the cci calculation will still occur even though there are short streamlines in the dataset that may alter expected behaviour.

Returns
Returns an array of CCI scores

References

[Jordan17] Jordan K. Et al., Cluster Confidence Index: A Streamline-Wise Pathway Reproducibility Metric for Diffusion-Weighted MRI Tractography, Journal of Neuroimaging, vol 28, no 1, 2017.

[Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for tractography simplification, Frontiers in Neuroscience, vol 6, no 175, 2012.

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
streamlinesone or a list of array-like of shape (N,3)

Array representing x,y,z of N points in a streamline.

tol_errorfloat (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_lengthfloat (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_streamlinesone or a list of array-like

Results of the linearization process.

Notes

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

References

Presseau15(1,2,3,4,5)

Presseau C. et al., A new compression format for fiber tracking datasets, NeuroImage, no 109, 73-83, 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 Streamlines-Based Metrics for Streamlines with Variable Step Sizes, ISMRM, 2015.

Examples

>>> from dipy.tracking.streamline import compress_streamlines
>>> import numpy as np
>>> # One streamline: a wiggling line
>>> rng = np.random.RandomState(42)
>>> streamline = np.linspace(0, 10, 100*3).reshape((100, 3))
>>> streamline += 0.2 * rng.rand(100, 3)
>>> c_streamline = compress_streamlines(streamline, tol_error=0.2)
>>> len(streamline)
100
>>> len(c_streamline)
10
>>> # Multiple streamlines
>>> streamlines = [streamline, streamline[::2]]
>>> c_streamlines = compress_streamlines(streamlines, tol_error=0.2)
>>> [len(s) for s in streamlines]
[100, 50]
>>> [len(s) for s in c_streamlines]
[10, 7]

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
streamlineslist

List of 2D ndarrays of shape[-1]==3

deform_field4D numpy array

x,y,z displacements stored in volume, shape[-1]==3

stream_to_current_gridarray, (4, 4)

transform matrix voxmm space to original grid space

current_grid_to_worldarray (4, 4)

transform matrix original grid space to world coordinates

stream_to_ref_gridarray (4, 4)

transform matrix voxmm space to new grid space

ref_grid_to_worldarray(4, 4)

transform matrix new grid space to world coordinates

Returns
new_streamlineslist

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

interpolate_scalar_3d

dipy.tracking.streamline.interpolate_scalar_3d()

Trilinear interpolation of a 3D scalar image

Interpolates the 3D image at the given locations. This function is a wrapper for _interpolate_scalar_3d for testing purposes, it is equivalent to scipy.ndimage.interpolation.map_coordinates with trilinear interpolation

Parameters
fieldarray, shape (S, R, C)

the 3D image to be interpolated

locationsarray, shape (n, 3)

(locations[i,0], locations[i,1], locations[i,2), 0<=i<n must contain the coordinates to interpolate the image at

Returns
outarray, shape (n,)

out[i], 0<=i<n will be the interpolated scalar at coordinates locations[i,:], or 0 if locations[i,:] is outside the image

insidearray, (n,)

if locations[i,:] is inside the image then inside[i]=1, else inside[i]=0

interpolate_vector_3d

dipy.tracking.streamline.interpolate_vector_3d()

Trilinear interpolation of a 3D vector field

Interpolates the 3D vector field at the given locations. This function is a wrapper for _interpolate_vector_3d for testing purposes, it is equivalent to using scipy.ndimage.interpolation.map_coordinates with trilinear interpolation at each vector component

Parameters
fieldarray, shape (S, R, C, 3)

the 3D vector field to be interpolated

locationsarray, shape (n, 3)

(locations[i,0], locations[i,1], locations[i,2), 0<=i<n must contain the coordinates to interpolate the vector field at

Returns
outarray, shape (n, 3)

out[i,:], 0<=i<n will be the interpolated vector at coordinates locations[i,:], or (0,0,0) if locations[i,:] is outside the field

insidearray, (n,)

if locations[i,:] is inside the vector field then inside[i]=1, else inside[i]=0

length

dipy.tracking.streamline.length()

Euclidean length of streamlines

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

Parameters
streamlinesndarray 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
lengthsscalar 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

nbytes

dipy.tracking.streamline.nbytes(streamlines)

orient_by_rois

dipy.tracking.streamline.orient_by_rois(streamlines, affine, roi1, roi2, in_place=False, as_generator=False)

Orient a set of streamlines according to a pair of ROIs

Parameters
streamlineslist or generator

List or generator of 2d arrays of 3d coordinates. Each array contains the xyz coordinates of a single streamline.

affinearray_like (4, 4)

The mapping from voxel coordinates to streamline points. The voxel_to_rasmm matrix, typically from a NIFTI file.

roi1, roi2ndarray

Binary masks designating the location of the regions of interest, or coordinate arrays (n-by-3 array with ROI coordinate in each row).

in_placebool

Whether to make the change in-place 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_generatorbool

Whether to return a generator as output. Default: False

Returns
streamlineslist 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, np.eye(4), roi1, roi2)
[array([[ 0.,  0.,  0.],
       [ 1.,  0.,  0.],
       [ 2.,  0.,  0.]]), array([[ 0.,  0.,  0.],
       [ 1.,  0.,  0.],
       [ 2.,  0.,  0.]])]

orient_by_streamline

dipy.tracking.streamline.orient_by_streamline(streamlines, standard, n_points=12, in_place=False, as_generator=False)

Orient a bundle of streamlines to a standard streamline.

Parameters
streamlinesStreamlines, list

The input streamlines to orient.

standardStreamlines, list, or ndarrray

This provides the standard orientation according to which the streamlines in the provided bundle should be reoriented.

n_points: int, optional

The number of samples to apply to each of the streamlines.

in_placebool

Whether to make the change in-place in the original input (and return a reference), or to make a copy of the list and return this copy, with the relevant streamlines reoriented. Default: False.

as_generatorbool

Whether to return a generator as output. Default: False

Returns
Streamlineswith each individual array oriented to be as similar as

possible to the standard.

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
pointsarray
offsetsarray
Returns
streamlines: sequence

select_by_rois

dipy.tracking.streamline.select_by_rois(streamlines, affine, rois, include, mode=None, tol=None)

Select streamlines based on logical relations with several regions of interest (ROIs). For example, select streamlines that pass near ROI1, but only if they do not pass near ROI2.

Parameters
streamlineslist

A list of candidate streamlines for selection

affinearray_like (4, 4)

The mapping from voxel coordinates to streamline points. The voxel_to_rasmm matrix, typically from a NIFTI file.

roislist or ndarray

A list of 3D arrays, each with shape (x, y, z) corresponding to the shape of the brain volume, or a 4D array with shape (n_rois, x, y, z). Non-zeros in each volume are considered to be within the region

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

modestring, 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 end-points is within tol from ROI

“both_end” : both end points are within tol from ROI.

tolfloat

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, np.eye(4), [mask1, mask2],
...                            [True, True],
...                            tol=1)
>>> list(selection) # The result is a generator
[array([[ 0. ,  0. ,  0.9],
       [ 1.9,  0. ,  0. ]]), array([[ 0.,  0.,  0.],
       [ 0.,  1.,  1.],
       [ 0.,  2.,  2.]])]
>>> selection = select_by_rois(streamlines, np.eye(4), [mask1, mask2],
...                            [True, False],
...                            tol=0.87)
>>> list(selection)
[array([[ 0.,  0.,  0.],
       [ 0.,  1.,  1.],
       [ 0.,  2.,  2.]])]
>>> selection = select_by_rois(streamlines, np.eye(4), [mask1, mask2],
...                            [True, True],
...                            mode="both_end",
...                            tol=1.0)
>>> list(selection)
[array([[ 0. ,  0. ,  0.9],
       [ 1.9,  0. ,  0. ]])]
>>> mask2[0, 2, 2] = True
>>> selection = select_by_rois(streamlines, np.eye(4), [mask1, mask2],
...                            [True, True],
...                            mode="both_end",
...                            tol=1.0)
>>> list(selection)
[array([[ 0. ,  0. ,  0.9],
       [ 1.9,  0. ,  0. ]]), array([[ 0.,  0.,  0.],
       [ 0.,  1.,  1.],
       [ 0.,  2.,  2.]])]

select_random_set_of_streamlines

dipy.tracking.streamline.select_random_set_of_streamlines(streamlines, select, rng=None)

Select a random set of streamlines

Parameters
streamlinesSteamlines

Object of 2D ndarrays of shape[-1]==3

selectint

Number of streamlines to select. If there are less streamlines than select then select=len(streamlines).

rngRandomState

Default None.

Returns
selected_streamlineslist

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_points-1 segments of equal length. Points of streamlines will be modified along the curve.

Parameters
streamlinesndarray 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_pointsint

integer representing number of points wanted along the curve.

Returns
new_streamlinesndarray or a list or dipy.tracking.Streamlines

Results of the downsampling or upsampling process.

Examples

>>> from dipy.tracking.streamline import set_number_of_points
>>> import numpy as np

One streamline, a semi-circle:

>>> theta = np.pi*np.linspace(0, 1, 100)
>>> x = np.cos(theta)
>>> y = np.sin(theta)
>>> z = 0 * x
>>> streamline = np.vstack((x, y, z)).T
>>> modified_streamline = set_number_of_points(streamline, 3)
>>> len(modified_streamline)
3

Multiple streamlines:

>>> streamlines = [streamline, streamline[::2]]
>>> new_streamlines = set_number_of_points(streamlines, 10)
>>> [len(s) for s in streamlines]
[100, 50]
>>> [len(s) for s in new_streamlines]
[10, 10]

transform_streamlines

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

Apply affine transformation to streamlines

Parameters
streamlinesStreamlines

Streamlines object

matarray, (4, 4)

transformation matrix

in_placebool

If True then change data in place. Be careful changes input streamlines.

Returns
new_streamlinesStreamlines

Sequence 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
pointsarray
offsetsarray

values_from_volume

dipy.tracking.streamline.values_from_volume(data, streamlines, affine)

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

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

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

affinearray_like (4, 4)

The mapping from voxel coordinates to streamline points. The voxel_to_rasmm matrix, typically from a NIFTI file.

Returns
array or list (depending on the input)values interpolate to each

coordinate along the length of each streamline.

Notes

Values are extracted from the image based on the 3D coordinates of the nodes that comprise the points in the streamline, without any interpolation into segments between the nodes. Using this function with streamlines that have been resampled into a very small number of nodes will result in very few values.

warn

dipy.tracking.streamline.warn(/, message, category=None, stacklevel=1, source=None)

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

Streamlines

dipy.tracking.streamlinespeed.Streamlines

alias of nibabel.streamlines.array_sequence.ArraySequence

compress_streamlines

dipy.tracking.streamlinespeed.compress_streamlines()

Compress streamlines by linearization as in [Presseau15].

The compression consists in merging consecutive segments that are nearly collinear. The merging is achieved by removing the point the two segments have in common.

The linearization process [Presseau15] ensures that every point being removed are within a certain margin (in mm) of the resulting streamline. Recommendations for setting this margin can be found in [Presseau15] (in which they called it tolerance error).

The compression also ensures that two consecutive points won’t be too far from each other (precisely less or equal than `max_segment_length`mm). This is a tradeoff to speed up the linearization process [Rheault15]. A low value will result in a faster linearization but low compression, whereas a high value will result in a slower linearization but high compression.

Parameters
streamlinesone or a list of array-like of shape (N,3)

Array representing x,y,z of N points in a streamline.

tol_errorfloat (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_lengthfloat (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_streamlinesone or a list of array-like

Results of the linearization process.

Notes

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

References

Presseau15(1,2,3,4,5)

Presseau C. et al., A new compression format for fiber tracking datasets, NeuroImage, no 109, 73-83, 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 Streamlines-Based Metrics for Streamlines with Variable Step Sizes, ISMRM, 2015.

Examples

>>> from dipy.tracking.streamline import compress_streamlines
>>> import numpy as np
>>> # One streamline: a wiggling line
>>> rng = np.random.RandomState(42)
>>> streamline = np.linspace(0, 10, 100*3).reshape((100, 3))
>>> streamline += 0.2 * rng.rand(100, 3)
>>> c_streamline = compress_streamlines(streamline, tol_error=0.2)
>>> len(streamline)
100
>>> len(c_streamline)
10
>>> # Multiple streamlines
>>> streamlines = [streamline, streamline[::2]]
>>> c_streamlines = compress_streamlines(streamlines, tol_error=0.2)
>>> [len(s) for s in streamlines]
[100, 50]
>>> [len(s) for s in c_streamlines]
[10, 7]

length

dipy.tracking.streamlinespeed.length()

Euclidean length of streamlines

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

Parameters
streamlinesndarray 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
lengthsscalar 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

set_number_of_points

dipy.tracking.streamlinespeed.set_number_of_points()
Change the number of points of streamlines

(either by downsampling or upsampling)

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

Parameters
streamlinesndarray 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_pointsint

integer representing number of points wanted along the curve.

Returns
new_streamlinesndarray or a list or dipy.tracking.Streamlines

Results of the downsampling or upsampling process.

Examples

>>> from dipy.tracking.streamline import set_number_of_points
>>> import numpy as np

One streamline, a semi-circle:

>>> theta = np.pi*np.linspace(0, 1, 100)
>>> x = np.cos(theta)
>>> y = np.sin(theta)
>>> z = 0 * x
>>> streamline = np.vstack((x, y, z)).T
>>> modified_streamline = set_number_of_points(streamline, 3)
>>> len(modified_streamline)
3

Multiple streamlines:

>>> streamlines = [streamline, streamline[::2]]
>>> new_streamlines = set_number_of_points(streamlines, 10)
>>> [len(s) for s in streamlines]
[100, 50]
>>> [len(s) for s in new_streamlines]
[10, 10]

OrderedDict

class dipy.tracking.utils.OrderedDict

Bases: dict

Dictionary that remembers insertion order

Methods

clear()

copy()

fromkeys(/, iterable[, value])

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

get(key[, default])

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

items()

keys()

move_to_end(/, key[, last])

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

pop(k[,d])

value.

popitem(/[, last])

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

setdefault(/, key[, default])

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

update([E, ]**F)

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

values()

__init__(*args, **kwargs)

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

clear() → None. Remove all items from od.
copy() → a shallow copy of od
fromkeys(/, iterable, value=None)

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

items() → a set-like object providing a view on D's items
keys() → a set-like object providing a view on D's keys
move_to_end(/, key, last=True)

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

Raise KeyError if the element does not exist.

pop(k[, d]) → v, remove specified key and return the corresponding

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

popitem(/, last=True)

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

Pairs are returned in LIFO order if last is true or FIFO order if false.

setdefault(/, key, default=None)

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

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

update([E, ]**F) → None. Update D from dict/iterable E and F.

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

values() → an object providing a view on D's values

combinations

class dipy.tracking.utils.combinations

Bases: object

combinations(iterable, r) –> combinations object

Return successive r-length combinations of elements in the iterable.

combinations(range(4), 3) –> (0,1,2), (0,1,3), (0,2,3), (1,2,3)

__init__(*args, **kwargs)

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

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.

Attributes
default_factory

Factory for default value called by __missing__().

Methods

clear()

copy()

fromkeys(iterable[, value])

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

get(key[, default])

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

items()

keys()

pop(k[,d])

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

popitem()

2-tuple; but raise KeyError if D is empty.

setdefault(key[, default])

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

update([E, ]**F)

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

values()

__init__(*args, **kwargs)

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

copy() → a shallow copy of D.
default_factory

Factory for default value called by __missing__().

groupby

class dipy.tracking.utils.groupby(iterable, key=None) → make an iterator that returns consecutive

Bases: object

keys and groups from the iterable. If the key function is not specified or is None, the element itself is used for grouping.

__init__(*args, **kwargs)

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

apply_affine

dipy.tracking.utils.apply_affine(aff, pts)

Apply affine matrix aff to points pts

Returns result of application of aff to the right of pts. The coordinate dimension of pts should be the last.

For the 3D case, aff will be shape (4,4) and pts will have final axis length 3 - maybe it will just be N by 3. The return value is the transformed points, in this case:

res = np.dot(aff[:3,:3], pts.T) + aff[:3,3:4]
transformed_pts = res.T

This routine is more general than 3D, in that aff can have any shape (N,N), and pts can have any shape, as long as the last dimension is for the coordinates, and is therefore length N-1.

Parameters
aff(N, N) array-like

Homogenous affine, for 3D points, will be 4 by 4. Contrary to first appearance, the affine will be applied on the left of pts.

pts(…, N-1) array-like

Points, where the last dimension contains the coordinates of each point. For 3D, the last dimension will be length 3.

Returns
transformed_pts(…, N-1) array

transformed points

Examples

>>> aff = np.array([[0,2,0,10],[3,0,0,11],[0,0,4,12],[0,0,0,1]])
>>> pts = np.array([[1,2,3],[2,3,4],[4,5,6],[6,7,8]])
>>> apply_affine(aff, pts) 
array([[14, 14, 24],
       [16, 17, 28],
       [20, 23, 36],
       [24, 29, 44]]...)

Just to show that in the simple 3D case, it is equivalent to:

>>> (np.dot(aff[:3,:3], pts.T) + aff[:3,3:4]).T 
array([[14, 14, 24],
       [16, 17, 28],
       [20, 23, 36],
       [24, 29, 44]]...)

But pts can be a more complicated shape:

>>> pts = pts.reshape((2,2,3))
>>> apply_affine(aff, pts) 
array([[[14, 14, 24],
        [16, 17, 28]],

       [[20, 23, 36],
        [24, 29, 44]]]...)

asarray

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

Convert the input to an array.

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

dtypedata-type, optional

By default, the data-type is inferred from the input data.

order{‘C’, ‘F’, ‘A’, ‘K’}, optional

Memory layout. ‘A’ and ‘K’ depend on the order of input array a. ‘C’ row-major (C-style), ‘F’ column-major (Fortran-style) memory representation. ‘A’ (any) means ‘F’ if a is Fortran contiguous, ‘C’ otherwise ‘K’ (keep) preserve input order Defaults to ‘C’.

likearray_like

Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as like supports the __array_function__ protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument.

Note

The like keyword is an experimental feature pending on acceptance of NEP 35.

New in version 1.20.0.

Returns
outndarray

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 column-major memory order.

asarray_chkfinite

Similar function which checks input for NaNs and Infs.

fromiter

Create an array from an iterator.

fromfunction

Construct an array by executing a function on grid positions.

Examples

Convert a list into an array:

>>> a = [1, 2]
>>> np.asarray(a)
array([1, 2])

Existing arrays are not copied:

>>> a = np.array([1, 2])
>>> np.asarray(a) is a
True

If dtype is set, array is copied only if dtype does not match:

>>> a = np.array([1, 2], dtype=np.float32)
>>> np.asarray(a, dtype=np.float32) is a
True
>>> np.asarray(a, dtype=np.float64) is a
False

Contrary to asanyarray, ndarray subclasses are not passed through:

>>> issubclass(np.recarray, np.ndarray)
True
>>> a = np.array([(1.0, 2), (3.0, 4)], dtype='f4,i4').view(np.recarray)
>>> np.asarray(a) is a
False
>>> np.asanyarray(a) is a
True

cdist

dipy.tracking.utils.cdist(XA, XB, metric='euclidean', *args, **kwargs)

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

See Notes for common calling conventions.

Parameters
XAndarray

An \(m_A\) by \(n\) array of \(m_A\) original observations in an \(n\)-dimensional space. Inputs are converted to float type.

XBndarray

An \(m_B\) by \(n\) array of \(m_B\) original observations in an \(n\)-dimensional space. Inputs are converted to float type.

metricstr 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’, ‘jensenshannon’, ‘kulsinski’, ‘mahalanobis’, ‘matching’, ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’, ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, ‘wminkowski’, ‘yule’.

*argstuple. Deprecated.

Additional arguments should be passed as keyword arguments

**kwargsdict, optional

Extra arguments to metric: refer to each metric documentation for a list of all possible arguments.

Some possible arguments:

p : scalar The p-norm to apply for Minkowski, weighted and unweighted. Default: 2.

w : ndarray The weight vector for metrics that support weights (e.g., Minkowski).

V : ndarray The variance vector for standardized Euclidean. Default: var(vstack([XA, XB]), axis=0, ddof=1)

VI : ndarray The inverse of the covariance matrix for Mahalanobis. Default: inv(cov(vstack([XA, XB].T))).T

out : ndarray The output array If not None, the distance matrix Y is stored in this array. Note: metric independent, it will become a regular keyword arg in a future scipy version

Returns
Yndarray

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:

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

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

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

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

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

    Computes the city block or Manhattan distance between the points.

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

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

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

    V is the variance vector; V[i] is the variance computed over all the i’th components of the points. If not passed, it is automatically computed.

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

    Computes the squared Euclidean distance \(||u-v||_2^2\) between the vectors.

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

    Computes the cosine distance between vectors u and v,

    \[1 - \frac{u \cdot v} {{||u||}_2 {||v||}_2}\]

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

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

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

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

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

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

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

  9. Y = cdist(XA, XB, 'jaccard')

    Computes the Jaccard distance between the points. Given two vectors, u and v, the Jaccard distance is the proportion of those elements u[i] and v[i] that disagree where at least one of them is non-zero.

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

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

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

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

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

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

\[d(u,v) = \frac{\sum_i (|u_i-v_i|)} {\sum_i (|u_i+v_i|)}\]
  1. Y = cdist(XA, XB, 'mahalanobis', VI=None)

Computes the Mahalanobis distance between the points. The Mahalanobis distance between two points u and v is \(\sqrt{(u-v)(1/V)(u-v)^T}\) where \((1/V)\) (the VI variable) is the inverse covariance. If VI is not None, VI will be used as the inverse covariance matrix.

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

Computes the Yule distance between the boolean vectors. (see yule function documentation)

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

Synonym for ‘hamming’.

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

Computes the Dice distance between the boolean vectors. (see dice function documentation)

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

Computes the Kulsinski distance between the boolean vectors. (see kulsinski function documentation)

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

Computes the Rogers-Tanimoto distance between the boolean vectors. (see rogerstanimoto function documentation)

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

Computes the Russell-Rao distance between the boolean vectors. (see russellrao function documentation)

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

Computes the Sokal-Michener distance between the boolean vectors. (see sokalmichener function documentation)

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

Computes the Sokal-Sneath distance between the vectors. (see sokalsneath function documentation)

  1. Y = cdist(XA, XB, 'wminkowski', p=2., w=w)

Computes the weighted Minkowski distance between the vectors. (see wminkowski function documentation)

  1. Y = cdist(XA, XB, f)

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

dm = cdist(XA, XB, lambda u, v: np.sqrt(((u-v)**2).sum()))

Note that you should avoid passing a reference to one of the distance functions defined in this library. For example,:

dm = cdist(XA, XB, sokalsneath)

would calculate the pair-wise distances between the vectors in X using the Python function sokalsneath. This would result in sokalsneath being called \({n \choose 2}\) times, which is inefficient. Instead, the optimized C version is more efficient, and we call it using the following syntax:

dm = cdist(XA, XB, 'sokalsneath')

Examples

Find the Euclidean distances between four 2-D coordinates:

>>> from scipy.spatial import distance
>>> coords = [(35.0456, -85.2672),
...           (35.1174, -89.9711),
...           (35.9728, -83.9422),
...           (36.1667, -86.7833)]
>>> distance.cdist(coords, coords, 'euclidean')
array([[ 0.    ,  4.7044,  1.6172,  1.8856],
       [ 4.7044,  0.    ,  6.0893,  3.3561],
       [ 1.6172,  6.0893,  0.    ,  2.8477],
       [ 1.8856,  3.3561,  2.8477,  0.    ]])

Find the Manhattan distance from a 3-D point to the corners of the unit cube:

>>> a = np.array([[0, 0, 0],
...               [0, 0, 1],
...               [0, 1, 0],
...               [0, 1, 1],
...               [1, 0, 0],
...               [1, 0, 1],
...               [1, 1, 0],
...               [1, 1, 1]])
>>> b = np.array([[ 0.1,  0.2,  0.4]])
>>> distance.cdist(a, b, 'cityblock')
array([[ 0.7],
       [ 0.9],
       [ 1.3],
       [ 1.5],
       [ 1.5],
       [ 1.7],
       [ 2.1],
       [ 2.3]])

connectivity_matrix

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

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

Parameters
streamlinessequence

A sequence of streamlines.

affinearray_like (4, 4)

The mapping from voxel coordinates to streamline coordinates. The voxel_to_rasmm matrix, typically from a NIFTI file.

label_volumendarray

An image volume with an integer data type, where the intensities in the volume map to anatomical structures.

inclusive: bool

Whether to analyze the entire streamline, as opposed to just the endpoints. Allowing this will increase calculation time and mapping size, especially if mapping_as_streamlines is True. False by default.

symmetricbool, True by default

Symmetric means we don’t distinguish between start and end points. If symmetric is True, matrix[i, j] == matrix[j, i].

return_mappingbool, False by default

If True, a mapping is returned which maps matrix indices to streamlines.

mapping_as_streamlinesbool, False by default

If True voxel indices map to lists of streamline objects. Otherwise voxel indices map to lists of integers.

Returns
matrixndarray

The number of connection between each pair of regions in label_volume.

mappingdefaultdict(list)

mapping[i, j] returns all the streamlines that connect region i to region j. If symmetric is True mapping will only have one key for each start end pair such that if i < j mapping will have key (i, j) but not key (j, i).

density_map

dipy.tracking.utils.density_map(streamlines, affine, vol_dims)

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

Parameters
streamlinesiterable

A sequence of streamlines.

affinearray_like (4, 4)

The mapping from voxel coordinates to streamline points. The voxel_to_rasmm matrix, typically from a NIFTI file.

vol_dims3 ints

The shape of the volume to be returned containing the streamlines counts

Returns
image_volumendarray, 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
affine4 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.

empty

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

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

Parameters
shapeint or tuple of int

Shape of the empty array, e.g., (2, 3) or 2.

dtypedata-type, optional

Desired output data-type for the array, e.g, numpy.int8. Default is numpy.float64.

order{‘C’, ‘F’}, optional, default: ‘C’

Whether to store multi-dimensional data in row-major (C-style) or column-major (Fortran-style) order in memory.

likearray_like

Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as like supports the __array_function__ protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument.

Note

The like keyword is an experimental feature pending on acceptance of NEP 35.

New in version 1.20.0.

Returns
outndarray

Array of uninitialized (arbitrary) data of the given shape, dtype, and order. Object arrays will be initialized to None.

See also

empty_like

Return an empty array with shape and type of input.

ones

Return a new array setting values to one.

zeros

Return a new array setting values to zero.

full

Return a new array of given shape filled with value.

Notes

empty, unlike zeros, does not set the array values to zero, and may therefore be marginally faster. On the other hand, it requires the user to manually set all the values in the array, and should be used with caution.

Examples

>>> np.empty([2, 2])
array([[ -9.74499359e+001,   6.69583040e-309],
       [  2.13182611e-314,   3.06959433e-309]])         #uninitialized
>>> np.empty([2, 2], dtype=int)
array([[-1073741821, -1067949133],
       [  496041986,    19249760]])                     #uninitialized

length

dipy.tracking.utils.length(streamlines)

Calculate the lengths of many streamlines in a bundle.

Parameters
streamlineslist

Each item in the list is an array with 3D coordinates of a streamline.

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
aarray_like

The array to perform in place operation on.

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

barray_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])
>>> a
array([-1, -2,  3,  4])

Increment items 0 and 1, and increment item 2 twice:

>>> a = np.array([1, 2, 3, 4])
>>> np.add.at(a, [0, 1, 2, 2], 1)
>>> a
array([2, 3, 5, 4])

Add items 0 and 1 in first array to second array, and store results in first array:

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

ndbincount

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

Like bincount, but for nd-indices.

Parameters
xarray_like (N, M)

M indices to a an Nd-array

weightsarray_like (M,), optional

Weights associated with indices

shapeoptional

the shape of the output

near_roi

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

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

Parameters
streamlineslist or generator

A sequence of streamlines. Each streamline should be a (N, 3) array, where N is the length of the streamline.

affinearray (4, 4)

The mapping between voxel indices and the point space for seeds. The voxel_to_rasmm matrix, typically from a NIFTI file.

region_of_interestndarray

A mask used as a target. Non-zero values are considered to be within the target region.

tolfloat

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.

modestring, optional

One of {“any”, “all”, “either_end”, “both_end”}, where return True if:

“any” : any point is within tol from ROI. Default.

“all” : all points are within tol from ROI.

“either_end” : either of the end-points is within tol from ROI

“both_end” : both end points are within tol from ROI.

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.

path_length

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

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

Parameters
streamlinesseq of (N, 3) arrays

A sequence of streamlines, path length is given in mm along the curve of the streamline.

aoiarray, 3d

A mask (binary array) of voxels from which to start computing distance.

affinearray (4, 4)

The mapping between voxel indices and the point space for seeds. The voxel_to_rasmm matrix, typically from a NIFTI file.

fill_valuefloat

The value of voxel in the path length map that are not connected to the aoi.

Returns
plmarray

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, affine, seeds_count=1, seed_count_per_voxel=True, random_seed=None)

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

Seeds points are placed randomly distributed in voxels of mask which are True. If seed_count_per_voxel is True, this function is similar to seeds_from_mask(), with the difference that instead of evenly distributing the seeds, it randomly places the seeds within the voxels specified by the mask.

Parameters
maskbinary 3d array_like

A binary array specifying where to place the seeds for fiber tracking.

affinearray, (4, 4)

The mapping between voxel indices and the point space for seeds. The voxel_to_rasmm matrix, typically from a NIFTI file. A seed point at the center the voxel [i, j, k] will be represented as [x, y, z] where [x, y, z, 1] == np.dot(affine, [i, j, k , 1]).

seeds_countint

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.

random_seedint

The seed for the random seed generator (numpy.random.seed).

Raises
ValueError

When mask is not a three-dimensional array

See also

seeds_from_mask

Examples

>>> mask = np.zeros((3,3,3), 'bool')
>>> mask[0,0,0] = 1
>>> random_seeds_from_mask(mask, np.eye(4), seeds_count=1,
... seed_count_per_voxel=True, random_seed=1)
array([[-0.0640051 , -0.47407377,  0.04966248]])
>>> random_seeds_from_mask(mask, np.eye(4), seeds_count=6,
... seed_count_per_voxel=True, random_seed=1)
array([[-0.0640051 , -0.47407377,  0.04966248],
       [ 0.0507979 ,  0.20814782, -0.20909526],
       [ 0.46702984,  0.04723225,  0.47268436],
       [-0.27800683,  0.37073231, -0.29328084],
       [ 0.39286015, -0.16802019,  0.32122912],
       [-0.42369171,  0.27991879, -0.06159077]])
>>> mask[0,1,2] = 1
>>> random_seeds_from_mask(mask, np.eye(4),
... seeds_count=2, seed_count_per_voxel=True, random_seed=1)
array([[-0.0640051 , -0.47407377,  0.04966248],
       [-0.27800683,  1.37073231,  1.70671916],
       [ 0.0507979 ,  0.20814782, -0.20909526],
       [-0.48962585,  1.00187459,  1.99577329]])

ravel_multi_index

dipy.tracking.utils.ravel_multi_index(multi_index, dims, mode='raise', order='C')

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

Parameters
multi_indextuple of array_like

A tuple of integer arrays, one array for each dimension.

dimstuple of ints

The shape of array into which the indices from multi_index apply.

mode{‘raise’, ‘wrap’, ‘clip’}, optional

Specifies how out-of-bounds indices are handled. Can specify either one mode or a tuple of modes, one mode per index.

  • ‘raise’ – raise an error (default)

  • ‘wrap’ – wrap around

  • ‘clip’ – clip to the range

In ‘clip’ mode, a negative index which would normally wrap will clip to 0 instead.

order{‘C’, ‘F’}, optional

Determines whether the multi-index should be viewed as indexing in row-major (C-style) or column-major (Fortran-style) order.

Returns
raveled_indicesndarray

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
roislist or ndarray

A list of 3D arrays, each with shape (x, y, z) corresponding to the shape of the brain volume, or a 4D array with shape (n_rois, x, y, z). Non-zeros in each volume are considered to be within the region.

includearray or list

A list or 1D array of boolean marking inclusion or exclusion criteria.

Returns
include_roiboolean 3D array

An array marking the inclusion mask.

exclude_roiboolean 3D array

An array marking the exclusion mask

Notes

The include_roi and exclude_roi can be used to perfom the operation: “(A or B or …) and not (X or Y or …)”, where A, B are inclusion regions and X, Y are exclusion regions.

seeds_from_mask

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

Create seeds for fiber tracking from a binary mask.

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

Parameters
maskbinary 3d array_like

A binary array specifying where to place the seeds for fiber tracking.

affinearray, (4, 4)

The mapping between voxel indices and the point space for seeds. The voxel_to_rasmm matrix, typically from a NIFTI file. A seed point at the center the voxel [i, j, k] will be represented as [x, y, z] where [x, y, z, 1] == np.dot(affine, [i, j, k , 1]).

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

Raises
ValueError

When mask is not a three-dimensional array

Examples

>>> mask = np.zeros((3,3,3), 'bool')
>>> mask[0,0,0] = 1
>>> seeds_from_mask(mask, np.eye(4), [1,1,1])
array([[ 0.,  0.,  0.]])

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
streamlinearray, shape (N, 3)

A single streamline

roi_coordsarray, shape (M, 3)

ROI coordinates transformed to the streamline coordinate frame.

tolfloat

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.

modestring

One of {“any”, “all”, “either_end”, “both_end”}, where return True if:

“any” : any point is within tol from ROI.

“all” : all points are within tol from ROI.

“either_end” : either of the end-points is within tol from ROI

“both_end” : both end points are within tol from ROI.

Returns
outboolean

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
streamlinessequence of ndarrays

The streamlines to be subsegmented.

max_segment_lengthfloat

The longest allowable segment length.

Returns
output_streamlinesgenerator

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, affine, target_mask, include=True)

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

Parameters
streamlinesiterable

A sequence of streamlines. Each streamline should be a (N, 3) array, where N is the length of the streamline.

affinearray (4, 4)

The mapping between voxel indices and the point space for seeds. The voxel_to_rasmm matrix, typically from a NIFTI file.

target_maskarray-like

A mask used as a target. Non-zero values are considered to be within the target region.

includebool, default True

If True, streamlines passing through target_mask are kept. If False, the streamlines not passing through target_mask are kept.

Returns
streamlinesgenerator

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

density_map

target_line_based

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

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

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

Parameters
streamlinesiterable

A sequence of streamlines. Each streamline should be a (N, 3) array, where N is the length of the streamline.

affinearray (4, 4)

The mapping between voxel indices and the point space for seeds. The voxel_to_rasmm matrix, typically from a NIFTI file.

target_maskarray-like

A mask used as a target. Non-zero values are considered to be within the target region.

includebool, default True

If True, streamlines passing through target_mask are kept. If False, the streamlines not passing through target_mask are kept.

Returns
streamlinesgenerator

A sequence of streamlines that pass through target_mask.

References

[Bresenham5] Bresenham, Jack Elton. “Algorithm for computer control of a

digital plotter”, IBM Systems Journal, vol 4, no. 1, 1965.

[Houde15] Houde et al. How to avoid biased streamlines-based metrics for

streamlines with variable step sizes, ISMRM 2015.

transform_tracking_output

dipy.tracking.utils.transform_tracking_output(tracking_output, affine, save_seeds=False)

Applies a linear transformation, given by affine, to streamlines. Parameters ———- streamlines : Streamlines generator

Either streamlines (list, ArraySequence) or a tuple with streamlines and seeds together

affinearray (4, 4)

The mapping between voxel indices and the point space for seeds. The voxel_to_rasmm matrix, typically from a NIFTI file.

save_seedsbool, optional

If set, seeds associated to streamlines will be also moved and returned

streamlinesgenerator

A generator for the sequence of transformed streamlines. If save_seeds is True, also return a generator for the transformed seeds.

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.

warn

dipy.tracking.utils.warn(/, message, category=None, stacklevel=1, source=None)

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

wraps

dipy.tracking.utils.wraps(wrapped, assigned=('__module__', '__name__', '__qualname__', '__doc__', '__annotations__'), updated=('__dict__', ))

Decorator factory to apply update_wrapper() to a wrapper function

Returns a decorator that invokes update_wrapper() with the decorated function as the wrapper argument and the arguments to wraps() as the remaining arguments. Default arguments are as for update_wrapper(). This is a convenience function to simplify applying partial() to update_wrapper().

streamline_mapping

dipy.tracking.vox2track.streamline_mapping()

Creates a mapping from voxel indices to streamlines.

Returns a dictionary where each key is a 3d voxel index and the associated value is a list of the streamlines that pass through that voxel.

Parameters
streamlinessequence

A sequence of streamlines.

affinearray_like (4, 4), optional

The mapping from voxel coordinates to streamline coordinates. The streamline values are assumed to be in voxel coordinates. IE [0, 0, 0] is the center of the first voxel and the voxel size is [1, 1, 1].

mapping_as_streamlinesbool, optional, False by default

If True voxel indices map to lists of streamline objects. Otherwise voxel indices map to lists of integers.

Returns
mappingdefaultdict(list)

A mapping from voxel indices to the streamlines that pass through that voxel.

Examples

>>> streamlines = [np.array([[0., 0., 0.],
...                          [1., 1., 1.],
...                          [2., 3., 4.]]),
...                np.array([[0., 0., 0.],
...                          [1., 2., 3.]])]
>>> mapping = streamline_mapping(streamlines, affine=np.eye(4))
>>> mapping[0, 0, 0]
[0, 1]
>>> mapping[1, 1, 1]
[0]
>>> mapping[1, 2, 3]
[1]
>>> mapping.get((3, 2, 1), 'no streamlines')
'no streamlines'
>>> mapping = streamline_mapping(streamlines, affine=np.eye(4),
...                              mapping_as_streamlines=True)
>>> mapping[1, 2, 3][0] is streamlines[1]
True

track_counts

dipy.tracking.vox2track.track_counts()

Counts of points in tracks that pass through voxels in volume

We find whether a point passed through a track by rounding the mm point values to voxels. For a track that passes through a voxel more than once, we only record counts and elements for the first point in the line that enters the voxel.

Parameters
trackssequence

sequence of T tracks. One track is an ndarray of shape (N, 3), where N is the number of points in that track, and tracks[t][n] is the n-th point in the t-th track. Points are of form x, y, z in voxel mm coordinates. That is, if i, j, k is the possibly non-integer voxel coordinate of the track point, and vox_sizes are 3 floats giving voxel sizes of dimensions 0, 1, 2 respectively, then the voxel mm coordinates x, y, z are simply i * vox_sizes[0], j * vox_sizes[1], k * vox_sizes[2]. This convention derives from trackviz. To pass in tracks as voxel coordinates, just pass vox_sizes=(1, 1, 1) (see below).

vol_dimssequence length 3

volume dimensions in voxels, x, y, z.

vox_sizesoptional, sequence length 3

voxel sizes in mm. Default is (1,1,1)

return_elements{True, False}, optional

If True, also return object array with one list per voxel giving track indices and point indices passing through the voxel (see below)

Returns
tcsndarray shape vol_dim

An array where entry tcs[x, y, z] is the number of tracks that passed through voxel at voxel coordinate x, y, z

tesndarray dtype np.object, shape vol_dim

If return_elements is True, we also return an object array with one object per voxel. The objects at each voxel are a list of integers, where the integers are the indices of the track that passed through the voxel.

Examples

Imagine you have a volume (voxel) space of dimension (10,20,30). Imagine you had voxel coordinate tracks in vs. To just fill an array with the counts of how many tracks pass through each voxel:

>>> vox_track0 = np.array([[0, 0, 0], [1.1, 2.2, 3.3], [2.2, 4.4, 6.6]])
>>> vox_track1 = np.array([[0, 0, 0], [0, 0, 1], [0, 0, 2]])
>>> vs = (vox_track0, vox_track1)
>>> vox_dim = (10, 20, 30) # original voxel array size
>>> tcs = track_counts(vs, vox_dim, (1, 1, 1), False)
>>> tcs.shape
(10, 20, 30)
>>> tcs[0, 0, 0:4]
array([2, 1, 1, 0])
>>> tcs[1, 2, 3], tcs[2, 4, 7]
(1, 1)

You can also use the routine to count into larger-than-voxel boxes. To do this, increase the voxel size and decrease the vox_dim accordingly:

>>> tcs=track_counts(vs, (10/2., 20/2., 30/2.), (2,2,2), False)
>>> tcs.shape
(5, 10, 15)
>>> tcs[1,1,2], tcs[1,2,3]
(1, 1)