Skip to contents

Multi-start MAP optimization of the joint phylo-niche posterior

Source: R/multistart_map.R
niche_multistart.Rd

Optimizes niche_logpost() from a space-filling design over niche_start_ranges(). By default it uses the compiled C++ objective through ucminfcpp::ucminf_xptr (finite-difference gradients, no R callbacks); set use_xptr = FALSE to optimize the R implementation instead. Start points that are not finite under the objective are skipped. The result includes per-species boundary flags so collapsed (\(\sigma \to \sigma_{\mathrm{floor}}\)), sliver-like (\(|\rho| \to \rho_{\mathrm{cap}}\)) and inflated (\(\sigma \to \infty\)) niches are reported explicitly rather than silently contaminating downstream fits.

Usage

niche_multistart(
  data,
  parameterization = c("noncentered_bounded", "noncentered", "centered",
    "centered_lograte", "unb", "bnd", "ctr", "ctrlr"),
  n_starts = 32,
  sigma_floor = 0.02,
  rho_cap = 0.98,
  use_xptr = TRUE,
  seed = 1,
  extra_starts = NULL,
  control = list(),
  verbose = TRUE
)

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

n_starts

Integer number of start points (Sobol/LHS design plus one data-driven centre). Increase for large clades.

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.

use_xptr

Logical; use the compiled C++ objective via ucminfcpp::ucminf_xptr (default TRUE). Falls back to the R objective and ucminf if the compiled backend or package is unavailable.

seed

Integer seed for the start design (LHS fallback only; Sobol is deterministic).

extra_starts

Optional numeric vector or matrix of additional start points in niche_theta_layout() order – e.g. the output of niche_warmstart() (per-species xnicher fits).

control

List of control arguments passed to the optimizer (defaults: grtol = 1e-5, xtol = 1e-10, stepmax = 5, maxeval = 3000).

verbose

Print per-start progress.

Value

A niche_multistart object: a list with map (named best theta), map_lp, solutions (per-start par, lp, convergence, maxgradient, start_lp), starts, boundary (per-species boundary report at the MAP; see niche_boundary_report()), parameterization, and the sigma_floor/rho_cap used.