Skip to contents

Fit an evolutionary model for niche parameters

Source: R/fit_evolution.R
fit_evolution.Rd

Unified interface for fitting phylogenetic evolutionary models (BM, OU, null) to the fundamental niche parameters estimated by fit_niche().

Usage

fit_evolution(
  stan_data,
  model = c("bm_constant", "bm_evolving", "ou_constant", "ou_evolving", "null"),
  chains = 4,
  iter_warmup = 1000,
  iter_sampling = 1000,
  seed = NULL,
  grainsize = 1,
  threads_per_chain = 1,
  mod = NULL,
  ...
)

Arguments

stan_data

A named list of Stan data, as returned by prepare_phylo_data() or prepare_phylo_niche_data(). Bookkeeping fields attached by the prepare functions (species, masked, ...) are dropped automatically via stan_only() before sampling. For the null model, the phylogenetic matrix C should be omitted.

model

Character string specifying the model. One of: "bm_constant" (BM with constant Sigma), "bm_evolving" (BM with evolving Sigma), "ou_constant" (OU with constant Sigma), "ou_evolving" (OU with evolving Sigma), "null" (independent species, no phylogeny).

chains

Integer, number of MCMC chains (default 4).

iter_warmup

Integer, warmup iterations per chain (default 1000).

iter_sampling

Integer, sampling iterations per chain (default 1000).

seed

Integer, random seed for reproducibility.

grainsize

Integer, grainsize for reduce_sum.

threads_per_chain

Integer, threads per chain for within-chain parallelisation (default 1). Values > 1 require the model compiled with stan_threads = TRUE.

mod

Optional pre-compiled CmdStanModel. If NULL, the model is compiled internally via compile_model().

...

Additional arguments passed to mod$sample().

Value

A CmdStanMCMC object. Use $summary() to obtain posterior summaries. Generated quantities include Sigma, R_corr, and log_lik per species.

Details

The model names map to the following Stan files:

bm_constantinst/stan/niche_bm_constant_sigma.stan
bm_evolvinginst/stan/niche_bm_evolving_sigma.stan
ou_constantinst/stan/niche_ou_constant_sigma.stan
ou_evolvinginst/stan/niche_ou_evolving_sigma.stan
nullinst/stan/niche_null_model.stan

For HPC workflows, pre-compile the model with compile_model() and pass the returned CmdStanModel object to the mod argument to avoid redundant compilation across parallel jobs.

Examples

if (FALSE) { # \dontrun{
  # Assume stan_data is prepared via prepare_phylo_data()
  mod <- compile_model("bm_constant")
  fit <- fit_evolution(stan_data, model = "bm_constant", mod = mod, chains = 2)
  fit$summary()
} # }