`AFQ.segmentation`#

Module Contents#

Classes#

Segmentation

Functions#

`clean_bundle`(tg[, n_points, clean_rounds, ...])	Clean a segmented fiber group based on the Mahalnobis distance of
`clean_by_endpoints`(streamlines, targets0, targets1[, ...])	Clean a collection of streamlines based on their two endpoints

class AFQ.segmentation.Segmentation(nb_points=False, nb_streamlines=False, seg_algo='AFQ', reg_algo=None, clip_edges=False, parallel_segmentation={'n_jobs': -1, 'engine': 'joblib', 'backend': 'loky'}, progressive=True, greater_than=50, rm_small_clusters=50, model_clust_thr=1.25, reduction_thr=25, refine=False, pruning_thr=12, b0_threshold=50, prob_threshold=0, roi_dist_tie_break=False, dist_to_waypoint=None, rng=None, return_idx=False, presegment_bundle_dict=None, presegment_kwargs={}, filter_by_endpoints=True, dist_to_atlas=4, save_intermediates=None)[source]#

_read_tg(tg=None)[source]#

segment(bundle_dict, tg, fdata=None, fbval=None, fbvec=None, mapping=None, reg_prealign=None, reg_template=None, img_affine=None, reset_tg_space=False)[source]#

Segment streamlines into bundles based on either waypoint ROIs [Yeatman2012] or RecoBundles [Garyfallidis2017]. Parameters ———- bundle_dict: dict or AFQ.api.BundleDict

Meta-data for the segmentation. The format is something like::

{‘bundle_name’: {
‘include’:[img1, img2], ‘prob_map’: img3, ‘cross_midline’: False, ‘start’: img4, ‘end’: img5}}

tgStatefulTractogram: Bundles to segment
fdata, fbval, fbvecstr: Full path to data, bvals, bvecs
mappingDiffeomorphicMap object, str or nib.Nifti1Image, optional.: A mapping between DWI space and a template. If None, mapping will be registered from data used in prepare_img. Default: None.
reg_prealignarray, optional.: The linear transformation to be applied to align input images to the reference space before warping under the deformation field. Default: None.
reg_templatestr or nib.Nifti1Image, optional.: Template to use for registration. Default: MNI T2.
img_affinearray, optional.: The spatial transformation from the measurement to the scanner space.
reset_tg_spacebool, optional: Whether to reset the space of the input tractogram after segmentation is complete. Default: False.

Returns

dictWhere keys are bundle names, values are tractograms of: these bundles.

References

Yeatman2012: Yeatman, Jason D., Robert F. Dougherty, Nathaniel J.

Myall, Brian A. Wandell, and Heidi M. Feldman. 2012. “Tract Profiles of White Matter Properties: Automating Fiber-Tract Quantification” PloS One 7 (11): e49790. .. [R03e71c6d7dc6-Garyfallidis17] Garyfallidis et al. Recognition of white matter bundles using local and global streamline-based registration and clustering, Neuroimage, 2017.

prepare_img(fdata, fbval, fbvec)[source]#: Prepare image data from DWI data. Parameters ———- fdata, fbval, fbvec : str

Full path to data, bvals, bvecs

prepare_map(mapping=None, reg_prealign=None, reg_template=None)[source]#

Set mapping between DWI space and a template. Parameters ———- mapping : DiffeomorphicMap object, str or nib.Nifti1Image, optional.

A mapping between DWI space and a template. If None, mapping will be registered from data used in prepare_img. Default: None.

reg_templatestr or nib.Nifti1Image, optional.: Template to use for registration (defaults to the MNI T2) Default: None.
reg_prealignarray, optional.: The linear transformation to be applied to align input images to the reference space before warping under the deformation field. Default: None.

cross_streamlines(tg=None, template=None, low_coord=10)[source]#: Classify the streamlines by whether they cross the midline. Creates a crosses attribute which is an array of booleans. Each boolean corresponds to a streamline, and is whether or not that streamline crosses the midline. Parameters ———- tg : StatefulTractogram class instance. template : nibabel.Nifti1Image class instance

An affine transformation into a template space.

_get_bundle_info(bundle, vox_dim, tol)[source]#: Get fiber probabilites and ROIs for a given bundle.

_return_empty(bundle)[source]#: Helper function for segment_afq, to return an empty dict under some conditions.

segment_afq(tg=None)[source]#: Assign streamlines to bundles using the waypoint ROI approach Parameters ———- tg : StatefulTractogram class instance

move_streamlines(tg, reg_algo='slr')[source]#

Streamline-based registration of a whole-brain tractogram to the MNI whole-brain atlas.

registration_algostr: “slr” or “syn”

segment_reco(tg=None)[source]#

Segment streamlines using the RecoBundles algorithm [Garyfallidis2017] Parameters ———- tg : StatefulTractogram class instance

A whole-brain tractogram to be segmented.

Returns#

fiber_groupsdict: Keys are names of the bundles, values are Streamline objects. The streamlines in each object have all been oriented to have the same orientation (using dts.orient_by_streamline).

AFQ.segmentation.clean_bundle(tg, n_points=100, clean_rounds=5, distance_threshold=3, length_threshold=4, min_sl=20, stat='mean', return_idx=False)[source]#

Clean a segmented fiber group based on the Mahalnobis distance of each streamline

Parameters

tgStatefulTractogram class instance: A whole-brain tractogram to be segmented.
n_pointsint, optional: Number of points to resample streamlines to. Default: 100
clean_roundsint, optional.: Number of rounds of cleaning based on the Mahalanobis distance from the mean of extracted bundles. Default: 5
distance_thresholdfloat, optional.: Threshold of cleaning based on the Mahalanobis distance (the units are standard deviations). Default: 3.
length_threshold: float, optional: Threshold for cleaning based on length (in standard deviations). Length of any streamline should not be more than this number of stdevs from the mean length.
min_slint, optional.: Number of streamlines in a bundle under which we will not bother with cleaning outliers. Default: 20.
statcallable or str, optional.: The statistic of each node relative to which the Mahalanobis is calculated. Default: np.mean (but can also use median, etc.)
return_idxbool: Whether to return indices in the original streamlines. Default: False.
Returns
——-
A StatefulTractogram class instance containing only the streamlines
that have a Mahalanobis distance smaller than `clean_threshold` from
the mean of each one of the nodes.

AFQ.segmentation.clean_by_endpoints(streamlines, targets0, targets1, tol=None, atlas=None, flip_sls=None)[source]#

Clean a collection of streamlines based on their two endpoints Filters down to only include items that have their starting points close to the targets0 and ending points close to targets1 Parameters ———- streamlines : sequence of N by 3 arrays

Where N is number of nodes in the array, the collection of streamlines to filter down to.

targets0, target1: sequences or Nx3 arrays or None.: The targets. Numerical values in the atlas array for targets for the first and last node in each streamline respectively, or NX3 arrays with each row containing the indices for these locations in the atlas. If provided a None, this means no restriction on that end.
tolfloat, optional A distance tolerance (in units that the coordinates: of the streamlines are represented in). Default: 0, which means that the endpoint is exactly in the coordinate of the target ROI.
atlas3D array or Nifti1Image class instance with a 3D array, optional.: Contains numerical values for ROIs. Default: if not provided, assume that targets0 and targets1 are both arrays of indices, and this information is not needed.
flip_sls1d array, optional: Length is len(streamlines), whether to flip the streamline.

Yields#

Generator of the indicies into streamlines that survive cleaning.

AFQ.segmentation#