Per-trait independent phylogenetic random intercepts: phylo_unique(species)

Canonical name for the D independent phylogenetic random intercepts. Each trait $t$ gets its own variance $\sigma^{2}_{\text{phy},t}$ on the same phylogenetic correlation matrix $\mathbf{C}_{\text{phy}}$; the per-trait random vectors are otherwise independent. Mathematically:

Usage

phylo_unique(species, tree = NULL, vcv = 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 / superseded.

Value

A formula marker; never evaluated.

Details

$$\mathbf p_t \sim \mathcal{N}(\mathbf{0},\, \sigma^{2}_{\text{phy},t}\,\mathbf{C}_{\text{phy}}),\qquad t = 1,\dots,T,$$

giving a phylogenetic counterpart of unique() – one independent variance per trait, all sharing the same phylogenetic precision.

Compare to phylo_scalar() (one shared variance), which collapses the T variances to a single $\sigma^{2}_{\text{phy}}$; and phylo_latent() (K factors), which induces across-trait correlation through a low-rank loading matrix.

Two co-fitting modes

phylo_unique() has two complementary modes:

Alone (legacy): When written without a paired phylo_latent(species, d = K), the engine implements the term internally as phylo_latent(species, d = T) with a diagonal $\boldsymbol\Lambda_{\text{phy}}$. The diagonal entries of $\boldsymbol\Lambda_{\text{phy}}$ are the per-trait phylogenetic SDs. This path stays for backward compatibility.
Paired with phylo_latent() (two-U PGLLVM, recommended): When written together with phylo_latent(species, d = K), the two terms co-fit as separate covariance components: $$\boldsymbol\Sigma_\text{phy} \;=\; \underbrace{\boldsymbol\Lambda_\text{phy}\boldsymbol\Lambda_\text{phy}^{\!\top}}_{\text{shared (rank K)}} \;+\; \underbrace{\mathbf S_\text{phy}}_{\text{per-trait unique}}.$$ $\boldsymbol\Lambda_\text{phy}$ is filled by the rank-K shared latent factors; $\mathbf S_\text{phy}$ carries the per-trait phylogenetic variances not absorbed by the K shared axes. This is the manuscript-aligned PGLLVM decomposition (Hadfield & Nakagawa 2010; Meyer & Kirkpatrick 2008; Halliwell et al. 2025). Replication (multiple sites per species) is required to break the S_phy / S_non confound at the species level.

Use extract_Sigma() with level = "phy" and part = "shared", "unique", or "total" to pull each component, the diagonal s_phy, or their sum.

Pass the phylogeny via tree = phylo (canonical, sparse $\mathbf{A}^{-1}$) or vcv = Cphy (, dense). See phylo_latent() for the full discussion of the two paths.

References

Hadfield, J. D. & Nakagawa, S. (2010) General quantitative genetic methods for comparative biology: phylogenies, taxonomies and multi-trait models for continuous and categorical characters. Journal of Evolutionary Biology 23(3): 494-508. doi:10.1111/j.1420-9101.2009.01915.x
Meyer, K. & Kirkpatrick, M. (2008) Perils of parsimony: properties of reduced-rank estimates of genetic covariance matrices. Genetics 178(4): 2223-2240.

Examples

if (FALSE) { # \dontrun{
  tree <- ape::rcoal(8); tree$tip.label <- paste0("sp", seq_len(8))
  sim <- simulate_site_trait(
    n_sites = 1, n_species = 8, n_traits = 3,
    mean_species_per_site = 8,
    Cphy = ape::vcv(tree, corr = TRUE),
    sigma2_phy = rep(0.3, 3), seed = 1
  )
  sim$data$species <- factor(sim$data$species, levels = tree$tip.label)
  fit <- gllvmTMB(
    value ~ 0 + trait + phylo_unique(species),
    data = sim$data, phylo_tree = tree
  )
} # }

Per-trait independent phylogenetic random intercepts: `phylo_unique(species)`