Create a spatial covariance parameter initial object

Create a spatial covariance parameter initial object that specifies initial and/or known values to use while estimating spatial covariance parameters with splm(), spglm(), spautor(), or spgautor().

Usage

spcov_initial(spcov_type, de, ie, range, extra, rotate, scale, known)

Arguments

spcov_type: The spatial covariance function type. Available options include "exponential", "spherical", "gaussian", "triangular", "circular", "cubic", "pentaspherical", "cosine", "wave", "jbessel", "gravity", "rquad", "magnetic", "matern", "cauchy", "pexponential", "car", "sar", and "none".
de: The spatially dependent (correlated) random error variance. Commonly referred to as a partial sill.
ie: The spatially independent (uncorrelated) random error variance. Commonly referred to as a nugget.
range: The correlation parameter.
extra: An extra covariance parameter used when spcov_type is "matern", "cauchy", "pexponential", "car", or "sar".
rotate: Anisotropy rotation parameter (from 0 to \(\pi\) radians). Not used if spcov_type is "car" or "sar".
scale: Anisotropy scale parameter (from 0 to 1). Not used if spcov_type is "car" or "sar".
known: A character vector indicating which spatial covariance parameters are to be assumed known. The value "given" is shorthand for assuming all spatial covariance parameters given to spcov_initial() are assumed known.

Value

A list with two elements: initial and is_known. initial is a named numeric vector indicating the spatial covariance parameters with specified initial and/or known values. is_known is a named numeric vector indicating whether the spatial covariance parameters in initial are known or not. The class of the list matches the value given to the spcov_type argument.

Details

The spcov_initial list is later passed to splm(), spglm(), spautor(), or spgautor(). NA values can be given for ie, rotate, and scale, which lets these functions find initial values for parameters that are sometimes otherwise assumed known (e.g., rotate and scale with splm() and spglm() and ie with spautor() and spgautor()). The spatial covariance functions can be generally expressed as \(de * R + ie * I\), where \(de\) is de above, \(R\) is a matrix that controls the spatial dependence structure among observations, \(h\), \(ie\) is ie above, and \(I\) is and identity matrix. Note that \(de\) and \(ie\) must be non-negative while \(range\) must be positive, except when spcov_type is car or sar, in which case \(range\) must be between the reciprocal of the maximum eigenvalue of W and the reciprocal of the minimum eigenvalue of W. Parametric forms for \(R\) are given below, where \(\eta = h / range\):

exponential: \(exp(- \eta )\)
spherical: \((1 - 1.5\eta + 0.5\eta^3) * I(h <= range)\)
gaussian: \(exp(- \eta^2 )\)
triangular: \((1 - \eta) * I(h <= range)\)
circular: \((1 - (2 / \pi) * (m * sqrt(1 - m^2) + sin^{-1}(m))) * I(h <= range), m = min(\eta, 1)\)
cubic: \((1 - 7\eta^2 + 8.75\eta^3 - 3.5\eta^5 + 0.75\eta^7) * I(h <= range)\)
pentaspherical: \((1 - 1.875\eta + 1.25\eta^3 - 0.375\eta^5) * I(h <= range)\)
cosine: \(cos(\eta)\)
wave: \(sin(\eta) / \eta * I(h > 0) + I(h = 0)\)
jbessel: \(Bj(h * range)\), Bj is Bessel-J function
gravity: \((1 + \eta^2)^{-0.5}\)
rquad: \((1 + \eta^2)^{-1}\)
magnetic: \((1 + \eta^2)^{-1.5}\)
matern: \(2^{1 - extra}/ \Gamma(extra) * \alpha^{extra} * Bk(\alpha, extra)\), \(\alpha = (2extra * \eta)^{0.5}\), Bk is Bessel-K function wit order \(1/5 \le extra \le 5\)
cauchy: \((1 + \eta^2)^{-extra}\), \(extra > 0\)
pexponential: \(exp(h^{extra}/range)\), \(0 < extra \le 2\)
car: \((I - range * W)^{-1} * M\), weights matrix \(W\), symmetry condition matrix \(M\), observations with no neighbors are given a unique variance parameter called \(extra\), \(extra \ge 0\).
sar: \([(I - range * W)(I - range * W)^T]^{-1}\), weights matrix \(W\), \(^T\) indicates matrix transpose, observations with no neighbors are given a unique variance parameter called \(extra\), \(extra \ge 0\).
none: \(0\)

All spatial covariance functions are valid in one spatial dimension. All spatial covariance functions except triangular and cosine are valid in two dimensions.

When the spatial covariance function is car or sar, extra represents the variance parameter for the observations in W without at least one neighbor (other than itself) -- these are called unconnected observations. extra is only used if there is at least one unconnected observation.

Examples

# known de value 1 and initial range value 0.4
spcov_initial("exponential", de = 1, range = 0.4, known = c("de"))
#> $initial
#>    de range 
#>   1.0   0.4 
#> 
#> $is_known
#>    de range 
#>  TRUE FALSE 
#> 
#> attr(,"class")
#> [1] "exponential"
# known ie value 0 and known range value 1
spcov_initial("gaussian", ie = 0, range = 1, known = c("given"))
#> $initial
#>    ie range 
#>     0     1 
#> 
#> $is_known
#>    ie range 
#>  TRUE  TRUE 
#> 
#> attr(,"class")
#> [1] "gaussian"
# ie given NA
spcov_initial("car", ie = NA)
#> $initial
#> ie 
#> NA 
#> 
#> $is_known
#>    ie 
#> FALSE 
#> 
#> attr(,"class")
#> [1] "car"