Simulate from a fitted model — simulate.drmTMB

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_julia'
simulate(object, nsim = 1, seed = NULL, ...)

# S3 method for class 'drmTMB'
simulate(object, nsim = 1, seed = NULL, re.form = NA, newdata = NULL, ...)

Arguments

object: A drmTMB fit.
nsim: Number of simulated data sets.
seed: Optional random-number seed. The previous .Random.seed state is restored after simulation.
...: Reserved for future simulation options; any value is an error.
re.form: NA (the default) or ~0 draws fresh random effects for every replicate (marginal simulation). NULL holds every random effect fixed at its fitted conditional-mode estimate (conditional simulation). These meanings match lme4::simulate.merMod(); earlier drmTMB versions reversed them (see Details).
newdata: Must be NULL. simulate() always draws for the training rows; drawing for new rows is not implemented, and a non-NULL value is an error rather than being silently ignored. For new rows, use predict_parameters() to get the distributional parameters and draw from the family's r*() function.

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

re.form follows the lme4::simulate.merMod() convention. By default (re.form = NA, or equivalently re.form = ~0), 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. Pass re.form = NULL to simulate conditionally on the fitted random effects instead (holding every random effect fixed at its conditional-mode estimate). 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 = NULL. Models without random effects are unaffected by re.form.

Earlier versions of drmTMB gave the explicit values the reverse meaning (NULL drew fresh random effects and NA held them fixed; #1487). The default output is unchanged, but code that passed re.form explicitly now runs the other simulation, so the first explicit re.form in a session prints a one-time message (class drmTMB_re_form_semantics_message).

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.

Examples

dat <- data.frame(y = c(0.2, 0.5, 1.1, 1.4), x = c(-1, 0, 1, 2))
fit <- drmTMB(bf(y ~ x, sigma ~ 1), data = dat)
simulate(fit, nsim = 2, seed = 1)
#>       sim_1     sim_2
#> 1 0.1279762 0.1921041
#> 2 0.6023192 0.5349613
#> 3 0.9539443 1.0426977
#> 4 1.5370147 1.4795283