Skip to contents

Joint phylo-niche log-posterior on the unconstrained scale

Source: R/niche_logpost.R
niche_logpost.Rd

Exact R implementation of the joint niche-evolution log-posterior used by the bm_evolving / ou_evolving Stan models, evaluated on the unconstrained ("math") parameter scale. This is the objective optimized by niche_multistart() and the reference for the compiled C++ backend (niche_logpost_xptr()); both agree to ~1e-12.

Usage

niche_logpost(
  theta,
  data,
  parameterization = c("noncentered_bounded", "noncentered", "centered",
    "centered_lograte", "unb", "bnd", "ctr", "ctrlr"),
  sigma_floor = 0.02,
  rho_cap = 0.98,
  debug = FALSE
)

Arguments

theta

Numeric vector in Stan declaration order (see niche_theta_layout() for names and length).

data

A prepared list from prepare_phylo_niche_data().

parameterization

One of "noncentered" (raw deviations, no bound on rho), "noncentered_bounded" (raw deviations, rho = rho_cap * tanh(z_rho); matches the Stan models), "centered", or "centered_lograte" (centered traits with declared log-rate parameters and lognormal rate priors).

sigma_floor

Hard lower bound on niche tolerances. The J&S presence-only likelihood has an unbounded spike as \(\sigma \to 0\) when the background sample does not cover the occurrence cluster (the "bg-hole" mode); the floor keeps the optimizer out of that degenerate region. Set to 0 to disable (not recommended on real data).

rho_cap

Bound on \(|\rho|\) for the bounded parameterizations.

debug

Print the prior/Jacobian/likelihood decomposition.

Value

Scalar log-posterior density (up to a constant), or -Inf outside the support.

Details

Parameter layout (Stan declaration order; rate slots hold log(rate)):


  mu_anc[P] | log_sigma_anc[P] | lrate_mu[P] | lrate_ls[P] |
  trait_matrix[S*P col-major] | shape_matrix[S*P] |
  z_rho_anc | lrate_rho | z_rho_vec[S]

For non-centered parameterizations the matrices are mu_raw and log_sigma_raw (standard-normal deviations mapped through chol(C)); for centered ones they are mu and log_sigma directly, with MVN(anc, rate*C + jitter*I) priors.

Species listed in data$masked contribute exactly zero to the likelihood (they carry no occurrence/background rows) but remain in the phylogenetic prior, so their niche is predicted from their relatives.

See also

niche_multistart, niche_logpost_xptr, prepare_phylo_niche_data