.. _scil_gradients_validate_sampling:

scil_gradients_validate_sampling
================================

::

	usage: __main__.py [-h] [--max_ratio MAX_RATIO] [--viz] [--save_viz out_dir]
	                   [--b0_threshold thr] [--skip_b0_check] [--tolerance tol]
	                   [-v [{DEBUG,INFO,WARNING,ERROR}]] [-f]
	                   in_gradients [in_gradients ...]
	
	Validate the sampling of a gradient table, in terms of how well distributed on
	the sphere the b-vectors are.
	
	To do so, the script compares the electrostatic-like repulsion energy [1] of
	the inputed b-vectors with the energy of optimally distributed b-vectors. The
	same number of directions per shell (the script supports multi-shell) as the
	input b-vectors are used to generate the optimal b-vectors as in [1]. It is
	possible that the inputed b-vectors are better distributed than the optimal
	ones.
	
	The script starts by looking for b0s, to remove them from the analysis. Then,
	it looks for duplicate b-vectors. Finally, both energies are computed and
	compared as the ratio between the inputed b-vectors' energy and the optimal
	b-vectors' energy (input_energy/optimal_energy). Above a given maximum ratio
	value, the script raises a warning.
	
	The user might want to use the -v verbose option to see the computed energies.
	The --viz option displays both the input and optimal b-vectors on a single
	shell. The --save_viz option saves this image as png. If --save_viz is used
	without --viz, the image will be saved but not shown. For more options on
	visualization, please use scil_viz_gradients_screenshot.
	------------------------------------------------------------------------------
	Reference:
	[1] Emmanuel Caruyer, Christophe Lenglet, Guillermo Sapiro,
	    Rachid Deriche. Design of multishell gradient sampling with uniform coverage
	    in diffusion MRI. Magnetic Resonance in Medicine, Wiley, 2013, 69 (6),
	    pp. 1534-1540. <http://dx.doi.org/10.1002/mrm.24736>
	------------------------------------------------------------------------------
	
	positional arguments:
	  in_gradients          Path(s) to the gradient file(s). Either FSL (.bval, .bvec) or MRtrix (.b).
	
	options:
	  -h, --help            show this help message and exit
	  --max_ratio MAX_RATIO
	                        Maximum value for the ratio between the inputed b-vectors' energy 
	                        and the optimal b-vectors' energy (input_energy/optimal_energy). [1.25]
	  --viz                 Visualize the inputed gradient scheme, then the optimal one.
	  --save_viz out_dir    Save the input and optimal gradient schemes in the specified folder. If --viz is not set, then the window is not shown but will be saved.
	  --b0_threshold thr    Threshold under which b-values are considered to be b0s.
	                        [Default: 20] 
	                        * Note. We would expect to find at least one b-value in the 
	                          range [0, b0_threshold]. 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 the original --b0_threshold and no b0 volumes.
	                        Use with care, and only if you understand your data.
	  --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.
	  -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.
	
	2.2.2