R: AWS for local constant models on a grid

aws {aws} | R Documentation

## AWS for local constant models on a grid

### Description

The function implements the propagation separation approach to nonparametric smoothing (formerly introduced as Adaptive weights smoothing) for varying coefficient likelihood models on a 1D, 2D or 3D grid. For "Gaussian" models, i.e. regression with additive "Gaussian" errors, a homoskedastic or heteroskedastic model is used depending on the content of `sigma2`

### Usage

    aws(y,hmax=NULL,aws=TRUE,memory=FALSE,family="Gaussian",
                    lkern="Triangle",homogen=TRUE,aggkern="Uniform",
                    sigma2=NULL,shape=NULL,scorr=0,spmin=0.25,
    		ladjust=1,wghts=NULL,u=NULL,graph=FALSE,demo=FALSE,
                    testprop=FALSE,maxni=FALSE)

### Arguments

`y` | array `y` containing the observe response (image intensity) data. `dim(y)` determines the dimensionality and extend of the grid design.
`hmax` | `hmax` specifies the maximal bandwidth. Defaults to `hmax=250, 12, 5` for 1D, 2D, 3D images, respectively. In case of `lkern="Gaussian"` the bandwidth is assumed to be given in full width half maximum (FWHM) units, i.e., `0.42466` times gridsize.
`aws` | logical: if TRUE structural adaptation (AWS) is used.
`memory` | logical: if TRUE stagewise aggregation is used as an additional adaptation scheme.
`family` | `family` specifies the probability distribution. Default is `family="Gaussian"`, also implemented are "Bernoulli", "Poisson", "Exponential", "Volatility", "Variance" and "NCchi". `family="Volatility"` specifies a Gaussian distribution with expectation 0 and unknown variance. `family="Volatility"` specifies that `p*y/theta` is distributed as χ^2 with `p=shape` degrees of freedom. `family="NCchi"` uses a noncentral Chi distribution with `p=shape` degrees of freedom and noncentrality parameter `theta`
`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.
`homogen` | logical: if TRUE the function tries to determine regions where weights can be fixed to 1. This may increase speed.
`aggkern` | character: kernel used in stagewise aggregation, either "Triangle" or "Uniform"
`sigma2` | `sigma2` allows to specify the variance in case of `family="Gaussian"`. Not used if `family!="Gaussian"`. Defaults to `NULL`. In this case a homoskedastic variance estimate is generated. If `length(sigma2)==length(y)` then `sigma2` is assumed to contain the pointwise variance of `y` and a heteroscedastic variance model is used.
`shape` | Allows to specify an additional shape parameter for certain family models. Currently only used for family="Variance", that is χ-Square distributed observations with `shape` degrees of freedom.
`scorr` | The vector `scorr` allows to specify a first order correlations of the noise for each coordinate direction, defaults to 0 (no correlation).
`spmin` | Determines the form (size of the plateau) in the adaptation kernel. Not to be changed by the user.
`ladjust` | factor to increase the default value of lambda
`wghts` | `wghts` specifies the diagonal elements of a weight matrix to adjust for different distances between grid-points in different coordinate directions, i.e. allows to define a more appropriate metric in the design space.
`u` | a "true" value of the regression function, may be provided to report risks at each iteration. This can be used to test the propagation condition with `u=0`
`graph` | If `graph=TRUE` intermediate results are illustrated after each iteration step. Defaults to `graph=FALSE`.
`demo` | If `demo=TRUE` the function pauses after each iteration. Defaults to `demo=FALSE`.
`testprop` | If set this provides diagnostics for testing the propagation condition. The values of `y` should correspond to the specified family and a global model.
`maxni` | If TRUE use max_{l<=k}(N_i^{(l)} instead of (N_i^{(k)} in the definition of the statistical penalty.

### Details

The function implements the propagation separation approach to nonparametric smoothing (formerly introduced as Adaptive weights smoothing) for varying coefficient likelihood models on a 1D, 2D or 3D grid. For "Gaussian" models, i.e. regression with additive "Gaussian" errors, a homoskedastic or heteroskedastic model is used depending on the content of `sigma2`. `aws==FALSE` provides the stagewise aggregation procedure from Belomestny and Spokoiny (2004). `memory==FALSE` provides Adaptive weights smoothing without control by stagewise aggregation.

The essential parameter in the procedure is a critical value `lambda`. This parameter has an interpretation as a significance level of a test for equivalence of two local parameter estimates. Optimal values mainly depend on the choosen `family`. Values set internally are choosen to fulfil a propagation condition, i.e. in case of a constant (global) parameter value and large `hmax` the procedure provides, with a high probability, the global (parametric) estimate. More formally we require the parameter `lambda` to be specified such that \bf{E} |\hat{θ}^k - θ| ≤ (1+α) \bf{E} |\tilde{θ}^k - θ| where \hat{θ}^k is the aws-estimate in step `k` and \tilde{θ}^k is corresponding nonadaptive estimate using the same bandwidth (`lambda=Inf`). The value of lambda can be adjusted by specifying the factor `ladjust`. Values `ladjust>1` lead to an less effective adaptation while `ladjust<<1` may lead to random segmentation of, with respect to a constant model, homogeneous regions.

The numerical complexity of the procedure is mainly determined by `hmax`. The number of iterations is approximately `Const*d*log(hmax)/log(1.25)` with `d` being the dimension of `y` and the constant depending on the kernel `lkern`. Comlexity in each iteration step is `Const*hakt*n` with `hakt` being the actual bandwith in the iteration step and `n` the number of design points. `hmax` determines the maximal possible variance reduction.

### Value

returns anobject of class `aws` with slots

`y = "numeric"` | y
`dy = "numeric"` | dim(y)
`x = "numeric"` | numeric(0)
`ni = "integer"` | integer(0)
`mask = "logical"` | logical(0)
`theta = "numeric"` | Estimates of regression function, `length: length(y)`
`mae = "numeric"` | Mean absolute error for each iteration step if u was specified, numeric(0) else
`var = "numeric"` | approx. variance of the estimates of the regression function. Please note that this does not reflect variability due to randomness of weights.
`xmin = "numeric"` | numeric(0)
`xmax = "numeric"` | numeric(0)
`wghts = "numeric"` | numeric(0), ratio of distances `wghts[-1]/wghts[1]`
`degree = "integer"` | 0
`hmax = "numeric"` | effective hmax
`sigma2 = "numeric"` | provided or estimated error variance
`scorr = "numeric"` | scorr
`family = "character"` | family
`shape = "numeric"` | shape
`lkern = "integer"` | integer code for lkern, 1="Plateau", 2="Triangle", 3="Quadratic", 4="Cubic", 5="Gaussian"
`lambda = "numeric"` | effective value of lambda
`ladjust = "numeric"` | effective value of ladjust
`aws = "logical"` | aws
`memory = "logical"` | memory
`homogen = "logical"` | homogen
`earlystop = "logical"` | FALSE
`varmodel = "character"` | "Constant"
`vcoef = "numeric"` | numeric(0)
`call = "function"` | the arguments of the call to `aws`

### Note

use `setCores='number of threads'` to enable parallel execution.

### Author(s)

Joerg Polzehl, polzehl@wias-berlin.de, http://www.wias-berlin.de/people/polzehl/

### References

Joerg Polzehl, Vladimir Spokoiny, Adaptive Weights Smoothing with applications to image restoration, J. R. Stat. Soc. Ser. B Stat. Methodol. 62 , (2000) , pp. 335–354

Joerg Polzehl, Vladimir Spokoiny, Propagation-separation approach for local likelihood estimation, Probab. Theory Related Fields 135 (3), (2006) , pp. 335–362.

Joerg Polzehl, Vladimir Spokoiny, in V. Chen, C.; Haerdle, W. and Unwin, A. (ed.) Handbook of Data Visualization Structural adaptive smoothing by propagation-separation methods Springer-Verlag, 2008, 471-492

### See Also

See also `paws`, `lpaws`, `vaws`,`link{awsdata}`, `aws.irreg`, `aws.gaussian`

### Examples

    require(aws)
    # 1D local constant smoothing
    ## Not run: demo(aws_ex1)
    ## Not run: demo(aws_ex2)
    # 2D local constant smoothing
    ## Not run: demo(aws_ex3)

[Package aws version 2.2-1 Index]