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().
spcov_initial(spcov_type, de, ie, range, extra, rotate, scale, known)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".
The spatially dependent (correlated) random error variance. Commonly referred to as a partial sill.
The spatially independent (uncorrelated) random error variance. Commonly referred to as a nugget.
The correlation parameter.
An extra covariance parameter used when spcov_type is
"matern", "cauchy", "pexponential", "car", or
"sar".
Anisotropy rotation parameter (from 0 to \(\pi\) radians).
Not used if spcov_type is "car" or "sar".
Anisotropy scale parameter (from 0 to 1).
Not used if spcov_type is "car" or "sar".
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.
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.
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. An alias for none is ie.
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.
# 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"