scilpy.segment package

scilpy.segment.bundleseg module

class scilpy.segment.bundleseg.BundleSeg(memmap_filenames, transformation, 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 logger. However, in essence they do the same thing. https://github.com/nipy/dipy/blob/master/dipy/segment/bundles.py

References

[1] Garyfallidis et al. Recognition of white matter

bundles using local and global streamline-based registration and clustering, Neuroimage, 2017.

cleanup()

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

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)

Finds streamlines that respect some criteria in a ROI, where the ROI is a bounding box of cuboid type.

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, in RASMM space, center origin.

• 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).

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)

Finds streamlines that respect some criteria in a ROI, where the ROI is a bounding box of ellipsoid type.

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, in RASMM space, center origin.

• 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)

Filters streamlines based on a given criteria (any, all, either_end, both_ends).

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_ends(sft, mask_1, mask_2)

Filters streamlines with one end in a mask and the other in another mask. See also filter_grid_roi, but here we may give two different masks for the endpoints.

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.streamlines_in_mask(sft, target_mask, all_in=False)

Finds the streamlines that are either touching a mask (if all_in=False) or entirely contained in the mask (if all_in=True).

Parameters:

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

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

• all_in (bool) – If true, finds streamlines satisfying the ‘all’ criteria. Else, finds streamlines satisfying the ‘any’ criteria.

Returns:

ids – Ids of the streamlines passing the test.

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)

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.

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, all_masks, any_masks, out_dir, compute_ic=False, save_wpc_separately=False, unique=True, remove_wpc_belonging_to_another_bundle=True, no_empty=True, bbox_check=True, dilate_endpoints=0)

Segments valid bundles (VB).

Parameters:

• sft (StatefulTractogram) – The tractogram to segment.

• gt_tails (list[str]) – List of filenames, each VB endpoint mask (first end)

• gt_heads (list[str]) – List of filenames, each VB endpoint mask (second end), in the same order as gt_tails. Ex, VB #2 uses gt_tails[2] and gt_head[2] as endpoints.

• bundle_names (list[str]) – Bundle names.

• bundle_lengths (list[[float, float] or None]) – Maximum length for each bundle. Either a limit range, [float, float] or None for no limit.

• angles (list[float]) – Maximum angle (in loops) for each bundle (in degree).

• orientation_lengths (list[[limitsx, limitsy, limitsz] or None]) – For each bundle, the length parameters in each direction: [[min_x, max_x], [min_y, max_y], [min_z, max_z]]. None for no limit.

• abs_orientation_lengths (list[[limitsx, limitsy, limitsz] or None]) – Idem, computed in absolute values.

• all_masks (list[np.ndarray or None]) – For each bundle, the “ALL” mask for this bundle: no point must be outside the mask.

• any_masks (list[np.ndarray or None]) – For each bundle, the “ANY” mask for this bundle: at least one point must pass through this mask.

• out_dir (str) – Output directory. We will save all VB, IC and WPC there.

• compute_ic (bool) – Also compute invalid connections (IC).

• save_wpc_separately (bool) – Separate wrong path connections (WPC) from other invalid connections (IC). WPC = correct endpoint ROIs but wrong path based on other criteria.

• unique (bool) – If True, streamlines are assigned to the first bundle they fit in and not to all.

• remove_wpc_belonging_to_another_bundle (bool) – If true, WPC actually belonging to any VB (in the case of overlapping ROIs) will be removed from the WPC classification.

• no_empty (bool) – If true, do not save empty bundles.

• bbox_check (bool) – If true, check bounding box validation.

• dilate_endpoints (int) – Dilate endpoint masks n-times. Default: 0.

Returns:

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

• wpc_sft_list (list[StatefulTractogram or None] or None) – The list of wrong path connections: streamlines connecting the right endpoint regions but not included in the ALL mask. This list has the same length as vb_sft_list. ** This is only computed if save_wpc_separately. Else, this is None.

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

• nc_sft_list (list[StatefulTractogram] or None) – The list of rejected streamlines that were not included in any IB.

• ib_names (list[StatefulTractogram] or None) – 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, save_empty=False, ignore_metadata=False)

Bases: object

scilpy.segment.voting_scheme.single_recognize(args)

Recobundle for a single bundle.

Parameters:

• bsg (Object) – Initialize BundleSeg 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:

transf_neighbor –

bundle_id(int)

Unique value to each bundle to identify them.

recognized_indices(numpy.ndarray)

Streamlines indices from the original tractogram.

recognized_scores(numpy.ndarray)

Scores of the recognized streamlines.

Return type:

tuple

scilpy.segment.voting_scheme.single_recognize_parallel(args)

Wrapper function to multiprocess recobundles execution.