.. _scil_tractogram_segment_connections_from_labels: scil_tractogram_segment_connections_from_labels =============================================== :: usage: __main__.py [-h] [--no_pruning] [--no_remove_loops] [--no_remove_outliers] [--no_remove_curv_dev] [--min_length MIN_LENGTH] [--max_length MAX_LENGTH] [--outlier_threshold OUTLIER_THRESHOLD] [--loop_max_angle LOOP_MAX_ANGLE] [--curv_qb_distance CURV_QB_DISTANCE] [--out_dir OUT_DIR] [--save_raw_connections] [--save_intermediate] [--save_discarded] [--save_final] [--out_labels_list OUT_FILE] [--reference REFERENCE] [--no_bbox_check] [--processes NBR] [-v [{DEBUG,INFO,WARNING,ERROR}]] [-f] in_tractograms [in_tractograms ...] in_labels out_hdf5 Divide a tractogram into its various connections using a brain parcellation (labels). Allows using our connectivity scripts. See for instance: >>> scil_connectivity_compute_matrices The hdf5 output format allows to store other information required for connectivity, such as the associated labels. To visualize the segmented bundles, it is possible to convert the result using: >>> scil_tractogram_convert_hdf5_to_trk Cleaning your tractogram ------------------------ Outliers may influence strongly the connectivity analysis. We recommand cleaning your tractogram as much as possible beforehand. Options are offered in this script and are activated by default. For the --outlier_threshold option, the default is our recommended trade-off for a good freesurfer parcellation. With smaller parcels (brainnetome, glasser) the threshold should most likely be reduced. See also: - scil_tractogram_filter_by_anatomy - scil_tractogram_filter_by_length - scil_tractogram_filter_by_roi - scil_tractogram_detect_loops The segmentation process ------------------------ Segmenting a tractogram based on its endpoints is not as straighforward as one could imagine. The endpoints could be outside any labelled region. The current strategy is to keep the longest streamline segment connecting 2 regions. If the streamline crosses other gray matter regions before reaching its final connected region, the kept connection is still the longest. This is robust to compressed streamlines. NOTE: this script can take a while to run. Please be patient. Example: on a tractogram with 1.8M streamlines, running on a SSD: - 15 minutes without post-processing, only saving final bundles. - 30 minutes with full post-processing, only saving final bundles. - 60 minutes with full post-processing, saving all possible files. Verifying the results --------------------- Good candidate connections to use for quality control (QC) are 1) the brainstem to precentral gyrus connection and 2) the precentral left to precentral right connection, or equivalent in your parcellation. Note that the final streamlines saved in the hdf5 are cut between the two associated labels (points after the ROIs are removed, if any). The output hdf5 architecture (nerdy stuff) ---------------------------- The output file is a hdf5 (.h5) where each bundle is a group with key 'LABEL1_LABEL2' and each. The array_sequence format cannot be stored directly in a hdf5, so each group is composed of 'data', 'offsets' and 'lengths' from the array_sequence. The 'data' is stored in VOX/CORNER for simplicity and efficiency. positional arguments: in_tractograms Tractogram filename (s). Format must be one of trk, tck, vtk, fib, dpy. If you have many tractograms for a single subject (ex, coming from Ensemble Tracking), we will merge them together. in_labels Labels file name (nifti). Labels must have 0 as background. Volumes must have isotropic voxels. out_hdf5 Output hdf5 file (.h5). options: -h, --help show this help message and exit --out_labels_list OUT_FILE Save the labels list as text file. Needed for scil_connectivity_compute_matrices and others. --reference REFERENCE Reference anatomy for tck/vtk/fib/dpy file support (.nii or .nii.gz). --no_bbox_check Activate to ignore validity of the bounding box during loading / saving of tractograms (ignores the presence of invalid streamlines). --processes NBR Number of sub-processes to start. Default: [1] -v [{DEBUG,INFO,WARNING,ERROR}] Produces verbose output depending on the provided level. Default level is warning, default when using -v is info. -f Force overwriting of the output files. Post-processing options: --no_pruning If set, will NOT prune on length. Length criteria in --min_length, --max_length. --no_remove_loops If set, will NOT remove streamlines making loops. Angle criteria based on --loop_max_angle. --no_remove_outliers If set, will NOT remove outliers using QB. Criteria based on --outlier_threshold. --no_remove_curv_dev If set, will NOT remove streamlines that deviate from the mean curvature. Threshold based on --curv_qb_distance. Pruning options: --min_length MIN_LENGTH Pruning minimal segment length. [20.0] --max_length MAX_LENGTH Pruning maximal segment length. [200.0] Outliers and loops options: --outlier_threshold OUTLIER_THRESHOLD Outlier removal threshold when using hierarchical QB. [0.6] --loop_max_angle LOOP_MAX_ANGLE Maximal winding angle over which a streamline is considered as looping. [330.0] --curv_qb_distance CURV_QB_DISTANCE Clustering threshold for centroids curvature filtering with QB. [10.0] Saving options: --out_dir OUT_DIR Output directory for each file based on options below, as separate files (.trk). --save_raw_connections If set, will save all raw cut connections in a subdirectory. --save_intermediate If set, will save the intermediate results of filtering. --save_discarded If set, will save discarded streamlines in subdirectories. Includes loops, outliers and qb_loops. --save_final If set, will save the final bundles (connections) on disk (.trk) as well as in the hdf5. If this is not set, you can also get the final bundles later, using: scil_tractogram_convert_hdf5_to_trk. 2.2.2