coco {cocons}R Documentation

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())

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).

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:

Value

(S4) An S4 object of class coco.

Author(s)

Federico Blasi

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

## Not run: 
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

## End(Not run)


[Package cocons version 0.1.4 Index]