Julia-engine Binomial fits with predictor-dependent SDs support marginal
simulation for independent ordinary random intercepts, coefficient-specific
SDs in one correlated ordinary block, and selected structured effects.
Gamma fits support complete-data animal intercept SDs
and an animal intercept-plus-numeric-slope model with separate
coefficient-specific SD formulas. Binomial animal intercept-plus-slope
blocks with separate coefficient-specific SD formulas use the fitted animal
covariance and coefficient correlation for marginal simulation. For both
Gamma routes, simulation uses
the supplied relationship matrix A at its raw scale, as the Julia fitter
and native TMB do, including when A has a non-unit diagonal. The
Julia Laplace route integrates these random effects and does not return
conditional modes, so re.form = NULL is refused.
Structured simulation uses the saved covariance and its fitted scale. A
fixed-coordinate Binomial spatial intercept or slope uses the same native
fixed-range covariance passed through the Julia related-matrix route.
Binomial animal intercept may be combined with one independent ordinary
random intercept when both have matching SD formulas; other combinations
of structured and ordinary effects are refused.
These routes require complete data and location-side SD targets.
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.
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
NA(the default) or~0draws fresh random effects for every replicate (marginal simulation).NULLholds every random effect fixed at its fitted conditional-mode estimate (conditional simulation). These meanings matchlme4::simulate.merMod(); earlier drmTMB versions reversed them (see Details).- ...
Reserved for future simulation options; any value is an error.
- newdata
Must be
NULL.simulate()always draws for the training rows; drawing for new rows is not implemented, and a non-NULLvalue is an error rather than being silently ignored. For new rows, usepredict_parameters()to get the distributional parameters and draw from the family'sr*()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 for ordinary location random effects with an admitted
predictor-dependent SD uses the fitted group-specific SD for each fresh
link-scale draw. For native Bernoulli phylogenetic and relatedness-matrix
(relmat) intercepts, it applies each tip or group's fitted SD to the fresh
structured draw. Julia Gamma animal models also support marginal simulation
for a complete-data animal intercept or an animal intercept plus one numeric
slope, with separate coefficient-specific SD formulas. The Julia fitter uses
the supplied relationship matrix at its raw scale, as native TMB does, and
simulation follows that same convention. These Gamma routes use location
SDs and fixed sigma ~ 1; conditional simulation with re.form = NULL is
unavailable for Julia Laplace fits.
A native Bernoulli relmat() model with one intercept, one numeric slope,
and a separate predictor-dependent SD formula for each coefficient also
supports marginal simulation; the two fields are drawn independently with
their fitted group-specific covariance scales. Native structured
intercept-plus-slope (q = 2) fits with one SD formula per coefficient also
support marginal simulation for the Binomial, Poisson, NB2, Gaussian and
Gamma families and the relmat, animal, phylo and spatial providers.
Each replicate draws the two unit-scale fields from R (x) K, where R
holds the fitted cross-coefficient correlation of a labelled
(1 + x | p | id) block (zero for an unlabelled block), and scales each
coefficient's field by its fitted group-specific SD. Any other fitted
correlation alongside the structured block is refused.
It 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. Other modelled structured-effect scales
are not yet supported outside the explicitly listed Bernoulli and Julia
Gamma routes. 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 other modelled
structured (heteroscedastic) random-effect scales; 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.