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