.. _scil_tractogram_commit: scil_tractogram_commit ====================== :: 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] [--reference REFERENCE] [--tolerance tol] [--skip_b0_check] [--processes NBR] [-v [{DEBUG,INFO,WARNING,ERROR}]] [-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_connections_from_labels 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) -------------------------------------------------------------------------------- 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. -------------------------------------------------------------------------------- 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. --reference REFERENCE Reference anatomy for tck/vtk/fib/dpy file support (.nii or .nii.gz). --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,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. 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. 2.2.2