Phylogenetic response-column slopes

Adds slope-only predictor deviations across response columns, with a tree relating those columns. If B is the response-column by predictor coefficient matrix, the model is $$\mathrm{Cov}(\mathrm{vec}(B^\mathsf{T})) = K_\mathrm{phy} \otimes \Sigma_\mathrm{predictor}.$$ The RHS must be the response-column factor resolved from trait =, and the tree's tips must match its levels. A single | estimates a full predictor covariance; || gives separate predictor variances with zero covariance. Both bars are identical with one predictor. The term never adds a random intercept; put column intercepts in the main formula with 0 + trait.

Usage

phylo_slope(formula, tree = NULL, vcv = NULL, A = NULL, Ainv = NULL)

Arguments

formula

A slope-only x1 + ... + xP | trait or || trait formula.

tree

An ape::phylo object whose tip labels match the resolved response-column levels. Canonical.

vcv

A labelled response-column covariance/correlation matrix. Legacy alias of A =.

A

A labelled response-column relatedness matrix; alias of vcv =.

Ainv

A labelled response-column precision matrix (inverse of A). Sparse inputs are preserved.

Value

A formula marker; never evaluated.

Details

Scope

This route is covered for Gaussian long-format data with one or more bare, finite numeric predictors. Wide-format column slopes, non-Gaussian responses, transformed/factor bases, latent predictor covariance, and intervals are not supported in this release. Use extract_Sigma(fit, level = "column_slope") for \(\Sigma_\mathrm{predictor}\).

For trait-specific intercept-and-slope covariance, use the corresponding augmented phylo_indep(), phylo_latent(), or phylo_dep() syntax.

A historical non-trait RHS route remains accepted to preserve existing fits. It is compatibility behaviour, not the teaching API; new code puts the resolved response-column factor on the RHS.

See also

slope(), animal_slope(), kernel_slope(), spatial_slope(), phylo_dep(), phylo_indep(), extract_Sigma().

Examples

if (FALSE) if (requireNamespace("ape", quietly = TRUE)) {
  set.seed(1); tree <- ape::rcoal(6); tree$tip.label <- paste0("sp", 1:6)
  dat <- expand.grid(site = factor(paste0("s", 1:12)), trait = factor(tree$tip.label))
  dat$elevation <- rnorm(nrow(dat)); dat$forest_cover <- rnorm(nrow(dat))
  dat$value <- rnorm(nrow(dat))
  fit <- gllvmTMB(value ~ 0 + trait + phylo_slope(elevation + forest_cover | trait, tree = tree),
    data = dat, trait = "trait", unit = "site", family = gaussian())
  extract_Sigma(fit, level = "column_slope")
} # \dontrun{}