segment
#
Module: segment.bundles
#




Instances of the Logger class represent a single logging channel. 


Find bundle adjacency between two given tracks/bundles 

Calculates bundle adjacency score between two given bundles 

Clusters bundles 

Calculates bundle shape similarity between two given bundles using bundle adjacency (BA) metric 
Module: segment.clustering
#

Provides identity indexing functionality. 

Provides functionalities for interacting with a cluster. 

Provides functionalities for interacting with a cluster. 

Provides functionalities for interacting with clustering outputs. 

Provides functionalities for interacting with clustering outputs that have centroids. 

Clusters streamlines using QuickBundles [Garyfallidis12]. 

Clusters streamlines using QuickBundlesX. 




Instances of the Logger class represent a single logging channel. 


Run QuickBundlesX and then run again on the centroids of the last layer 
Module: segment.clustering_algorithms
#

Provides functionalities for interacting with a cluster. 

Provides functionalities for interacting with clustering outputs that have centroids. 
alias of 

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


Returns the first element of an iterable and the iterator. 

Clusters streamlines using QuickBundles. 

Clusters streamlines using QuickBundlesX. 
Module: segment.clusteringspeed
#

Provides functionalities for interacting with a cluster. 

Provides functionalities for interacting with clustering outputs that have centroids. 
Provides Cython functionalities to interact with clustering outputs. 

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

alias of 





Module: segment.cythonutils
#
Module: segment.featurespeed
#
Extracts features from a sequential datum. 

Extracts features from a sequential datum. 

Extracts features from a sequential datum. 

Extracts features from a sequential datum. 

Extracts features from a sequential datum. 

Extracts features from a sequential datum. 

Extracts features from a sequential datum. 

Extracts features from a sequential datum. 


Extracts features from data. 

Infers shape of the features extracted from data. 
Module: segment.fss
#



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

Return the nearest (smallest) for each column given an coup sparse matrix 
Module: segment.mask
#

Applies median filter multiple times on input data. 

Mask vol with mask. 

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

Crops the input volume. 

Simple brain extraction tool method for images from DWI data. 

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

Cleans a segmentation of the corpus callosum so no random pixels are included. 
Module: segment.metric
#

Computes the MDF (Minimum average DirectFlip) distance [Garyfallidis12] between two streamlines. 

Compute the average ManhattanL1 distance (MDF without flip) 

Compute the average EuclideanL2 distance (MDF without flip) 
Module: segment.metricspeed
#
Computes the average of pointwise Euclidean distances between two sequential data. A sequence of Ndimensional 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]. . 

Computes the cosine distance between two vectors. 

Computes a distance between two sequential data. 

Computes a distance between two sequential data. 

Computes the MDF distance (minimum average directflip) between two sequential data. A sequence of Ndimensional 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]. . 

Computes the sum of pointwise Euclidean distances between two sequential data. A sequence of Ndimensional 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]. . 


Computes a distance between datum1 and datum2. 

Computes the distance matrix between two lists of sequential data. 
Module: segment.mrf
#
Observation model assuming that the intensity of each class is constant. 

Module: segment.threshold
#

Return threshold value based on Otsu's method. 

Adjusts upper intensity boundary using rates 

Find the upper bound for visualization of medical images 
Module: segment.tissue
#

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 streamlinebased 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='LBFGSB', 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 Streamlinebased 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:
 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])
(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 ‘LBFGSB’)
 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 streamlinebased 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='LBFGSB', 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 Streamlinebased 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:
 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])
(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 ‘LBFGSB’)
 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 streamlinebased 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 subareas “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 sublevels. 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 : arraylike, 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>)#
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>)#
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 Ndimensional 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 DirectFlip (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 DirectFlip (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
#
TreeClusterMap
#
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 subareas “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 sublevels. 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>)#
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>)#
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
#
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: 1e6)
 __init__(*args, **kwargs)#
DTYPE
#
 dipy.segment.clusteringspeed.DTYPE#
alias of
float32
QuickBundles
#
QuickBundlesX
#
TreeCluster
#
TreeClusterMap
#
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 Ndimensional 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 Ndimensional points is represented as a 2D array with shape (nb_points, nb_dimensions).
The feature being extracted consists of one Ndimensional 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 Ndimensional 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)#
Feature
#
 class dipy.segment.featurespeed.Feature#
Bases:
object
Extracts features from a sequential datum.
A sequence of Ndimensional 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 Ndimensional 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 Ndimensional points.
Returns#
 int, 1tuple or 2tuple
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 Ndimensional 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 preprocessing.
 __init__(*args, **kwargs)#
MidpointFeature
#
 class dipy.segment.featurespeed.MidpointFeature#
Bases:
CythonFeature
Extracts features from a sequential datum.
A sequence of Ndimensional points is represented as a 2D array with shape (nb_points, nb_dimensions).
The feature being extracted consists of one Ndimensional 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 Ndimensional 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 Ndimensional points is represented as a 2D array with shape (nb_points, nb_dimensions).
The feature being extracted consists of one vector in the Ndimensional space pointing from one endpoint of the sequence to the other (i.e. S[1]S[0]).
 __init__(*args, **kwargs)#
extract#
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 Ndimensional 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 KD Tree structure with reference streamlines, using streamlines barycenter and meanpoints. 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 inbetween 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]StOnge 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]StOnge 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 nonempty 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 nonempty 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]
tovol[..., 1
). Returns —— masked_vol : ndarray vol multiplied by mask where mask may have been extended to match extra dimensions in vol
bounding_box#
crop#
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 ismedian_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 ifinput_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 scikitimage 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:
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)#
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.
 thresholdarraylike
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#
mdf#
 dipy.segment.metric.mdf(s1, s2)#
Computes the MDF (Minimum average DirectFlip) distance [Garyfallidis12] between two streamlines.
Streamlines must have the same number of points.
Parameters#
 s12D array
A streamline (sequence of Ndimensional points).
 s22D array
A streamline (sequence of Ndimensional 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 ManhattanL1 distance (MDF without flip)
Arrays are representing a single streamline or a list of streamlines that have the same number of Ndimensional 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 EuclideanL2 distance (MDF without flip)
Arrays are representing a single streamline or a list of streamlines that have the same number of Ndimensional 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 Ndimensional 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 Ndimensional 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 Ndimensional 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, 1tuple or 2tuple
Shape of the first data point’s features.
 shape2int, 1tuple or 2tuple
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 Ndimensional 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, 1tuple or 2tuple
shape of the first data point’s features
 shape2int, 1tuple or 2tuple
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 directflip) between two sequential data. A sequence of Ndimensional 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 Ndimensional 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 Ndimensional 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 Ndimensional points.
 datum22D array
Sequence of Ndimensional 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 Ndimensional 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 Ndimensional points.
 data2list of 2D arrays
Llist of sequences of Ndimensional 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 loglikelihood 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 loglikelihood 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 loglikelihood 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 grayscale 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 grayscale 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
negloglikelihood
Initializes the segmentation of an image with negloglikelihood field given by nloglike. The class of each voxel is selected as the one with the minimum negloglikelihood (i.e. maximumlikelihood 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 scikitimage 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 1e05.
 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.