segment

Bases: Metric

__init__(*args, **kwargs)

are_compatible(shape1, shape2)

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

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

Parameters

shape1int, 1-tuple or 2-tuple

shape of the first data point’s features

shape2int, 1-tuple or 2-tuple

shape of the second data point’s features

Returns

are_compatiblebool

whether or not shapes are compatible

dist(features1, features2)

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

Parameters

features12D array

Features of the first data point.

features22D array

Features of the second data point.

Returns

double

Distance between two data points.

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)

rngRandomState

If None define RandomState in initialization function. Default: None

verbose: bool, optional.

If True, log information.

Notes

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

References

[Garyfallidis17]

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

evaluate_results(model_bundle, pruned_streamlines, slr_select)

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

Parameters

model_bundle : Streamlines pruned_streamlines : Streamlines slr_select : tuple

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

Returns

ba_valuefloat

bundle adjacency value between model bundle and pruned bundle

bmd_valuefloat

bundle minimum distance value between model bundle and pruned bundle

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

Recognize the model_bundle in self.streamlines

Parameters

model_bundleStreamlines

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

model_clust_thrfloat

MDF distance threshold for the model bundles

reduction_thrfloat, optional

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

reduction_distancestring, optional

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

slrbool, optional

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

num_threadsint, optional

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

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

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

If 1D array with:

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

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

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

If int:

1. 6

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

2. 7

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

3. 12

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

If str:

1. “rigid”

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

2. “similarity”

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

3. “affine”

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

(default None)

slr_boundsarray, optional

(default None)

slr_selecttuple, optional

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

slr_methodstring, optional

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

pruning_thrfloat, optional

Pruning after reducing the search space (default 5).

pruning_distancestring, optional

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

Returns

recognized_transfStreamlines

Recognized bundle in the space of the model tractogram

recognized_labelsarray

Indices of recognized bundle in the original tractogram

References

[Garyfallidis17]

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

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

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

Parameters

model_bundleStreamlines

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

pruned_streamlinesStreamlines

Recognized bundle from target tractogram by RecoBundles.

model_clust_thrfloat

MDF distance threshold for the model bundles

reduction_thrfloat

Reduce search space by (mm) (default 14)

reduction_distancestring

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

slrbool

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

slr_metric : BundleMinDistanceMetric slr_x0 : array or int or str

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

If 1D array with:

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

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

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

If int:

1. 6

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

2. 7

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

3. 12

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

If str:

1. “rigid”

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

2. “similarity”

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

3. “affine”

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

(default None)

slr_boundsarray

(default None)

slr_selecttuple

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

slr_methodstring

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

pruning_thrfloat

Pruning after reducing the search space (default 6).

pruning_distancestring

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

Returns

recognized_transfStreamlines

Recognized bundle in the space of the model tractogram

recognized_labelsarray

Indices of recognized bundle in the original tractogram

References

[Garyfallidis17]

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

[Chandio2020]

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

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

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

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.

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.

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.

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.

Bases: object

__init__()

abstract cluster(data, ordering=None)

Clusters data.

Subclasses will perform their clustering algorithm here.

Parameters

datalist of N-dimensional arrays

Each array represents a data point.

orderingiterable of indices, optional

Specifies the order in which data points will be clustered.

Returns

ClusterMap object

Result of the clustering.

Bases: Clustering

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

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

cluster(streamlines, ordering=None)

Clusters streamlines into bundles.

Performs quickbundles algorithm using predefined metric and threshold.

Parameters

streamlineslist of 2D arrays

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

orderingiterable of indices

Specifies the order in which data points will be clustered.

Returns

ClusterMapCentroid object

Result of the clustering.

Bases: Clustering

Clusters streamlines using QuickBundlesX.

Bases: ClusterCentroid

__init__(threshold, centroid, indices=None)

add(child)

property is_leaf

return_indices()

Bases: ClusterMap

__init__(root)

get_clusters(wanted_level)

iter_preorder(node)

property refdata

traverse_postorder(node, visit)

Bases: object

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

Fast Streamline Search (FFS)

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

Parameters

ref_streamlinesStreamlines

Streamlines (ref) to generate the tree structure.

max_radiusfloat

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

nb_mptsint, optional

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

bin_sizefloat, optional

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

resamplingint, optional

Number of points used to reshape each streamline.

bidirectionalbool, optional

Compute the smallest distance with and without flip.

Notes

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

References

[StOnge2022]

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

radius_search(streamlines, radius, use_negative=True)

Radius Search using Fast Streamline Search

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

Parameters

streamlinesStreamlines

Streamlines to generate the tree structure.

radiusfloat

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

use_negativebool, optional

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

Returns

resscipy COOrdinates sparse matrix (nb_slines x nb_slines_ref)

Adjacency matrix containing all neighbors within the given radius

Notes

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

References

[StOnge2022]

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

Bases: object

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

__init__(save_history=False, verbose=True)

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

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

Parameters

imagendarray,

3D structural image.

nclassesint,

number of desired classes.

betafloat,

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

tolerance: float,

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

max_iterfloat,

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

Returns

initial_segmentationndarray,

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

final_segmentationndarray,

3D final refined segmentation containing all tissue types.

PVEndarray,

3D probability map of each tissue type.