Skip to contents

Generic dense-kernel covariance keywords

Source: R/kernel-keywords.R
kernel_latent.Rd

kernel_latent() fits a named random-effect tier with a user-supplied between-unit covariance matrix K. For one named tier, unique = TRUE adds a kernel-structured diagonal \(\boldsymbol\Psi\) companion; the default FALSE is loadings-only. Two or more named kernel_latent() tiers may share the same grouping levels, each with its own K, loading matrix, and latent field. Multi-kernel fits are loadings-only: unique = TRUE and kernel_dep() are not available in that combination. Similar kernels can be weakly separable, so use diagnose_kernel_separability() before assigning a distinct interpretation to each component.

A matrix returned by make_cross_kernel() is treated as a fixed supplied covariance. The model does not estimate its association structure or bridge strength. extract_Gamma() returns descriptive point summaries; it does not provide calibrated intervals or establish a causal evolutionary process.

Usage

kernel_latent(unit, K, d = 1, name = "kernel", unique = FALSE)

kernel_indep(unit, K, name = "kernel", common = FALSE)

kernel_dep(unit, K, name = "kernel")

Arguments

unit

Unquoted grouping column whose levels align with rownames(K).

K

Numeric dense positive-semidefinite covariance or correlation matrix aligned to the grouping levels.

d

Integer latent rank for kernel_latent().

name

Character scalar used as the extractor level, e.g. extract_Sigma(fit, level = "cross").

unique

Logical; TRUE auto-includes the kernel-structured diagonal trait-specific \(\boldsymbol\Psi\) companion for a single dense-kernel tier. The default FALSE preserves the loadings-only subset.

common

FALSE (default) for a separate dense-kernel variance per trait (kernel_indep); TRUE ties all traits to one shared variance, the canonical spelling for the soft-deprecated kernel_scalar().

Value

A formula marker; never evaluated as a regular R function.

Examples

if (FALSE) { # \dontrun{
A <- diag(5)
dat <- data.frame(
  unit = factor(rep(paste0("u", 1:5), each = 2), levels = paste0("u", 1:5)),
  obs = factor(seq_len(10)),
  y1 = rnorm(10),
  y2 = rnorm(10)
)
rownames(A) <- colnames(A) <- levels(dat$unit)
fit <- gllvmTMB(
  traits(y1, y2) ~
    1 + kernel_latent(unit, K = A, d = 1, name = "known",
                      unique = TRUE),
  data = dat,
  unit = "obs",
  cluster = "unit",
  family = gaussian()
)
extract_Sigma(fit, level = "known")
} # }