usage: __main__.py [-h] [--drawn_roi DRAWN_ROI [DRAWN_ROI ...]]
[--atlas_roi ATLAS_ROI [ATLAS_ROI ...]]
[--bdo BDO [BDO ...]] [--x_plane X_PLANE [X_PLANE ...]]
[--y_plane Y_PLANE [Y_PLANE ...]]
[--z_plane Z_PLANE [Z_PLANE ...]]
[--filtering_list FILTERING_LIST]
[--overwrite_distance OVERWRITE_DISTANCE [OVERWRITE_DISTANCE ...]]
[--save_masks_atlas_roi SAVE_MASKS_ATLAS_ROI] [--no_empty]
[--display_counts] [--save_rejected FILENAME]
[--indent INDENT] [--sort_keys] [--reference REFERENCE]
[-v [{DEBUG,INFO,WARNING}]] [-f]
in_tractogram out_tractogram
Filtering of a tractogram based on any combination of conditions involving a
ROI (ex: keep streamlines whose endoints are inside the ROI, exclude
streamlines not entirely included in a ROI, etc.)
See also:
- scil_tractogram_detect_loops.py
- scil_tractogram_filter_by_anatomy.py
(Can reject streamlines with endpoints in the WM or the CSF based on
labels)
- scil_tractogram_filter_by_length.py
- scil_tractogram_filter_by_orientation.py
Condition
---------
For every type of ROI, two or three values are expected: MODE CRITERIA DISTANCE
(DISTANCE is always optional)
- MODE must be one of these values: ['any', 'all', 'either_end', 'both_ends']
- any: any part of the streamline must be in the mask
- all: all parts of the streamline must be in the mask.
- either_end: at least one end of the streamline must be in the mask.
- both_ends: both ends of the streamline must be in the mask.
- CRITERIA must be one of these values: ['include', 'exclude']
- Include: If condition from MODE is respected, streamline is included.
- Exlucde: If condition from MODE is respected, streamline is excluded.
- DISTANCE must be an int and is optional.
Type of ROI
-----------
- Drawn ROI: Directly loaded from a binary file.
- Atlas ROI: Selected label from an atlas.
- ID is one or multiple integer values in the atlas. If multiple values,
ID needs to be between quotes.
Example: "1:6 9 10:15" will use values between 1 and 6 and values
between 10 and 15 included as well as value 9.
- BDO: The ROI is the interior of a bounding box.
- Planes: The ROI is the equivalent of a one-voxel plane.
* Using mode 'all' with x/y/z plane works but makes very little sense.
Note: `--drawn_roi MASK.nii.gz all include` is equivalent to
`--drawn_roi INVERSE_MASK.nii.gz any exclude`
For example, this allows to find out all streamlines entirely in the WM in one
command (without manually inverting the mask first) or to remove any streamline
staying in the GM without getting out.
Supports multiple filtering conditions
--------------------------------------
Multiple filtering conditions can be used, with varied ROI types if necessary.
Combining two conditions is equivalent to a logical AND between the conditions.
Order of application does not matter for the final result, but may change the
intermediate files, if any.
Distance management
-------------------
DISTANCE is optional, and it should be used carefully with large voxel size
(e.g > 2.5mm). The value is in voxel for ROIs and in mm for bounding boxes.
Anisotropic data will affect each direction differently.
When using --overwrite_distance, any filtering option with given criteria
will have its DISTANCE value replaced.
Usage examples:
---------------
- Filter out "bad streamlines" that have points out of the brain mask.
>>> scil_tractogram_filter_by_roi.py my_tractogram.trk bettter_tractogram.trk --drawn_roi t1_bet_mask.nii.gz 'all' 'include'
- Segment a bundle or reject outliers from a roughly segmented bundles by
keeping only streamlines connecting region1 and region2 and entirely situated
in the frontal part of the brain, not touching some lesion ROI.
>>> scil_tractogram_filter_by_roi.py my_tractogram.trk segmented_bundle.trk --drawn_roi region1.nii.gz 'either_end' 'include' --drawn_roi region2.nii.gz 'either_end' 'include' --drawn_roi frontal_lobe.nii.gz 'all' 'include' --drawn_roi lesion.nii.gz 'any' 'exclude'
Formerly: scil_filter_tractogram.py
positional arguments:
in_tractogram Path of the input tractogram file.
out_tractogram Path of the output tractogram file.
options:
-h, --help show this help message and exit
--drawn_roi DRAWN_ROI [DRAWN_ROI ...]
ROI_NAME MODE CRITERIA DISTANCE (distance in voxel is optional)
Filename of a hand drawn ROI (.nii or .nii.gz).
--atlas_roi ATLAS_ROI [ATLAS_ROI ...]
ATLAS_NAME ID MODE CRITERIA DISTANCE (distance in voxel is optional)
Filename of an atlas (.nii or .nii.gz).
--bdo BDO [BDO ...] BDO_NAME MODE CRITERIA DISTANCE (distance in mm is optional)
Filename of a bounding box (bdo) file from MI-Brain.
--x_plane X_PLANE [X_PLANE ...]
PLANE MODE CRITERIA DISTANCE (distance in voxel is optional)
Slice number in X, in voxel space.
--y_plane Y_PLANE [Y_PLANE ...]
PLANE MODE CRITERIA DISTANCE (distance in voxel is optional)
Slice number in Y, in voxel space.
--z_plane Z_PLANE [Z_PLANE ...]
PLANE MODE CRITERIA DISTANCE (distance in voxel is optional)
Slice number in Z, in voxel space.
--filtering_list FILTERING_LIST
Text file containing one rule per line
(i.e. drawn_roi mask.nii.gz both_ends include 1).
--overwrite_distance OVERWRITE_DISTANCE [OVERWRITE_DISTANCE ...]
MODE CRITERIA DISTANCE (distance in voxel for ROIs and in mm for bounding box).
If set, it will overwrite the distance associated to a specific mode/criteria.
--save_masks_atlas_roi SAVE_MASKS_ATLAS_ROI
If set, will save the atlas roi masks. The value to provide is the
prefix, ex: my_path/atlas_roi_. Whole filename will be
my_path/atlas_roi_{id}.nii.gz
--no_empty Do not write file if there is no streamline.
--display_counts Print streamline count before and after filtering
--save_rejected FILENAME
Save rejected streamlines to output tractogram.
--reference REFERENCE
Reference anatomy for tck/vtk/fib/dpy file
support (.nii or .nii.gz).
-v [{DEBUG,INFO,WARNING}]
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.
Json options:
--indent INDENT Indent for json pretty print.
--sort_keys Sort keys in output json.
Scilpy version: 2.0.2