Phylogenetic structured-effect marker

phylo() marks user-facing syntax for phylogenetic dependence. The current fitted paths support Gaussian location and residual-scale effects, response-specific direct-SD formulas for location effects, labelled bivariate Gaussian location-scale blocks, and single-axis ordinary Poisson and NB2 location effects. Use phylo(1 | species, tree = tree) in univariate Gaussian mu, univariate Gaussian sigma, ordinary Poisson mu, or ordinary NB2 mu, phylo(1 + x | species, tree = tree) for the supported unlabelled ordinary Poisson/NB2 count slope, one numeric univariate Gaussian mu slope with independent intercept/slope SDs, matching univariate Gaussian mu and sigma intercept terms for a mean-scale phylogenetic correlation, matching terms in bivariate Gaussian mu1 and mu2, matching labelled all-four intercept terms across Gaussian mu1, mu2, sigma1, and sigma2, or the supported shared-label all-four one-slope model. A single shared intercept label estimates the full q4 block; a mu1/mu2 intercept label plus a separate sigma1/sigma2 intercept label estimates the block-diagonal fallback. The all-four phylo(1 + x | p | species, tree = tree) model has native point-fit/extractor evidence only; bridge parity, intervals, coverage, REML, AI-REML, block-diagonal all-four slope layouts, Gaussian multiple phylogenetic slopes, pure, labelled, or multiple non-Gaussian phylogenetic slopes, zero-inflated phylogenetic effects, and phylogenetic slope correlations are not supported. The public phylo() API requires an ultrametric tree with branch lengths and normalizes the Brownian covariance by the tree height when building the Hadfield and Nakagawa A-inverse sparse-precision path. Thus the latent Brownian field has unit variance at each tip, and the fitted phylogenetic SD uses this unit-height convention. Multiplying all branch lengths by a positive constant leaves the normalized covariance unchanged. The supplied tree object is not modified.

Usage

phylo(term, tree, tolerance = sqrt(.Machine$double.eps))

Arguments

term

Structured random-effect term, currently 1 | species or 1 + x | species.

tree

Ultrametric phylogeny input with branch lengths. Relative branch lengths determine the phylogenetic covariance; absolute tree height is normalized internally.

tolerance

Relative tolerance for the ultrametricity check, applied as tolerance * scale where scale is the tree height (see validate_phylo_tree()). Defaults to sqrt(.Machine$double.eps). Raise it only after confirming with range(ape::node.depth.edgelength(tree)[seq_len(ape::Ntip(tree))]) that the tip-depth spread is genuinely negligible for the tree, not a real problem with it.

Value

A formula marker; never evaluated by users.

Examples

bf(y ~ x + phylo(1 | species, tree = tree), sigma ~ z)
#> <drm_formula>
#> y ~ x + phylo(1 | species, tree = tree)
#> sigma ~ z
bf(count ~ x + phylo(1 | species, tree = tree))
#> <drm_formula>
#> count ~ x + phylo(1 | species, tree = tree)
bf(count ~ x + phylo(1 + x | species, tree = tree))
#> <drm_formula>
#> count ~ x + phylo(1 + x | species, tree = tree)
bf(y ~ x + phylo(1 | species, tree = tree, tolerance = 1e-4))
#> <drm_formula>
#> y ~ x + phylo(1 | species, tree = tree, tolerance = 1e-04)