R: Evaluate an expression in a list of imputed data sets

with.mitml.list

R Documentation

Evaluate an expression in a list of imputed data sets

Description

The with and within methods evaluate R expressions in a list of multiply imputed data sets.

Usage


## S3 method for class 'mitml.list'
with(data, expr, include.data = FALSE, ...)
## S3 method for class 'mitml.list'
within(data, expr, ignore = NULL, ...)

Arguments

`data`	A list of imputed data sets with class `mitml.list` as produced by `mitmlComplete` or `as.mitml.list`.
`expr`	An R expression to be evaluated for each data set.
`include.data`	Either a logical flag or a character string denoting how the data are included when `expr` is evaluated (see 'Details'). If `FALSE`, an environment is created from `data`, and `expr` is evaluated therein. If `TRUE`, a call is constructed from `expr` and evaluated with the imputed data in the `"data"` slot. If character, a call is constructed from `expr` and evaluated with the imputed data in the slot named by `include.data`. Default is `FALSE`.
`ignore`	A character vector naming objects that are created but should not be saved (see 'Details').
`...`	Not used.

Details

The two functions provide with and within methods for objects of class mitml.list. They evaluate an R expression repeatedly for each of the imputed data sets but return different values: with returns the result of the evaluated expression; within returns the resulting data sets.

The within function is useful for transforming and computing variables in the imputed data (e.g., centering, calculating cluster means, etc.). The with function is useful, for example, for fitting statistical models. The list of fitted models can be analyzed using testEstimates, testModels, testConstraints, or anova.

The include.data argument can be used to include the imputed data sets in the call to fit statistical models (expr) using with. This is useful for fitting models that require that the fitting function be called with a proper data argument (e.g., lavaan or nlme; see 'Examples'). Setting include.data = TRUE will fit the model with the imputed data sets used as the data argument. Setting include.data = "df" (or similar) will fit the model with the imputed data sets as the df argument (useful if the function refers to the data by a nonstandard name, such as "df").

The ignore argument can be used to declare objects that are not to be saved in the data sets created by within.

Value

with: A list of class mitml.results containing the evaluated expression for each data set.

within: A list of class mitml.list containing the imputed data modified by the evaluated expression.

Author(s)

Simon Grund

Examples

data(studentratings)

fml <- ReadDis + SES ~ ReadAchiev + (1|ID)
imp <- panImpute(studentratings, formula = fml, n.burn = 1000, n.iter = 100, m = 5)

implist <- mitmlComplete(imp)

# * Example 1: data transformation

# calculate and save cluster means
new1.implist <- within(implist, Means.ReadAchiev <- clusterMeans(ReadAchiev, ID))

# center variables, calculate interaction terms, ignore byproducts
new2.implist <- within(implist, {
  M.SES <- mean(SES)
  M.CognAbility <- mean(CognAbility)
  C.SES <- SES - M.SES
  C.CognAbility <- CognAbility - M.CognAbility
  SES.CognAbility <- C.SES * C.CognAbility
}, ignore = c("M.SES", "M.CognAbility"))

# * Example 2: fitting statistical models

# fit regression model
fit.lm <- with(implist, lm(ReadAchiev ~ ReadDis))

# fit multilevel model with lme4
require(lme4)
fit.lmer <- with(implist, lmer(ReadAchiev ~ ReadDis + (1|ID)))

## Not run: 
# fit structural equation model with lavaan (with include.data = TRUE)
require(lavaan)
mod <- "ReadAchiev ~ ReadDis"
fit.sem <- with(implist,
                sem(model = mod, cluster = "ID", estimator = "MLR"),
                include.data = TRUE)

## End(Not run)