Project supplied niche states to geographic space — project_ancestral

Takes niche parameter estimates (extant species or ancestral states previously reconstructed by a phylogenetic evolutionary model) and projects them onto a geographic raster using the xnicher habitat-suitability engine. This function does not itself perform ancestral reconstruction; it consumes states estimated elsewhere.

Usage

project_ancestral_niche(
  phy,
  anc_mu,
  anc_Sigma,
  env,
  node_labels,
  output_dir = NULL,
  overwrite = FALSE,
  suffix = "ancestral",
  ...
)

Arguments

phy: An object of class phylo from ape, with tip labels matching the species for which ancestral states were reconstructed.
anc_mu: A S x P matrix of posterior mean ancestral niche centroid positions, one row per node (tips + internal nodes).
anc_Sigma: A S x P x P array of posterior mean ancestral niche covariance matrices.
env: A multi-layer SpatRaster from terra, with one layer per environmental variable, in the same order as the niche dimensions.
node_labels: Character vector of node labels (tips first, then internal nodes in the order returned by the model).
output_dir: Character. Directory to write GeoTIFF output files. If NULL, returns in-memory rasters.
overwrite: Logical. Whether to overwrite existing output files.
suffix: Character. Suffix appended to output file names (before extension).
...: Additional arguments passed to habitat_suitability.

Value

A named list of SpatRaster objects (one per node); names are node labels. When output_dir is NULL the rasters are in memory; otherwise they are file-backed GeoTIFFs.

Details

The function computes a habitat-suitability raster for each ancestral (or terminal) niche state using the habitat_suitability function from xnicher. The suitability is the standardized multivariate normal density \(S(x) = exp(-0.5 (x - mu)^\top Sigma^{-1} (x - mu))\) evaluated at every grid cell of the environmental raster.

For terminal (tip) nodes, the projected niche represents the contemporary niche envelope. For internal nodes, it represents the reconstructed ancestral niche. These can be compared to test hypotheses about niche conservatism vs. divergence.