`segment`#

Module: `segment.bundles`#

`RecoBundles`(streamlines, *[, greater_than, ...])
`check_range`(streamline, gt, lt)
`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, ...])	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.
`QuickBundlesX`(thresholds, *[, metric])	Clusters streamlines using QuickBundlesX.
`TreeCluster`(threshold, centroid, *[, indices])
`TreeClusterMap`(root)
`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, ...])	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, ...])	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`	Extract 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`	Extract features from a sequential datum.
`ResampleFeature`	Extract 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, ...[, ...])
`nearest_from_matrix_row`(coo_array)	Return the nearest (smallest) for each row given an coup sparse matrix
`nearest_from_matrix_col`(coo_array)	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 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.
`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.
`SumPointwiseEuclideanMetric`	Computes the sum of pointwise Euclidean distances between two sequential data.
`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.
`compute_directional_average`(data, bvals, *)	Compute the mean signal for each unique b-value shell and fit a linear model.
`dam_classifier`(data, bvals, wm_threshold, *)	Computes the P-map (fitting slope) on data to extract white and grey matter.

Module: `segment.utils`#

remove_holes_and_islands(binary_img, *[, ...])

Remove any small mask chunks or holes that could be in the segmentation output.

`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)[source]#

Bases: object

Methods

`evaluate_results`(model_bundle, ...)	Compare the similarity between two given bundles, model bundle, and extracted bundle.
`recognize`(model_bundle, model_clust_thr, *)	Recognize the model_bundle in self.streamlines
`refine`(model_bundle, pruned_streamlines, ...)	Refine and recognize the model_bundle in self.streamlines This method expects once pruned streamlines as input.

evaluate_results(model_bundle, pruned_streamlines, slr_select)[source]#

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

Parameters:

model_bundleStreamlines: Model bundle streamlines.
pruned_streamlinesStreamlines: Pruned bundle streamlines.
slr_selecttuple: Select the number of streamlines from model to neighborhood 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')[source]#

Recognize the model_bundle in self.streamlines

See [1] for further details about the method.

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_metricBundleMinDistanceMetric

slr_x0array 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:

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

If str:

“rigid”
x0 = np.array([0, 0, 0, 0, 0, 0])
“similarity”
x0 = np.array([0, 0, 0, 0, 0, 0, 1.])
“affine”
x0 = np.array([0, 0, 0, 0, 0, 0, 1., 1., 1, 0, 0, 0])

slr_boundsarray, optional

SLR bounds.

slr_selecttuple, optional

Select the number of streamlines from model to neighborhood 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.

pruning_distancestring, optional

Pruning distance type can be mdf or mam.

Returns:

recognized_transfStreamlines: Recognized bundle in the space of the model tractogram
recognized_labelsarray: Indices of recognized bundle in the original tractogram

References

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')[source]#

Refine and recognize the model_bundle in self.streamlines This method expects once pruned streamlines as input. It refines the first output of RecoBundles 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.

See [1], [2] for further details about the method.

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.

slr_metricBundleMinDistanceMetric

Bundle distance metric.

slr_x0array or int or str

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

If 1D array with:

6 elements then only rigid registration is performed with the 3 first elements for translation and 3 for rotation.
7 elements also isotropic scaling is performed (similarity).
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:

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

If str:

“rigid”
x0 = np.array([0, 0, 0, 0, 0, 0])
“similarity”
x0 = np.array([0, 0, 0, 0, 0, 0, 1.])
“affine”
x0 = np.array([0, 0, 0, 0, 0, 0, 1., 1., 1, 0, 0, 0])

slr_boundsarray

SLR bounds.

slr_selecttuple

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

slr_methodstring

Optimization method ‘L_BFGS_B’ or ‘Powell’ optimizers can be used.

pruning_thrfloat

Pruning after reducing the search space.

pruning_distancestring

Pruning distance type can be mdf or mam.

Returns:

recognized_transfStreamlines: Recognized bundle in the space of the model tractogram
recognized_labelsarray: Indices of recognized bundle in the original tractogram

References

check_range#

dipy.segment.bundles.check_range(streamline, gt, lt)[source]#

bundle_adjacency#

dipy.segment.bundles.bundle_adjacency(dtracks0, dtracks1, threshold)[source]#

Find bundle adjacency between two given tracks/bundles

See [3] for further details about the method.

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

ba_analysis#

dipy.segment.bundles.ba_analysis(recognized_bundle, expert_bundle, *, nb_pts=20, threshold=6.0)[source]#

Calculates bundle adjacency score between two given bundles

See [3] for further details about the method.

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, optional: Discretizing streamlines to have nb_pts number of points
thresholdfloat, optional: 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

cluster_bundle#

dipy.segment.bundles.cluster_bundle(bundle, clust_thr, rng, *, nb_pts=20, select_randomly=500000)[source]#

Clusters bundles

See [3] for further details about the method.

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, optional: Discretizing streamlines to have nb_points number of points
select_randomly: integer, optional: Randomly select streamlines from the input bundle

Returns:

centroidsStreamlines: clustered centroids of the input bundle

References

bundle_shape_similarity#

dipy.segment.bundles.bundle_shape_similarity(bundle1, bundle2, rng, *, clust_thr=(5, 3, 1.5), threshold=6)[source]#

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

See [3], [2] for further details about the method.

Parameters:

bundle1Streamlines: White matter tract from one subject (eg: AF_L)
bundle2Streamlines: White matter tract from another subject (eg: AF_L)
rngnp.random.Generator: Random number generator.
clust_thrarray-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

`Identity`#

class dipy.segment.clustering.Identity[source]#

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.

`Cluster`#

class dipy.segment.clustering.Cluster(*, id=0, indices=None, refdata=None)[source]#

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, optional: Id of this cluster in its associated cluster_map object.
refdatalist, optional: Actual elements that clustered indices refer to.

Methods

assign(*indices)

Assigns indices to this cluster.

Notes

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

assign(*indices)[source]#

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=None)[source]#

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, optional: Id of this cluster in its associated cluster_map object.
refdatalist, optional: Actual elements that clustered indices refer to.

Methods

`assign`(id_datum, features)	Assigns a data point to this cluster.
`update`()	Update centroid of this cluster.

Notes

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

assign(id_datum, features)[source]#

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()[source]#

Update centroid of this cluster.

Returns:

convergedbool: Tells if the centroid has moved.

`ClusterMap`#

class dipy.segment.clustering.ClusterMap(*, refdata=None)[source]#

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.

Attributes:

clusters
refdata

Methods

`add_cluster`(*clusters)	Adds one or multiple clusters to this cluster map.
`clear`()	Remove all clusters from this cluster map.
`clusters_sizes`()	Gets the size of every cluster contained in this cluster map.
`get_large_clusters`(min_size)	Gets clusters which contains at least min_size elements.
`get_small_clusters`(max_size)	Gets clusters which contains at most max_size elements.
`remove_cluster`(*clusters)	Remove one or multiple clusters from this cluster map.
`size`()	Gets number of clusters contained in this cluster map.

add_cluster(*clusters)[source]#

Adds one or multiple clusters to this cluster map.

Parameters:

*clustersCluster object, …: Cluster(s) to be added in this cluster map.

clear()[source]#: Remove all clusters from this cluster map.

property clusters#

clusters_sizes()[source]#

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)[source]#

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)[source]#

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)[source]#

Remove one or multiple clusters from this cluster map.

Parameters:

*clustersCluster object, …: Cluster(s) to be removed from this cluster map.

size()[source]#: Gets number of clusters contained in this cluster map.

`ClusterMapCentroid`#

class dipy.segment.clustering.ClusterMapCentroid(*, refdata=None)[source]#

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.

Attributes:

centroids
clusters
refdata

Methods

`add_cluster`(*clusters)	Adds one or multiple clusters to this cluster map.
`clear`()	Remove all clusters from this cluster map.
`clusters_sizes`()	Gets the size of every cluster contained in this cluster map.
`get_large_clusters`(min_size)	Gets clusters which contains at least min_size elements.
`get_small_clusters`(max_size)	Gets clusters which contains at most max_size elements.
`remove_cluster`(*clusters)	Remove one or multiple clusters from this cluster map.
`size`()	Gets number of clusters contained in this cluster map.

property centroids#

`Clustering`#

class dipy.segment.clustering.Clustering[source]#

Bases: object

Methods

cluster(data, *[, ordering])

Clusters data.

abstract cluster(data, *, ordering=None)[source]#

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=None)[source]#

Bases: Clustering

Clusters streamlines using QuickBundles.

Given a list of streamlines, the QuickBundles algorithm [3] 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:

thresholdfloat: The maximum distance from a bundle 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 [3] is used and streamlines are automatically resampled so they have 12 points.
max_nb_clustersint, optional: Limits the creation of bundles.

Methods

cluster(streamlines, *[, ordering])

Clusters streamlines into bundles.

References

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(name='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]

cluster(streamlines, *, ordering=None)[source]#

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, optional: 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')[source]#

Bases: Clustering

Clusters streamlines using QuickBundlesX.

See [4] for further details about the method.

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 [3] is used and streamlines are automatically resampled so they have 12 points.

Methods

cluster(streamlines, *[, ordering])

Clusters streamlines into bundles.

References

cluster(streamlines, *, ordering=None)[source]#

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)[source]#

Bases: ClusterCentroid

Attributes:

is_leaf

Methods

`assign`(id_datum, features)	Assigns a data point to this cluster.
`update`()	Update centroid of this cluster.

add
return_indices

add(child)[source]#

property is_leaf#

return_indices()[source]#

`TreeClusterMap`#

class dipy.segment.clustering.TreeClusterMap(root)[source]#

Bases: ClusterMap

Attributes:

clusters
refdata

Methods

`add_cluster`(*clusters)	Adds one or multiple clusters to this cluster map.
`clear`()	Remove all clusters from this cluster map.
`clusters_sizes`()	Gets the size of every cluster contained in this cluster map.
`get_large_clusters`(min_size)	Gets clusters which contains at least min_size elements.
`get_small_clusters`(max_size)	Gets clusters which contains at most max_size elements.
`remove_cluster`(*clusters)	Remove one or multiple clusters from this cluster map.
`size`()	Gets number of clusters contained in this cluster map.

get_clusters
iter_preorder
traverse_postorder

get_clusters(wanted_level)[source]#

iter_preorder(node)[source]#

property refdata#

traverse_postorder(node, visit)[source]#

qbx_and_merge#

dipy.segment.clustering.qbx_and_merge(streamlines, thresholds, *, nb_pts=20, select_randomly=None, rng=None, verbose=False)[source]#

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.

See [3] and [4] for further details about the method.

Parameters:

streamlinesStreamlines: Streamlines.
thresholdssequence: 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

`ClusterCentroid`#

class dipy.segment.clustering_algorithms.ClusterCentroid(centroid, *, id=0, indices=None, refdata=None)[source]#

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, optional: Id of this cluster in its associated cluster_map object.
refdatalist, optional: Actual elements that clustered indices refer to.

Methods

`assign`(id_datum, features)	Assigns a data point to this cluster.
`update`()	Update centroid of this cluster.

Notes

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

assign(id_datum, features)[source]#

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()[source]#

Update centroid of this cluster.

Returns:

convergedbool: Tells if the centroid has moved.

`ClusterMapCentroid`#

class dipy.segment.clustering_algorithms.ClusterMapCentroid(*, refdata=None)[source]#

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.

Attributes:

centroids
clusters
refdata

Methods

`add_cluster`(*clusters)	Adds one or multiple clusters to this cluster map.
`clear`()	Remove all clusters from this cluster map.
`clusters_sizes`()	Gets the size of every cluster contained in this cluster map.
`get_large_clusters`(min_size)	Gets clusters which contains at least min_size elements.
`get_small_clusters`(max_size)	Gets clusters which contains at most max_size elements.
`remove_cluster`(*clusters)	Remove one or multiple clusters from this cluster map.
`size`()	Gets number of clusters contained in this cluster map.

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.

See [3] for further details about the method.

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

quickbundlesx#

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

Clusters streamlines using QuickBundlesX.

See [3] and [4] for further details about the method.

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

`ClusterCentroid`#

class dipy.segment.clusteringspeed.ClusterCentroid(centroid, *, id=0, indices=None, refdata=None)[source]#

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, optional: Id of this cluster in its associated cluster_map object.
refdatalist, optional: Actual elements that clustered indices refer to.

Methods

`assign`(id_datum, features)	Assigns a data point to this cluster.
`update`()	Update centroid of this cluster.

Notes

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

assign(id_datum, features)[source]#

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()[source]#

Update centroid of this cluster.

Returns:

convergedbool: Tells if the centroid has moved.

`ClusterMapCentroid`#

class dipy.segment.clusteringspeed.ClusterMapCentroid(*, refdata=None)[source]#

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.

Attributes:

centroids
clusters
refdata

Methods

`add_cluster`(*clusters)	Adds one or multiple clusters to this cluster map.
`clear`()	Remove all clusters from this cluster map.
`clusters_sizes`()	Gets the size of every cluster contained in this cluster map.
`get_large_clusters`(min_size)	Gets clusters which contains at least min_size elements.
`get_small_clusters`(max_size)	Gets clusters which contains at most max_size elements.
`remove_cluster`(*clusters)	Remove one or multiple clusters from this cluster map.
`size`()	Gets number of clusters contained in this cluster map.

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.

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

`DTYPE`#

dipy.segment.clusteringspeed.DTYPE#: alias of float32

`QuickBundles`#

class dipy.segment.clusteringspeed.QuickBundles#

Bases: object

Methods

get_cluster_map
get_stats

get_cluster_map()#

get_stats()#

`QuickBundlesX`#

class dipy.segment.clusteringspeed.QuickBundlesX#

Bases: object

Methods

get_stats
get_tree_cluster_map
insert

get_stats()#

get_tree_cluster_map()#

insert(datum, datum_idx)#

`TreeCluster`#

class dipy.segment.clusteringspeed.TreeCluster(threshold, centroid, *, indices=None)[source]#

Bases: ClusterCentroid

Attributes:

is_leaf

Methods

`assign`(id_datum, features)	Assigns a data point to this cluster.
`update`()	Update centroid of this cluster.

add
return_indices

add(child)[source]#

property is_leaf#

return_indices()[source]#

`TreeClusterMap`#

class dipy.segment.clusteringspeed.TreeClusterMap(root)[source]#

Bases: ClusterMap

Attributes:

clusters
refdata

Methods

`add_cluster`(*clusters)	Adds one or multiple clusters to this cluster map.
`clear`()	Remove all clusters from this cluster map.
`clusters_sizes`()	Gets the size of every cluster contained in this cluster map.
`get_large_clusters`(min_size)	Gets clusters which contains at least min_size elements.
`get_small_clusters`(max_size)	Gets clusters which contains at most max_size elements.
`remove_cluster`(*clusters)	Remove one or multiple clusters from this cluster map.
`size`()	Gets number of clusters contained in this cluster map.

get_clusters
iter_preorder
traverse_postorder

get_clusters(wanted_level)[source]#

iter_preorder(node)[source]#

property refdata#

traverse_postorder(node, visit)[source]#

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

Attributes:

is_order_invariant: Is this feature invariant to the sequence’s ordering

Methods

`extract`(datum)	Extracts features from a sequential datum.
`infer_shape`(datum)	Infers the shape of features extracted from a sequential datum.

`CenterOfMassFeature`#

class dipy.segment.featurespeed.CenterOfMassFeature#

Bases: CythonFeature

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

Attributes:

is_order_invariant: Is this feature invariant to the sequence’s ordering

Methods

`extract`(datum)	Extracts features from a sequential datum.
`infer_shape`(datum)	Infers the shape of features extracted from a sequential datum.

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

Attributes:

is_order_invariant: Is this feature invariant to the sequence’s ordering

Methods

`extract`(datum)	Extracts features from a sequential datum.
`infer_shape`(datum)	Infers the shape of features extracted from a sequential datum.

Notes

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

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)

Attributes:

is_order_invariant: Is this feature invariant to the sequence’s ordering

Methods

`extract`(datum)	Extracts features from a sequential datum.
`infer_shape`(datum)	Infers the shape of features extracted from a sequential datum.

Notes

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

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.

Attributes:

is_order_invariant: Is this feature invariant to the sequence’s ordering

Methods

`extract`(datum)	Extracts features from a sequential datum.
`infer_shape`(datum)	Infers the shape of features extracted from a sequential datum.

`MidpointFeature`#

class dipy.segment.featurespeed.MidpointFeature#

Bases: CythonFeature

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

Attributes:

is_order_invariant: Is this feature invariant to the sequence’s ordering

Methods

`extract`(datum)	Extracts features from a sequential datum.
`infer_shape`(datum)	Infers the shape of features extracted from a sequential datum.

`ResampleFeature`#

class dipy.segment.featurespeed.ResampleFeature#

Bases: CythonFeature

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

Attributes:

is_order_invariant: Is this feature invariant to the sequence’s ordering

Methods

`extract`(datum)	Extracts features from a sequential datum.
`infer_shape`(datum)	Infers the shape of features extracted from a sequential datum.

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

Attributes:

is_order_invariant: Is this feature invariant to the sequence’s ordering

Methods

`extract`(datum)	Extracts features from a sequential datum.
`infer_shape`(datum)	Infers the shape of features extracted from a sequential datum.

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)[source]#

Bases: object

Methods

radius_search(streamlines, radius, *[, ...])

Radius Search using Fast Streamline Search

radius_search(streamlines, radius, *, use_negative=True)[source]#

Radius Search using Fast Streamline Search

For each given streamlines, return all reference streamlines within the given radius. See [5] 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

nearest_from_matrix_row#

dipy.segment.fss.nearest_from_matrix_row(coo_array)[source]#

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

Parameters:

coo_arrayscipy COOrdinates sparse array (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_array)[source]#

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

Parameters:

coo_arrayscipy 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)[source]#

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)[source]#

Mask vol with mask.

Parameters:

volndarray: Array with \(V\) dimensions
maskndarray: 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_volndarray: vol multiplied by mask where mask may have been extended to match extra dimensions in vol

bounding_box#

dipy.segment.mask.bounding_box(vol)[source]#

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)[source]#

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, finalize_mask=False)[source]#

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, optional: Radius (in voxels) of the applied median filter.
numpass: int, optional: Number of pass of the median filter.
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.
dilateNone or int, optional: number of iterations for binary dilation
finalize_maskbool, optional: Whether to remove potential holes or islands. Useful for solving minor errors.

Returns:

maskedvolumendarray: Masked input_volume
mask3D ndarray: The binary brain mask

Notes

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

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

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.

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)[source]#

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)[source]#

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)[source]#

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

Streamlines must have the same number of points.

See [3] for a definition of the distance.

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

mean_manhattan_distance#

dipy.segment.metric.mean_manhattan_distance(a, b)[source]#

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)[source]#

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:

featureFeature object, optional: It is used to extract features before computing the distance.

Attributes:

feature: Feature object used to extract features from sequential data
is_order_invariant: Is this metric invariant to the sequence’s ordering

Methods

`are_compatible`(shape1, shape2)	Checks if features can be used by metric.dist based on their shape.
`dist`(features1, features2)	Computes a distance between two data points based on their features.

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`#

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

Attributes:

feature: Feature object used to extract features from sequential data
is_order_invariant: Is this metric invariant to the sequence’s ordering

Methods

`are_compatible`(shape1, shape2)	Checks if features can be used by metric.dist based on their shape.
`dist`(features1, features2)	Computes a distance between two data points based on their features.

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

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

Attributes:

feature: Feature object used to extract features from sequential data
is_order_invariant: Is this metric invariant to the sequence’s ordering

Methods

`are_compatible`(shape1, shape2)	Checks if features can be used by metric.dist based on their shape.
`dist`(features1, features2)	Computes a distance between two data points based on their features.

Notes

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

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.

Attributes:

feature: Feature object used to extract features from sequential data
is_order_invariant: Is this metric invariant to the sequence’s ordering

Methods

`are_compatible`(shape1, shape2)	Checks if features can be used by metric.dist based on their shape.
`dist`(features1, features2)	Computes a distance between two data points based on their features.

Notes

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

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

Attributes:

feature: Feature object used to extract features from sequential data
is_order_invariant: Is this metric invariant to the sequence’s ordering

Methods

`are_compatible`(shape1, shape2)	Checks if features can be used by metric.dist based on their shape.
`dist`(features1, features2)	Computes a distance between two data points based on their features.

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

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:

featureFeature object, optional: It is used to extract features before computing the distance.

Attributes:

feature: Feature object used to extract features from sequential data
is_order_invariant: Is this metric invariant to the sequence’s ordering

Methods

`are_compatible`(shape1, shape2)	Checks if features can be used by metric.dist based on their shape.
`dist`(features1, features2)	Computes a distance between two data points based on their features.

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#

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.

Methods

`initialize_param_uniform`(image, nclasses)	Initializes the means and variances uniformly
`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).
`prob_image`(img, nclasses, mu, sigmasq, P_L_N)	Conditional probability of the label given the image
`seg_stats`(input_image, seg_image, nclass)	Mean and standard variation for N desired tissue classes
`update_param`(image, P_L_Y, mu, nclasses)	Updates the means and the variances in each iteration for all the labels.

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

Methods

`icm_ising`(nloglike, beta, seg)	Executes one iteration of the ICM algorithm for MRF MAP estimation.
`initialize_maximum_likelihood`(nloglike)	Initializes the segmentation of an image with given
`prob_neighborhood`(seg, beta, nclasses)	Conditional probability of the label given the neighborhood Equation 2.18 of the Stan Z.

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)[source]#

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)[source]#

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:

highfloat: the upper_bound value for normalization

upper_bound_by_percent#

dipy.segment.threshold.upper_bound_by_percent(data, *, percent=1)[source]#

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:

datandarray
percentfloat

Returns:

upper_boundfloat

`TissueClassifierHMRF`#

class dipy.segment.tissue.TissueClassifierHMRF(*, save_history=False, verbose=True)[source]#

Bases: object

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

Methods

classify(image, nclasses, beta, *[, ...])

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.

classify(image, nclasses, beta, *, tolerance=1e-05, max_iter=100)[source]#

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, optional: Value that defines the percentage of change tolerated to prevent the ICM loop to stop. Default is 1e-05. If you want tolerance check to be disabled put ‘tolerance = 0’.
max_iterint, optional: Fixed number of desired iterations. Default is 100. This parameter defines the maximum number of iterations the algorithm will perform. The loop may terminate early if the change in energy sum between iterations falls below the threshold defined by tolerance. However, if tolerance is explicitly set to 0, this early stopping mechanism is disabled, and the algorithm will run for the specified number of iterations unless another stopping criterion is met.

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.

compute_directional_average#

dipy.segment.tissue.compute_directional_average(data, bvals, *, s0_map=None, masks=None, b0_mask=None, b0_threshold=50, low_signal_threshold=50)[source]#

Compute the mean signal for each unique b-value shell and fit a linear model.

Parameters:

datandarray: The diffusion MRI data.
bvalsndarray: The b-values corresponding to the diffusion data.
s0_mapndarray, optional: Precomputed mean signal map for b=0 images.
masksndarray, optional: Precomputed masks for each unique b-value shell.
b0_maskndarray, optional: Precomputed mask for b=0 images.
b0_thresholdfloat, optional: The intensity threshold for a b=0 image.
low_signal_thresholdfloat, optional: The threshold below which a voxel is considered to have low signal.

Returns:

Pfloat: The slope of the linear model.
Vfloat: The intercept of the linear model.

dam_classifier#

dipy.segment.tissue.dam_classifier(data, bvals, wm_threshold, *, b0_threshold=50, low_signal_threshold=50)[source]#

Computes the P-map (fitting slope) on data to extract white and grey matter.

See [6] for further details about the method.

Parameters:

datandarray: The diffusion MRI data.
bvalsndarray: The b-values corresponding to the diffusion data.
wm_thresholdfloat: The threshold below which a voxel is considered white matter.
b0_thresholdfloat, optional: The intensity threshold for a b=0 image.
low_signal_thresholdfloat, optional: The threshold below which a voxel is considered to have low signal.

Returns:

wm_maskndarray: A binary mask for white matter.
gm_maskndarray: A binary mask for grey matter.

References

remove_holes_and_islands#

dipy.segment.utils.remove_holes_and_islands(binary_img, *, slice_wise=False)[source]#

Remove any small mask chunks or holes that could be in the segmentation output.

Parameters:

binary_imgnp.ndarray: Binary image
slice_wisebool, optional: Whether to run slice wise background correction as well

Returns:

largest_imgnp.ndarray

segment#

Module: segment.bundles#

Module: segment.clustering#

Module: segment.clustering_algorithms#

Module: segment.clusteringspeed#

Module: segment.cythonutils#

Module: segment.featurespeed#

Module: segment.fss#

Module: segment.mask#

Module: segment.metric#

Module: segment.metricspeed#

Module: segment.mrf#

Module: segment.threshold#

Module: segment.tissue#

Module: segment.utils#

check_range#

bundle_adjacency#

ba_analysis#

cluster_bundle#

bundle_shape_similarity#

qbx_and_merge#

clusters_centroid2clustermap_centroid#

peek#

quickbundles#

quickbundlesx#

evaluate_aabb_checks#

extract#

infer_shape#

nearest_from_matrix_row#

nearest_from_matrix_col#

multi_median#

applymask#

bounding_box#

crop#

median_otsu#

segment_from_cfa#

clean_cc_mask#

mdf#

mean_manhattan_distance#

mean_euclidean_distance#

dist#

distance_matrix#

otsu#

upper_bound_by_rate#

upper_bound_by_percent#

compute_directional_average#

dam_classifier#

remove_holes_and_islands#

`segment`#

Module: `segment.bundles`#

Module: `segment.clustering`#

Module: `segment.clustering_algorithms`#

Module: `segment.clusteringspeed`#

Module: `segment.cythonutils`#

Module: `segment.featurespeed`#

Module: `segment.fss`#

Module: `segment.mask`#

Module: `segment.metric`#

Module: `segment.metricspeed`#

Module: `segment.mrf`#

Module: `segment.threshold`#

Module: `segment.tissue`#

Module: `segment.utils`#