.. _scil_aodf_metrics:

scil_aodf_metrics
=================

::

	usage: __main__.py [-h] [--mask MASK] [--asi_map ASI_MAP]
	                   [--odd_power_map ODD_POWER_MAP] [--peaks PEAKS]
	                   [--peak_values PEAK_VALUES] [--peak_indices PEAK_INDICES]
	                   [--nufid NUFID] [--not_all] [--at A_THRESHOLD]
	                   [--rt R_THRESHOLD]
	                   [--sphere {repulsion100,repulsion200,repulsion724,symmetric362,symmetric642,symmetric724}]
	                   [--processes NBR]
	                   [--sh_basis {descoteaux07,tournier07,descoteaux07_legacy,tournier07_legacy}]
	                   [-v [{DEBUG,INFO,WARNING,ERROR}]] [-f]
	                   in_sh
	
	Script to compute various metrics derivated from asymmetric ODF.
	
	These metrics include the asymmetric peak directions image, a number of fiber
	directions (nufid) map [1], the asymmetry index (ASI) map [2] and an odd-power
	map [3].
	
	The asymmetric peak directions image contains peaks per hemisphere, considering
	antipodal sphere directions as distinct. On a symmetric signal, the number of
	asymmetric peaks extracted is then twice the number of symmetric peaks.
	
	The nufid map is the asymmetric alternative to NuFO maps. It counts the
	number of asymmetric peaks extracted and ranges in [0..N] with N the maximum
	number of peaks.
	
	The asymmetric index is a cosine-based metric in the range [0..1], with 0
	corresponding to a perfectly symmetric signal and 1 to a perfectly asymmetric
	signal.
	
	The odd-power map is also in the range [0..1], with 0 corresponding to a
	perfectly symmetric signal and 1 to a perfectly anti-symmetric signal. It is
	given as the ratio of the L2-norm of odd SH coefficients on the L2-norm of all
	SH coefficients.
	
	--------------------------------------------------------------------------------
	References:
	[1] C. Poirier and M. Descoteaux, "Filtering Methods for Asymmetric ODFs:
	    Where and How Asymmetry Occurs in the White Matter." bioRxiv. 2022 Jan 1;
	    2022.12.18.520881. doi: https://doi.org/10.1101/2022.12.18.520881
	
	[2] S. Cetin Karayumak, E. Özarslan, and G. Unal,"Asymmetric Orientation
	    Distribution Functions (AODFs) revealing intravoxel geometry in diffusion MRI"
	    Magnetic Resonance Imaging, vol. 49, pp. 145-158, Jun. 2018,
	    doi: https://doi.org/10.1016/j.mri.2018.03.006.
	
	[3] C. Poirier, E. St-Onge, and M. Descoteaux, "Investigating the Occurrence of
	    Asymmetric Patterns in White Matter Fiber Orientation Distribution Functions"
	    [Abstract], In: Proc. Intl. Soc. Mag. Reson. Med. 29 (2021), 2021 May 15-20,
	    Vancouver, BC, Abstract number 0865.
	---------------------------------------------------------------------------------
	
	positional arguments:
	  in_sh                 Input SH image.
	
	options:
	  -h, --help            show this help message and exit
	  --mask MASK           Optional mask.
	  --asi_map ASI_MAP     Output asymmetry index (ASI) map.
	  --odd_power_map ODD_POWER_MAP
	                        Output odd power map.
	  --peaks PEAKS         Output filename for the extracted peaks.
	  --peak_values PEAK_VALUES
	                        Output filename for the extracted peaks values.
	  --peak_indices PEAK_INDICES
	                        Output filename for the generated peaks indices on the sphere.
	  --nufid NUFID         Output filename for the nufid file.
	  --not_all             If set, only saves the files specified using the file flags [False].
	  --at A_THRESHOLD      Absolute threshold on fODF amplitude. This value should be set to
	                        approximately 1.5 to 2 times the maximum fODF amplitude in isotropic voxels
	                        (ie. ventricles).
	                        Use scil_fodf_max_in_ventricles to find the maximal value.
	                        See [Dell'Acqua et al HBM 2013] [0.0].
	  --rt R_THRESHOLD      Relative threshold on fODF amplitude in percentage [0.1].
	  --sphere {repulsion100,repulsion200,repulsion724,symmetric362,symmetric642,symmetric724}
	                        Sphere to use for peak directions estimation [symmetric724].
	  --processes NBR       Number of sub-processes to start. 
	                        Default: [1]
	  --sh_basis {descoteaux07,tournier07,descoteaux07_legacy,tournier07_legacy}
	                        Spherical harmonics basis used for the SH coefficients. 
	                        Must be either descoteaux07', 'tournier07', 
	                        'descoteaux07_legacy' or 'tournier07_legacy' [['descoteaux07_legacy']]:
	                            'descoteaux07'       : SH basis from the Descoteaux et al.
	                                                   MRM 2007 paper
	                            'tournier07'         : SH basis from the new Tournier et al.
	                                                   NeuroImage 2019 paper, as in MRtrix 3.
	                            'descoteaux07_legacy': SH basis from the legacy Dipy implementation
	                                                   of the Descoteaux et al. MRM 2007 paper
	                            'tournier07_legacy'  : SH basis from the legacy Tournier et al.
	                                                   NeuroImage 2007 paper.
	  -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