.. _scil_bundle_alter_to_target_dice:

scil_bundle_alter_to_target_dice
================================

::

	usage: __main__.py [-h] [--min_dice MIN_DICE] [--epsilon EPSILON]
	                   (--subsample | --trim | --cut | --replace | --transform)
	                   [--from_end] [--save_transform FILE] [--seed SEED]
	                   [--shuffle] [-f] [-v [{DEBUG,INFO,WARNING,ERROR}]]
	                   [--reference REFERENCE]
	                   in_bundle out_bundle
	
	This script is used to alter a bundle while keeping it similar enough to the
	original version (keeping the dice coefficient above a given threshold).
	The script will subsample, trim, cut, replace or transform the streamlines
	until the minimum dice is reached.
	
	Various operations choices cannot be combined in one run, use the script
	multiple times if needed.
	
	All operations use a dichotomic search to find the parameter that gets as close
	as possible to the specified minimum dice coefficient (with an epsilon for
	convergence).
	
	- The subsample operation will remove streamlines until the minimum dice is
	  reached. This affects the whole bundle.
	
	- The trim operation will use the lowest density voxels (starting at 1) to
	  remove points from the streamlines until the minimum dice is reached.
	  This typically affect the edge of the bundle.
	
	- The cut operation will remove points from the start (or end) streamlines
	  until the minimum dice is reached. This affects one end of the bundle.
	
	- The replace operation will upsample the tractogram (generate new streamlines
	  with noise) and then subsample the tractogram. This effectively replaces
	  streamlines with similar ones until the minimum dice is reached.
	  This affects the whole bundle.
	
	- The transform operation will apply random rotations to the streamlines
	  until the minimum dice is reached. This affects the whole bundle.
	
	positional arguments:
	  in_bundle             Input bundle filename (.trk, .tck).
	  out_bundle            Output bundle filename (.trk, .tck).
	
	options:
	  -h, --help            show this help message and exit
	  --min_dice MIN_DICE   Minimum dice to reach [0.9].
	  --epsilon EPSILON     Epsilon for the convergence [0.01].
	  --seed SEED, -s SEED  Seed for RNG. Default based on --min_dice.
	  --shuffle             Shuffle the streamlines and orientation afteralteration.
	  -f                    Force overwriting of the output files.
	  -v [{DEBUG,INFO,WARNING,ERROR}]
	                        Produces verbose output depending on the provided level. 
	                        Default level is warning, default when using -v is info.
	  --reference REFERENCE
	                        Reference anatomy for tck/vtk/fib/dpy file
	                        support (.nii or .nii.gz).
	
	Alteration options:
	  --subsample           Pick a subset of streamlines.
	  --trim                Trim streamlines using low density voxel.
	  --cut                 Cut streamlines from endpoints.
	  --replace             Replace streamlines with similar ones.
	  --transform           Transform streamlines using a random linear transformation.
	  --from_end            Cut streamlines from the tail rather than the head.
	                        Only available with --cut.
	  --save_transform FILE
	                        Save the transformation matrix to a file.
	                        Only available with --transform.
	
	2.2.2