Simulate new responses from a fitted gllvmTMB model

Draws nsim new response vectors from a fitted model. By default (condition_on_RE = FALSE) the random effects are redrawn from the fitted covariance and the response is drawn from the fitted family — the unconditional simulation appropriate for a parametric bootstrap. Redraw is not implemented for every tier; a fit using an unhandled tier falls back to conditional simulation with a warning, and intervals derived from it are too narrow. Set condition_on_RE = TRUE for the older conditional behaviour, which reuses the fitted random-effect modes and only adds residual noise.

Usage

# S3 method for class 'gllvmTMB_multi'
simulate(
  object,
  nsim = 1,
  seed = NULL,
  newdata = NULL,
  condition_on_RE = FALSE,
  ...
)

Arguments

object

A fit returned by gllvmTMB().

nsim

Number of replicate response vectors to draw. Default 1.

seed

Optional RNG seed.

newdata

Optional new data frame; if supplied, predictions are computed at newdata and noise is drawn around them. The newdata must contain enough columns to rebuild the fixed-effects design and any random-effect grouping that was active.

condition_on_RE

Logical (default FALSE). When FALSE (the default), random effects are redrawn from the fitted covariance — the unconditional simulation appropriate for parametric bootstrap. Redraw is currently implemented for the rr_B, diag_B, rr_W, diag_W, propto, lv_B, phylo_rr, diag_species, and the native temporal tier. A temporal fit redraws its recursive temporal state together with every supported ordinary/source tier; it does not retain fitted ordinary modes in an unconditional draw.

Not every tier is covered. The admitted replicated-AR1 temporal_indep() + spatial_indep() cell redraws its independent SPDE field. Other SPDE spatial forms and the diagonal phylogenetic tier (phylo_diag) fall back to conditional simulation and emits a one-shot warning naming the unhandled tiers. Because conditional simulation reuses the fitted random- effect modes rather than redrawing them, it understates between-unit variability: intervals derived from it (for example via bootstrap_Sigma()) are too narrow and should not be read as calibrated. Treat the warning as a signal that simulate-based uncertainty is not trustworthy for that fit.

When TRUE, the existing fitted RE modes are reused (the older glmmTMB-style conditional simulation that only adds Gaussian noise on top of fit$report$eta). Forced to TRUE when newdata is supplied (RE modes for unseen levels cannot be redrawn).

...

Currently unused.

Value

A matrix of dimension n_obs x nsim (or nrow(newdata) x nsim when newdata is supplied). Per-row family coverage (#1079): rows are drawn from their true fitted distribution for gaussian, binomial (at the row's actual trial count, not forced to Bernoulli), poisson, lognormal, Gamma, nbinom2, nbinom1, Beta, betabinomial, student-t, zero-truncated poisson, zero-truncated nbinom2, delta_lognormal, delta_gamma, ordinal_probit, and multinomial. The one exception is tweedie, which has no exact draw implemented; its rows (and any other unrecognised family) are returned as NA_real_, together with a warning naming the affected family_id values — never a Gaussian-on-link-scale substitute, and never silent. The newdata path (predictions on unseen data) still falls back to a Gaussian-on-link-scale draw for every family, with its own warning; family-aware newdata simulation is not yet implemented.

Details

For rho-enabled structured trait intercepts, unconditional draws use the attenuated source covariance for both loadings and folded Psi, with independent observation residuals retained. Unsupported additional components produce an error instead of a conditional fallback. This supports simulation; automatic covariance bootstrap refits are not yet supported for these fits.