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

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

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