Phylogenetic random effect: lme4-bar mode-dispatch wrapper

phylo() is a unified entry point for the package's five canonical phylogenetic keywords (phylo_scalar, phylo_unique, 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 five canonical 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)

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" / "diag" / "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.

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 = "diag")`	(mandatory)	`phylo_unique(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 "diag" / "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().

Augmented LHS (Stage 3, not yet shipped)

Augmented LHS forms — 1 + x (intercept + slope), 0 + trait + (0 + trait):x (per-trait intercepts + per-trait slopes on covariate x), x || species (uncorrelated) — are reserved for Design 07 Stage 3 engine work. The parser currently raises an error pointing at this status.

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)
# Per-trait phylogenetic variances on shared A (= phylo_unique)
fit_u <- gllvmTMB(value ~ 0 + trait +
                    phylo(0 + trait | species, mode = "diag", tree = tree),
                  data = df)
# 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)
# Backward-compat: legacy bare-name form
Cphy <- vcv(tree, corr = TRUE)
fit_legacy <- gllvmTMB(value ~ 0 + trait + phylo(species),
                       data = df, phylo_vcv = Cphy)
} # }