Phylogenetic random effect: lme4-bar mode-dispatch wrapper

phylo() is a unified entry point for the package's three phylogenetic modes (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 three 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_indep(0 + trait \\| species, common = TRUE)`
`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 (requireNamespace("ape", quietly = TRUE)) {
  set.seed(1)
  tree <- ape::rcoal(60); tree$tip.label <- paste0("sp", seq_len(60))
  sim <- simulate_site_trait(
    n_sites = 1, n_species = 60, n_traits = 3,
    mean_species_per_site = 60,
    Cphy = ape::vcv(tree, corr = TRUE),
    sigma2_phy = rep(1, 3), sigma2_eps = 0.2, seed = 1
  )
  df <- sim$data
  df$species <- factor(tree$tip.label[as.integer(df$species)],
                       levels = tree$tip.label)
  Cphy <- ape::vcv(tree, corr = TRUE)
  # \donttest{
  # Single shared phylogenetic variance (= phylo_indep(..., common = TRUE))
  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
  fit_legacy <- gllvmTMB(value ~ 0 + trait + phylo(species),
                         data      = df,
                         trait     = "trait",
                         unit      = "species",
                         cluster   = "species",
                         phylo_vcv = Cphy)
  # }
}
#> ! Formula keyword `phylo()` is a deprecated alias; use `phylo_indep()` for new
#>   code.
#> ℹ `phylo_indep(0 + trait | species, common = TRUE)` =/=> `phylo(species)`
#> → Aliases will be dropped at the next minor release. See `?phylo_indep`.