Skip to contents

Prepare joint phylogenetic niche data for evolutionary models

Source: R/prepare_phylo_niche_data.R
prepare_phylo_niche_data.Rd

Builds the concatenated data list used by the joint niche-evolution Stan models (e.g. bm_evolving, ou_evolving) and by niche_logpost() / niche_multistart(). Unlike prepare_niche_data() (single-species) and prepare_phylo_data() (two-stage niche_params interface), this function takes per-species occurrence and background environmental matrices directly and returns the object consumed by the joint models.

Usage

prepare_phylo_niche_data(
  env_occ_list,
  env_m_list,
  tree,
  mask_species = NULL,
  eta = 1,
  rate_mu_scale = 1,
  rate_log_sigma_scale = 1,
  rate_rho_scale = NULL,
  z_rho_anc_prior = 0,
  z_rho_anc_sigma = 1
)

Arguments

env_occ_list

Named list of numeric matrices (one per species): environmental values at occurrence points. Names must match the tip labels of tree.

env_m_list

Named list of numeric matrices with environmental values at background (accessible-area, \(M\)) points for each species. For commensurate niche estimates across species, pass the same shared sample to every species (see Details).

tree

A phylo object covering all species in env_occ_list.

mask_species

Optional character vector of tip labels to keep in the phylogenetic prior but exclude from the likelihood. Masked species contribute no occurrence/background rows, so the evolutionary model predicts their niche from their relatives – the recommended treatment for species whose realised occurrences occupy too few environmental cells to identify a two-dimensional ellipse (microendemics; see Details).

eta

Reserved for LKJ priors in higher-dimensional extensions.

rate_mu_scale

Scale of the half-normal prior on the BM rate of the centroid.

rate_log_sigma_scale

Scale of the half-normal prior on the BM rate of the log tolerances.

rate_rho_scale

Scale of the half-normal prior on the BM rate of z_rho. If NULL (default), set to 1 / max(diag(C)).

z_rho_anc_prior

Prior mean of the ancestral Fisher-z correlation.

z_rho_anc_sigma

Prior SD of the ancestral Fisher-z correlation.

Value

A named list with fields S, P, N_occ_total, occ, occ_start, N_occ, N_m_total, env_m, m_start, N_m, C, mu_anc_prior, mu_anc_sigma, rate_mu_scale, rate_log_sigma_scale, rate_rho_scale, z_rho_anc_prior, z_rho_anc_sigma, eta, species, masked. masked is a logical vector (length S, tree-tip order) flagging likelihood-excluded species.

Details

Shared background. The presence-only likelihood normalises each species' ellipse against its background sample. If every species receives an independent subsample of a shared accessible area, Monte Carlo holes near small-range clusters create a spurious \(\sigma \to 0\) likelihood mode (the "bg-hole" artefact). Always pass the identical background matrix (same rows) for every species, or use shared_background_sample() to draw it once.

Masking microendemics. Presence-only data only bound the fundamental niche from above; a species whose occurrences fall in \(\lesssim 10\) unique environmental cells carries essentially no information about niche shape, and its likelihood is dominated by the \(\sigma \to 0\) boundary. mask_species removes such species from the likelihood while keeping them in the phylogenetic covariance, so their niche is predicted from their relatives – turning an identifiability limit into a testable prediction target.

See also

niche_logpost, niche_multistart, niche_boundary_report