usage: __main__.py [-h] [--invalid IS.trk] [--ib IB/] [--wpc WPC/]
[--json_prefix p] [--part2_ROI_segmentation] [--gt_dir DIR]
[--indent INDENT] [--sort_keys] [--reference REFERENCE]
[--no_bbox_check] [-v [{DEBUG,INFO,WARNING,ERROR}]] [-f]
gt_config VB_folder
This script is intended to score all bundles from a single tractogram. Each
valid bundle is compared to its ground truth.
Ex: It was used for the ISMRM 2015 Challenge scoring.
Our bundle tractometry analysis scripts
---------------------------------------
- scil_bundle_pairwise_comparison:
- can compare any pair (any combo) from the input list.
- can compare the input list against a single file (--single_compare)
- scil_bundle_score_many_bundles_one_tractogram:
- scores files against their individual ground truth.
- scil_bundle_score_same_bundle_many_segmentations:
- compare many versions of a single bundle.
* If you have volumes associated to your bundles, the following script could be
of interest for you: scil_volume_pairwise_comparison
This script
-----------
We expect your tractogram to be already segmented into valid bundles.
See our scripts scil_tractogram_segment_with [...].
For usage in combination with scil_tractogram_segment_with_ROI_and_score, see
particular instructions below.
The easiest usage of this script requires:
- Having all bundles to be scored in a single folder.
- Creating a config file associating each input tractogram to its
reference tractogram.
>> scil_bundle_score_many_bundles_one_tractogram config_file VB_folder
Additionnaly, this script can include, in the output json, the percentage of
invalid streamlines (IS) or invalid bundles, using --is, --ib, etc.
Config file
-----------
The config file needs to be a json containing a dict of the ground-truth
bundles as keys. The value for each bundle is itself a dictionnary with the
path to reference bundles. The reference names must be included in the
segmented bundles' names. Ex: VB_folder/segmented_CC_subjX.trk.
Example config file:
{
"CC": "PATH/ref_grouth_truth_CC.nii.gz",
"OR_L": "PATH/ref_grouth_truth_OR_L.nii.gz",
}
* Files must be .tck, .trk, .nii or .nii.gz. If it is a tractogram, a mask will
be created. If it is a nifti file, it will be considered to be a mask.
Usage as part 2 of segment_with_ROI
-----------------------------------
This script can be used as the second part of script
>> scil_tractogram_segment_with_ROI_and_score
Then, we suppose that the bundles are already segmented and saved as follows:
root_dir/
segmented_VB/*_VS.trk.
segmented_IB/*_*_IC.trk (optional)
segmented_WPC/*_wpc.trk (optional)
IS.trk OR NC.trk (if segmented_IB is present)
Use option --part2_ROI_segmentation, and, as main input folder, give the
root_dir instead of the VB_folder. We will automatically set VB_folder, --is,
--vb and --wpc to follow this organization. Also, use the same config file as
in scil_tractogram_segment_with_ROI_and_score:
{
"Ground_truth_bundle_0": {
"gt_mask": "PATH/bundle0.nii.gz",
}
}
Tractometry
-----------
Global connectivity metrics:
- Computed by default:
- VS: valid streamlines, belonging to a bundle (i.e. respecting all the
criteria for that bundle; endpoints, limit_mask, gt_mask.).
- IS: invalid streamlines. All other streamlines. IS = IC + NC.
- Optional:
- WPC: wrong path connections, streamlines connecting correct ROIs but not
respecting the other criteria for that bundle. Such streamlines always
exist but they are only saved separately if specified in the options.
Else, they are merged back with the IS.
By definition. WPC are only computed if "limits masks" are provided.
- IC: invalid connections, streamlines joining an incorrect combination of
ROIs. Use carefully, quality depends on the quality of your ROIs and no
analysis is done on the shape of the streamlines.
- NC: no connections. Invalid streamlines minus invalid connections.
- Fidelity metrics:
- OL: Overlap. Percentage of ground truth voxels containing streamline(s)
for a given bundle.
- OR: Overreach. Amount of voxels containing streamline(s) when they
shouldn't, for a given bundle. We compute two versions :
OR_pct_vs = divided by the total number of voxel covered by the bundle.
(percentage of the voxels touched by VS).
Values range between 0 and 100%. Values are not defined when we
recovered no streamline for a bundle, but we set the OR_pct_vs to 0
in that case.
OR_pct_gt = divided by the total size of the ground truth bundle mask.
Values could be higher than 100%.
- f1 score: which is the same as the Dice score.
positional arguments:
gt_config .json config file configured as specified above.
VB_folder Directory containing all bundles to be scored.
(Ex: Output directory from scil_tractogram_segment_with_ROI_and_score
or from scil_tractogram_segment_with_bundleseg).
It is expected to contain a file IS.trk and
files segmented_VB/*_VS.trk, with, possibly, files
segmented_WPC/*_wpc.trk and segmented_IC/
options:
-h, --help show this help message and exit
--invalid IS.trk To include the percentage of invalid streamlines include your
invalid streamlines here (or no-connection streamlines).
--ib IB/ To include the percentage of invalid streamlines in each segmented invalid
bundle, add the path to your invalid bundles here.
--wpc WPC/ To include the percentage of wrong path streamlines for each valid bundle,
add the path to your WPC bundles here.
--json_prefix p Prefix of the output json file. Ex: 'study_x_'.
Suffix will be results.json. If the prefix does not contain a directory,
file will be saved inside your root directory.
--part2_ROI_segmentation
If set, configure everything to be used as part 2 of script
scil_tractogram_segment_with_ROI_and_score.
--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).
-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.
Additions to gt_config:
--gt_dir DIR Root path of the ground truth files listed in the gt_config.
If not set, filenames in the config file are considered
as absolute paths.
Json options:
--indent INDENT Indent for json pretty print.
--sort_keys Sort keys in output json.
2.2.2