segment

Module: segment.bundles

RecoBundles(streamlines[, greater_than, ...])
check_range(streamline, gt, lt)
logger	Instances of the Logger class represent a single logging channel.
bundle_adjacency(dtracks0, dtracks1, threshold)	Find bundle adjacency between two given tracks/bundles
ba_analysis(recognized_bundle, expert_bundle)	Calculates bundle adjacency score between two given bundles
cluster_bundle(bundle, clust_thr, rng[, ...])	Clusters bundles
bundle_shape_similarity(bundle1, bundle2, rng)	Calculates bundle shape similarity between two given bundles using bundle adjacency (BA) metric

Module: segment.clustering

Identity()	Provides identity indexing functionality.
Cluster([id, indices, refdata])	Provides functionalities for interacting with a cluster.
ClusterCentroid(centroid[, id, indices, refdata])	Provides functionalities for interacting with a cluster.
ClusterMap([refdata])	Provides functionalities for interacting with clustering outputs.
ClusterMapCentroid([refdata])	Provides functionalities for interacting with clustering outputs that have centroids.
Clustering()
QuickBundles(threshold[, metric, ...])	Clusters streamlines using QuickBundles [Garyfallidis12].
QuickBundlesX(thresholds[, metric])	Clusters streamlines using QuickBundlesX.
TreeCluster(threshold, centroid[, indices])
TreeClusterMap(root)
logger	Instances of the Logger class represent a single logging channel.
qbx_and_merge(streamlines, thresholds[, ...])	Run QuickBundlesX and then run again on the centroids of the last layer

Module: segment.clustering_algorithms

ClusterCentroid(centroid[, id, indices, refdata])	Provides functionalities for interacting with a cluster.
ClusterMapCentroid([refdata])	Provides functionalities for interacting with clustering outputs that have centroids.
DTYPE	alias of float32
clusters_centroid2clustermap_centroid(...)	Converts a ClustersCentroid object (Cython) to a ClusterMapCentroid object (Python).
peek(iterable)	Returns the first element of an iterable and the iterator.
quickbundles(streamlines, metric, threshold)	Clusters streamlines using QuickBundles.
quickbundlesx(streamlines, metric, thresholds)	Clusters streamlines using QuickBundlesX.

Module: segment.clusteringspeed

ClusterCentroid(centroid[, id, indices, refdata])	Provides functionalities for interacting with a cluster.
ClusterMapCentroid([refdata])	Provides functionalities for interacting with clustering outputs that have centroids.
Clusters	Provides Cython functionalities to interact with clustering outputs.
ClustersCentroid	Provides Cython functionalities to interact with clustering outputs having the notion of cluster's centroid.
DTYPE	alias of float32
QuickBundles
QuickBundlesX
TreeCluster(threshold, centroid[, indices])
TreeClusterMap(root)
evaluate_aabb_checks()

Module: segment.cythonutils

Module: segment.featurespeed

ArcLengthFeature	Extracts features from a sequential datum.
CenterOfMassFeature	Extracts features from a sequential datum.
CythonFeature	Extracts features from a sequential datum.
Feature	Extracts features from a sequential datum.
IdentityFeature	Extracts features from a sequential datum.
MidpointFeature	Extracts features from a sequential datum.
ResampleFeature	Extracts features from a sequential datum.
VectorOfEndpointsFeature	Extracts features from a sequential datum.
extract(feature, data)	Extracts features from data.
infer_shape(feature, data)	Infers shape of the features extracted from data.

Module: segment.fss

FastStreamlineSearch(ref_streamlines, max_radius)
nearest_from_matrix_row(coo_matrix)	Return the nearest (smallest) for each row given an coup sparse matrix
nearest_from_matrix_col(coo_matrix)	Return the nearest (smallest) for each column given an coup sparse matrix

Module: segment.mask

multi_median(data, median_radius, numpass)	Applies median filter multiple times on input data.
applymask(vol, mask)	Mask vol with mask.
bounding_box(vol)	Compute the bounding box of nonzero intensity voxels in the volume.
crop(vol, mins, maxs)	Crops the input volume.
median_otsu(input_volume[, vol_idx, ...])	Simple brain extraction tool method for images from DWI data.
segment_from_cfa(tensor_fit, roi, threshold)	Segment the cfa inside roi using the values from threshold as bounds.
clean_cc_mask(mask)	Cleans a segmentation of the corpus callosum so no random pixels are included.

Module: segment.metric

mdf(s1, s2)	Computes the MDF (Minimum average Direct-Flip) distance [Garyfallidis12] between two streamlines.
mean_manhattan_distance(a, b)	Compute the average Manhattan-L1 distance (MDF without flip)
mean_euclidean_distance(a, b)	Compute the average Euclidean-L2 distance (MDF without flip)

Module: segment.metricspeed

AveragePointwiseEuclideanMetric	Computes the average of pointwise Euclidean distances between two sequential data. A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions). A feature object can be specified in order to calculate the distance between the features, rather than directly between the sequential data. Parameters ---------- feature : Feature object, optional It is used to extract features before computing the distance. Notes ----- The distance between two 2D sequential data:: s1 s2 0* a 0 | | 1 | | b 1 | 2 c *2 is equal to \((a+b+c)/3\) where \(a\) is the Euclidean distance between s1[0] and s2[0], \(b\) between s1[1] and s2[1] and \(c\) between s1[2] and s2[2]. .
CosineMetric	Computes the cosine distance between two vectors.
CythonMetric	Computes a distance between two sequential data.
Metric	Computes a distance between two sequential data.
MinimumAverageDirectFlipMetric	Computes the MDF distance (minimum average direct-flip) between two sequential data. A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions). Notes ----- The distance between two 2D sequential data:: s1 s2 0* a 0 | | 1 | | b 1 | 2 c *2 is equal to \(\min((a+b+c)/3, (a'+b'+c')/3)\) where \(a\) is the Euclidean distance between s1[0] and s2[0], \(b\) between s1[1] and s2[1], \(c\) between s1[2] and s2[2], \(a'\) between s1[0] and s2[2], \(b'\) between s1[1] and s2[1] and \(c'\) between s1[2] and s2[0]. .
SumPointwiseEuclideanMetric	Computes the sum of pointwise Euclidean distances between two sequential data. A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions). A feature object can be specified in order to calculate the distance between the features, rather than directly between the sequential data. Parameters ---------- feature : Feature object, optional It is used to extract features before computing the distance. Notes ----- The distance between two 2D sequential data:: s1 s2 0* a 0 | | 1 | | b 1 | 2 c *2 is equal to \(a+b+c\) where \(a\) is the Euclidean distance between s1[0] and s2[0], \(b\) between s1[1] and s2[1] and \(c\) between s1[2] and s2[2]. .
dist(metric, datum1, datum2)	Computes a distance between datum1 and datum2.
distance_matrix(metric, data1[, data2])	Computes the distance matrix between two lists of sequential data.

Module: segment.mrf

ConstantObservationModel()	Observation model assuming that the intensity of each class is constant.
IteratedConditionalModes()

Module: segment.threshold

otsu(image[, nbins])	Return threshold value based on Otsu's method.
upper_bound_by_rate(data[, rate])	Adjusts upper intensity boundary using rates
upper_bound_by_percent(data[, percent])	Find the upper bound for visualization of medical images

Module: segment.tissue

TissueClassifierHMRF([save_history, verbose])

This class contains the methods for tissue classification using the Markov Random Fields modeling approach

RecoBundles

class dipy.segment.bundles.RecoBundles(streamlines, greater_than=50, less_than=1000000, cluster_map=None, clust_thr=15, nb_pts=20, rng=None, verbose=False)

Bases: object

__init__(streamlines, greater_than=50, less_than=1000000, cluster_map=None, clust_thr=15, nb_pts=20, rng=None, verbose=False)

Recognition of bundles

Extract bundles from a participants’ tractograms using model bundles segmented from a different subject or an atlas of bundles. See [Garyfallidis17] for the details.

Parameters

streamlinesStreamlines

The tractogram in which you want to recognize bundles.

greater_thanint, optional

Keep streamlines that have length greater than this value (default 50)

less_thanint, optional

Keep streamlines have length less than this value (default 1000000)

cluster_mapQB map, optional.

Provide existing clustering to start RB faster (default None).

clust_thrfloat, optional.

Distance threshold in mm for clustering streamlines. Default: 15.

nb_ptsint, optional.

Number of points per streamline (default 20)

rngnp.random.Generator

If None define generator in initialization function. Default: None

verbose: bool, optional.

If True, log information.

Notes

Make sure that before creating this class that the streamlines and the model bundles are roughly in the same space. Also default thresholds are assumed in RAS 1mm^3 space. You may want to adjust those if your streamlines are not in world coordinates.

References

[Garyfallidis17]

Garyfallidis et al. Recognition of white matter bundles using local and global streamline-based registration and clustering, Neuroimage, 2017.

evaluate_results(model_bundle, pruned_streamlines, slr_select)

Compare the similarity between two given bundles, model bundle, and extracted bundle.

Parameters

model_bundle : Streamlines pruned_streamlines : Streamlines slr_select : tuple

Select the number of streamlines from model to neirborhood of model to perform the local SLR.

Returns

ba_valuefloat

bundle adjacency value between model bundle and pruned bundle

bmd_valuefloat

bundle minimum distance value between model bundle and pruned bundle

recognize(model_bundle, model_clust_thr, reduction_thr=10, reduction_distance='mdf', slr=True, num_threads=None, slr_metric=None, slr_x0=None, slr_bounds=None, slr_select=(400, 600), slr_method='L-BFGS-B', pruning_thr=5, pruning_distance='mdf')

Recognize the model_bundle in self.streamlines

Parameters

model_bundleStreamlines

model bundle streamlines used as a reference to extract similar streamlines from input tractogram

model_clust_thrfloat

MDF distance threshold for the model bundles

reduction_thrfloat, optional

Reduce search space in the target tractogram by (mm) (default 10)

reduction_distancestring, optional

Reduction distance type can be mdf or mam (default mdf)

slrbool, optional

Use Streamline-based Linear Registration (SLR) locally (default True)

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.

slr_metric : BundleMinDistanceMetric slr_x0 : array or int or str, optional

Transformation allowed. translation, rigid, similarity or scaling Initial parametrization for the optimization.

If 1D array with:

a) 6 elements then only rigid registration is performed with the 3 first elements for translation and 3 for rotation. b) 7 elements also isotropic scaling is performed (similarity). c) 12 elements then translation, rotation (in degrees), scaling and shearing are performed (affine).

Here is an example of x0 with 12 elements: x0=np.array([0, 10, 0, 40, 0, 0, 2., 1.5, 1, 0.1, -0.5, 0])

This has translation (0, 10, 0), rotation (40, 0, 0) in degrees, scaling (2., 1.5, 1) and shearing (0.1, -0.5, 0).

If int:

1. 6

   x0 = np.array([0, 0, 0, 0, 0, 0])

2. 7

   x0 = np.array([0, 0, 0, 0, 0, 0, 1.])

3. 12

   x0 = np.array([0, 0, 0, 0, 0, 0, 1., 1., 1, 0, 0, 0])

If str:

1. “rigid”

   x0 = np.array([0, 0, 0, 0, 0, 0])

2. “similarity”

   x0 = np.array([0, 0, 0, 0, 0, 0, 1.])

3. “affine”

   ``x0 = np.array([0, 0, 0, 0, 0, 0, 1., 1., 1, 0, 0, 0])

(default None)

slr_boundsarray, optional

(default None)

slr_selecttuple, optional

Select the number of streamlines from model to neirborhood of model to perform the local SLR.

slr_methodstring, optional

Optimization method ‘L_BFGS_B’ or ‘Powell’ optimizers can be used. (default ‘L-BFGS-B’)

pruning_thrfloat, optional

Pruning after reducing the search space (default 5).

pruning_distancestring, optional

Pruning distance type can be mdf or mam (default mdf)

Returns

recognized_transfStreamlines

Recognized bundle in the space of the model tractogram

recognized_labelsarray

Indices of recognized bundle in the original tractogram

References

[Garyfallidis17]

Garyfallidis et al. Recognition of white matter bundles using local and global streamline-based registration and clustering, Neuroimage, 2017.

refine(model_bundle, pruned_streamlines, model_clust_thr, reduction_thr=14, reduction_distance='mdf', slr=True, slr_metric=None, slr_x0=None, slr_bounds=None, slr_select=(400, 600), slr_method='L-BFGS-B', pruning_thr=6, pruning_distance='mdf')

Refine and recognize the model_bundle in self.streamlines This method expects once pruned streamlines as input. It refines the first output of recobundle by applying second local slr (optional), and second pruning. This method is useful when we are dealing with noisy data or when we want to extract small tracks from tractograms. This time, search space is created using pruned bundle and not model bundle.

Parameters

model_bundleStreamlines

model bundle streamlines used as a reference to extract similar streamlines from input tractogram

pruned_streamlinesStreamlines

Recognized bundle from target tractogram by RecoBundles.

model_clust_thrfloat

MDF distance threshold for the model bundles

reduction_thrfloat

Reduce search space by (mm) (default 14)

reduction_distancestring

Reduction distance type can be mdf or mam (default mdf)

slrbool

Use Streamline-based Linear Registration (SLR) locally (default True)

slr_metric : BundleMinDistanceMetric slr_x0 : array or int or str

Transformation allowed. translation, rigid, similarity or scaling Initial parametrization for the optimization.

If 1D array with:

a) 6 elements then only rigid registration is performed with the 3 first elements for translation and 3 for rotation. b) 7 elements also isotropic scaling is performed (similarity). c) 12 elements then translation, rotation (in degrees), scaling and shearing are performed (affine).

Here is an example of x0 with 12 elements: x0=np.array([0, 10, 0, 40, 0, 0, 2., 1.5, 1, 0.1, -0.5, 0])

This has translation (0, 10, 0), rotation (40, 0, 0) in degrees, scaling (2., 1.5, 1) and shearing (0.1, -0.5, 0).

If int:

1. 6

   x0 = np.array([0, 0, 0, 0, 0, 0])

2. 7

   x0 = np.array([0, 0, 0, 0, 0, 0, 1.])

3. 12

   x0 = np.array([0, 0, 0, 0, 0, 0, 1., 1., 1, 0, 0, 0])

If str:

1. “rigid”

   x0 = np.array([0, 0, 0, 0, 0, 0])

2. “similarity”

   x0 = np.array([0, 0, 0, 0, 0, 0, 1.])

3. “affine”

   ``x0 = np.array([0, 0, 0, 0, 0, 0, 1., 1., 1, 0, 0, 0])

(default None)

slr_boundsarray

(default None)

slr_selecttuple

Select the number of streamlines from model to neirborhood of model to perform the local SLR.

slr_methodstring

Optimization method ‘L_BFGS_B’ or ‘Powell’ optimizers can be used. (default ‘L-BFGS-B’)

pruning_thrfloat

Pruning after reducing the search space (default 6).

pruning_distancestring

Pruning distance type can be mdf or mam (default mdf)

Returns

recognized_transfStreamlines

Recognized bundle in the space of the model tractogram

recognized_labelsarray

Indices of recognized bundle in the original tractogram

References

[Garyfallidis17]

Garyfallidis et al. Recognition of white matter bundles using local and global streamline-based registration and clustering, Neuroimage, 2017.

[Chandio2020]

Chandio, B.Q., Risacher, S.L., Pestilli, F.,

Bullock, D., Yeh, FC., Koudoro, S., Rokem, A., Harezlak, J., and Garyfallidis, E. Bundle analytics, a computational framework for investigating the shapes and profiles of brain pathways across populations. Sci Rep 10, 17149 (2020)

check_range

dipy.segment.bundles.check_range(streamline, gt, lt)

logger

dipy.segment.bundles.logger()

Instances of the Logger class represent a single logging channel. A “logging channel” indicates an area of an application. Exactly how an “area” is defined is up to the application developer. Since an application can have any number of areas, logging channels are identified by a unique string. Application areas can be nested (e.g. an area of “input processing” might include sub-areas “read CSV files”, “read XLS files” and “read Gnumeric files”). To cater for this natural nesting, channel names are organized into a namespace hierarchy where levels are separated by periods, much like the Java or Python package namespace. So in the instance given above, channel names might be “input” for the upper level, and “input.csv”, “input.xls” and “input.gnu” for the sub-levels. There is no arbitrary limit to the depth of nesting.

bundle_adjacency

dipy.segment.bundles.bundle_adjacency(dtracks0, dtracks1, threshold)

Find bundle adjacency between two given tracks/bundles

Parameters

dtracks0Streamlines

White matter tract from one subject

dtracks1Streamlines

White matter tract from another subject

thresholdfloat

Threshold controls how much strictness user wants while calculating bundle adjacency between two bundles. Smaller threshold means bundles should be strictly adjacent to get higher BA score.

Returns

resFloat

Bundle adjacency score between two tracts

References

[Garyfallidis12]

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

ba_analysis

dipy.segment.bundles.ba_analysis(recognized_bundle, expert_bundle, nb_pts=20, threshold=6.0)

Calculates bundle adjacency score between two given bundles

Parameters

recognized_bundleStreamlines

Extracted bundle from the whole brain tractogram (eg: AF_L)

expert_bundleStreamlines

Model bundle used as reference while extracting similar type bundle from input tractogram

nb_ptsinteger (default 20)

Discretizing streamlines to have nb_pts number of points

thresholdfloat (default 6)

Threshold used for in computing bundle adjacency. Threshold controls how much strictness user wants while calculating bundle adjacency between two bundles. Smaller threshold means bundles should be strictly adjacent to get higher BA score.

Returns

Bundle adjacency score between two tracts

References

[Garyfallidis12]

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

cluster_bundle

dipy.segment.bundles.cluster_bundle(bundle, clust_thr, rng, nb_pts=20, select_randomly=500000)

Clusters bundles

Parameters

bundleStreamlines

White matter tract

clust_thrfloat

clustering threshold used in quickbundlesX

rngnp.random.Generator

numpy’s random generator for generating random values.

nb_pts: integer (default 20)

Discretizing streamlines to have nb_points number of points

select_randomly: integer (default 500000)

Randomly select streamlines from the input bundle

Returns

centroidsStreamlines

clustered centroids of the input bundle

References

[Garyfallidis12]

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

bundle_shape_similarity

dipy.segment.bundles.bundle_shape_similarity(bundle1, bundle2, rng, clust_thr=(5, 3, 1.5), threshold=6)

Calculates bundle shape similarity between two given bundles using bundle adjacency (BA) metric

Parameters

bundle1Streamlines

White matter tract from one subject (eg: AF_L)

bundle2Streamlines

White matter tract from another subject (eg: AF_L)

rng : np.random.Generator clust_thr : array-like, optional

list of clustering thresholds used in quickbundlesX

thresholdfloat, optional

Threshold used for in computing bundle adjacency. Threshold controls how much strictness user wants while calculating shape similarity between two bundles. Smaller threshold means bundles should be strictly similar to get higher shape similarity score.

Returns

ba_valueFloat

Bundle similarity score between two tracts

References

[Chandio2020]

Chandio, B.Q., Risacher, S.L., Pestilli, F., Bullock, D.,

Yeh, FC., Koudoro, S., Rokem, A., Harezlak, J., and Garyfallidis, E. Bundle analytics, a computational framework for investigating the shapes and profiles of brain pathways across populations. Sci Rep 10, 17149 (2020)

[Garyfallidis12]

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

Identity

class dipy.segment.clustering.Identity

Bases: object

Provides identity indexing functionality.

This can replace any class supporting indexing used for referencing (e.g. list, tuple). Indexing an instance of this class will return the index provided instead of the element. It does not support slicing.

__init__()

Cluster

class dipy.segment.clustering.Cluster(id=0, indices=None, refdata=<dipy.segment.clustering.Identity object>)

Bases: object

Provides functionalities for interacting with a cluster.

Useful container to retrieve index of elements grouped together. If a reference to the data is provided to cluster_map, elements will be returned instead of their index when possible.

Parameters

cluster_mapClusterMap object

Reference to the set of clusters this cluster is being part of.

idint

Id of this cluster in its associated cluster_map object.

refdatalist (optional)

Actual elements that clustered indices refer to.

Notes

A cluster does not contain actual data but instead knows how to retrieve them using its ClusterMap object.

__init__(id=0, indices=None, refdata=<dipy.segment.clustering.Identity object>)

assign(*indices)

Assigns indices to this cluster.

Parameters

*indiceslist of indices

Indices to add to this cluster.

ClusterCentroid

class dipy.segment.clustering.ClusterCentroid(centroid, id=0, indices=None, refdata=<dipy.segment.clustering.Identity object>)

Bases: Cluster

Provides functionalities for interacting with a cluster.

Useful container to retrieve the indices of elements grouped together and the cluster’s centroid. If a reference to the data is provided to cluster_map, elements will be returned instead of their index when possible.

Parameters

cluster_mapClusterMapCentroid object

Reference to the set of clusters this cluster is being part of.

idint

Id of this cluster in its associated cluster_map object.

refdatalist (optional)

Actual elements that clustered indices refer to.

Notes

A cluster does not contain actual data but instead knows how to retrieve them using its ClusterMapCentroid object.

__init__(centroid, id=0, indices=None, refdata=<dipy.segment.clustering.Identity object>)

assign(id_datum, features)

Assigns a data point to this cluster.

Parameters

id_datumint

Index of the data point to add to this cluster.

features2D array

Data point’s features to modify this cluster’s centroid.

update()

Update centroid of this cluster.

Returns

convergedbool

Tells if the centroid has moved.

ClusterMap

class dipy.segment.clustering.ClusterMap(refdata=<dipy.segment.clustering.Identity object>)

Bases: object

Provides functionalities for interacting with clustering outputs.

Useful container to create, remove, retrieve and filter clusters. If refdata is given, elements will be returned instead of their index when using Cluster objects.

Parameters

refdatalist

Actual elements that clustered indices refer to.

__init__(refdata=<dipy.segment.clustering.Identity object>)

add_cluster(*clusters)

Adds one or multiple clusters to this cluster map.

Parameters

*clustersCluster object, …

Cluster(s) to be added in this cluster map.

clear()

Remove all clusters from this cluster map.

property clusters

clusters_sizes()

Gets the size of every cluster contained in this cluster map.

Returns

list of int

Sizes of every cluster in this cluster map.

get_large_clusters(min_size)

Gets clusters which contains at least min_size elements.

Parameters

min_sizeint

Minimum number of elements a cluster needs to have to be selected.

Returns

list of Cluster objects

Clusters having at least min_size elements.

get_small_clusters(max_size)

Gets clusters which contains at most max_size elements.

Parameters

max_sizeint

Maximum number of elements a cluster can have to be selected.

Returns

list of Cluster objects

Clusters having at most max_size elements.

property refdata

remove_cluster(*clusters)

Remove one or multiple clusters from this cluster map.

Parameters

*clustersCluster object, …

Cluster(s) to be removed from this cluster map.

size()

Gets number of clusters contained in this cluster map.

ClusterMapCentroid

class dipy.segment.clustering.ClusterMapCentroid(refdata=<dipy.segment.clustering.Identity object>)

Bases: ClusterMap

Provides functionalities for interacting with clustering outputs that have centroids.

Allows to retrieve easily the centroid of every cluster. Also, it is a useful container to create, remove, retrieve and filter clusters. If refdata is given, elements will be returned instead of their index when using ClusterCentroid objects.

Parameters

refdatalist

Actual elements that clustered indices refer to.

__init__(refdata=<dipy.segment.clustering.Identity object>)

property centroids

Clustering

class dipy.segment.clustering.Clustering

Bases: object

__init__()

abstract cluster(data, ordering=None)

Clusters data.

Subclasses will perform their clustering algorithm here.

Parameters

datalist of N-dimensional arrays

Each array represents a data point.

orderingiterable of indices, optional

Specifies the order in which data points will be clustered.

Returns

ClusterMap object

Result of the clustering.

QuickBundles

class dipy.segment.clustering.QuickBundles(threshold, metric='MDF_12points', max_nb_clusters=2147483647)

Bases: Clustering

Clusters streamlines using QuickBundles [Garyfallidis12]. Given a list of streamlines, the QuickBundles algorithm sequentially assigns each streamline to its closest bundle in \(\mathcal{O}(Nk)\) where \(N\) is the number of streamlines and \(k\) is the final number of bundles. If for a given streamline its closest bundle is farther than threshold, a new bundle is created and the streamline is assigned to it except if the number of bundles has already exceeded max_nb_clusters. Parameters ———- threshold : float The maximum distance from a bundle for a streamline to be still considered as part of it. metric : str or Metric object (optional) The distance metric to use when comparing two streamlines. By default, the Minimum average Direct-Flip (MDF) distance [Garyfallidis12] is used and streamlines are automatically resampled so they have 12 points. max_nb_clusters : int Limits the creation of bundles. Examples ——– >>> from dipy.segment.clustering import QuickBundles >>> from dipy.data import get_fnames >>> from dipy.io.streamline import load_tractogram >>> from dipy.tracking.streamline import Streamlines >>> fname = get_fnames(‘fornix’) >>> fornix = load_tractogram(fname, ‘same’, … bbox_valid_check=False).streamlines >>> streamlines = Streamlines(fornix) >>> # Segment fornix with a threshold of 10mm and streamlines resampled >>> # to 12 points. >>> qb = QuickBundles(threshold=10.) >>> clusters = qb.cluster(streamlines) >>> len(clusters) 4 >>> list(map(len, clusters)) [61, 191, 47, 1] >>> # Resampling streamlines differently is done explicitly as follows. >>> # Note this has an impact on the speed and the accuracy (tradeoff). >>> from dipy.segment.featurespeed import ResampleFeature >>> from dipy.segment.metricspeed import AveragePointwiseEuclideanMetric >>> feature = ResampleFeature(nb_points=2) >>> metric = AveragePointwiseEuclideanMetric(feature) >>> qb = QuickBundles(threshold=10., metric=metric) >>> clusters = qb.cluster(streamlines) >>> len(clusters) 4 >>> list(map(len, clusters)) [58, 142, 72, 28] References ———- .. [Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for tractography simplification, Frontiers in Neuroscience, vol 6, no 175, 2012.

__init__(threshold, metric='MDF_12points', max_nb_clusters=2147483647)

cluster(streamlines, ordering=None)

Clusters streamlines into bundles.

Performs quickbundles algorithm using predefined metric and threshold.

Parameters

streamlineslist of 2D arrays

Each 2D array represents a sequence of 3D points (points, 3).

orderingiterable of indices

Specifies the order in which data points will be clustered.

Returns

ClusterMapCentroid object

Result of the clustering.

QuickBundlesX

class dipy.segment.clustering.QuickBundlesX(thresholds, metric='MDF_12points')

Bases: Clustering

Clusters streamlines using QuickBundlesX.

Parameters

thresholdslist of float

Thresholds to use for each clustering layer. A threshold represents the maximum distance from a cluster for a streamline to be still considered as part of it.

metricstr or Metric object (optional)

The distance metric to use when comparing two streamlines. By default, the Minimum average Direct-Flip (MDF) distance [Garyfallidis12] is used and streamlines are automatically resampled so they have 12 points.

References

[Garyfallidis12]

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

[Garyfallidis16]

Garyfallidis E. et al. QuickBundlesX: Sequential clustering of millions of streamlines in multiple levels of detail at record execution time. Proceedings of the, International Society of Magnetic Resonance in Medicine (ISMRM). Singapore, 4187, 2016.

__init__(thresholds, metric='MDF_12points')

cluster(streamlines, ordering=None)

Clusters streamlines into bundles.

Performs QuickbundleX using a predefined metric and thresholds.

Parameters

streamlineslist of 2D arrays

Each 2D array represents a sequence of 3D points (points, 3).

orderingiterable of indices

Specifies the order in which data points will be clustered.

Returns

TreeClusterMap object

Result of the clustering.

TreeCluster

class dipy.segment.clustering.TreeCluster(threshold, centroid, indices=None)

Bases: ClusterCentroid

__init__(threshold, centroid, indices=None)

add(child)

property is_leaf

return_indices()

TreeClusterMap

class dipy.segment.clustering.TreeClusterMap(root)

Bases: ClusterMap

__init__(root)

get_clusters(wanted_level)

iter_preorder(node)

property refdata

traverse_postorder(node, visit)

logger

dipy.segment.clustering.logger()

Instances of the Logger class represent a single logging channel. A “logging channel” indicates an area of an application. Exactly how an “area” is defined is up to the application developer. Since an application can have any number of areas, logging channels are identified by a unique string. Application areas can be nested (e.g. an area of “input processing” might include sub-areas “read CSV files”, “read XLS files” and “read Gnumeric files”). To cater for this natural nesting, channel names are organized into a namespace hierarchy where levels are separated by periods, much like the Java or Python package namespace. So in the instance given above, channel names might be “input” for the upper level, and “input.csv”, “input.xls” and “input.gnu” for the sub-levels. There is no arbitrary limit to the depth of nesting.

qbx_and_merge

dipy.segment.clustering.qbx_and_merge(streamlines, thresholds, nb_pts=20, select_randomly=None, rng=None, verbose=False)

Run QuickBundlesX and then run again on the centroids of the last layer

Running again QuickBundles at a layer has the effect of merging some of the clusters that may be originally divided because of branching. This function help obtain a result at a QuickBundles quality but with QuickBundlesX speed. The merging phase has low cost because it is applied only on the centroids rather than the entire dataset.

Parameters

streamlines : Streamlines thresholds : sequence

List of distance thresholds for QuickBundlesX.

nb_ptsint

Number of points for discretizing each streamline

select_randomlyint

Randomly select a specific number of streamlines. If None all the streamlines are used.

rngnumpy.random.Generator

If None then generator is initialized internally.

verbosebool, optional.

If True, log information. Default False.

Returns

clustersobj

Contains the clusters of the last layer of QuickBundlesX after merging.

References

[Garyfallidis12]

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

[Garyfallidis16]

Garyfallidis E. et al. QuickBundlesX: Sequential clustering of millions of streamlines in multiple levels of detail at record execution time. Proceedings of the, International Society of Magnetic Resonance in Medicine (ISMRM). Singapore, 4187, 2016.

ClusterCentroid

class dipy.segment.clustering_algorithms.ClusterCentroid(centroid, id=0, indices=None, refdata=<dipy.segment.clustering.Identity object>)

Bases: Cluster

Provides functionalities for interacting with a cluster.

Useful container to retrieve the indices of elements grouped together and the cluster’s centroid. If a reference to the data is provided to cluster_map, elements will be returned instead of their index when possible.

Parameters

cluster_mapClusterMapCentroid object

Reference to the set of clusters this cluster is being part of.

idint

Id of this cluster in its associated cluster_map object.

refdatalist (optional)

Actual elements that clustered indices refer to.

Notes

A cluster does not contain actual data but instead knows how to retrieve them using its ClusterMapCentroid object.

__init__(centroid, id=0, indices=None, refdata=<dipy.segment.clustering.Identity object>)

assign(id_datum, features)

Assigns a data point to this cluster.

Parameters

id_datumint

Index of the data point to add to this cluster.

features2D array

Data point’s features to modify this cluster’s centroid.

update()

Update centroid of this cluster.

Returns

convergedbool

Tells if the centroid has moved.

ClusterMapCentroid

class dipy.segment.clustering_algorithms.ClusterMapCentroid(refdata=<dipy.segment.clustering.Identity object>)

Bases: ClusterMap

Provides functionalities for interacting with clustering outputs that have centroids.

Allows to retrieve easily the centroid of every cluster. Also, it is a useful container to create, remove, retrieve and filter clusters. If refdata is given, elements will be returned instead of their index when using ClusterCentroid objects.

Parameters

refdatalist

Actual elements that clustered indices refer to.

__init__(refdata=<dipy.segment.clustering.Identity object>)

property centroids

DTYPE

dipy.segment.clustering_algorithms.DTYPE

alias of float32

clusters_centroid2clustermap_centroid

dipy.segment.clustering_algorithms.clusters_centroid2clustermap_centroid(clusters_list)

Converts a ClustersCentroid object (Cython) to a ClusterMapCentroid object (Python).

Only basic functionalities are provided with a Clusters object. To have more flexibility, one should use ClusterMap object, hence this conversion function.

Parameters

clusters_listClustersCentroid object

Result of the clustering contained in a Cython’s object.

Returns

ClusterMapCentroid object

Result of the clustering contained in a Python’s object.

peek

dipy.segment.clustering_algorithms.peek(iterable)

Returns the first element of an iterable and the iterator.

quickbundles

dipy.segment.clustering_algorithms.quickbundles(streamlines, metric, threshold, max_nb_clusters=2147483647, ordering=None)

Clusters streamlines using QuickBundles.

Parameters

streamlineslist of 2D arrays

List of streamlines to cluster.

metricMetric object

Tells how to compute the distance between two streamlines.

thresholddouble

The maximum distance from a cluster for a streamline to be still considered as part of it.

max_nb_clustersint, optional

Limits the creation of bundles. (Default: inf)

orderingiterable of indices, optional

Iterate through data using the given ordering.

Returns

ClusterMapCentroid object

Result of the clustering.

References

[Garyfallidis12]

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

quickbundlesx

dipy.segment.clustering_algorithms.quickbundlesx(streamlines, metric, thresholds, ordering=None)

Clusters streamlines using QuickBundlesX.

Parameters

streamlineslist of 2D arrays

List of streamlines to cluster.

metricMetric object

Tells how to compute the distance between two streamlines.

thresholdslist of double

Thresholds to use for each clustering layer. A threshold represents the maximum distance from a cluster for a streamline to be still considered as part of it.

orderingiterable of indices, optional

Iterate through data using the given ordering.

Returns

TreeClusterMap object

Result of the clustering. Use get_clusters() to get the clusters at a specific level of the hierarchy.

References

[Garyfallidis16]

Garyfallidis E. et al. QuickBundlesX: Sequential

clustering of millions of streamlines in multiple levels of detail at record execution time. Proceedings of the, International Society of Magnetic Resonance in Medicine (ISMRM). Singapore, 4187, 2016.

[Garyfallidis12]

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

ClusterCentroid

class dipy.segment.clusteringspeed.ClusterCentroid(centroid, id=0, indices=None, refdata=<dipy.segment.clustering.Identity object>)

Bases: Cluster

Provides functionalities for interacting with a cluster.

Useful container to retrieve the indices of elements grouped together and the cluster’s centroid. If a reference to the data is provided to cluster_map, elements will be returned instead of their index when possible.

Parameters

cluster_mapClusterMapCentroid object

Reference to the set of clusters this cluster is being part of.

idint

Id of this cluster in its associated cluster_map object.

refdatalist (optional)

Actual elements that clustered indices refer to.

Notes

A cluster does not contain actual data but instead knows how to retrieve them using its ClusterMapCentroid object.

__init__(centroid, id=0, indices=None, refdata=<dipy.segment.clustering.Identity object>)

assign(id_datum, features)

Assigns a data point to this cluster.

Parameters

id_datumint

Index of the data point to add to this cluster.

features2D array

Data point’s features to modify this cluster’s centroid.

update()

Update centroid of this cluster.

Returns

convergedbool

Tells if the centroid has moved.

ClusterMapCentroid

class dipy.segment.clusteringspeed.ClusterMapCentroid(refdata=<dipy.segment.clustering.Identity object>)

Bases: ClusterMap

Provides functionalities for interacting with clustering outputs that have centroids.

Allows to retrieve easily the centroid of every cluster. Also, it is a useful container to create, remove, retrieve and filter clusters. If refdata is given, elements will be returned instead of their index when using ClusterCentroid objects.

Parameters

refdatalist

Actual elements that clustered indices refer to.

__init__(refdata=<dipy.segment.clustering.Identity object>)

property centroids

Clusters

class dipy.segment.clusteringspeed.Clusters

Bases: object

Provides Cython functionalities to interact with clustering outputs.

This class allows one to create clusters and assign elements to them. Assignments of a cluster are represented as a list of element indices.

__init__(*args, **kwargs)

ClustersCentroid

class dipy.segment.clusteringspeed.ClustersCentroid

Bases: Clusters

Provides Cython functionalities to interact with clustering outputs having the notion of cluster’s centroid.

This class allows one to create clusters, assign elements to them and update their centroid.

Parameters

centroid_shapeint, tuple of int

Information about the shape of the centroid.

epsfloat, optional

Consider the centroid has not changed if the changes per dimension are less than this epsilon. (Default: 1e-6)

__init__(*args, **kwargs)

DTYPE

dipy.segment.clusteringspeed.DTYPE

alias of float32

QuickBundles

class dipy.segment.clusteringspeed.QuickBundles

Bases: object

__init__(*args, **kwargs)

get_cluster_map()

get_stats()

QuickBundlesX

class dipy.segment.clusteringspeed.QuickBundlesX

Bases: object

__init__(*args, **kwargs)

get_stats()

get_tree_cluster_map()

insert(datum, datum_idx)

TreeCluster

class dipy.segment.clusteringspeed.TreeCluster(threshold, centroid, indices=None)

Bases: ClusterCentroid

__init__(threshold, centroid, indices=None)

add(child)

property is_leaf

return_indices()

TreeClusterMap

class dipy.segment.clusteringspeed.TreeClusterMap(root)

Bases: ClusterMap

__init__(root)

get_clusters(wanted_level)

iter_preorder(node)

property refdata

traverse_postorder(node, visit)

evaluate_aabb_checks

dipy.segment.clusteringspeed.evaluate_aabb_checks()

ArcLengthFeature

class dipy.segment.featurespeed.ArcLengthFeature

Bases: CythonFeature

Extracts features from a sequential datum.

A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions).

The feature being extracted consists of one scalar representing the arc length of the sequence (i.e. the sum of the length of all segments).

__init__(*args, **kwargs)

CenterOfMassFeature

class dipy.segment.featurespeed.CenterOfMassFeature

Bases: CythonFeature

Extracts features from a sequential datum.

A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions).

The feature being extracted consists of one N-dimensional point representing the mean of the points, i.e. the center of mass.

__init__(*args, **kwargs)

CythonFeature

class dipy.segment.featurespeed.CythonFeature

Bases: Feature

Extracts features from a sequential datum.

A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions).

Parameters

is_order_invariantbool, optional

Tells if this feature is invariant to the sequence’s ordering (Default: True).

Notes

By default, when inheriting from CythonFeature, Python methods will call their C version (e.g. CythonFeature.extract -> self.c_extract).

__init__(*args, **kwargs)

extract(datum)

Extracts features from a sequential datum.

Parameters

datum2D array

Sequence of N-dimensional points.

Returns

2D array

Features extracted from datum.

Notes

This method calls its Cython version self.c_extract accordingly.

infer_shape(datum)

Infers the shape of features extracted from a sequential datum.

Parameters

datum2D array

Sequence of N-dimensional points.

Returns

tuple

Shape of the features.

Notes

This method calls its Cython version self.c_infer_shape accordingly.

Feature

class dipy.segment.featurespeed.Feature

Bases: object

Extracts features from a sequential datum.

A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions).

Parameters

is_order_invariantbool (optional)

tells if this feature is invariant to the sequence’s ordering. This means starting from either extremities produces the same features. (Default: True)

Notes

When subclassing Feature, one only needs to override the extract and infer_shape methods.

__init__(*args, **kwargs)

extract(datum)

Extracts features from a sequential datum.

Parameters

datum2D array

Sequence of N-dimensional points.

Returns

2D array

Features extracted from datum.

infer_shape(datum)

Infers the shape of features extracted from a sequential datum.

Parameters

datum2D array

Sequence of N-dimensional points.

Returns

int, 1-tuple or 2-tuple

Shape of the features.

is_order_invariant

Is this feature invariant to the sequence’s ordering

IdentityFeature

class dipy.segment.featurespeed.IdentityFeature

Bases: CythonFeature

Extracts features from a sequential datum.

A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions).

The features being extracted are the actual sequence’s points. This is useful for metric that does not require any pre-processing.

__init__(*args, **kwargs)

MidpointFeature

class dipy.segment.featurespeed.MidpointFeature

Bases: CythonFeature

Extracts features from a sequential datum.

A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions).

The feature being extracted consists of one N-dimensional point representing the middle point of the sequence (i.e. `nb_points//2`th point).

__init__(*args, **kwargs)

ResampleFeature

class dipy.segment.featurespeed.ResampleFeature

Bases: CythonFeature

Extracts features from a sequential datum.

A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions).

The features being extracted are the points of the sequence once resampled. This is useful for metrics requiring a constant number of points for all

streamlines.

__init__(*args, **kwargs)

VectorOfEndpointsFeature

class dipy.segment.featurespeed.VectorOfEndpointsFeature

Bases: CythonFeature

Extracts features from a sequential datum.

A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions).

The feature being extracted consists of one vector in the N-dimensional space pointing from one end-point of the sequence to the other (i.e. S[-1]-S[0]).

__init__(*args, **kwargs)

extract

dipy.segment.featurespeed.extract(feature, data)

Extracts features from data.

Parameters

featureFeature object

Tells how to extract features from the data.

datumlist of 2D arrays

List of sequence of N-dimensional points.

Returns

list of 2D arrays

List of features extracted from data.

infer_shape

dipy.segment.featurespeed.infer_shape(feature, data)

Infers shape of the features extracted from data.

Parameters

featureFeature object

Tells how to infer shape of the features.

datalist of 2D arrays

List of sequences of N-dimensional points.

Returns

list of tuples

Shapes of the features inferred from data.

FastStreamlineSearch

class dipy.segment.fss.FastStreamlineSearch(ref_streamlines, max_radius, nb_mpts=4, bin_size=20.0, resampling=24, bidirectional=True)

Bases: object

__init__(ref_streamlines, max_radius, nb_mpts=4, bin_size=20.0, resampling=24, bidirectional=True)

Fast Streamline Search (FFS)

Generate the Binned K-D Tree structure with reference streamlines, using streamlines barycenter and mean-points. See [StOnge2022] for further details.

Parameters

ref_streamlinesStreamlines

Streamlines (ref) to generate the tree structure.

max_radiusfloat

The maximum radius (distance) for subsequent streamline search. Used to compute the overlap in-between bins.

nb_mptsint, optional

Number of means points to improve computation speed. (this only changes computation time)

bin_sizefloat, optional

The bin size to separate streamlines in groups. (this only changes computation time)

resamplingint, optional

Number of points used to reshape each streamline.

bidirectionalbool, optional

Compute the smallest distance with and without flip.

Notes

Make sure that streamlines are aligned in the same space. Preferably in millimeter space (voxmm or rasmm).

References

[StOnge2022]

St-Onge E. et al. Fast Streamline Search: An Exact Technique for Diffusion MRI Tractography. Neuroinformatics, 2022.

radius_search(streamlines, radius, use_negative=True)

Radius Search using Fast Streamline Search

For each given streamlines, return all reference streamlines within the given radius. See [StOnge2022] for further details.

Parameters

streamlinesStreamlines

Streamlines to generate the tree structure.

radiusfloat

Search radius (with MDF / average L2 distance) must be smaller than max_radius when FFS was initialized.

use_negativebool, optional

When used with bidirectional, negative values are returned for reversed order neighbors.

Returns

resscipy COOrdinates sparse matrix (nb_slines x nb_slines_ref)

Adjacency matrix containing all neighbors within the given radius

Notes

Given streamlines should be already aligned with ref streamlines. Preferably in millimeter space (voxmm or rasmm).

References

[StOnge2022]

St-Onge E. et al. Fast Streamline Search: An Exact Technique for Diffusion MRI Tractography. Neuroinformatics, 2022.

nearest_from_matrix_row

dipy.segment.fss.nearest_from_matrix_row(coo_matrix)

Return the nearest (smallest) for each row given an coup sparse matrix

Parameters

coo_matrixscipy COOrdinates sparse matrix (nb_slines x nb_slines_ref)

Adjacency matrix containing all neighbors within the given radius

Returns

non_zero_idsnumpy array (nb_non_empty_row x 1)

Indices of each non-empty slines (row)

nearest_idnumpy array (nb_non_empty_row x 1)

Indices of the nearest reference match (column)

nearest_distnumpy array (nb_non_empty_row x 1)

Distance for each nearest match

nearest_from_matrix_col

dipy.segment.fss.nearest_from_matrix_col(coo_matrix)

Return the nearest (smallest) for each column given an coup sparse matrix

Parameters

coo_matrixscipy COOrdinates sparse matrix (nb_slines x nb_slines_ref)

Adjacency matrix containing all neighbors within the given radius

Returns

non_zero_idsnumpy array (nb_non_empty_col x 1)

Indices of each non-empty reference (column)

nearest_idnumpy array (nb_non_empty_col x 1)

Indices of the nearest slines match (row)

nearest_distnumpy array (nb_non_empty_col x 1)

Distance for each nearest match

multi_median

dipy.segment.mask.multi_median(data, median_radius, numpass)

Applies median filter multiple times on input data.

Parameters

datandarray

The input volume to apply filter on.

median_radiusint

Radius (in voxels) of the applied median filter

numpass: int

Number of pass of the median filter

Returns

datandarray

Filtered input volume.

applymask

dipy.segment.mask.applymask(vol, mask)

Mask vol with mask. Parameters ———- vol : ndarray Array with \(V\) dimensions mask : ndarray Binary mask. Has \(M\) dimensions where \(M <= V\). When \(M < V\), we append \(V - M\) dimensions with axis length 1 to mask so that mask will broadcast against vol. In the typical case vol can be 4D, mask can be 3D, and we append a 1 to the mask shape which (via numpy broadcasting) has the effect of applying the 3D mask to each 3D slice in vol (vol[..., 0] to vol[..., -1). Returns ——- masked_vol : ndarray vol multiplied by mask where mask may have been extended to match extra dimensions in vol

bounding_box

dipy.segment.mask.bounding_box(vol)

Compute the bounding box of nonzero intensity voxels in the volume.

Parameters

volndarray

Volume to compute bounding box on.

Returns

npminslist

Array containing minimum index of each dimension

npmaxslist

Array containing maximum index of each dimension

crop

dipy.segment.mask.crop(vol, mins, maxs)

Crops the input volume.

Parameters

volndarray

Volume to crop.

minsarray

Array containing minimum index of each dimension.

maxsarray

Array containing maximum index of each dimension.

Returns

volndarray

The cropped volume.

median_otsu

dipy.segment.mask.median_otsu(input_volume, vol_idx=None, median_radius=4, numpass=4, autocrop=False, dilate=None)

Simple brain extraction tool method for images from DWI data.

It uses a median filter smoothing of the input_volumes vol_idx and an automatic histogram Otsu thresholding technique, hence the name median_otsu.

This function is inspired from Mrtrix’s bet which has default values median_radius=3, numpass=2. However, from tests on multiple 1.5T and 3T data from GE, Philips, Siemens, the most robust choice is median_radius=4, numpass=4.

Parameters

input_volumendarray

3D or 4D array of the brain volume.

vol_idxNone or array, optional.

1D array representing indices of axis=3 of a 4D input_volume. None is only an acceptable input if input_volume is 3D.

median_radiusint

Radius (in voxels) of the applied median filter (default: 4).

numpass: int

Number of pass of the median filter (default: 4).

autocrop: bool, optional

if True, the masked input_volume will also be cropped using the bounding box defined by the masked data. Should be on if DWI is upsampled to 1x1x1 resolution. (default: False).

dilateNone or int, optional

number of iterations for binary dilation

Returns

maskedvolumendarray

Masked input_volume

mask3D ndarray

The binary brain mask

Notes

Copyright (C) 2011, the scikit-image team All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of skimage nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS’’ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

segment_from_cfa

dipy.segment.mask.segment_from_cfa(tensor_fit, roi, threshold, return_cfa=False)

Segment the cfa inside roi using the values from threshold as bounds.

Parameters

tensor_fitTensorFit object

TensorFit object

roindarray

A binary mask, which contains the bounding box for the segmentation.

thresholdarray-like

An iterable that defines the min and max values to use for the thresholding. The values are specified as (R_min, R_max, G_min, G_max, B_min, B_max)

return_cfabool, optional

If True, the cfa is also returned.

Returns

maskndarray

Binary mask of the segmentation.

cfandarray, optional

Array with shape = (…, 3), where … is the shape of tensor_fit. The color fractional anisotropy, ordered as a nd array with the last dimension of size 3 for the R, G and B channels.

clean_cc_mask

dipy.segment.mask.clean_cc_mask(mask)

Cleans a segmentation of the corpus callosum so no random pixels are included.

Parameters

maskndarray

Binary mask of the coarse segmentation.

Returns

new_cc_maskndarray

Binary mask of the cleaned segmentation.

mdf

dipy.segment.metric.mdf(s1, s2)

Computes the MDF (Minimum average Direct-Flip) distance [Garyfallidis12] between two streamlines.

Streamlines must have the same number of points.

Parameters

s12D array

A streamline (sequence of N-dimensional points).

s22D array

A streamline (sequence of N-dimensional points).

Returns

double

Distance between two streamlines.

References

[Garyfallidis12]

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

mean_manhattan_distance

dipy.segment.metric.mean_manhattan_distance(a, b)

Compute the average Manhattan-L1 distance (MDF without flip)

Arrays are representing a single streamline or a list of streamlines that have the same number of N-dimensional points (two last axis).

Parameters

a2D or 3D array

A streamline or concatenated streamlines (array of S streamlines by P points in N dimension).

b2D or 3D array

A streamline or concatenated streamlines (array of S streamlines by P points in N dimension).

Returns

1D array

Distance between each S streamlines

mean_euclidean_distance

dipy.segment.metric.mean_euclidean_distance(a, b)

Compute the average Euclidean-L2 distance (MDF without flip)

Arrays are representing a single streamline or a list of streamlines that have the same number of N-dimensional points (two last axis).

Parameters

a2D or 3D array

A streamline or concatenated streamlines (array of S streamlines by P points in N dimension).

b2D or 3D array

A streamline or concatenated streamlines (array of S streamlines by P points in N dimension).

Returns

1D array

Distance between each S streamlines

AveragePointwiseEuclideanMetric

class dipy.segment.metricspeed.AveragePointwiseEuclideanMetric

Bases: SumPointwiseEuclideanMetric

Computes the average of pointwise Euclidean distances between two sequential data. A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions). A feature object can be specified in order to calculate the distance between the features, rather than directly between the sequential data. Parameters ———- feature : Feature object, optional It is used to extract features before computing the distance. Notes —– The distance between two 2D sequential data:: s1 s2 0* a 0 | | 1 | | b 1 | 2 c *2 is equal to \((a+b+c)/3\) where \(a\) is the Euclidean distance between s1[0] and s2[0], \(b\) between s1[1] and s2[1] and \(c\) between s1[2] and s2[2].

__init__(*args, **kwargs)

CosineMetric

class dipy.segment.metricspeed.CosineMetric

Bases: CythonMetric

Computes the cosine distance between two vectors. A vector (i.e. a N-dimensional point) is represented as a 2D array with shape (1, nb_dimensions). Notes —– The distance between two vectors \(v_1\) and \(v_2\) is equal to \(\frac{1}{\pi} \arccos\left(\frac{v_1 \cdot v_2}{\|v_1\| \|v_2\|}\right)\) and is bounded within \([0,1]\).

__init__(*args, **kwargs)

CythonMetric

class dipy.segment.metricspeed.CythonMetric

Bases: Metric

Computes a distance between two sequential data.

A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions). A feature object can be specified in order to calculate the distance between extracted features, rather than directly between the sequential data.

Parameters

featureFeature object, optional

It is used to extract features before computing the distance.

Notes

When subclassing CythonMetric, one only needs to override the c_dist and c_are_compatible methods.

__init__(*args, **kwargs)

are_compatible(shape1, shape2)

Checks if features can be used by metric.dist based on their shape.

Basically this method exists so we don’t have to do this check inside method dist (speedup).

Parameters

shape1int, 1-tuple or 2-tuple

Shape of the first data point’s features.

shape2int, 1-tuple or 2-tuple

Shape of the second data point’s features.

Returns

bool

Whether or not shapes are compatible.

Notes

This method calls its Cython version self.c_are_compatible accordingly.

dist(features1, features2)

Computes a distance between two data points based on their features.

Parameters

features12D array

Features of the first data point.

features22D array

Features of the second data point.

Returns

double

Distance between two data points.

Notes

This method calls its Cython version self.c_dist accordingly.

Metric

class dipy.segment.metricspeed.Metric

Bases: object

Computes a distance between two sequential data.

A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions). A feature object can be specified in order to calculate the distance between extracted features, rather than directly between the sequential data.

Parameters

featureFeature object, optional

It is used to extract features before computing the distance.

Notes

When subclassing Metric, one only needs to override the dist and are_compatible methods.

__init__(*args, **kwargs)

are_compatible(shape1, shape2)

Checks if features can be used by metric.dist based on their shape.

Basically this method exists so we don’t have to do this check inside the metric.dist function (speedup).

Parameters

shape1int, 1-tuple or 2-tuple

shape of the first data point’s features

shape2int, 1-tuple or 2-tuple

shape of the second data point’s features

Returns

are_compatiblebool

whether or not shapes are compatible

dist(features1, features2)

Computes a distance between two data points based on their features.

Parameters

features12D array

Features of the first data point.

features22D array

Features of the second data point.

Returns

double

Distance between two data points.

feature

Feature object used to extract features from sequential data

is_order_invariant

Is this metric invariant to the sequence’s ordering

MinimumAverageDirectFlipMetric

class dipy.segment.metricspeed.MinimumAverageDirectFlipMetric

Bases: AveragePointwiseEuclideanMetric

Computes the MDF distance (minimum average direct-flip) between two sequential data. A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions). Notes —– The distance between two 2D sequential data:: s1 s2 0* a 0 | | 1 | | b 1 | 2 c *2 is equal to \(\min((a+b+c)/3, (a'+b'+c')/3)\) where \(a\) is the Euclidean distance between s1[0] and s2[0], \(b\) between s1[1] and s2[1], \(c\) between s1[2] and s2[2], \(a'\) between s1[0] and s2[2], \(b'\) between s1[1] and s2[1] and \(c'\) between s1[2] and s2[0].

__init__(*args, **kwargs)

is_order_invariant

Is this metric invariant to the sequence’s ordering

SumPointwiseEuclideanMetric

class dipy.segment.metricspeed.SumPointwiseEuclideanMetric

Bases: CythonMetric

Computes the sum of pointwise Euclidean distances between two sequential data. A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions). A feature object can be specified in order to calculate the distance between the features, rather than directly between the sequential data. Parameters ———- feature : Feature object, optional It is used to extract features before computing the distance. Notes —– The distance between two 2D sequential data:: s1 s2 0* a 0 | | 1 | | b 1 | 2 c *2 is equal to \(a+b+c\) where \(a\) is the Euclidean distance between s1[0] and s2[0], \(b\) between s1[1] and s2[1] and \(c\) between s1[2] and s2[2].

__init__(*args, **kwargs)

dist

dipy.segment.metricspeed.dist(metric, datum1, datum2)

Computes a distance between datum1 and datum2.

A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions).

Parameters

metricMetric object

Tells how to compute the distance between datum1 and datum2.

datum12D array

Sequence of N-dimensional points.

datum22D array

Sequence of N-dimensional points.

Returns

double

Distance between two data points.

distance_matrix

dipy.segment.metricspeed.distance_matrix(metric, data1, data2=None)

Computes the distance matrix between two lists of sequential data.

The distance matrix is obtained by computing the pairwise distance of all tuples spawn by the Cartesian product of data1 with data2. If data2 is not provided, the Cartesian product of data1 with itself is used instead. A sequence of N-dimensional points is represented as a 2D array with shape (nb_points, nb_dimensions).

Parameters

metricMetric object

Tells how to compute the distance between two sequential data.

data1list of 2D arrays

List of sequences of N-dimensional points.

data2list of 2D arrays

Llist of sequences of N-dimensional points.

Returns

2D array (double)

Distance matrix.

ConstantObservationModel

class dipy.segment.mrf.ConstantObservationModel

Bases: object

Observation model assuming that the intensity of each class is constant. The model parameters are the means \(\mu_{k}\) and variances \(\sigma_{k}\) associated with each tissue class. According to this model, the observed intensity at voxel \(x\) is given by \(I(x) = \mu_{k} + \eta_{k}\) where \(k\) is the tissue class of voxel \(x\), and \(\eta_{k}\) is a Gaussian random variable with zero mean and variance \(\sigma_{k}^{2}\). The observation model is responsible for computing the negative log-likelihood of observing any given intensity \(z\) at each voxel \(x\) assuming the voxel belongs to each class \(k\). It also provides a default parameter initialization.

__init__()

Initializes an instance of the ConstantObservationModel class

initialize_param_uniform(image, nclasses)

Initializes the means and variances uniformly

The means are initialized uniformly along the dynamic range of image. The variances are set to 1 for all classes

Parameters

imagearray

3D structural image

nclassesint

number of desired classes

Returns

muarray

1 x nclasses, mean for each class

sigmaarray

1 x nclasses, standard deviation for each class. Set up to 1.0 for all classes.

negloglikelihood(image, mu, sigmasq, nclasses)

Computes the gaussian negative log-likelihood of each class at each voxel of image assuming a gaussian distribution with means and variances given by mu and sigmasq, respectively (constant models along the full volume). The negative log-likelihood will be written in nloglike.

Parameters

imagendarray

3D gray scale structural image

mundarray

mean of each class

sigmasqndarray

variance of each class

nclassesint

number of classes

Returns

nloglikendarray

4D negloglikelihood for each class in each volume

prob_image(img, nclasses, mu, sigmasq, P_L_N)

Conditional probability of the label given the image

Parameters

imgndarray

3D structural gray-scale image

nclassesint

number of tissue classes

mundarray

1 x nclasses, current estimate of the mean of each tissue class

sigmasqndarray

1 x nclasses, current estimate of the variance of each tissue class

P_L_Nndarray

4D probability map of the label given the neighborhood.

Previously computed by function prob_neighborhood

Returns

P_L_Yndarray

4D probability of the label given the input image

seg_stats(input_image, seg_image, nclass)

Mean and standard variation for N desired tissue classes

Parameters

input_imagendarray

3D structural image

seg_imagendarray

3D segmented image

nclassint

number of classes (3 in most cases)

Returns

mu, varndarrays

1 x nclasses dimension Mean and variance for each class

update_param(image, P_L_Y, mu, nclasses)

Updates the means and the variances in each iteration for all the labels. This is for equations 25 and 26 of Zhang et. al., IEEE Trans. Med. Imag, Vol. 20, No. 1, Jan 2001.

Parameters

imagendarray

3D structural gray-scale image

P_L_Yndarray

4D probability map of the label given the input image computed by the expectation maximization (EM) algorithm

mundarray

1 x nclasses, current estimate of the mean of each tissue class.

nclassesint

number of tissue classes

Returns

mu_updndarray

1 x nclasses, updated mean of each tissue class

var_updndarray

1 x nclasses, updated variance of each tissue class

IteratedConditionalModes

class dipy.segment.mrf.IteratedConditionalModes

Bases: object

__init__()

icm_ising(nloglike, beta, seg)

Executes one iteration of the ICM algorithm for MRF MAP estimation. The prior distribution of the MRF is a Gibbs distribution with the Potts/Ising model with parameter beta:

https://en.wikipedia.org/wiki/Potts_model

Parameters

nloglikendarray

4D shape, nloglike[x, y, z, k] is the negative log likelihood of class k at voxel (x, y, z)

betafloat

positive scalar, it is the parameter of the Potts/Ising model. Determines the smoothness of the output segmentation.

segndarray

3D initial segmentation. This segmentation will change by one iteration of the ICM algorithm

Returns

new_segndarray

3D final segmentation

energyndarray

3D final energy

initialize_maximum_likelihood(nloglike)

Initializes the segmentation of an image with given

neg-loglikelihood

Initializes the segmentation of an image with neglog-likelihood field given by nloglike. The class of each voxel is selected as the one with the minimum neglog-likelihood (i.e. maximum-likelihood segmentation).

Parameters

nloglikendarray

4D shape, nloglike[x, y, z, k] is the likelihhood of class k for voxel (x, y, z)

Returns

segndarray

3D initial segmentation

prob_neighborhood(seg, beta, nclasses)

Conditional probability of the label given the neighborhood Equation 2.18 of the Stan Z. Li book (Stan Z. Li, Markov Random Field Modeling in Image Analysis, 3rd ed., Advances in Pattern Recognition Series, Springer Verlag 2009.)

Parameters

segndarray

3D tissue segmentation derived from the ICM model

betafloat

scalar that determines the importance of the neighborhood and the spatial smoothness of the segmentation. Usually between 0 to 0.5

nclassesint

number of tissue classes

Returns

PLNndarray

4D probability map of the label given the neighborhood of the voxel.

otsu

dipy.segment.threshold.otsu(image, nbins=256)

Return threshold value based on Otsu’s method. Copied from scikit-image to remove dependency.

Parameters

imagearray

Input image.

nbinsint

Number of bins used to calculate histogram. This value is ignored for integer arrays.

Returns

thresholdfloat

Threshold value.

upper_bound_by_rate

dipy.segment.threshold.upper_bound_by_rate(data, rate=0.05)

Adjusts upper intensity boundary using rates

It calculates the image intensity histogram, and based on the rate value it decide what is the upperbound value for intensity normalization, usually lower bound is 0. The rate is the ratio between the amount of pixels in every bins and the bins with highest pixel amount

Parameters

datafloat

Input intensity value data

ratefloat

representing the threshold whether a specific histogram bin that should be count in the normalization range

Returns

high : float

the upper_bound value for normalization

upper_bound_by_percent

dipy.segment.threshold.upper_bound_by_percent(data, percent=1)

Find the upper bound for visualization of medical images

Calculate the histogram of the image and go right to left until you find the bound that contains more than a percentage of the image.

Parameters

data : ndarray percent : float

Returns

upper_bound : float

TissueClassifierHMRF

class dipy.segment.tissue.TissueClassifierHMRF(save_history=False, verbose=True)

Bases: object

This class contains the methods for tissue classification using the Markov Random Fields modeling approach

__init__(save_history=False, verbose=True)

classify(image, nclasses, beta, tolerance=None, max_iter=None)

This method uses the Maximum a posteriori - Markov Random Field approach for segmentation by using the Iterative Conditional Modes and Expectation Maximization to estimate the parameters.

Parameters

imagendarray,

3D structural image.

nclassesint,

number of desired classes.

betafloat,

smoothing parameter, the higher this number the smoother the output will be.

tolerance: float,

value that defines the percentage of change tolerated to prevent the ICM loop to stop. Default is 1e-05.

max_iterfloat,

fixed number of desired iterations. Default is 100. If the user only specifies this parameter, the tolerance value will not be considered. If none of these two parameters

Returns

initial_segmentationndarray,

3D segmented image with all tissue types specified in nclasses.

final_segmentationndarray,

3D final refined segmentation containing all tissue types.

PVEndarray,

3D probability map of each tissue type.