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