spcov_initial {spmodel}

Create a spatial covariance parameter initial object

Description

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.

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.

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.

Examples

# known de value 1 and initial range value 0.4
spcov_initial("exponential", de = 1, range = 0.4, known = c("de"))
# known ie value 0 and known range value 1
spcov_initial("gaussian", ie = 0, range = 1, known = c("given"))
# ie given NA
spcov_initial("car", ie = NA)