.. _scil_tractogram_resample:

scil_tractogram_resample
========================

::

	usage: __main__.py [-h] [--never_upsample] [--point_wise_std [POINT_WISE_STD]]
	                   [--tube_radius [TUBE_RADIUS]] [--gaussian SIGMA]
	                   [--keep_invalid_streamlines] [--compress [COMPRESS_TH]]
	                   [--downsample_per_cluster]
	                   [--qbx_thresholds QBX_THRESHOLDS [QBX_THRESHOLDS ...]]
	                   [--seed SEED] [--reference REFERENCE]
	                   [-v [{DEBUG,INFO,WARNING,ERROR}]] [-f]
	                   in_tractogram nb_streamlines out_tractogram
	
	Script to resample a tractogram to a set number of streamlines.
	
	Default behavior:
	- If the number of requested streamlines is lower than the streamline count:
	DOWNSAMPLE
	- If the number of requested streamlines is higher than the streamline count:
	UPSAMPLE  (to prevent upsampling when not desired, use --never_upsample).
	
	Upsampling:
	    Works by generating new streamlines, either by fitting a polynomial on
	    a noisy version of the streamline (with option --point_wise_std) or by
	    "parallel transport"; translating copies of existing streamlines by a
	    random amount (with option --tube_radius). If both options are selected,
	    streamlines are first translated, then noise is added.
	
	    Includes smoothing (of value --gaussian) to compensate for the noisiness of
	    new streamlines generated by the process.
	
	    * Note that the new streamlines may not have the same step size as initial
	    streamlines.
	
	    Can be useful to build training sets for machine learning algorithms, to
	    upsample under-represented bundles or downsample over-represented bundles.
	
	Downsampling:
	    Works by selecting a subset of streamlines.
	
	    Includes the possibility of choosing randomly *per Quickbundle cluster* to
	    ensure that all clusters are represented in the final tractogram.
	
	Example usage:
	$ scil_tractogram_resample input.trk 1000 output.trk       --point_wise_std 0.5 --gaussian 5 --keep_invalid_streamlines
	$ scil_viz_bundle output.trk --local_coloring --width=0.1
	
	positional arguments:
	  in_tractogram         Input tractography file.
	  nb_streamlines        Number of streamlines to resample the tractogram to.
	  out_tractogram        Output tractography file.
	
	options:
	  -h, --help            show this help message and exit
	  --never_upsample      Make sure to never upsample a tractogram.
	                        Useful when downsampling a batch of files at once.
	  --seed SEED           Use a specific random seed for the resampling.
	  --reference REFERENCE
	                        Reference anatomy for tck/vtk/fib/dpy file
	                        support (.nii or .nii.gz).
	  -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.
	
	Upsampling options:
	  --point_wise_std [POINT_WISE_STD]
	                        Noise to add to existing streamlines points to generate new ones.
	                        Value is in mm. Default if set: 1.0.
	  --tube_radius [TUBE_RADIUS]
	                        Maximum distance to generate streamlines around the original ones. 
	                        Value is in mm. Default if set: 1.0.
	  --gaussian SIGMA      If set, smooth the upsampled streamlines. Value is the gaussian sigma.
	                         Uses the coordinates of surrounding points on the 
	                        streamline to blur the streamlines.
	                        A good sigma choice would be around 5. Default: no smoothing.
	  --keep_invalid_streamlines
	                        Keep invalid newly generated streamlines that may go out of the 
	                        bounding box.
	  --compress [COMPRESS_TH]
	                        If set, compress the resulting streamline. Value is the maximum 
	                        compression distance in mm.[0.1]
	
	Downsampling options:
	  --downsample_per_cluster
	                        If set, downsampling will be done per cluster (computed with 
	                        Quickbundles) to ensure that at least some streamlines are 
	                        kept per bundle. Else, random downsampling is performed (default).
	  --qbx_thresholds QBX_THRESHOLDS [QBX_THRESHOLDS ...]
	                        If you chose option '--downsample_per_cluster', you may set 
	                        the Quickbundles threshold value(s) here. Default: [40, 30, 20]
	
	2.2.2