scilpy.segment package

scilpy.segment.models module

scilpy.segment.models.remove_similar_streamlines(streamlines, threshold=5)

Remove similar streamlines, shuffling streamlines will impact the results. Only provide a small set of streamlines (below 2000 if possible).

Parameters:

• streamlines (list of numpy.ndarray) – Input streamlines to remove duplicates from.

• threshold (float) – Distance threshold to consider two streamlines similar, in mm.

Returns:

streamlines

Return type:

list of numpy.ndarray

scilpy.segment.recobundlesx module

class scilpy.segment.recobundlesx.RecobundlesX(memmap_filenames, clusters_indices, wb_centroids, rng=None)

Bases: object

This class is a ‘remastered’ version of the Dipy Recobundles class. Made to be used in sync with the voting_scheme. Adapted in many way for HPC processing and increase control over parameters and logging. However, in essence they do the same thing. https://github.com/nipy/dipy/blob/master/dipy/segment/bundles.py

References

[Garyfallidis17]

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

cleanup()

get_final_pruned_indices()

Public getter for the final indices recognize by the algorithm.

prune_far_from_model(pruning_thr=10)

Wrapper function to prune clusters from the tractogram too far from the model.

Parameters:

pruning_thr (float, distance in) – thresholds = [32, 16, 24, neighbors_cluster_thr]

recognize(model_bundle, model_clust_thr=8, pruning_thr=8, slr_transform_type='similarity', identifier=None)

Parameters:

• model_bundle (list or ArraySequence) – Model bundle as loaded by the nibabel API.

• model_clust_thr (obj) – Distance threshold (mm) for model clustering (QBx)

• pruning_thr (int) – Distance threshold (mm) for the final pruning.

• slr_transform_type (str) – Define the transformation for the local SLR. [translation, rigid, similarity, scaling]

• identifier (str) – Identify the current bundle being recognized for the logging.

Returns:

clusters – Streamlines that were recognized by Recobundles and these parameters.

Return type:

list

scilpy.segment.streamlines module

scilpy.segment.streamlines.filter_cuboid(sft, cuboid_radius, cuboid_center, filter_type, is_exclude)

Parameters:

• sft (StatefulTractogram) – StatefulTractogram containing the streamlines to segment.

• cuboid_radius (numpy.ndarray (3)) – Size in mm, x/y/z of the cuboid.

• cuboid_center (numpy.ndarray (3)) – Center x/y/z of the cuboid.

• filter_type (str) – One of the 4 following choices: ‘any’, ‘all’, ‘either_end’, ‘both_ends’.

• is_exclude (bool) – Value to indicate if the ROI is an AND (false) or a NOT (true).

• is_in_vox (bool) – Value to indicate if the ROI is in voxel space.

Returns:

• ids (list) – Ids of the streamlines passing through the mask.

• sft (StatefulTractogram) – Filtered sft

scilpy.segment.streamlines.filter_ellipsoid(sft, ellipsoid_radius, ellipsoid_center, filter_type, is_exclude, is_in_vox=False)

Parameters:

• sft (StatefulTractogram) – Tractogram containing the streamlines to segment.

• ellipsoid_radius (numpy.ndarray (3)) – Size in mm, x/y/z of the ellipsoid.

• ellipsoid_center (numpy.ndarray (3)) – Center x/y/z of the ellipsoid.

• filter_type (str) – One of the 4 following choices, ‘any’, ‘all’, ‘either_end’, ‘both_ends’.

• is_exclude (bool) – Value to indicate if the ROI is an AND (false) or a NOT (true).

• is_in_vox (bool) – Value to indicate if the ROI is in voxel space.

Returns:

• ids (list) – Ids of the streamlines passing through the mask.

• sft (StatefulTractogram) – Filtered sft

scilpy.segment.streamlines.filter_grid_roi(sft, mask, filter_type, is_exclude, filter_distance=0, return_sft=False, return_rejected_sft=False)

Parameters:

• sft (StatefulTractogram) – Tractogram containing the streamlines to segment.

• mask (numpy.ndarray) – Binary mask in which the streamlines should pass.

• filter_type (str) –

  One of the 4 following choices:

  ’any’, ‘all’, ‘either_end’, ‘both_ends’

• is_exclude (bool) – Value to indicate if the ROI is an AND (false) or a NOT (true).

• filter_distance (int) – The number of passes for dilation.

• return_sft (bool) – If true, returns a StatefulTractogram rather than the list of indices.

• return_rejected_sft (bool) – If true, also returns a StatefulTractogram of the rejected streamlines. (Only if return_sft also true).

Returns:

• list of ids (list or StatefulTractogram) – Ids of the streamlines passing through the mask.

• new_sft (StatefulTractogram) – Filtered sft (if return_sft)

• rejected (StatefulTractogram) – sft of rejected streamlines (if return_rejected_sft)

scilpy.segment.streamlines.filter_grid_roi_both(sft, mask_1, mask_2)

Filters streamlines with one end in a mask and the other in another mask.

Parameters:

• sft (StatefulTractogram) – StatefulTractogram containing the streamlines to segment.

• mask_1 (numpy.ndarray) – Binary mask in which the streamlines should start or end.

• mask_2 (numpy.ndarray) – Binary mask in which the streamlines should start or end.

Returns:

• new_sft (StatefulTractogram) – Filtered sft.

• ids (list) – Ids of the streamlines passing through the mask.

scilpy.segment.streamlines.pre_filtering_for_geometrical_shape(sft, size, center, filter_type, is_in_vox)

Parameters:

• sft (StatefulTractogram) – Tractogram containing the streamlines to segment.

• size (numpy.ndarray (3)) – Size in mm, x/y/z of the ROI.

• center (numpy.ndarray (3)) – Center x/y/z of the ROI.

• filter_type (str) – One of the 4 following choices, ‘any’, ‘all’, ‘either_end’, ‘both_ends’.

• is_in_vox (bool) – Value to indicate if the ROI is in voxel space.

Returns:

• ids (list) – Ids of the streamlines passing through the mask.

• sft (StatefulTractogram) – Filtered sft

scilpy.segment.streamlines.streamlines_in_mask(sft, target_mask, all_in=False)

Parameters:

• sft (StatefulTractogram) – StatefulTractogram containing the streamlines to segment.

• target_mask (numpy.ndarray) – Binary mask in which the streamlines should pass.

Returns:

ids – Ids of the streamlines passing through the mask.

Return type:

list

scilpy.segment.tractogram_from_roi module

scilpy.segment.tractogram_from_roi.compute_endpoint_masks(roi_options, out_dir)

If endpoints without heads/tails are loaded, split them and continue normally after. Q/C of the output is important. Compatibility between files should be already verified.

Parameters:

• roi_options (dict) – Keys are the bundle names. For each bundle, the value is itself a dictionary either key ‘gt_endpoints’ (the name of the file containing the bundle’s endpoints), or both keys ‘gt_tail’ and ‘gt_head’ (the names of the respetive files).

• out_dir (str) – Where to save the heads and tails.

Returns:

tails, heads

Return type:

lists of filenames with length the number of bundles.

scilpy.segment.tractogram_from_roi.compute_masks_from_bundles(gt_files, parser, args, inverse_mask=False)

Compute ground-truth masks. If the file is already a mask, load it. If it is a bundle, compute the mask. If the filename is None, appends None to the lists of masks. Compatibility between files should already be verified.

Parameters:

• gt_files (list) – List of either StatefulTractograms or niftis.

• parser (ArgumentParser) – Argument parser which handles the script’s arguments. Used to print parser errors, if any.

• args (Namespace) – List of arguments passed to the script. Used for its ‘ref’ and ‘bbox_check’ arguments.

• inverse_mask (bool) – If true, returns the list of inversed masks instead.

Returns:

mask – The loaded masks.

Return type:

list[numpy.ndarray]

scilpy.segment.tractogram_from_roi.segment_tractogram_from_roi(sft, gt_tails, gt_heads, bundle_names, bundle_lengths, angles, orientation_lengths, abs_orientation_lengths, inv_all_masks, any_masks, list_rois, args)

Segments valid bundles (VB). Based on args: - args.compute_ic: computes invalid bundles (IB) - args.save_wpc_separately: compute WPC

Returns:

• vb_sft_list (list) – The list of valid bundles discovered. These files are also saved in segmented_VB/*_VS.trk.

• wpc_sft_list (list) – The list of wrong path connections: streamlines connecting the right endpoint regions but not included in the ALL mask. ** This is only computed if args.save_wpc_separately. Else, this is None.

• ib_sft_list (list) – The list of invalid bundles: streamlines connecting regions that should not be connected. ** This is only computed if args.compute_ic. Else, this is None.

• nc_sft_list (list) – The list of rejected streamlines that were not included in any IB.

• ib_names (list) – The list of names for invalid bundles (IB). They are created from the combinations of ROIs used for IB computations.

• bundle_stats (dict) – Dictionnary of the processing information for each VB bundle.

scilpy.segment.voting_scheme module

class scilpy.segment.voting_scheme.VotingScheme(config, atlas_directory, transformation, output_directory, minimal_vote_ratio=0.5)

Bases: object

scilpy.segment.voting_scheme.single_recognize(rbx, model_filepath, model_bundle, bundle_pruning_thr, bundle_names, seed)

Recobundle for a single bundle.

Parameters:

• rbx (Object) – Initialize RBx object with QBx ClusterMap as values

• model_filepath (str) – Path to the model bundle file

• model_bundle (ArraySequence) – Model bundle.

• bundle_pruning_thr (float) – Threshold for pruning the model bundle

• bundle_names (list) – List of string with bundle names for models (to get bundle_id)

• seed (int) – Value to initialize the RandomState of numpy

Returns:

• bundle_id (int) – Unique value to each bundle to identify them.

• recognized_indices (numpy.ndarray) – Streamlines indices from the original tractogram.

scilpy.segment.voting_scheme.single_recognize_parallel(args)

Wrapper function to multiprocess recobundles execution.