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. Must be a single positive integer. 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, phylo_diag, diag_species, the SPDE spatial fields of spatial_indep(), spatial_scalar() and spatial_latent(), 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 slope-augmented SPDE spatial forms (for example spatial_indep(1 + x | coords)) fall back to conditional simulation and emit 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 uses the fitted conditional predictor). For AGHQ, the predictor uses the stored latent modes at the fitted parameters. 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.