.. _scil_sh_to_aodf:

scil_sh_to_aodf
===============

::

	usage: __main__.py [-h] [--out_sym OUT_SYM]
	                   [--sh_basis {descoteaux07,tournier07,descoteaux07_legacy,tournier07_legacy}]
	                   [--sphere {repulsion100,repulsion200,repulsion724,symmetric362,symmetric642,symmetric724}]
	                   [--method {unified,cosine}] [--sigma_spatial SIGMA_SPATIAL]
	                   [--sigma_align SIGMA_ALIGN] [--sigma_range SIGMA_RANGE]
	                   [--sigma_angle SIGMA_ANGLE] [--disable_spatial]
	                   [--disable_align] [--disable_range] [--include_center]
	                   [--win_hwidth WIN_HWIDTH] [--sharpness SHARPNESS]
	                   [--device {cpu,gpu}] [--use_opencl]
	                   [--patch_size PATCH_SIZE] [-v [{DEBUG,INFO,WARNING,ERROR}]]
	                   [-f]
	                   in_sh out_sh
	
	Script to estimate asymmetric ODFs (aODFs) from a spherical harmonics image.
	
	Two methods are available:
	    * Unified filtering [1] combines four asymmetric filtering methods into
	      a single equation and relies on a combination of four gaussian filters.
	    * Cosine filtering [2] is a simpler implementation using cosine distance
	      for assigning weights to neighbours.
	
	Unified filtering can be accelerated using OpenCL with the option --use_opencl.
	Make sure you have pyopencl installed before using this option. By default, the
	OpenCL program will run on the cpu. To use a gpu instead, also specify the
	option --device gpu.
	----------------------------------------------------------------------------------
	References:
	[1] Poirier and Descoteaux, 2024, "A Unified Filtering Method for Estimating
	    Asymmetric Orientation Distribution Functions", Neuroimage, vol. 287,
	    https://doi.org/10.1016/j.neuroimage.2024.120516
	
	[2] Poirier et al, 2021, "Investigating the Occurrence of Asymmetric Patterns
	    in White Matter Fiber Orientation Distribution Functions", ISMRM 2021
	    (abstract 0865)
	---------------------------------------------------------------------------------
	
	positional arguments:
	  in_sh                 Path to the input file.
	  out_sh                File name for averaged signal.
	
	options:
	  -h, --help            show this help message and exit
	  --out_sym OUT_SYM     Name of optional symmetric output. [None]
	  --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.
	  --sphere {repulsion100,repulsion200,repulsion724,symmetric362,symmetric642,symmetric724}
	                        Sphere used for the SH to SF projection. [repulsion200]
	  --method {unified,cosine}
	                        Method for estimating asymmetric ODFs [unified].
	                        One of:
	                            'unified': Unified filtering [1].
	                            'cosine' : Cosine-based filtering [2].
	  --device {cpu,gpu}    Device to use for execution. [cpu]
	  --use_opencl          Accelerate code using OpenCL (requires pyopencl
	                        and a working OpenCL implementation).
	  --patch_size PATCH_SIZE
	                        OpenCL patch size. [40]
	  -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.
	
	Shared filter arguments:
	  --sigma_spatial SIGMA_SPATIAL
	                        Standard deviation for spatial distance. [1.0]
	
	Unified filter arguments:
	  --sigma_align SIGMA_ALIGN
	                        Standard deviation for alignment filter. [0.8]
	  --sigma_range SIGMA_RANGE
	                        Standard deviation for range filter
	                        *relative to SF range of image*. [0.2]
	  --sigma_angle SIGMA_ANGLE
	                        Standard deviation for angular filter
	                        (disabled by default).
	  --disable_spatial     Disable spatial filtering.
	  --disable_align       Disable alignment filtering.
	  --disable_range       Disable range filtering.
	  --include_center      Include center voxel in neighourhood.
	  --win_hwidth WIN_HWIDTH
	                        Filtering window half-width. Defaults to 3*sigma_spatial.
	
	Cosine filter arguments:
	  --sharpness SHARPNESS
	                        Specify sharpness factor to use for
	                        weighted average. [1.0]
	
	2.2.2