correlation_builder {sim2Dpredictr}

Build a Correlation Matrix for 2D Spatial Data

Description

This function "builds" a correlation matrix based on user specifications.

Usage

correlation_builder(
  corr.structure = "ar1",
  im.res,
  corr.min = NULL,
  neighborhood = "none",
  rho = NULL,
  phi = NULL,
  w = NULL,
  h = NULL,
  r = NULL,
  print.all = FALSE,
  round.d = FALSE
)

Arguments

corr.structure

One of "ar1", exponential, gaussian, or "CS". Correlations between locations i and j are rho^{d} for corr.structure = "ar1", exp(-phi * d) for corr.structure = "exponential", exp(-phi * d ^ 2) for corr.structure = "gaussian", and rho when corr.structure = "CS". Note that d is the Euclidean distance between locations i and j.

im.res

A vector defining the dimension of spatial data. The first entry is the number of rows and the second entry is the number of columns.

corr.min

Scalar value to specify the minimum non-zero correlation. Any correlations below corr.min are set to 0. Especially for high image resolution using this option can result in a sparser covariance matrix, which may significantly speed up draws when using spam. This option is preferred to using neighborhood and associated arguments when the primary concern is to avoid very small correlations and improve computation efficiency. Default is NULL, which places no restrictions on the correlations.

neighborhood

Defines the neighborhood within which marginal correlations are non-zero. The default is "none", which allows marginal correlations to extend indefinitely. neighborhood = "round" defines a circular neighborhood about locations and neighborhood = "rectangle" defines a rectangular neighborhood about locations. Note that this argument differs from that in precision_builder, in which neighborhood defines conditional non-zero correlations.

rho

This is the maximum possible correlation between locations i and j. For all i,j rho MUST be between -1 and 1.

phi

A scalar value greater than 0 that determines the decay rate of correlation. This argument is only utilized when corr.structure %in% c("exponential", "gaussian").

w, h

If neighborhood = "rectangle" then w and h are the number of locations to the left/right and above/below a location i that define its neighborhood. Any locations outside this neighborhood have have zero correlation with location i.

r

If neighborhood = "round", then if locations i,j are separated by distance d \ge r, the correlation between them is zero.

print.all

If print.all = TRUE, then prints each correlation and allows you to check whether the correlations are as you intended. This option is NOT recommended for large point lattices/images.

round.d

If round.d = TRUE, then d is rounded to the nearest whole number.

Value

Returns (nr*nc) by (nr*nc) correlation matrix.

Note

Caution is recommended when using corr.min or neighborhood to set many correlations to 0, as not all specifications will result in a positive definite matrix. In particular, sharp drop-offs tend to result in non-positive definite matrices.

Examples

## examples
correlation_builder(corr.structure = "ar1", im.res = c(3, 3), rho = 0.5,
                    neighborhood = "round", r = 6, print.all = TRUE)

correlation_builder(corr.structure = "exponential", im.res = c(3, 3), 
                    phi = 0.5,
                    neighborhood = "round", r = 3, print.all = TRUE)

correlation_builder(corr.structure = "CS", im.res = c(3, 3),
                    rho = 0.5, print.all = TRUE)

## no "true" zeros, but gets close
c.nr <- correlation_builder(corr.structure = "ar1", neighborhood = "none",
                    corr.min = NULL, im.res = c(15, 15), rho = 0.5)
length(c.nr[c.nr > 0])
min(c.nr)

## set corr.min gives many zero entries; sparser structure
c.r <- correlation_builder(corr.structure = "ar1", neighborhood = "none",
                    corr.min = 0.01, im.res = c(15, 15), rho = 0.5)
## raw number > 0
length(c.r[c.r > 0])
## proportion > 0
length(c.r[c.r > 0]) / length(c.nr)