Create a covariance parameter initial object

Source: R/initial.R

Create a covariance parameter initial object that specifies initial and/or known values to use while estimating specific covariance parameters with ssn_lm() or ssn_glm(). See spmodel::randcov_initial() for documentation regarding random effect covariance parameter initial objects.

tailup_initial(tailup_type, de, range, known)

taildown_initial(taildown_type, de, range, known)

euclid_initial(euclid_type, de, range, rotate, scale, known)

nugget_initial(nugget_type, nugget, known)

Arguments

tailup_type

The tailup covariance function type. Available options include "linear", "spherical", "exponential", "mariah", "epa", and "none".

de

The spatially dependent (correlated) random error variance. Commonly referred to as a partial sill.

range

The correlation parameter.

known

A character vector indicating which covariance parameters are to be assumed known. The value "given" is shorthand for assuming all covariance parameters given to *_initial() are assumed known.

taildown_type

The taildown covariance function type. Available options include "linear", "spherical", "exponential", "mariah", "epa", and "none".

euclid_type

The euclidean covariance function type. Available options include "spherical", "exponential", "gaussian", "cosine", "cubic", "pentaspherical", "wave", "jbessel", "gravity", "rquad", "magnetic", and "none".

rotate

Anisotropy rotation parameter (from 0 to \(\pi\) radians) for the euclidean portion of the covariance. A value of 0 (the default) implies no rotation.

scale

Anisotropy scale parameter (from 0 to 1) for the euclidean portion of the covariance. A value of 1 (the default) implies no scaling.

nugget_type

The nugget covariance function type. Available options include "nugget" or "none".

nugget

The spatially independent (not correlated) random error variance. Commonly referred to as a nugget.

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 the relevant spatial covariance type.

Details

Create an initial object for use with ssn_lm() or ssn_glm(). 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 ssn_lm() and ssn_glm(). Parametric forms for each spatial covariance type are presented below.

tailup_type Details: Let \(D\) be a matrix of hydrologic distances, \(W\) be a diagonal matrix of weights from additive, \(r = D / range\), and \(I\) be an identity matrix. Then parametric forms for flow-connected elements of \(R(zu)\) are given below:

  • linear: \((1 - r) * (r <= 1) * W\)

  • spherical: \((1 - 1.5r + 0.5r^3) * (r <= 1) * W\)

  • exponential: \(exp(-r) * W\)

  • mariah: \(log(90r + 1) / 90r * (D > 0) + 1 * (D = 0) * W\)

  • epa: \((D - range)^2 * F * (r <= 1) * W / 16range^5\)

  • none: \(I\) * W

Details describing the F matrix in the epa covariance are given in Garreta et al. (2010). Flow-unconnected elements of \(R(zu)\) are assumed uncorrelated. Observations on different networks are also assumed uncorrelated.

taildown_type Details: Let \(D\) be a matrix of hydrologic distances, \(r = D / range\), and \(I\) be an identity matrix. Then parametric forms for flow-connected elements of \(R(zd)\) are given below:

  • linear: \((1 - r) * (r <= 1)\)

  • spherical: \((1 - 1.5r + 0.5r^3) * (r <= 1)\)

  • exponential: \(exp(-r)\)

  • mariah: \(log(90r + 1) / 90r * (D > 0) + 1 * (D = 0)\)

  • epa: \((D - range)^2 * F1 * (r <= 1) / 16range^5\)

  • none: \(I\)

Now let \(A\) be a matrix that contains the shorter of the two distances between two sites and the common downstream junction, \(r1 = A / range\), \(B\) be a matrix that contains the longer of the two distances between two sites and the common downstream junction, \(r2 = B / range\), and \(I\) be an identity matrix. Then parametric forms for flow-unconnected elements of \(R(zd)\) are given below:

  • linear: \((1 - r2) * (r2 <= 1)\)

  • spherical: \((1 - 1.5r1 + 0.5r2) * (1 - r2)^2 * (r2 <= 1)\)

  • exponential: \(exp(-(r1 + r2))\)

  • mariah: \((log(90r1 + 1) - log(90r2 + 1)) / (90r1 - 90r2) * (A =/ B) + (1 / (90r1 + 1)) * (A = B)\)

  • epa: \((B - range)^2 * F2 * (r2 <= 1) / 16range^5\)

  • none: \(I\)

Details describing the F1 and F2 matrices in the epa covariance are given in Garreta et al. (2010). Observations on different networks are assumed uncorrelated.

euclid_type Details: Let \(D\) be a matrix of Euclidean distances, \(r = D / range\), and \(I\) be an identity matrix. Then parametric forms for elements of \(R(ze)\) are given below:

  • exponential: \(exp(- r )\)

  • spherical: \((1 - 1.5r + 0.5r^3) * (r <= 1)\)

  • gaussian: \(exp(- r^2 )\)

  • cubic: \((1 - 7r^2 + 8.75r^3 - 3.5r^5 + 0.75r^7) * (r <= 1)\)

  • pentaspherical: \((1 - 1.875r + 1.25r^3 - 0.375r^5) * (r <= 1)\)

  • cosine: \(cos(r)\)

  • wave: \(sin(r) * (h > 0) / r + (h = 0)\)

  • jbessel: \(Bj(h * range)\), Bj is Bessel-J function

  • gravity: \((1 + r^2)^{-0.5}\)

  • rquad: \((1 + r^2)^{-1}\)

  • magnetic: \((1 + r^2)^{-1.5}\)

  • none: \(I\)

nugget_type Details: Let \(I\) be an identity matrix and \(0\) be the zero matrix. Then parametric forms for elements the nugget variance are given below:

  • nugget: \(I\)

  • none: \(0\)

In short, the nugget effect is modeled when nugget_type is "nugget" and omitted when nugget_type is "none".

Dispersion and random effect initial objects are specified via spmodel::dispersion_initial() and spmodel::randcov_initial(), respectively.

References

Peterson, E.E. and Ver Hoef, J.M. (2010) A mixed-model moving-average approach to geostatistical modeling in stream networks. Ecology 91(3), 644--651.

Ver Hoef, J.M. and Peterson, E.E. (2010) A moving average approach for spatial statistical models of stream networks (with discussion). Journal of the American Statistical Association 105, 6--18. DOI: 10.1198/jasa.2009.ap08248. Rejoinder pgs. 22--24.

Examples

tailup_initial("exponential", de = 1, range = 20, known = "range")
#> $initial
#>    de range 
#>     1    20 
#> 
#> $is_known
#>    de range 
#> FALSE  TRUE 
#> 
#> attr(,"class")
#> [1] "tailup_exponential"
tailup_initial("exponential", de = 1, range = 20, known = "given")
#> $initial
#>    de range 
#>     1    20 
#> 
#> $is_known
#>    de range 
#>  TRUE  TRUE 
#> 
#> attr(,"class")
#> [1] "tailup_exponential"
euclid_initial("spherical", de = 2, range = 4, scale = 0.8, known = c("range", "scale"))
#> $initial
#>    de range scale 
#>   2.0   4.0   0.8 
#> 
#> $is_known
#>    de range scale 
#> FALSE  TRUE  TRUE 
#> 
#> attr(,"class")
#> [1] "euclid_spherical"
dispersion_initial("nbinomial", dispersion = 5)
#> $initial
#> dispersion 
#>          5 
#> 
#> $is_known
#> dispersion 
#>      FALSE 
#> 
#> attr(,"class")
#> [1] "nbinomial"