covStructFormula {lgc}R Documentation

Formula interface to covStructs.

Description

Specify a full Gaussian Markov Random Field via formulas.

Usage

  covStructFormula(formula, data, fixef = NULL,
    delta = 1e-06, invdelta = 1/delta,
    delta.nonlin = delta, nugef = NULL, update.args = NULL,
    scale = NULL, nonlin = NULL, parameters = NULL,
    denseFixef = FALSE, ignore.proj = FALSE)

Arguments

formula

Random effect formula (details below).

data

Data.frame

fixef

Fixed effect formula. NAs in model.matrix are replaced by zeros.

delta

Tiny number. Precision of flat prior on fixed effects.

invdelta

Huge number. Precision of nugget effect when no nugget is desired.

nugef

Nugget effect formula.

update.args

List used to re-parameterize the covStruct.

Details

The present interface allow the construction of Gaussian Random Fields of the form Z=Z'+A β where Z'=B Y+ε and Y=c(X_1,...,X_k). With this notation Y is the mean zero hidden random field which is a composition of multiple hidden multivariate layers X_1,...,X_k. The design matrix B plays the role of looking up the relevant contributions of X_1,...,X_k to each observation entry. The construction is controlled by the arguments

Currently defined syntax of the random field formula

  1. ID(factor) Defines IID process with variance one on the levels of factor.

  2. DIAG(factor) Defines a process of independent variables with a variance parameter for each level of factor.

  3. AR1(factor) Defines a stationary AR1 process with variance one on the levels of factor.

  4. AR2(factor) Defines a stationary AR2 process with variance one on the levels of factor.

  5. contAR2(numeric) Defines a variance 1 process with covariance structure ρ(t)=\exp(a*t/s)*(\cos(b*t/s)-a/b*\sin(b*t/s)), b=√{1+a^2} (with derivative augmentation to obtain exact sparseness of the precision matrix on any irregular grid). The parameter a is a shape parameter in the interval (-1,0) and s is a positive scale parameter. The structure solves a linear 2nd order ODE and can approximate most powered exponential correlations. For instance the shape a=-0.77 is close to a Gaussian correlation.

  6. CORR(factor) Defines a free un-structured correlation matrix on the levels of factor.

  7. GMRF1(gridFactor) Defines a first order Gaussian Markov Random Field on the grid associated with gridFactor. Is neither stationary nor of variance one. The model is also known as "Besags proper model".

  8. COV(distFactor,form) Defines a process in terms of the covariance specified through the formula form. Distance matrices (or increment matrices) are looked up in the level attributes of distFactor.

  9. * The notation X*Y generates a process on the product space with the multiplicative covariance structure.

  10. + The notation X+Y generates independent processes X and Y and relates the observation to the sum.

  11. : The notation a:X relates the observation to the process X scaled with a covariate a.

  12. PARM(name) Generates a scale parameter that can be multiplied with a term.

  13. SCALE(X) Multiplies different scale parameters on each component of the process X (should only be applied to reasonably low dimensional X). The aggregation of scale parameters can be controlled by SCALE(X,fac) where fac is a factor with length equal to the dimension of X. This will add nlevels(fac) scale parameters.

  14. PROJ(X) Project the covariance structure by removing entries for which no direct data-entry is associated. This does not change the model but only affects the internal sparse representation and computation time. Note that projection generally destroys sparseness. However it can sometimes improve performance on large separable fields by replacing e.g X*Y*Z by X*Y*PROJ(Z).

Note that factors with NAs can be used to indicate that there is no relation between a given observation and one or more of the random field terms. This may be useful in situations where multiple different data sources are modelled.

Value

Object of class covStruct with attributes used by fitlgc.

See Also

fitlgc

Examples

##' === Separable correlation on grid with a nugget effect.
d <- expand.grid(x=factor(1:7),y=factor(1:8))
C <- covStructFormula(~AR1(x)*AR1(y)+AR2(y),nugef=~1,fixef=NULL,data=d)
##' === Some methods
C@parameters
simulate(C)
image(C)

[Package lgc version 1.4 Index]