getSimulations: Get model simulations

In DHARMa: Residual Diagnostics for Hierarchical (Multi-Level / Mixed) Regression Models

Get model simulations

Description

Wrapper to simulate from a fitted model.

Usage

getSimulations(object, nsim = 1, simulateREs = c("conditional",
  "unconditional", "user-specified"), type = c("normal", "refit"), ...)

## Default S3 method:
getSimulations(object, nsim = 1,
  simulateREs = c("conditional", "unconditional", "user-specified"),
  type = c("normal", "refit"), ...)

## S3 method for class 'negbin'
getSimulations(object, nsim = 1,
  simulateREs = c("conditional", "unconditional", "user-specified"),
  type = c("normal", "refit"), ...)

## S3 method for class 'gam'
getSimulations(object, nsim = 1,
  simulateREs = c("conditional", "unconditional", "user-specified"),
  type = c("normal", "refit"), mgcViz = TRUE, ...)

## S3 method for class 'merMod'
getSimulations(object, nsim = 1,
  simulateREs = c("conditional", "unconditional", "user-specified"),
  type = c("normal", "refit"), ...)

## S3 method for class 'glmmTMB'
getSimulations(object, nsim = 1,
  simulateREs = c("conditional", "unconditional", "user-specified"),
  type = c("normal", "refit"), ...)

## S3 method for class 'HLfit'
getSimulations(object, nsim = 1,
  simulateREs = c("conditional", "unconditional", "user-specified"),
  type = c("normal", "refit"), ...)

## S3 method for class 'MixMod'
getSimulations(object, nsim = 1,
  simulateREs = c("conditional", "unconditional", "user-specified"),
  type = c("normal", "refit"), ...)

## S3 method for class 'phylolm'
getSimulations(object, nsim = 1,
  simulateREs = c("conditional", "unconditional", "user-specified"),
  type = c("normal", "refit"), ...)

## S3 method for class 'phyloglm'
getSimulations(object, nsim = 1,
  simulateREs = c("conditional", "unconditional", "user-specified"),
  type = c("normal", "refit"), ...)

## S3 method for class 'brmsfit'
getSimulations(object, nsim = 1,
  simulateREs = c("conditional", "unconditional", "user-specified"),
  type = c("normal", "refit"), ...)

Arguments

object	a fitted model.
nsim	number of simulations.
simulateREs	which hierarchical levels should be re-simulated. If conditional, the simulations are done conditional on all fitted random effects (default). If unconditional, all hierarchical levels are re-simulated, including the random effects. With user-specified, the default simulate function of the respective fitted model object is used. See details and simulateResiduals.
type	if simulations should be prepared for getQuantile or for refit.
...	additional parameters to be passed on, usually to the simulate function of the respective model class.
mgcViz	whether simulations should be created with mgcViz (if mgcViz is available)

Details

The purpose of this function is to wrap or implement the simulate function of different model classes to return simulations from fitted models in a standardized way.

One important parameter is simulateRE, which controls which hierarchical levels are held constant (conditioned on), and which are re-simulated. The default as of DHARMa 0.5.0 is to simulate "conditional" on all fitted random effects. The setting "unconditional" re-simulates all REs.

With simulateREs = "user-specified", users can supply additional parameters to the simulate function of the respective model class and thus condition on specific REs or structures. The exact behavior will depend on the regression package. For details, please see vignette, or consult the help of the different packages. If choosing simulateREs = "user-specified" with no additional parameters, the default simulation function of the respective regression package is used. This corresponds to the DHARMa behavior prior to 0.5.0.

If the model was fit with weights and the respective model class does not include the weights in the simulations, getSimulations will throw a warning. The background is if weights are used on the likelihood directly, then what is fitted is effectively a pseudo likelihood, and there is no way to directly simulate from the specified likelihood. Whether or not residuals can be used in this case depends very much on what is tested and how weights are used. I'm sorry to say that it is hard to give a general recommendation, you have to consult someone that understands how weights are processed in the respective model class.

Binomial models with a cbind(successes, failures) response and prior weights are not supported; getSimulations stops for them.

Value

a matrix with simulations.

Author(s)

Florian Hartig

See Also

getObservedResponse, getRefit, getFixedEffects, getFitted

Examples

testData = createData(sampleSize = 400, family = gaussian())

fittedModel <- lm(observedResponse ~ Environment1 , data = testData)

# response that was used to fit the model
getObservedResponse(fittedModel)

# predictions of the model for these points
getFitted(fittedModel)

# predictions on the scale of the observed response
# (differs from getFitted only for k/n binomial models)
getFittedResponse(fittedModel)

# extract simulations from the model as matrix
getSimulations(fittedModel, nsim = 2)

# extract simulations from the model for refit (often requires different structure)
x = getSimulations(fittedModel, nsim = 2, type = "refit")

getRefit(fittedModel, x[[1]])

getRefit(fittedModel, getObservedResponse(fittedModel))

# get data frame that was used to fit the model
getData(fittedModel)

DHARMa documentation built on Nov. 7, 2026, 5:08 p.m.