simulate() draws new response values from the fitted drmTMB model. For
univariate Gaussian models with known sampling covariance, simulation uses
the total observation covariance implied by the known sampling covariance
plus the fitted residual scale. For Student-t models, simulation uses fitted
mu, sigma, and nu. For lognormal models, simulation uses fitted
log-scale mu and sigma. For Gamma models, simulation uses fitted mean
mu and coefficient of variation sigma. For beta models, simulation uses
fitted mean mu and public scale sigma with internal
phi = 1 / sigma^2. For Tweedie models, simulation uses fitted mu,
public sigma, and power nu, with internal dispersion phi = sigma^2.
For zero-one beta models, simulation draws exact
boundary values from the fitted zoi/coi probabilities and interior
values from the fitted beta component. For beta-binomial models, simulation
draws latent success probabilities from the fitted beta distribution and then
success counts from the stored trial denominators. For binomial models,
simulation draws success counts from the fitted event probability and stored
trial denominators. For cumulative-logit ordinal models, simulation draws
ordered categories from the fitted cumulative-logit
probabilities. For Poisson models, simulation uses the fitted mean mu. For
zero-inflated Poisson models, simulation uses
fitted conditional mean mu and structural-zero probability zi. For
negative-binomial 2 models, simulation uses fitted mu and overdispersion
scale sigma, with Var(y) = mu + sigma^2 * mu^2; zero-truncated NB2
models draw from this NB2 component conditional on positive counts. The
zero-inflated NB2 path adds structural-zero probability zi; the hurdle NB2
path adds hurdle-zero probability hu and draws nonzero counts from the
zero-truncated NB2 component. For bivariate
Gaussian models without known
sampling covariance, simulation uses the fitted mu1, mu2, sigma1,
sigma2, and residual rho12. If a dense bivariate known V was supplied,
simulation uses the full row-paired observation covariance V + Omega.
For bivariate Student-t models, simulation instead uses one shared
chi-squared scale-mixture draw per response pair together with the fitted
shared nu; independent marginal t draws would be a different model.
Usage
# S3 method for class 'drmTMB'
simulate(object, nsim = 1, seed = NULL, re.form = NULL, ...)Arguments
- object
A
drmTMBfit.- nsim
Number of simulated data sets.
- seed
Optional random-number seed. The previous
.Random.seedstate is restored after simulation.- re.form
NULL(the default) draws fresh random effects for every replicate (marginal simulation).NAholds every random effect fixed at its fitted conditional-mode estimate (conditional simulation).- ...
Reserved for future simulation options.
Value
A data frame. Univariate models return one column per simulation.
Bivariate models return paired columns named sim_<j>_y1 and
sim_<j>_y2.
Details
By default (re.form = NULL), models with ordinary grouped random effects
draw a fresh random-effect realization for every replicate, so
replicate-to-replicate variability reflects both the between-group and the
residual sources of variance (matching the lme4/glmmTMB re.form
convention). Pass re.form = NA to simulate conditionally on the fitted
random effects instead (holding every random effect fixed at its
conditional-mode estimate, the behaviour this function had before
re.form was added). Marginal simulation also redraws a single-endpoint
(q == 1) phylogenetic, spatial, relatedness-matrix (relmat),
animal-model, or phylo_interaction structured mu random effect from its
fitted covariance sd^2 * Q^-1. It does not yet support a structured mu
random effect correlated across more than one trait or distributional
parameter (q > 1, including a multi-endpoint phylo_interaction term),
correlated covariance-block random effects, predictor-dependent
random-effect correlation (corpair) regression, or a modelled
(heteroscedastic) random-effect scale; simulate() throws an informative
error naming the unsupported structure for those models and directs the
user to re.form = NA. Models without random effects are unaffected by
re.form.
For a fit made with missing = miss_control(response = "include"),
simulate() returns NA at masked rows for every family, matching
residuals(), so posterior-predictive tools such as
DHARMa::createDHARMa() see draws only where a response was observed.