usage: __main__.py [-h] [--volume OUT_FILE] [--streamline_count OUT_FILE]
[--length OUT_FILE] [--similarity IN_FOLDER OUT_FILE]
[--metrics IN_FILE OUT_FILE]
[--lesion_load IN_FILE OUT_DIR] [--include_dps OUT_DIR]
[--min_lesion_vol MIN_LESION_VOL] [--density_weighting]
[--no_self_connection]
[--force_labels_list FORCE_LABELS_LIST] [--processes NBR]
[-v [{DEBUG,INFO,WARNING,ERROR}]] [-f]
in_hdf5 in_labels
This script computes a variety of measures in the form of connectivity
matrices. This script only generates matrices in the form of array, it does not
visualize or reorder the labels (node).
See also
>> scil_connectivity_compute_simple_matrix
which simply computes the connectivity matrix (either binary or with the
streamline count), directly from the endpoints.
In comparison, the current script A) uses more complex segmentation, and
B) outputs more matrices, using various metrics,
A) Connections segmentations
----------------------------
Segmenting a tractogram based on its endpoints is not as straighforward as one
could imagine. The endpoints could be outside any labelled region. This script
is made to follow
>> scil_tractogram_segment_connections_from_labels,
which already carefully segmented the connections.
The current script uses 1) the same labels list as input, 2) the resulting
pre-segmented tractogram in the hdf5 format, and 3) a text file containing the
list of labels that should be part of the matrices. The ordering of labels in
the matrices will follow the same order as the list.
B) Outputs
----------
Each connection can be seen as a 'bundle'.
- Streamline count.
- Length: mean streamline length (mm).
Note that this matrix, as well as the volume-weighted, can be used to
normalize a streamline count matrix in scil_connectivity_normalize.
- Volume-weighted: Volume of the bundle.
- Similarity: mean density.
Uses pre-computed density maps, which can be obtained with
>> scil_connectivity_hdf5_average_density_map
The bundles should be averaged version in the same space. This will
compute the weighted-dice between each node and their homologuous average
version.
- Any metric: You can provide your own maps through --metrics. The average
non-zero value in the volume occupied by the bundle will be reported in
the matrices nodes.
Ex: --metrics FA.niigz fa.npy --metrics T1.nii.gz t1.npy
- Lesions-related metrics: The option --lesion_load will compute 3
lesion(s)-related matrices (saved in the chosen output directory):
lesion_count.npy, lesion_vol.npy, and lesion_sc.npy. They represent the
number of lesion, the total volume of lesion(s) and the total number of
streamlines going through the lesion(s) for each bundle. See also:
>> scil_analyse_lesion_load
>> scil_lesions_info
- Mean DPS: Mean values in the data_per_streamline of each streamline in the
bundles.
What next?
==========
See our other scripts to help you achieve your goals:
- Normalize a streamline-count matrix based on other matrices using
scil_connectivity_normalize.
- Compute a t-test between two groups of subjects using
scil_connectivity_compare_populations.
- See all our scripts starting with scil_connectivity_ for more ideas!
positional arguments:
in_hdf5 Input filename for the hdf5 container (.h5).
in_labels Labels file name (nifti).
This generates a NxN connectivity matrix, where N
is the number of values in in_labels.
options:
-h, --help show this help message and exit
--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.
Output matrices options:
--volume OUT_FILE Output file for the volume weighted matrix (.npy), computed in mm3.
--streamline_count OUT_FILE
Output file for the streamline count weighted matrix (.npy).
--length OUT_FILE Output file for the length weighted matrix (.npy), weighted in mm.
--similarity IN_FOLDER OUT_FILE
Input folder containing the averaged bundle density
maps (.nii.gz) and output file for the similarity weighted matrix (.npy).
The density maps should be named using the same labels as in the hdf5 (LABEL1_LABEL2.nii.gz).
--metrics IN_FILE OUT_FILE
Input (.nii.gz). and output file (.npy) for a metric weighted matrix.
--lesion_load IN_FILE OUT_DIR
Input binary mask (.nii.gz) and output directory for all lesion-related matrices.
--include_dps OUT_DIR
Save matrices from data_per_streamline in the output directory.
COMMIT-related values will be summed instead of averaged.
Will always overwrite files.
Processing options:
--min_lesion_vol MIN_LESION_VOL
Minimum lesion volume in mm3 [7].
--density_weighting Use density-weighting for the metric weighted matrix.
--no_self_connection Eliminate the diagonal from the matrices.
--force_labels_list FORCE_LABELS_LIST
Path to a labels list (.txt) in case of missing labels in the atlas.
2.2.2