designr (version 0.1.13)

simLMM: Simulate data from a linear mixed-effects model

Description

This function simulates artificial data from a linear mixed-effects model. Parameters can either be set by hand using the parameters listed below *or* using a fitted lmerMod object.

Usage

simLMM(
  formula,
  data = NULL,
  Fixef,
  VC_sd,
  CP = 0,
  LMM = NULL,
  empirical = FALSE,
  verbose = TRUE,
  family = "gaussian"
)

Arguments

formula

A formula as used in a call to the lmer function: a one-sided linear formula object describing both the fixed-effects and random-effects part of the model, with no response variable to the left of the ~ operator.

data

a data frame containing the variables named in formula. Optional if LMM is provided.

Fixef

a vector of all fixed-effect model parameters.

VC_sd

standard deviations of the variance components for the random effects. This is a list of vectors, where different list entries reflect different grouping structures, and each vector contains standard deviations of variance components (random intercepts and random slopes) for one grouping factor. The last list entry is the standard deviation of the residual noise term (for gaussian or lognormal families only).

CP

correlation parameters of the random effects. If CP is a single number, then all CP are set to this same value. If CP is a vector of length equal to the number of grouping factor, then each vector entry specifies one fixed value for all CP associated with this grouping factor. Otherwise, CP can be a list of correlation matrices, which specifies a full correlation matrix for each grouping structure.

LMM

if a lmerMod object containing a fitted lmer model is provided, then simLMM uses the estimated model parameters for data simulation. Note: If LMM is provided, formula, Fixef, VC_sd, CP, and family are taken from the provided fitted model, the arguments are ignored in the model call, and a warning is given.

empirical

logical. If true, Fixef specify the empirical not population fixed effects parameters. empirical=TRUE does not work for residual Bernoulli noise, and not if continuous covariates are used.

verbose

logical. If TRUE (default), then information about the used model parameters is provided. If FALSE, then no output is generated.

family

string specifying the response distribution: "gaussian" (default) assumes a normal distribution, binomial specifies a Bernoulli distribution with a logit link function, "lognormal" specifies a log-normal distribution; with "lp", only the linear predictor is generated with no residual noise.

Examples

design <-
  fixed.factor("X", levels=c("X1", "X2")) +
  random.factor("Subj", instances=30)
dat <- design.codes(design)
contrasts(dat$X) <- c(-1, +1)

dat$ysim <- simLMM(formula = ~ 1 + X + (1 + X | Subj),
                   data = dat,
                   Fixef = c(200, 10),
                   VC_sd = list(c(30,10), 50),
                   CP = 0.3,
                   empirical = TRUE)

dat$Xn <- ifelse(dat$X=="X1",-1,1)
# lme4::lmer(ysim ~ Xn + (Xn || Subj), data=dat, control=lmerControl(calc.derivs=FALSE))