usage: __main__.py [-h] --in_bundles IN_BUNDLES [IN_BUNDLES ...]
[--in_bundles_names IN_BUNDLES_NAMES [IN_BUNDLES_NAMES ...]]
[--dps_key DPS_KEY] [--max_theta MAX_THETA]
[--abs_thr ABS_THR] [--rel_thr REL_THR]
[--norm {fixel,voxel,none} [{fixel,voxel,none} ...]]
[--split_bundles] [--split_fixels] [--single_bundle]
[--out_dir OUT_DIR] [--prefix PREFIX] [--suffix SUFFIX]
[-f] [--processes NBR] [-v [{DEBUG,INFO,WARNING}]]
in_peaks
Analyze bundles at the fixel level using peaks and bundles (.trk). If the
bundles files are names as {bundle_name}.trk, simply use the --in_bundles
argument without --in_bundles_names. If it is not the case or you want other
names to be saved, please use --in_bundles_names to provide bundles names
IN THE SAME ORDER as the inputed bundles.
The duration of the script depends heavily on the number of bundles, the number
of streamlines in bundles and the number of processors used. For a standard
tractoflow/rbx_flow output with ~30 bundles, it should not take over 30
minutes.
The script produces various output:
- bundles_LUT.txt : array of (N) bundle names
Lookup table (LUT) to know the order of the bundles in the various
outputs. When an output contains results for all bundles, it is always
the last dimension of the np.ndarray and it follows the order of the
lookup table.
- fixel_density_maps : np.ndarray (x, y, z, 5, N)
For each voxel, it gives the density of bundles associated with each
of the 5 fixels. If the normalization is chosen as the voxel-type, then
the sum of the density over a voxel is 1. If the normalization is chosen
as the fixel-type, then the sum of the density over each fixel is 1, so
the sum over a voxel will be higher than 1 (except in the single-fiber
case). If the normalization if chosen as none, no normalization is done.
This can be useful to keep the information un-normalized.
The density maps can be computed using the streamline count, or
any streamline weighting like COMMIT or SIFT, through the
data_per_streamline using the --dps_key argument. NOTE: This is a 5D file
that will not be easily inputed to a regular viewer. Use --split_bundles
or --split_fixels options to save the 4D versions for visualization.
- fixel_density_masks : np.ndarray (x, y, z, 5, N)
For each voxel, it gives whether or not each bundle is associated
with each of the 5 fixels. In other words, it is a masked version of
fixel_density_maps, using two different thresholds. First, the absolute
threshold (abs_thr) is applied on the maps before the normalization,
either on the number of streamlines or the streamline weights. Second,
after the normalization, the relative threshold (rel_thr) is applied on
the maps as a minimal value of density to be counted as an association.
This does nothing if the normalization is set to none.
NOTE: This is a 5D file that will not be easily inputed to a regular
viewer. Use --split_bundles or --split_fixels options to save the 4D
versions for visualization.
- voxel_density_maps : np.ndarray (x, y, z, N)
For each voxel, it gives the density of each bundle within the voxel,
regardless of fixels. In other words, it gives the fraction of each
bundle per voxel. This is only outputed if the normalization of the maps
is chosen as the voxel-type or none-type, because the fixel-type does not
translate to meaningful results when summed into a voxel.
- voxel_density_masks: np.ndarray (x, y, z, N)
For each voxel, it gives whether or not each bundle is present. This is
computed from fixel_density_masks, so the same thresholds prevail.
- nb_bundles_per_fixel : np.ndarray (x, y, z)
For each voxel, it gives the number of bundles associated with each of
the 5 fixels.
- nb_bundles_per_voxel : np.ndarray (x, y, z)
For each voxel, it gives the number of bundles within the voxel. This
accounts for bundles that might be associated with more than one fixel,
so no bundle is counted more than once in a voxel.
If more than one normalization type is given, every output will be computed
for each normalization. In any case, the normalization type is added after
the basename of the output, such as fixel_density_maps_voxel-norm.
If the split_bundles argument is given, the script will also save the
fixel_density_maps and fixel_density_masks separated by bundles, with
names fixel_density_map_{bundle_name}.nii.gz and
fixel_density_mask_{bundle_name}.nii.gz.
These will have the shape (x, y, z, 5).
If the split_fixels argument is given, the script will also save the
fixel_density_maps and fixel_density_masks separated by fixels, with
names fixel_density_map_f{fixel_id}.nii.gz and
fixel_density_mask_f{fixel_id}.nii.gz.
These will have the shape (x, y, z, N).
If the single_bundle argument is given, the script will also save the
single-fiber single-bundle masks, which are obtained by selecting the
voxels where only one bundle and one fiber (fixel) are present. There will
be one single_bundle_mask_{bundle_name}.nii.gz per bundle, and a whole WM
version single_bundle_mask_WM.nii.gz.
These will have the shape (x, y, z).
WARNING: If multiple normalization types are given, along with the
split_bundles, split_fixels and single_bundle arguments, this script will
produce a lot of outputs.
positional arguments:
in_peaks Path of the peaks. The peaks are expected to be given as unit directions.
To get these from fODF or SH data, use the script scil_fodf_metrics.py
with the abs_peaks_and_values option.
options:
-h, --help show this help message and exit
--in_bundles IN_BUNDLES [IN_BUNDLES ...]
List of paths of the bundles (.trk) to analyze.
--in_bundles_names IN_BUNDLES_NAMES [IN_BUNDLES_NAMES ...]
List of the names of the bundles, in the same order as they were given.
If this argument is not used, the script assumes that the name of the bundle
is its filename without extensions.
--dps_key DPS_KEY Key to access the data per streamline to use as weight when computing the maps,
instead of the number of streamlines. [None].
--max_theta MAX_THETA
Maximum angle between streamline and peak to be associated [45].
-f Force overwriting of the output files.
--processes NBR Number of sub-processes to start.
Default: [1]
-v [{DEBUG,INFO,WARNING}]
Produces verbose output depending on the provided level.
Default level is warning, default when using -v is info.
Mask parameters:
--abs_thr ABS_THR Value of density maps threshold to obtain density masks, in number of streamlines
or streamline weighting if --dps_key is given. Any number of streamlines
or weight above this value will pass the absolute threshold test [0].
--rel_thr REL_THR Value of density maps threshold to obtain density masks, as a ratio of the normalized density
Any normalized density above this value will pass the relative threshold test.
Must be between 0 and 1 [0.01].
--norm {fixel,voxel,none} [{fixel,voxel,none} ...]
Way of normalizing the density maps. If fixel, will normalize the maps per fixel,
in each voxel. If voxel, will normalize the maps per voxel.
If none, will not normalize the maps. If multiple choices, will save each of them [voxel].
Output options:
--split_bundles If set, save the density maps and masks for each bundle separately
in addition to the all in one version.
--split_fixels If set, save the density maps and masks for each fixel separately
in addition to the all in one version.
--single_bundle If set, will save the single-fiber single-bundle masks as well.
These are obtained by selecting the voxels where only one bundle is present
(and one fiber/fixel).
--out_dir OUT_DIR Path to the output directory where all the output files will be saved.
Current directory by default.
--prefix PREFIX Prefix to add to all predetermined output filenames.
We recommand finishing with an underscore for better readability [].
--suffix SUFFIX Suffix to add to all predetermined output filenames.
We recommand starting with an underscore for better readability [].
Scilpy version: 2.0.2