.. _scil_btensor_metrics:

scil_btensor_metrics
====================

::

	usage: __main__.py [-h] --in_dwis IN_DWIS [IN_DWIS ...] --in_bvals IN_BVALS
	                   [IN_BVALS ...] --in_bvecs IN_BVECS [IN_BVECS ...]
	                   --in_bdeltas {0,1,-0.5,0.5} [{0,1,-0.5,0.5} ...]
	                   [--mask MASK] [--tolerance tol] [--skip_b0_check]
	                   [--fit_iters FIT_ITERS] [--random_iters RANDOM_ITERS]
	                   [--do_weight_bvals] [--do_weight_pa] [--do_multiple_s0]
	                   [--op OP] [--fa FA] [--processes NBR]
	                   [-v [{DEBUG,INFO,WARNING,ERROR}]] [-f] [--not_all]
	                   [--md file] [--ufa file] [--mk_i file] [--mk_a file]
	                   [--mk_t file]
	
	Script to compute microstructure metrics using the DIVIDE method. In order to
	operate, the script needs at leats two different types of b-tensor encodings.
	Note that custom encodings are not yet supported, so that only the linear
	tensor encoding (LTE, b_delta = 1), the planar tensor encoding
	(PTE, b_delta = -0.5), the spherical tensor encoding (STE, b_delta = 0) and
	the cigar shape tensor encoding (b_delta = 0.5) are available. Moreover, all
	of `--in_dwis`, `--in_bvals`, `--in_bvecs` and `--in_bdeltas` must have the
	same number of arguments. Be sure to keep the same order of encodings
	throughout all these inputs and to set `--in_bdeltas` accordingly (IMPORTANT).
	
	By default, will output all possible files, using default names. Thus, this
	script outputs the results from the DIVIDE fit or direct derivatives:
	mean diffusivity (MD), isotropic mean kurtosis (mk_i), anisotropic mean
	kurtosis (mk_a), total mean kurtosis (mk_t) and finally micro-FA (uFA).
	Specific names can be specified using the
	file flags specified in the "File flags" section.
	
	If --not_all is set, only the files specified explicitly by the flags
	will be output. The order parameter can also be computed from the uFA and a
	precomputed FA, using separate input parameters.
	
	>>> scil_btensor_metrics --in_dwis LTE.nii.gz PTE.nii.gz STE.nii.gz
	    --in_bvals LTE.bval PTE.bval STE.bval --in_bvecs LTE.bvec PTE.bvec STE.bvec
	    --in_bdeltas 1 -0.5 0 --mask mask.nii.gz
	
	IMPORTANT: If the script does not converge to a solution, it is probably due to
	noise outside the brain. Thus, it is strongly recommanded to provide a brain
	mask with --mask.
	
	Based on Markus Nilsson, Filip Szczepankiewicz, Björn Lampinen, André Ahlgren,
	João P. de Almeida Martins, Samo Lasic, Carl-Fredrik Westin,
	and Daniel Topgaard. An open-source framework for analysis of multidimensional
	diffusion MRI data implemented in MATLAB.
	Proc. Intl. Soc. Mag. Reson. Med. (26), Paris, France, 2018.
	
	options:
	  -h, --help            show this help message and exit
	  --in_dwis IN_DWIS [IN_DWIS ...]
	                        Path to the input diffusion volume for each b-tensor encoding type.
	  --in_bvals IN_BVALS [IN_BVALS ...]
	                        Path to the bval file, in FSL format, for each b-tensor encoding type.
	  --in_bvecs IN_BVECS [IN_BVECS ...]
	                        Path to the bvec file, in FSL format, for each b-tensor encoding type.
	  --in_bdeltas {0,1,-0.5,0.5} [{0,1,-0.5,0.5} ...]
	                        Value of b_delta for each b-tensor encoding type, in the same order as dwi, bval and bvec inputs.
	  --mask MASK           Path to a binary mask. Only the data inside the mask will be used for computations and reconstruction.
	  --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 --tolerance). 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 --tolerance and no b0 volumes.
	                        Use with care, and only if you understand your data.
	  --fit_iters FIT_ITERS
	                        The number of time the gamma fit will be done [1]
	  --random_iters RANDOM_ITERS
	                        The number of iterations for the initial parameters search. [50]
	  --do_weight_bvals     If set, does not do a weighting on the bvalues in the gamma fit.
	  --do_weight_pa        If set, does not do a powder averaging weighting in the gamma fit.
	  --do_multiple_s0      If set, does not take into account multiple baseline signals.
	  --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.
	  --not_all             If set, only saves the files specified using the file flags. (Default: False)
	
	Order parameter (OP):
	  --op OP               Output filename for the order parameter. The OP will not be output if this is not given. Computation of the OP also requires a precomputed FA map (given using --fa).
	  --fa FA               Path to a FA map. Needed for calculating the OP.
	
	File flags:
	  --md file             Output filename for the MD.
	  --ufa file            Output filename for the microscopic FA.
	  --mk_i file           Output filename for the isotropic mean kurtosis.
	  --mk_a file           Output filename for the anisotropic mean kurtosis.
	  --mk_t file           Output filename for the total mean kurtosis.
	
	2.2.2