Per-species boundary diagnostics at a fitted point — niche_boundary

Flags niche parameters that sit on an identifiability boundary of the J&S presence-only likelihood: at_floor (\(\sigma\) pinned at sigma_floor, the degenerate point-mass mode), rho_at_cap (sliver-like ellipse, \(|\rho| \to \rho_{\mathrm{cap}}\)), and sigma_huge (nearly-uniform niche over the accessible area). These are diagnostics, not errors: a species at the floor with few environmental cells is microendemic – a real identifiability limit – whereas one with many cells and good background coverage was likely a sampling artefact of the background draw.

Usage

niche_boundary_report(
  data,
  theta,
  parameterization = "noncentered_bounded",
  sigma_floor = 0.02,
  rho_cap = 0.98
)

Arguments

data: A list from prepare_phylo_niche_data().
theta: A theta vector (see niche_theta_layout()).
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.

Value

A data.frame with per-species sigma1, sigma2, rho, empirical SD floor (emp_sd_min), n_occ, n_cells, masked, and a flag column ("ok", "masked", "at_floor", "rho_at_cap", "sigma_huge", "few_cells").