First-order autoregressive covariance structure

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.

Examples

if (FALSE) { # \dontrun{
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)
} # }