with.mitml.list: Evaluate an expression in a list of imputed data sets

View source: R/with.mitml.list.R

with.mitml.listR Documentation

Evaluate an expression in a list of imputed data sets


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


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



A list of imputed data sets with class mitml.list as produced by mitmlComplete or as.mitml.list.


An R expression to be evaluated for each data set.


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.


A character vector naming objects that are created but should not be saved (see 'Details').


Not used.


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.


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.


Simon Grund

See Also

mitmlComplete, anova.mitml.result, testEstimates, testModels, testConstraints



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
fit.lmer <- with(implist, lmer(ReadAchiev ~ ReadDis + (1|ID)))

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

## End(Not run)

mitml documentation built on March 31, 2023, 7:01 p.m.