Skip to contents

Per-species warm-start for the joint phylo-niche objective

Source: R/niche_warmstart.R
niche_warmstart.Rd

Fits each species independently with optimize_niche and assembles a starting vector in niche_theta_layout() order for the joint model: ancestral states are set to the cross-species means, rates to the cross-species variances, and (for non-centred parameterizations) the raw residuals are solved through the Cholesky factor of \(C\) so the implied species values equal the per-species MLEs.

Usage

niche_warmstart(
  data,
  parameterization = "noncentered_bounded",
  rho_cap = 0.98,
  likelihood = "weighted",
  prior_log_sigma_lambda = 10,
  num_starts = 50,
  min_cells = 5,
  verbose = FALSE
)

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

rho_cap

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

likelihood

xnicher likelihood family used for the per-species fits. "weighted" (default) is the M-restricted J&S family; "presence_only" fits the unnormalized model.

prior_log_sigma_lambda

Penalty strength on \(\log\sigma\) passed to optimize_niche; regularises the per-species fits away from the degenerate \(\sigma \to 0\) mode. Increase if warm-start species collapse.

num_starts

Number of multi-start points per species (passed to optimize_niche).

min_cells

Minimum number of distinct environmental cells to attempt an independent fit; species below the threshold (and masked species) use empirical moments or the ancestor mean.

verbose

Print per-species fit results.

Value

A list with theta (named vector in niche_theta_layout() order, ready for niche_multistart(extra_starts = ...)) and per_species (data frame of the independent fits).

Details

This gives niche_multistart() a biologically informed start – each species begins at its own independent niche optimum – alongside the default Sobol/LHS design. Per-species fits that fail to converge, or that land on the degenerate \(\sigma \to 0\) mode (far below the empirical spread), fall back to empirical moments; masked or otherwise unfitted species start at the phylogenetic conditional mean given the fitted species (the ancestor mean when no species fits).