usage: __main__.py [-h] [--nbr_dir NBR_DIR] [--nbr_iter NBR_ITER]
[--in_peaks IN_PEAKS] [--in_tracking_mask IN_TRACKING_MASK]
[--commit2] [--lambda_commit_2 LAMBDA_COMMIT_2]
[--ball_stick] [--para_diff PARA_DIFF]
[--perp_diff PERP_DIFF [PERP_DIFF ...]]
[--iso_diff ISO_DIFF [ISO_DIFF ...]]
[--keep_whole_tractogram]
[--save_kernels DIRECTORY | --load_kernels DIRECTORY]
[--compute_only] [--tolerance tol] [--skip_b0_check]
[--processes NBR] [-v [{DEBUG,INFO,WARNING}]] [-f]
in_tractogram in_dwi in_bval in_bvec out_dir
Convex Optimization Modeling for Microstructure Informed Tractography (COMMIT)
estimates, globally, how a given tractogram explains the DWI in terms of signal
fit, assuming a certain forward microstructure model. It assigns a weight to
each streamline, which represents how well it explains the DWI signal globally.
The default forward microstructure model is stick-zeppelin-ball, which requires
multi-shell data and a peak file (principal fiber directions in each voxel,
typically from a field of fODFs).
It is possible to use the ball-and-stick model for single-shell and multi-shell
data. In this case, the peak file is not mandatory. Multi-shell should follow a
"NODDI protocol" (low and high b-values), multiple shells with similar b-values
should not be used with COMMIT.
The output from COMMIT is:
- fit_NRMSE.nii.gz
fiting error (Normalized Root Mean Square Error)
- fit_RMSE.nii.gz
fiting error (Root Mean Square Error)
- results.pickle
Dictionary containing the experiment parameters and final weights
- compartment_EC.nii.gz
(est. Extra-Cellular signal fraction)
- compartment_IC.nii.gz
(est. Intra-Cellular signal fraction)
- compartment_ISO.nii.gz
(est. isotropic signal fraction (freewater comportment)):
Each of COMMIT compartments
- streamline_weights.txt
Text file containing the commit weights for each streamline of the
input tractogram.
- streamlines_length.txt
Text file containing the length (mm) of each streamline.
- streamline_weights_by_length.txt
Text file containing the commit weights for each streamline of the
input tractogram, ordered by their length.
- tot_streamline_weights
Text file containing the total commit weights of each streamline.
Equal to commit_weights * streamlines_length (W_i * L_i)
- essential.trk / non_essential.trk
Tractograms containing the streamlines below or equal (essential) and
above (non_essential) a threshold_weights of 0.
- decompose_commit.h5
In the case where the input is a hdf5 file only, we will save an output
hdf5 with the following information separated into each bundle's dps:
- streamlines_weights
- streamline_weights_by_length
For each bundle, only the essential streamlines are kept.
This script can divide the input tractogram in two using a threshold to apply
on the streamlines' weight. The threshold used is 0.0, keeping only streamlines
that have non-zero weight and that contribute to explain the DWI signal.
Streamlines with 0 weight are essentially not necessary according to COMMIT.
COMMIT2 is available only for HDF5 data from
scil_tractogram_segment_bundles_for_connectivity.py and
with the --ball_stick option. Use the --commit2 option to activite it, slightly
longer computation time. This wrapper offers a simplify way to call COMMIT,
but does not allow to use (or fine-tune) every parameter. If you want to use
COMMIT with full access to all parameters,
visit: https://github.com/daducci/COMMIT
When tunning parameters, such as --iso_diff, --para_diff, --perp_diff or
--lambda_commit_2 you should evaluate the quality of results by:
- Looking at the 'density' (GTM) of the connnectome (essential tractogram)
- Confirm the quality of WM bundles reconstruction (essential tractogram)
- Inspect the (N)RMSE map and look for peaks or anomalies
- Compare the density map before and after (essential tractogram)
Formerly: scil_run_commit.py
positional arguments:
in_tractogram Input tractogram (.trk or .tck or .h5).
in_dwi Diffusion-weighted image used by COMMIT (.nii.gz).
in_bval b-values in the FSL format (.bval).
in_bvec b-vectors in the FSL format (.bvec).
out_dir Output directory for the COMMIT maps.
options:
-h, --help show this help message and exit
--nbr_dir NBR_DIR Number of directions, on the half of the sphere,
representing the possible orientations of the response functions [500].
--nbr_iter NBR_ITER Maximum number of iterations [1000].
--in_peaks IN_PEAKS Peaks file representing principal direction(s) locally,
typically coming from fODFs. This file is mandatory for the default
stick-zeppelin-ball model.
--in_tracking_mask IN_TRACKING_MASK
Binary mask where tratography was allowed.
If not set, uses a binary mask computed from the streamlines.
--tolerance tol The tolerated gap between the b-values to extract and the current b-value.
[Default: 20]
* Note. We would expect to find at least one b-value in the
range [0, tolerance]. To skip this check, use --skip_b0_check.
--skip_b0_check By default, we supervise that at least one b0 exists in your data
(i.e. b-values below the default --b0_threshold). Use this option to
allow continuing even if the minimum b-value is suspiciously high.
If no b-value is found below the threshold, the script will continue
with your minimal b-value as new --b0_threshold.
Use with care, and only if you understand your data.
--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.
-f Force overwriting of the output files.
COMMIT2 options:
--commit2 Run commit2, requires .h5 as input and will force
ball&stick model.
--lambda_commit_2 LAMBDA_COMMIT_2
Specify the clustering prior strength [0.001].
Model options:
--ball_stick Use the ball&Stick model, disable the zeppelin compartment.
Only model suitable for single-shell data.
--para_diff PARA_DIFF
Parallel diffusivity in mm^2/s.
Default for both ball_stick and stick_zeppelin_ball: 1.7E-3.
--perp_diff PERP_DIFF [PERP_DIFF ...]
Perpendicular diffusivity in mm^2/s.
Default for ball_stick: None
Default for stick_zeppelin_ball: [0.51E-3]
--iso_diff ISO_DIFF [ISO_DIFF ...]
Istropic diffusivity in mm^2/s.
Default for ball_stick: [2.0E-3]
Default for stick_zeppelin_ball: [1.7E-3, 3.0E-3]
Tractogram options:
--keep_whole_tractogram
Save a tractogram copy with streamlines weights in the data_per_streamline
[False].
--compute_only Compute kernels only, --save_kernels must be used.
Kernels options:
--save_kernels DIRECTORY
Output directory for the COMMIT kernels.
--load_kernels DIRECTORY
Input directory where the COMMIT kernels are located.
References:
[1] Daducci, Alessandro, et al. "COMMIT: convex optimization modeling for
microstructure informed tractography." IEEE transactions on medical
imaging 34.1 (2014): 246-257.
[2] Schiavi, Simona, et al. "A new method for accurate in vivo mapping of
human brain connections using microstructural and anatomical information."
Science advances 6.31 (2020): eaba8245.