Auxiliary 3D smoothing routines

smooth3D and medianFilter3D are auxiliary functions for non-adaptive smoothing of 3D image data using kernel or median smoothing. Both function restrict to sub-areas determined by a mask. The functions are used in packages dti and qMRI.

Functions aws3Dmask and aws3Dmaskfull perform adaptive weights smoothing on statistical parametric maps in fMRI. Variability of results is determined from smoothed (using the same weighting schemes) residuals in order to correctly account for spatial correlation. These functions are intended to be used internally in package fmri. They have been moved here because they share significant parts of the openMP parallelized Fortran code underlying function aws.

smooth3D(y, h, mask, lkern = "Gaussian", weighted = FALSE, sigma2 = NULL,
         wghts = NULL)
medianFilter3D(y, h = 10, mask = NULL)
aws3Dmask(y, mask, lambda, hmax, res = NULL, sigma2 = NULL, lkern = "Gaussian",
   skern = "Plateau", weighted = TRUE, u = NULL, wghts = NULL,
   h0 = c(0, 0, 0), testprop = FALSE)
aws3Dmaskfull(y, mask, lambda, hmax, res = NULL, sigma2 = NULL, lkern = "Gaussian",
       skern = "Plateau", weighted = TRUE, u = NULL, wghts = NULL,
       testprop = FALSE)

Arguments

y	3D array of data in case of functions `smooth3D` and `medianFilter3D`. For `aws3Dmask*` with `!is.null(mask)` a vector of length `sum(mask)` containing only data values within the specified mask.
lkern	character: location kernel, either "Triangle", "Plateau", "Quadratic", "Cubic" or "Gaussian". The default "Triangle" is equivalent to using an Epanechnikov kernel, "Quadratic" and "Cubic" refer to a Bi-weight and Tri-weight kernel, see Fan and Gijbels (1996). "Gaussian" is a truncated (compact support) Gaussian kernel. This is included for comparisons only and should be avoided due to its large computational costs.
weighted	logical: use inverse variances as weights.
sigma2	`sigma2` allows to specify the variance of data entries.
mask	optional logical mask, same dimensionality as `y`
h	bandwidth to use. In case of `lkern="Gaussian"` this is in FWHM (full width half maximum) units. Value refers to first voxel dimension.
wghts	voxel dimensions. Defaults to `c(1,1,1)`
lambda	kritical scale parameter in hypothesis testing (adaptive weights smoothing)
hmax	maximum bandwidth for adaptive weights smoothing
res	array of residuals with dimension `c(nres,sum(mask))`.
skern	`skern` specifies the kernel for the statistical penalty. Defaults to "Plateau", the alternatives are "Triangle" and "Exp". "Plateau" specifies a kernel that is equal to 1 in the interval (0,.3), decays linearly in (.3,1) and is 0 for arguments larger than 1. `lkern="Plateau"` and `lkern="Triangle"` allow for much faster computation (saves up to 50% CPU-time). `lkern="Plateau"` produces a less random weighting scheme.
u	For test purposes in simulations: noisless 3D data.
h0	Vector of 3 bandwidths corresponding to a Gaussian kernel that would produce a comparable spatial correlation by convoluting iid data.
testprop	logical: test the validity of a propagation condition for the specified value of `lambda`.

Value

Functions smooth3D and medianFilter3D return a 3D array. Functions awsmask* return a list with smoothed values of y in component theta and smoothed residuals in component res.

Author

Joerg Polzehl polzehl@wias-berlin.de, Karsten Tabelow tabelow@wias-berlin.de

Note

Functions awsmask* are used intenally in package fmri. They refer to the situation, typical for fMRI, where the data are spatially correlated and this correlation can be accessed using residuals with respect to a model.