Bayesian estimation of the fundamental niche as a multivariate normal ellipsoid from occurrence data using Stan via cmdstanr, with phylogenetic evolutionary models (BM, OU) and ancestral state reconstruction.
Details
arfun is a complete framework for:
Estimating the fundamental niche as a bivariate normal ellipsoid from occurrence data (single species)
Fitting phylogenetic evolutionary models (BM, OU) to the niche parameters across multiple species
Reconstructing ancestral niche states
Projecting niches into geographic space
Single-species niche estimation
The fundamental niche is estimated as a bivariate normal ellipsoid where occurrence points follow a multivariate normal distribution with mean mu (centroid) and covariance Sigma = diag(sigma) * R * diag(sigma)
where mu is the centroid (optimal environment), sigma are the tolerances (niche breadths), and R is the correlation matrix.
The package provides:
- prepare_niche_data
Convert occurrence data into the list format required by the Stan model.
- fit_niche
Compile and fit the Bayesian presence-only niche model using cmdstanr.
- extract_pars
Extract posterior summaries of the niche centroid (
mu), standard deviations (sigma), covariance matrix (Sigma) and correlation matrix (R_corr).
Phylogenetic evolutionary models
For clade-level analyses, arfun provides five evolutionary models:
| Model | Description |
| bm_constant | BM on mu, sigma, rho; constant Sigma (Sharma et al. 2024 case) |
| bm_evolving | BM on mu, sigma, rho; evolving Sigma (per-species covariance) |
| ou_constant | OU on mu, sigma, rho; constant Sigma |
| ou_evolving | OU on mu, sigma, rho; evolving Sigma |
| null | Independent species, no phylogeny; each species has its own mu_s and Sigma_s |
Parallelisation
All models support reduce_sum parallelisation via:
compile_model(stan_threads = TRUE)— compile with thread supportfit_niche(..., grainsize = n, threads = m)— run with parallel likelihood evaluation
reduce_sum also compiles and runs serially without thread
support on CmdStan >= 2.33 (verified on CmdStan 2.36); threading only
changes speed, not correctness.
For HPC workflows, pre-compile the model once and pass the CmdStanModel
object to avoid redundant compilation across parallel jobs.
References
Jimenez, L., Soberon, J., Christen, J.A. and Soto, D. (2019). On the problem of modeling a fundamental niche from occurrence data. Ecological Modelling 397: 74-83. DOI: 10.1016/j.ecolmodel.2018.11.013
Jimenez, L. and Soberon, J. (2022). Estimating the fundamental niche: accounting for the uneven availability of existing climates in the calibration area. Ecological Modelling 464: 109823. DOI: 10.1016/j.ecolmodel.2021.109823
Sharma, S. et al. (2024). Phylogenetic comparative methods for niche evolution. In review.