Fixed-kernel response-column slopes

Adds slope-only response-column deviations coupled by a supplied labelled covariance matrix K. With response-column by predictor coefficient matrix B, the model is $$\mathrm{Cov}(\mathrm{vec}(B^\mathsf{T})) = K \otimes \Sigma.$$ A single | estimates a full predictor covariance Sigma; || makes it diagonal. For one predictor these are the same model. K must be finite, symmetric, positive definite, and have row and column names matching the levels of the response-column factor. Its storage order need not match the factor order because labels are used for alignment.

Usage

kernel_slope(formula, K, name = "kernel")

Arguments

formula: A slope-only bar formula with bare numeric predictor names on the left and the resolved response-column factor on the right.
K: A labelled positive-definite covariance matrix for the response columns.
name: A non-empty label retained in extractor source metadata.

Value

A formula marker; never evaluated.

Details

Scope

This route is covered for one labelled positive-definite kernel, Gaussian long-format data, and one or more bare, finite numeric predictors. The supplied matrix is used on its original scale. Wide-format column slopes, non-Gaussian responses, transformed/factor bases, and a random intercept inside this term are not supported in this release.

Examples

set.seed(1)
dat <- expand.grid(unit = factor(1:20), trait = factor(paste0("sp", 1:8)))
dat$lat <- rnorm(nrow(dat)); dat$temp <- rnorm(nrow(dat))
# Each response column has its own slopes on lat and temp.
b_lat <- rnorm(8, sd = 0.5); b_temp <- rnorm(8, sd = 0.3)
k <- as.integer(dat$trait)
dat$value <- 0.2 * k + b_lat[k] * dat$lat + b_temp[k] * dat$temp +
  rnorm(nrow(dat), sd = 0.3)
# With K = diag(n) this is the same model as slope(); any labelled
# positive-definite K (e.g. a similarity among response columns) works.
K <- diag(nlevels(dat$trait))
dimnames(K) <- list(levels(dat$trait), levels(dat$trait))
# \donttest{
fit <- gllvmTMB(
  value ~ 0 + trait + kernel_slope(lat + temp | trait, K = K),
  data = dat, trait = "trait", unit = "unit",
  family = gaussian()
)
extract_Sigma(fit, level = "column_slope")
#> $Sigma
#>             lat       temp
#> lat  0.24382368 0.05533166
#> temp 0.05533166 0.05792642
#> 
#> $R
#>            lat      temp
#> lat  1.0000000 0.4655834
#> temp 0.4655834 1.0000000
#> 
#> $level
#> [1] "column_slope"
#> 
#> $part
#> [1] "dep"
#> 
#> $source
#> $source$type
#> [1] "kernel"
#> 
#> $source$grouping
#> [1] "trait"
#> 
#> $source$labels
#> [1] "sp1" "sp2" "sp3" "sp4" "sp5" "sp6" "sp7" "sp8"
#> 
#> $source$name
#> [1] "kernel"
#> 
#> $source$scale
#> [1] "as_supplied"
#> 
#> 
#> $predictors
#> [1] "lat"  "temp"
#> 
#> $column_labels
#> [1] "sp1" "sp2" "sp3" "sp4" "sp5" "sp6" "sp7" "sp8"
#> 
#> $note
#> [1] "Slope-only response-column coefficients from the kernel source with a full predictor covariance. The response-column source covariance supplies the other Kronecker factor; this is not a trait-level Sigma."
#> 
# }