Phylogenetic random effect: lme4-bar mode-dispatch wrapper

phylo() is a unified entry point for the package's four taught phylogenetic modes (phylo_scalar, phylo_indep, phylo_latent, phylo_dep). It accepts an lme4-bar formula on the first argument and dispatches to the appropriate canonical keyword based on the LHS shape and the optional mode = ... argument. The four current keywords stay first-class – phylo() is an additive alias matching the lme4 / brms / drmTMB convention.

Usage

phylo(
  formula,
  tree = NULL,
  vcv = NULL,
  mode = NULL,
  d = 1,
  unique = FALSE,
  A = NULL,
  Ainv = NULL
)

Arguments

formula: An lme4-bar formula (<lhs> | <species_column>) OR, for backward-compat, a bare unquoted column name (legacy form). The bar's RHS is the species factor; the LHS determines the covariance structure (combined with mode, see Dispatch rules).
tree: An ape::phylo object. Canonical. Sparse \(\mathbf A^{-1}\) via Hadfield & Nakagawa (2010).
vcv: A tip-only phylogenetic correlation matrix (n_species x n_species). Legacy / superseded.
mode: One of "scalar" / "indep" / "latent" / "dep". Optional when LHS is 1 (defaults silently to "scalar"). Mandatory when LHS is 0 + trait.
d: Latent rank for mode = "latent". Default 1.
unique: Logical; for mode = "latent", TRUE includes the phylo-structured diagonal \(\boldsymbol\Psi_{phy}\) companion. The default FALSE preserves the loadings-only source-specific latent path.
A: Tip-level relatedness matrix; alias of vcv =.
Ainv: Sparse precision matrix (inverse of A).

Value

A formula marker; never evaluated.

Dispatch rules

Form	Mode default	Rewrites to
`phylo(1 \\| species)`	`"scalar"`	`phylo_scalar(species)`
`phylo(0 + trait \\| species, mode = "indep")`	(mandatory)	`phylo_indep(0 + trait \\| species)`
`phylo(0 + trait \\| species, mode = "latent", d = K)`	(mandatory)	`phylo_latent(species, d = K)`
`phylo(0 + trait \\| species, mode = "dep")`	(mandatory)	`phylo_dep(0 + trait \\| species)`

When the LHS expands to a single column (1, intercept-only), mode is degenerate: it defaults silently to "scalar", and explicit mode = "scalar" is accepted (no warning). When the LHS is 0 + trait, mode is mandatory – choosing between "indep" / "latent" / "dep" is a meaningful decision (per-trait diagonal vs reduced-rank decomposition vs full unstructured) and the parser refuses to silently default.

Backward compatibility

Legacy bare-name calls phylo(species) and phylo(species, vcv = Cphy) continue to work as deprecated aliases of phylo_scalar(species) / phylo_scalar(species, vcv = Cphy). The legacy form rewrites to propto(0 + species | trait) internally, picking up the phylogenetic covariance from the top-level phylo_vcv = argument to gllvmTMB().

Intercept-and-slope terms

The unified phylo() wrapper is limited to intercept-only trait covariance. For an intercept and one or more slopes, use an explicit structured mode such as phylo_indep(), phylo_latent(), or phylo_dep(); unsupported LHS forms fail with a message showing the accepted syntax.

Cross-package coexistence

drmTMB also exposes phylo(1 | species, tree = tree) with the same Hadfield-Nakagawa sparse \(\mathbf A^{-1}\) internal path. Both packages share the same calling convention; user muscle memory transfers.

Examples

if (FALSE) { # \dontrun{
library(ape)
tree <- rcoal(20); tree$tip.label <- paste0("sp", 1:20)
# Single shared phylogenetic variance (= phylo_scalar)
fit_s <- gllvmTMB(value ~ 0 + trait + phylo(1 | species, tree = tree),
                  data    = df,
                  trait   = "trait",
                  unit    = "species",
                  cluster = "species")
# Per-trait independent phylogenetic variances on shared A
fit_u <- gllvmTMB(value ~ 0 + trait +
                    phylo(0 + trait | species, mode = "indep", tree = tree),
                  data    = df,
                  trait   = "trait",
                  unit    = "species",
                  cluster = "species")
# Reduced-rank cross-trait phylogenetic decomposition (= phylo_latent)
fit_l <- gllvmTMB(value ~ 0 + trait +
                    phylo(0 + trait | species, mode = "latent",
                          d = 2, tree = tree),
                  data    = df,
                  trait   = "trait",
                  unit    = "species",
                  cluster = "species")
# Backward-compat: legacy bare-name form
Cphy <- vcv(tree, corr = TRUE)
fit_legacy <- gllvmTMB(value ~ 0 + trait + phylo(species),
                       data      = df,
                       trait     = "trait",
                       unit      = "species",
                       cluster   = "species",
                       phylo_vcv = Cphy)
} # }