====== SMP::Smooth - smooth a surface-based map ======

===== Motivation =====
For several reasons, applying additional smoothing to statistical maps can be advantageous (e.g. to compare patterns of activation across subjects and/or studies). This method allows to apply such a smoothing.

===== Requirements =====
To perform the smoothing, you must have a valid SMP object as well as the SRF object that contains the respective neighborhood information.

===== Notes =====
**Other than in voxel-space (3D) smoothing, this function uses an iterative approach to create a gaussian smoothing, it is thus recommended to rather apply a higher number of smoothing iterations instead of trying to increase the kernel size!**

===== Reference / smp.Help('Smooth') =====
<file> SMP::Smooth  - smooth SMP map with neighbors of an SRF
 
 FORMAT:       [smp = ] smp.Smooth(srf [, niter [, mapno [, k]]]);
 
 Input fields:
 
       srf         SRF object with required neighbor information
       niter       number of iterations (default: 1)
       mapno       which map number (default: 1)
       k           smoothing kernel in mm (only for direct neighbors, 2)
 
 Output fields:
 
       smp         object with one added, smoothed map</file>

==== Input fields ====
=== srf ===
This is the surface object from which the neighborhood information is taken; it must match in number of vertices to the SMP.

=== niter ===
Number of smoothing iterations. In general it is advisable to have a higher number of iterations compared to kernel size to get more qualitative results.

=== mapno ===
Indices of map(s) to smooth.

=== k ===
Smoothing kernel size; a regular 2D kernel is constructed (squaring the one-dimensional kernel weights), and these weights are then applied to the map values of neighboring vertices (see below for more details).

===== Algorithm =====
After creating the 2D kernel weights, the smoothing is applied in iterations. During each iteration, each vertices value is replaced by a weighted sum of the value itself and an equally inter-neighbor weighted sum of the first-degree neighbors:

{{:smp_smooth_formula.png|SMP smoothing formula for one vertex, using the values of its first-degree neighbors}}

In other words, the central kernel weight remains with the old value and the remainder to 1 is split across the next neighbors according to the kernel weight given by their distance to the vertex. This approach takes both the neighborhood and the distance of vertices into account.

After the smoothing is performed, the mean of the map is adjusted to reflect the original mean value (to counter rounding errors if a high number of iterations was used), **if and only if** the standard deviation is not smaller than the sum (for most skewed maps this is the case).