cocons (version 0.1.5)

coco: Creates a coco S4 object

Description

Creates an S4 object of class coco, which is the centerpiece of the cocons package. The function provides a set of consistency checks for ensuring the suitability of the different objects involved.

Usage

coco(type, data, locs, z, model.list, info, output = list())

Value

(S4) An S4 object of class coco.

Arguments

type

(character) One of two available types "dense" or "sparse". See description.

data

(data.frame) A data.frame with covariates information, where colnames(data) matches model.list specification.

locs

(matrix) A matrix with spatial locations.

z

(vector or matrix) A matrix of \(n \times r\) response realizations, one realization per column. When considering only one realization, a vector can also be provided.

model.list

(list) A list specifying a model for each source of nonstationarity.

info

(list or NULL) A list specifying characteristics of the coco object.

output

(list or NULL) Empty or the resulting object from running optimParallel, adding to this a list with boundary information (see getBoundaries to check the expected structure).

Author

Federico Blasi

Details

Two types of coco objects are available, each assuming a different type of covariance matrix for the Gaussian process. Type "dense" builds dense covariance matrices (non zero elements), while type "sparse" builds sparse covariance matrices by tapering the dense covariance matrix with a compact isotropic compact-supported correlation matrix [1]. Type "sparse" allows a set of efficient algorithms, thus making it more suitable for large sample sizes.

An important component of the coco S4 class is the model.list specification, involving individual formulas provided as a list, where each of them specifies a covariate-based parametric model for a specific source of nonstationarity. It involves "mean" for the spatial mean, the "std.dev" for the marginal standard deviation, "scale", "aniso" and "tilt", each of them shaping specific aspects of the local spatial geometrically anisotropy structure, "smooth" handling local smoothness, and "nugget" handling the local nugget effect. The models are defined as:

Source	Related to	Description	Model
mean	\(\mu\)	Spatial mean function	\(\boldsymbol{X}_1\boldsymbol{\beta}\)
std.dev	\(\sigma^{X}\)	Marginal standard deviation	\(\text{exp}(0.5 \boldsymbol{X}_2 \boldsymbol{\alpha})\)
scale	\(\boldsymbol{\Sigma}^{X}\)	Local scale	\(\text{exp}(\boldsymbol{X}_3 \boldsymbol{\theta}_1)\)
aniso	\(\boldsymbol{\Sigma}^{X}\)	Local geometric anisotropy	\(\text{exp}(\boldsymbol{X}_4 \boldsymbol{\theta}_2)\)
tilt	\(\boldsymbol{\Sigma}^{X}\)	(Restricted) local tilt	\(\cos(\text{logit}^{-1}(\boldsymbol{X}_5 \boldsymbol{\theta}_3))\)
smooth	\(\nu^{X}\)	Local smoothness	\((\nu_{u} - \nu_{l})/(1+\text{exp}(-\boldsymbol{X}_6 \boldsymbol{\phi})) + \nu_{l}\)
nugget	\(\sigma^{X}_{\epsilon}\)	Local micro-scale variability	\(\text{exp}(\boldsymbol{X}_7 \boldsymbol{\zeta})\)

where \(\boldsymbol{\beta}\), \(\boldsymbol{\alpha}\), \(\boldsymbol{\theta}_1\), \(\boldsymbol{\theta}_2\), \(\boldsymbol{\theta}_3\), \(\boldsymbol{\phi}\), and \(\boldsymbol{\zeta}\) are the parameter vectors of each model, \(\nu_{l}\), and \(\nu_{u}\) are the lower and upper bounds limiting the range of variation of the spatially-varying smoothness, and where \(\boldsymbol{X}_{\ell}\) relates to the design matrix defined by the specific models for each of the source of nonstationarity.

Lastly, arguments for the "info" list argument involve:

• "lambda.reg": (numeric) a positive scalar specifying the regularization parameter. Larger values discourage highly-smoothed long-tailed covariance functions.

• "lambda.Sigma": (numeric) a positive scalar specifying the penalization parameter for the covariate-driven covariance parameters.

• "lambda.betas": (numeric) a positive scalar specifying the penalization parameter for the covariate-driven spatial mean parameters.

• "sparse.point": (numeric) a cutting point for which smaller coefficients in absolute value will be set to zero after the smoothed L1 penalization optimization. Used in combination with lambda.Sigma and lambda.betas. By default, it is set to 1e-4.

• "smooth.limits": (numeric vector) specifying the range of variation for the spatially varying smoothness (e.g. c(0.5, 2.5)).

• "taper": (numeric) specifying the desired taper function from the spam package (only for "sparse" coco objects).

• "delta": (numeric) specifying the taper range/scale (only for "sparse" coco objects).

• "skip.scale": (integer vector) By default, all covariates are scaled. skip.scale allows to specify the index of those variables in data that should not be scaled during the optimization.

References

[1] Furrer, Reinhard, Marc G. Genton, and Douglas Nychka. "Covariance tapering for interpolation of large spatial datasets." Journal of Computational and Graphical Statistics 15.3 (2006): 502-523.

See Also

spam::cov.wend1()

Examples

if (FALSE) {
locs <- expand.grid(seq(0,1,length.out = 10),
seq(0,1,length.out = 10))

toydata <- data.frame('x' = locs[,1])

set.seed(1)
z <- rnorm(100)

model.list <- list('mean' = 0,
                   'std.dev' = formula( ~ 1),
                   'scale' = formula( ~ 1 + x),
                   'aniso' = 0,
                   'tilt' = 0,
                   'smooth' = 3/2,
                   'nugget' = -Inf)
                   
coco_object <- coco(type = 'dense',
                    data = toydata,
                    locs = as.matrix(locs),
                    z = z,
                    model.list = model.list)

coco_object
}