metricm: Distance-based (metric) spatial correlation structures

In sommer: Solving Mixed Model Equations in R

Distance-based (metric) spatial correlation structures

Description

Exponential, power, gaussian, spherical and circular correlation structures computed from distances between locations, isotropic or anisotropic. The returned dimensionless covariance shape is intended for use inside vsm, which supplies the single overall variance scale.

Usage

metricm(x, model = c("exponential", "power", "gaussian", "spherical", "circular"),
        range = NULL, rho = NULL, anisotropy = c("none", "product", "geometric"),
        angle = pi/2, ratio = 1.5, metric = c("euclidean", "manhattan"),
        distance = NULL, fixed = NULL)

Arguments

x	Numeric coordinate vector (1-D) or matrix/data frame whose rows give coordinates. Repeated coordinates share one covariance level.
model	Correlation function, see Details.
range	Starting range \phi (one per axis with product anisotropy). Defaults to the median positive distance.
rho	Starting correlation per unit distance for model="power", in (0,1). Defaults to e^{-1} at the median distance.
anisotropy	"none"; "product", one parameter per axis, K=f_x(|dx|)f_y(|dy|); or "geometric", coordinates rotated by angle and the second rotated axis divided by ratio. Anisotropy requires 2-D coordinates.
angle	Starting anisotropy angle in (0, pi).
ratio	Starting positive anisotropy ratio.
metric	Distance metric for isotropic models; "manhattan" is only valid (positive definite) for the exponential and power models.
distance	Optional symmetric q by q distance matrix with zero diagonal, aligned to the unique locations (isotropic models only).
fixed	Logical vector, one value per parameter (in the order range/rho, then angle and ratio), recycled if of length one.

Details

With h=d/\phi:

model	K(d)	validity	ASReml
exponential	e^{-h}	any dimension	exp, iexp
power	\rho^{d}	any dimension	exp, iexp (same parameterization)
gaussian	e^{-h^2}	any dimension	gau, igau
spherical	1-\frac32h+\frac12h^3 for h<1, else 0	up to 3-D	isp
circular	\frac{2}{\pi}(\arccos h-h\sqrt{1-h^2}) for h<1, else 0	up to 2-D	cir

Product anisotropy (exponential, power and gaussian) corresponds to ASReml aexp/agau; geometric anisotropy corresponds to ASReml's anisotropic Matern and is also available in maternm. The power model is the exponential model with \phi=-1/\log\rho, and the exponential model equals maternm(nu=0.5).

Ranges and ratios are optimized on log scales, correlations and angles through bounded logits, with analytic derivatives. The structure is dense over the q locations, so it is intended for up to a few thousand locations. On a complete row-by-column grid, product anisotropy is a Kronecker product of two 1-D structures; vsm(metricm(row, "power"), metricm(col, "power"), ism(units)) fits the same model while keeping the compact grid engine. The gaussian model is nearly singular for close locations; keep a residual (nugget) term. With geometric anisotropy the angle is not identifiable when the ratio is close to one, and the ratio can drift to extreme values when the data are isotropic.

Value

A list with the incidence matrix Z and a CovarianceFactor descriptor covFactor, for use inside vsm.

See Also

maternm, ar1m, sar, car, vsm.

Examples

set.seed(1)
co <- cbind(x = runif(30, 0, 10), y = runif(30, 0, 10))
d <- data.frame(x = rep(co[, 1], each = 2), y = rep(co[, 2], each = 2), one = factor(1))
d$yield <- rnorm(60)
fit <- mmes(yield ~ 1,
  random = ~ vsm(metricm(cbind(x, y), model = "power"), ism(one)),
  data = d,
  control = mmes_control(diagnostics = list(verbose = FALSE)))
covparams_mmes(fit)

sommer documentation built on Oct. 24, 2026, 1:08 a.m.