Skip to contents

Single-shared-variance phylogenetic random effect: phylo_scalar(species)

Source: R/brms-sugar.R
phylo_scalar.Rd

Soft-deprecated; use phylo_indep(0 + trait | species, common = TRUE). Name for the single-scalar (per-trait) phylogenetic random intercept. Each trait carries an independent length-n_species draw \(\mathbf p_t \sim \mathcal{N}(\mathbf{0}, \sigma^{2}_{\text{phy}}\,\mathbf{C}_{\text{phy}})\) with one shared scaling \(\sigma^{2}_{\text{phy}}\) across all traits. Formerly phylo(species) – same engine, new name. Compare to phylo_indep() (D independent variances) and phylo_latent() (K-dim factor decomposition).

Usage

phylo_scalar(species, tree = NULL, vcv = NULL, A = NULL, Ainv = NULL)

Arguments

species

Unquoted column name for the species factor.

tree

An ape::phylo object. Canonical.

vcv

A tip-only phylogenetic correlation matrix (n_species x n_species). Legacy alias of A =.

A

Tip-level relatedness matrix (n_species x n_species) – alias of vcv =, aligned with the animal_* family's argument naming.

Ainv

Sparse precision matrix (inverse of A).

Value

A formula marker; never evaluated.

Details

Pass the phylogeny via tree = phylo (canonical, sparse \(\mathbf{A}^{-1}\); Hadfield & Nakagawa 2010) or vcv = Cphy ([Superseded], dense). See phylo_latent() for the full discussion of the two paths.

See also

phylo_latent(), phylo_indep(), phylo_dep(), phylo() (deprecated alias).

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
  )
  sim$data$species <- factor(
    tree$tip.label[as.integer(sim$data$species)],
    levels = tree$tip.label
  )
  # phylo_scalar() is compatibility syntax and warns once per session;
  # the same model is phylo_indep(0 + trait | species, tree = tree,
  # common = TRUE).
  # \donttest{
  fit <- gllvmTMB(
    value ~ 0 + trait + phylo_scalar(species, tree = tree),
    data    = sim$data,
    trait   = "trait",
    unit    = "species",
    cluster = "species"
  )
  # }
}
#> Warning: ! Formula keyword `phylo_scalar()` is soft-deprecated as of gllvmTMB 0.5.0
#>   (compatibility syntax).
#> ℹ The covariance grid now has three modes: `indep()`, `dep()`, `latent()`. The
#>   one-shared-variance case is `common = TRUE`.
#> → Use `phylo_indep(..., common = TRUE)`; it fits the same model.