Segmentation Parameters#

This page documents the configuration options for controlling bundle recognition in pyAFQ. These parameters can be passed directly when using the CLI or passed as arguments when using the API.

Example Usage#

from AFQ.api.group import GroupAFQ
import AFQ.data.fetch as afd
import os.path as op

afd.organize_stanford_data()

myafq = GroupAFQ(
    bids_path=op.join(afd.afq_home, 'stanford_hardi'),
    preproc_pipeline='vistasoft',
    segmentation_params=dict(
        dist_to_waypoint=10,
        dist_to_atlas=10)
    )

Segmentation Parameter Reference#

AFQ.recognition.recognize.recognize(tg, img, mapping, bundle_dict, reg_template, nb_points=False, nb_streamlines=False, clip_edges=False, clean_unclipped=False, rb_recognize_params=None, refine_reco=False, prob_threshold=0, dist_to_waypoint=0, rng=None, return_idx=False, filter_by_endpoints=True, dist_to_atlas=4, save_intermediates=None, cleaning_params=None, chunk_size=1000000)[source]

Segment streamlines into bundles.

Parameters:

tgStatefulTractogram, or path to a TRXfile: Tractogram to segment.
imgstr, nib.Nifti1Image: Image for reference.
mappingMappingDefinition: Mapping from subject to template.
bundle_dictdict or AFQ.api.BundleDict: Dictionary of bundles to segment.
reg_templatestr, nib.Nifti1Image: Template image for registration.
nb_pointsint, boolean: Resample streamlines to nb_points number of points. If False, no resampling is done. Can only be done on a StatefulTractogram. Default: False
nb_streamlinesint, boolean: Subsample streamlines to nb_streamlines. Can only be done on a StatefulTractogram. If False, no subsampling is done. Default: False
clip_edgesbool: Whether to clip the streamlines to be only in between the ROIs. Default: False
clean_unclippedbool: Whether to use the unclipped streamlines when cleaning. Only considered if clip_edges is True or bundlesection is in the bundle_dict. Default: False
rb_recognize_paramsdict: RecoBundles parameters for the recognize function. Default: None
refine_recobool: Whether to refine the RecoBundles segmentation. Default: False
prob_thresholdfloat.: Using AFQ Algorithm. Initial cleaning of fiber groups is done using probability maps from [Hua2008]. Here, we choose an average probability that needs to be exceeded for an individual streamline to be retained. Default: 0.
dist_to_waypointfloat.: The distance that a streamline node has to be from the waypoint ROI in order to be included or excluded. If a bundle has inc_addtol or exc_addtol in its bundle_dict, that tolerance will be added to this distance. For example, if you wanted to increase tolerance for the right arcuate waypoint ROIs by 3 each, you could make the following modification to your bundle_dict: bundle_dict[“Right Arcuate”][“inc_addtol”] = [3, 3] Additional tolerances can also be negative. Default: 0.
rngRandomState or int: If None, creates RandomState. If int, creates RandomState with seed rng. Used in RecoBundles Algorithm. Default: None.
return_idxbool: Whether to return the indices in the original streamlines as part of the output of segmentation. Default: False.
filter_by_endpoints: bool: Whether to filter the bundles based on their endpoints. Default: True.
dist_to_atlasfloat: If filter_by_endpoints is True, this is the required distance from the endpoints to the atlas ROIs. Default: 4
save_intermediatesstr, optional: The full path to a folder into which intermediate products are saved. If None, means no saving of intermediates. Default: None.
cleaning_paramsdict, optional: Cleaning params to pass to seg.clean_bundle. This will override the default parameters of that method. However, this can be overridden by setting the cleaning parameters in the bundle_dict. Default: None.
chunk_sizeint, optional: Number of streamlines to preprocess at a time. The full tractogram is processed in chunks of this size to keep peak memory bounded. Per-chunk surviving candidates are merged before the global per-bundle filtering steps run. Default: int(1e6).

References

[Hua2008]

Hua K, Zhang J, Wakana S, Jiang H, Li X, et al. (2008) Tract probability maps in stereotaxic spaces: analyses of white matter anatomy and tract-specific quantification. Neuroimage 39: 336-347

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

[Garyfallidis2018]

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