Compiled C++ objective for the phylo-niche log-posterior

Builds an external pointer to the compiled version of niche_logpost() (identical math, ~1e-12 agreement) for use with ucminfcpp::ucminf_xptr. This is the fast path used by niche_multistart(); it can also be passed to any optimizer that accepts an ObjFun external pointer.

Usage

niche_logpost_xptr(
  data,
  parameterization = "noncentered_bounded",
  sigma_floor = 0.02,
  rho_cap = 0.98,
  grad = c("central", "forward")
)

Arguments

data

A 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.

grad

Finite-difference scheme for the optimizer gradient: "central" (default, more accurate) or "forward" (cheaper).

Value

An external pointer (ucminf::ObjFun) evaluating \(-\mathrm{lp}\) plus a finite-difference gradient, suitable for ucminfcpp::ucminf_xptr. Evaluate the log-posterior at a point with niche_logpost_eval_xptr().