.. _scil_tractogram_segment_with_bundleseg:

scil_tractogram_segment_with_bundleseg
======================================

::

	usage: __main__.py [-h] [--out_dir OUT_DIR] [--save_empty]
	                   [--minimal_vote_ratio MINIMAL_VOTE_RATIO]
	                   [--ignore_metadata]
	                   [--exploration_mode | --modify_distance_thr MODIFY_DISTANCE_THR]
	                   [--seed SEED] [--inverse] [--reference REFERENCE]
	                   [--processes NBR] [-v [{DEBUG,INFO,WARNING,ERROR}]] [-f]
	                   in_tractograms [in_tractograms ...] in_config_file
	                   in_directory in_transfo
	
	Compute BundleSeg & supports multi-atlas & multi-parameters. This is similar to
	what our previous RecobundlesX (RBx) script could do, but BundleSeg is better
	and more efficient.
	
	For a single bundle segmentation, see the lighter version:
	>>> scil_tractogram_segment_with_recobundles
	
	Hints:
	- The model needs to be cleaned and lightweight.
	- The transform should come from ANTs: (using the --inverse flag)
	  >>> AntsRegistrationSyNQuick.sh -d 3 -m MODEL_REF -f SUBJ_REF
	  If you are not sure about the transformation 'direction' you can try
	scil_tractogram_segment_with_recobundles. See its documentation for
	explanation on how to verify the direction.
	- The number of folders inside 'models_directories' will increase the number of
	runs. Each folder is considered like an atlas and bundles inside will initiate
	more BundleSeg executions. The more atlases you have, the more robust the
	recognition will be.
	
	Example data and usage available at: https://zenodo.org/records/10103446
	If you want to use previous versions in the zenodo record, you may also need
	previous versions of scilpy.
	
	For CPU usage, it can be variable (advanced CPU vs. basic CPU):
	    On personal computer: 4 CPU per subject and then it is better to parallelize
	    across subjects.
	    On a cluster: 8 CPU per subject and then it is better to parallelize across
	    subjects.
	
	For RAM usage, it is recommanded to use this heuristic:
	    (size of inputs tractogram (GB) * number of processes) < RAM (GB)
	This is important because many instances of data structures are initialized
	in parallel and can lead to a RAM overflow.
	
	------------------------------------------------------------------------------------------
	Reference:
	[1] St-Onge, Etienne, Kurt G. Schilling, and Francois Rheault."BundleSeg: A versatile,
	    reliable and reproducible approach to white matter bundle segmentation." International
	    Workshop on Computational Diffusion MRI. Cham: Springer Nature Switzerland (2023)
	------------------------------------------------------------------------------------------
	
	positional arguments:
	  in_tractograms        Input tractogram filenames (.trk or .tck).
	                        Must have compatible headers if .trk.
	  in_config_file        Path of the config file (.json)
	  in_directory          Path of parent folder of models directories.
	                        Each folder inside will be considered as a different atlas.
	  in_transfo            Path for the transformation to model space (.txt, .npy or .mat).
	
	options:
	  -h, --help            show this help message and exit
	  --out_dir OUT_DIR     Path for the output directory [voting_results].
	  --save_empty          Save empty files for bundles that were not recognized.
	  --minimal_vote_ratio MINIMAL_VOTE_RATIO
	                        Streamlines will only be considered for saving if
	                        recognized often enough.
	                        The ratio is a value between 0 and 1. Ex: If you have 5 input model 
	                        directories and a minimal_vote_ratio of 0.5, you will need at least 
	                        3 votes. [0.5]
	  --ignore_metadata     Ignore metadata in the tractogram if present. This will only 
	                        consider the geometry of the streamlines for saving.
	  --seed SEED           Random number generator seed 0.
	  --inverse             Use the inverse transformation.
	  --reference REFERENCE
	                        Reference anatomy for tck/vtk/fib/dpy file
	                        support (.nii or .nii.gz).
	  --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.
	
	Exploration mode:
	  --exploration_mode    Use higher pruning threshold, but optimal filtering can be explored using 
	                        scil_bundle_explore_bundleseg
	  --modify_distance_thr MODIFY_DISTANCE_THR
	                        Increase or decrease the distance threshold for pruning for all bundles 
	                        in the configuration [0.0]
	
	2.2.2