Various tools related to creating and working with streamlines.
This module provides tools for targeting streamlines using ROIs, for making
connectivity matrices from whole brain fiber tracking and some other tools that
allow streamlines to interact with image data.
Dipy uses affine matrices to represent the relationship between streamline
points, which are defined as points in a continuous 3d space, and image voxels,
which are typically arranged in a discrete 3d grid. Dipy uses a convention
similar to nifti files to interpret these affine matrices. This convention is
that the point at the center of voxel [i,j,k] is represented by the point
[x,y,z] where [x,y,z,1]=affine*[i,j,k,1]. Also when the
phrase “voxel coordinates” is used, it is understood to be the same as affine=eye(4).
As an example, let’s 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:
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 correspondence 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.)
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 correspondence in th following way
the first column 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.)
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
Notes
This is an implementation of the LiFE model described in
[1].
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.
evalsarray-like, 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, optional
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.
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.
evalsarray-like (3 items, optional)
The eigenvalues of the canonical tensor used as a response
function. Default:[0.001, 0, 0].
sphere: `dipy.core.Sphere` instance, optional
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
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.
The estimated eigenvalues of a single fiber tensor.
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.
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
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.
dipy.tracking.metrics.inside_sphere(xyz, center, radius)[source]#
If any point of the track is inside a sphere of a specified
center and radius return True otherwise False. Mathematically 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.
dipy.tracking.metrics.inside_sphere_points(xyz, center, radius)[source]#
If a track intersects with a sphere of a specified center and
radius return the points that are inside the sphere otherwise False.
Mathematically 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
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
>>> importnumpyasnp>>> 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,s=3,k=2,nest=-1)>>> len(xyzn)>len(xyz)True
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
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.
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 [2] (based on the streamline MDF distance from
Garyfallidis et al.[3]).
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.
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.
as_generatorbool
Whether to return a generator as output.
Returns:
streamlineslist or generator
The same 3D arrays as a list or generator, but reoriented with respect
to the ROIs
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.
as_generatorbool
Whether to return a generator as output.
Returns:
Streamlineswith each individual array oriented to be as similar as
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.
The basis that shcoeff are associated with.
dipy.reconst.shm.real_sh_descoteaux is used by default.
legacy: bool, optional
True to use a legacy basis definition for backward compatibility
with previous tournier07 and descoteaux07 implementations.
nbr_threads: int, optional
Number of threads to use for the processing. By default, all available threads
will be used.
random_seed: int, optional
Seed for the random number generator, must be >= 0. A value of greater than 0
will all produce the same streamline trajectory for a given seed coordinate.
A value of 0 may produces various streamline tracjectories for a given seed
coordinate.
seed_buffer_fraction: float, optional
Fraction of the seed buffer to use. A value of 1.0 will use the entire seed
buffer. A value of 0.5 will use half of the seed buffer then the other half.
a way to reduce memory usage.
return_all: bool, optional
True to return all the streamlines, False to return only the streamlines that
reached the stopping criterion.
save_seeds: bool, optional
True to return the seeds with the associated streamline.
The basis that shcoeff are associated with.
dipy.reconst.shm.real_sh_descoteaux is used by default.
legacy: bool, optional
True to use a legacy basis definition for backward compatibility
with previous tournier07 and descoteaux07 implementations.
nbr_threads: int, optional
Number of threads to use for the processing. By default, all available threads
will be used.
random_seed: int, optional
Seed for the random number generator, must be >= 0. A value of greater than 0
will all produce the same streamline trajectory for a given seed coordinate.
A value of 0 may produces various streamline tracjectories for a given seed
coordinate.
seed_buffer_fraction: float, optional
Fraction of the seed buffer to use. A value of 1.0 will use the entire seed
buffer. A value of 0.5 will use half of the seed buffer then the other half.
a way to reduce memory usage.
return_all: bool, optional
True to return all the streamlines, False to return only the streamlines that
reached the stopping criterion.
save_seeds: bool, optional
True to return the seeds with the associated streamline.
Parallel Transport Tractography (PTT) tracking algorithm.
Parameters:
seed_positionsndarray
Seed positions in world space.
scStoppingCriterion
Stopping criterion.
affinendarray
Affine matrix.
seed_directionsndarray, optional
Seed directions.
shndarray, optional
Spherical Harmonics (SH) data.
peaksndarray, optional
Peaks array
sfndarray, optional
Spherical Function (SF).
min_lenint, optional
Minimum length of the streamlines.
max_lenint, optional
Maximum length of the streamlines.
step_sizefloat, optional
Step size of the tracking.
voxel_sizendarray, optional
Voxel size.
max_anglefloat, optional
Maximum angle.
pmf_thresholdfloat, optional
PMF threshold.
probe_lengthfloat, optional
Probe length.
probe_radiusfloat, optional
Probe radius.
probe_qualityint, optional
Probe quality.
probe_countint, optional
Probe count.
data_support_exponentint, optional
Data support exponent.
sphereSphere, optional
Sphere.
basis_typename of basis
The basis that shcoeff are associated with.
dipy.reconst.shm.real_sh_descoteaux is used by default.
legacy: bool, optional
True to use a legacy basis definition for backward compatibility
with previous tournier07 and descoteaux07 implementations.
nbr_threads: int, optional
Number of threads to use for the processing. By default, all available threads
will be used.
random_seed: int, optional
Seed for the random number generator, must be >= 0. A value of greater than 0
will all produce the same streamline trajectory for a given seed coordinate.
A value of 0 may produces various streamline tracjectories for a given seed
coordinate.
seed_buffer_fraction: float, optional
Fraction of the seed buffer to use. A value of 1.0 will use the entire seed
buffer. A value of 0.5 will use half of the seed buffer then the other half.
a way to reduce memory usage.
return_all: bool, optional
True to return all the streamlines, False to return only the streamlines that
reached the stopping criterion.
save_seeds: bool, optional
True to return the seeds with the associated streamline.
The basis that shcoeff are associated with.
dipy.reconst.shm.real_sh_descoteaux is used by default.
legacy: bool, optional
True to use a legacy basis definition for backward compatibility
with previous tournier07 and descoteaux07 implementations.
nbr_threads: int, optional
Number of threads to use for the processing. By default, all available threads
will be used.
random_seed: int, optional
Seed for the random number generator, must be >= 0. A value of greater than 0
will all produce the same streamline trajectory for a given seed coordinate.
A value of 0 may produces various streamline tracjectories for a given seed
coordinate.
seed_buffer_fraction: float, optional
Fraction of the seed buffer to use. A value of 1.0 will use the entire seed
buffer. A value of 0.5 will use half of the seed buffer then the other half.
a way to reduce memory usage.
return_all: bool, optional
True to return all the streamlines, False to return only the streamlines that
reached the stopping criterion.
save_seeds: bool, optional
True to return the seeds with the associated streamline.
The basis that shcoeff are associated with.
dipy.reconst.shm.real_sh_descoteaux is used by default.
legacy: bool, optional
True to use a legacy basis definition for backward compatibility
with previous tournier07 and descoteaux07 implementations.
nbr_threads: int, optional
Number of threads to use for the processing. By default, all available threads
will be used.
random_seed: int, optional
Seed for the random number generator, must be >= 0. A value of greater than 0
will all produce the same streamline trajectory for a given seed coordinate.
A value of 0 may produces various streamline tracjectories for a given seed
coordinate.
seed_buffer_fraction: float, optional
Fraction of the seed buffer to use. A value of 1.0 will use the entire seed
buffer. A value of 0.5 will use half of the seed buffer then the other half.
a way to reduce memory usage.
return_all: bool, optional
True to return all the streamlines, False to return only the streamlines that
reached the stopping criterion.
save_seeds: bool, optional
True to return the seeds with the associated streamline.
The basis that shcoeff are associated with.
dipy.reconst.shm.real_sh_descoteaux is used by default.
legacy: bool, optional
True to use a legacy basis definition for backward compatibility
with previous tournier07 and descoteaux07 implementations.
nbr_threads: int, optional
Number of threads to use for the processing. By default, all available threads
will be used.
random_seed: int, optional
Seed for the random number generator, must be >= 0. A value of greater than 0
will all produce the same streamline trajectory for a given seed coordinate.
A value of 0 may produces various streamline tracjectories for a given seed
coordinate.
seed_buffer_fraction: float, optional
Fraction of the seed buffer to use. A value of 1.0 will use the entire seed
buffer. A value of 0.5 will use half of the seed buffer then the other half.
a way to reduce memory usage.
return_all: bool, optional
True to return all the streamlines, False to return only the streamlines that
reached the stopping criterion.
save_seeds: bool, optional
True to return the seeds with the associated streamline.
The basis that shcoeff are associated with.
dipy.reconst.shm.real_sh_descoteaux is used by default.
legacy: bool, optional
True to use a legacy basis definition for backward compatibility
with previous tournier07 and descoteaux07 implementations.
nbr_threads: int, optional
Number of threads to use for the processing. By default, all available threads
will be used.
random_seed: int, optional
Seed for the random number generator, must be >= 0. A value of greater than 0
will all produce the same streamline trajectory for a given seed coordinate.
A value of 0 may produces various streamline tracjectories for a given seed
coordinate.
seed_buffer_fraction: float, optional
Fraction of the seed buffer to use. A value of 1.0 will use the entire seed
buffer. A value of 0.5 will use half of the seed buffer then the other half.
a way to reduce memory usage.
return_all: bool, optional
True to return all the streamlines, False to return only the streamlines that
reached the stopping criterion.
pft_back_tracking_distfloat, optional
Back tracking distance.
pft_front_tracking_distfloat, optional
Front tracking distance.
pft_max_trialint, optional
Maximum number of trials.
particle_countint, optional
Number of particles.
save_seeds: bool, optional
True to return the seeds with the associated streamline.
min_wm_pve_before_stoppingfloat, optional
Minimum white matter partial volume estimation before stopping.
Count 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.
Count 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. 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).
Split 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.
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.
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.Generator).
Filter 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.
See [4] and [5] for further
details about the method.
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.
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.
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
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 perform the operation: “(A
or B or …) and not (X or Y or …)”, where A, B are inclusion regions
and X, Y are exclusion regions.