with.mitml.list: 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 mitml.list
with(data, expr, include.data = FALSE, ...)
# S3 method for mitml.list
within(data, expr, ignore = NULL, ...)

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.

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.

Author

Simon Grund

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.

Examples

Run this code

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)))

if (FALSE) {
# 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)
}

Run the code above in your browser using DataLab

Hear from leaders powering AI transformation