ar1m: First-order autoregressive covariance structure

In sommer: Solving Mixed Model Equations in R

First-order autoregressive covariance structure

Description

First-order autoregressive covariance structure. The returned dimensionless covariance shape is intended for use inside vsm, which supplies the single overall variance scale.

Usage

ar1m(x, rho = 0.30, fixed = FALSE,
     variance = c("homogeneous", "heterogeneous"), values = NULL)

Arguments

x	Ordered factor or design defining q ordered covariance levels.
rho	Starting AR(1) correlation in (-1,1).
fixed	For homogeneous variance, a logical indicating whether rho is fixed. For heterogeneous variance, a logical vector of length q: rho followed by q-1 variance-ratio parameters.
variance	Whether the AR correlation has homogeneous or heterogeneous marginal variances.
values	Optional q positive starting variances when variance = "heterogeneous".

Details

The homogeneous AR(1) shape is

K_{ij}=\rho^{|i-j|}.

Heterogeneous mode uses

K=D R(\rho)D,

with the first variance fixed as the relative-scale reference. The working correlation coordinate is \eta=\operatorname{atanh}(\rho), ensuring |\rho|<1.

Factor levels define the lag order, so numeric-looking levels must be in increasing numeric order; ar1m() warns otherwise. Inside vsm() one correlation is shared by every level of the other Kronecker factors. For a separate correlation per trial, wrap the vsm() term in dsumm.

Value

A list containing the incidence/design matrix in Z and a compiled CovarianceFactor v2 descriptor in covFactor, for use inside vsm.

See Also

ar2m, ar3m, toeplitzm, vsm, dsumm.

Examples

## Not run: 
vsm(ar1m(time), ism(id))

# Separable row-by-range residual shared across trials:
# rcov = ~ vsm(dsm(trial), ar1m(range), ar1m(row), ism(units))
# Trial-specific correlations and variances:
# rcov = ~ dsumm(vsm(ar1m(range), ar1m(row), ism(units)), by=trial)

## End(Not run)

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