simulate.merMod {lme4} | R Documentation

## Simulate Responses From `merMod` Object

### Description

Simulate responses from a `"merMod"` fitted model object, i.e., from the model represented by it.

### Usage

    ## S3 method for class 'merMod'
    simulate(object, nsim = 1, seed = NULL,
    	 use.u = FALSE, re.form = NA, ReForm, REForm, REform,
    	 newdata=NULL, newparams=NULL, family=NULL,
    	 allow.new.levels = FALSE, na.action = na.pass, ...)

    ## S3 method for class 'formula'
    simulate(object, nsim = 1 , seed = NULL,
             family, weights=NULL, offset=NULL, ...)

    .simulateFun(object, nsim = 1, seed = NULL, use.u = FALSE,
                 re.form = NA, ReForm, REForm, REform,
                 newdata=NULL, newparams=NULL,
                 formula=NULL, family=NULL, weights=NULL, offset=NULL,
                 allow.new.levels = FALSE, na.action = na.pass, ...)

### Arguments

`object` | (for `simulate.merMod`) a fitted model object or (for `simulate.formula`) a (one-sided) mixed model formula, as described for `lmer`.
`nsim` | positive integer scalar - the number of responses to simulate.
`seed` | an optional seed to be used in `set.seed` immediately before the simulation so as to generate a reproducible sample.
`use.u` | (logical) if `TRUE`, generate a simulation conditional on the current random-effects estimates; if `FALSE` generate new Normally distributed random-effects values. (Redundant with `re.form`, which is preferred: `TRUE` corresponds to `re.form = NULL` (condition on all random effects), while `FALSE` corresponds to `re.form = ~0` (condition on none of the random effects).)
`re.form` | formula for random effects to condition on. If `NULL`, condition on all random effects; if `NA` or `~0`, condition on no random effects. See Details.
`ReForm, REForm, REform` | deprecated: `re.form` is now the preferred argument name.
`newdata` | data frame for which to evaluate predictions.
`newparams` | new parameters to use in evaluating predictions, specified as in the `start` parameter for `lmer` or `glmer` – a list with components `theta` and `beta` and (for LMMs or GLMMs that estimate a scale parameter) `sigma`
`formula` | a (one-sided) mixed model formula, as described for `lmer`.
`family` | a GLM family, as in `glmer`.
`weights` | prior weights, as in `lmer` or `glmer`.
`offset` | offset, as in `glmer`.
`allow.new.levels` | (logical) if FALSE (default), then any new levels (or `NA` values) detected in `newdata` will trigger an error; if TRUE, then the prediction will use the unconditional (population-level) values for data with previously unobserved levels (or `NA`s).
`na.action` | what to do with `NA` values in new data: see `na.fail`
`...` | optional additional arguments: none are used at present.

### Details

- ordinarily `simulate` is used to generate new values from an existing, fitted model (`merMod` object): however, if `formula`, `newdata`, and `newparams` are specified, `simulate` generates the appropriate model structure to simulate from.

- The `re.form` argument allows the user to specify how the random effects are incorporated in the simulation. All of the random effects terms included in `re.form` will be conditioned on - that is, the conditional modes of those random effects will be included in the deterministic part of the simulation. (If new levels are used (and `allow.new.levels` is `TRUE`), the conditional modes for these levels will be set to the population mode, i.e. values of zero will be used for the random effects.) Conversely, the random effect terms that are not included in `re.form` will be simulated from - that is, new values will be chosen for each group based on the estimated random-effects variances.

  The default behaviour (using `re.form=NA`) is to condition on none of the random effects, simulating new values for all of the random effects.

- For Gaussian fits, `sigma` specifies the residual standard deviation; for Gamma fits, it specifies the shape parameter (the rate parameter for each observation i is calculated as shape/mean(i)). For negative binomial fits, the overdispersion parameter is specified via the family, e.g. `simulate(..., family=negative.binomial(theta=1.5))`.

### See Also

`bootMer` for “simulestimate”, i.e., where each simulation is followed by refitting the model.

### Examples

    ## test whether fitted models are consistent with the
    ##  observed number of zeros in CBPP data set:
    gm1 <- glmer(cbind(incidence, size - incidence) ~ period + (1 | herd),
                 data = cbpp, family = binomial)
    gg <- simulate(gm1,1000)
    zeros <- sapply(gg,function(x) sum(x[,"incidence"]==0))
    plot(table(zeros))
    abline(v=sum(cbpp$incidence==0),col=2)
    ##
    ## simulate from a non-fitted model; in this case we are just
    ## replicating the previous model, but
    params <- list(theta=0.5,beta=c(2,-1,-2,-3))
    simdat <- with(cbpp,expand.grid(herd=levels(herd),period=factor(1:4)))
    simdat$size <- 15
    simdat$incidence <- sample(0:1,size=nrow(simdat),replace=TRUE)
    form <- formula(gm1)[-2]
    simulate(form,newdata=simdat,family=binomial,
        newparams=params)

[Package lme4 version 1.1-12 Index]