Generic dense-kernel covariance keywords

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, rho = 1)

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

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

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.

rho

Source strength: a number in [0,1] fixes rho * K + (1-rho) * diag(diag(K)) on the legacy-resolved source scale. Omitted or explicit 1 preserves the existing model. NULL estimates strength for one Gaussian structured trait-intercept block with complete replicated multivariate observations and no competing ordinary covariance. Estimated latent terms require rank one and at least four traits. The same strength applies to the entire latent-plus-Psi covariance. This parameter is not a variance-share summary. Fixed attenuation and the admitted Gaussian estimator have implementation checks; recovery is regime-specific.

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")
} # }