Simulate niche evolution along a phylogeny

Generates virtual-clade niche parameters (\(\mu\), \(\log\sigma\), \(z_\rho = \mathrm{atanh}(\rho)\)) under Brownian motion, Ornstein–Uhlenbeck, or an independent-species null process. The output matches the parameterization estimated by the joint models and consumed by virtual_species_occurrences(), enabling reverse-engineering benchmarks: simulate a niche-evolution process inside a real accessible area, then check that niche_multistart() / fit_evolution() recover it.

Usage

simulate_niche_evolution(
  tree,
  process = c("bm", "ou", "null"),
  mu_anc = c(0, 0),
  log_sigma_anc = log(c(0.4, 0.4)),
  z_rho_anc = 0,
  rate_mu = c(0.3, 0.3),
  rate_log_sigma = c(0.3, 0.3),
  rate_rho = 0.3,
  alpha = c(1, 1, 1),
  seed = NULL
)

Arguments

tree

A phylo object.

process

One of "bm" (Brownian motion), "ou" (Ornstein–Uhlenbeck toward the ancestral optimum), or "null" (independent species: every tip draws its niche independently of the phylogeny).

mu_anc

Length-2 ancestral centroid.

log_sigma_anc

Length-2 ancestral log tolerances.

z_rho_anc

Ancestral Fisher-z correlation.

rate_mu, rate_log_sigma, rate_rho

Evolutionary rates (BM variance per unit root-to-tip time; under "ou" the stationary variance is rate/(2*alpha)).

alpha

OU constraint strength per trait block (recycled if length 1): c(mu, log_sigma, z_rho). Ignored under "bm"/"null".

seed

Optional RNG seed.

Value

A list with mu (S x P), sigma (S x P, on the natural scale), rho (S), tree, and process. Row order matches tree$tip.label.

Details

Tips evolve by recursive branch traversal from the root: under BM each branch adds N(0, rate * branch_length); under OU the child value is theta + (parent - theta) * exp(-alpha * t) + N(0, rate/(2 alpha) * (1 - exp(-2 alpha t))); under "null" each tip draws independently of the root and of each other, N(theta, rate * t_tip) where t_tip is its terminal branch length.

See also

virtual_species_occurrences, niche_multistart