MatchThem: with – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

with

Evaluates an Expression in Matched or Weighted Imputed Datasets

Description

with() runs a model on the n imputed datasets of the supplied mimids or wimids object. The typical sequence of steps to do a matching procedure on the imputed datasets are:

Impute the missing values using the mice() function (from the mice package) or the amelia() function (from the Amelia package), resulting in a multiple imputed dataset (an object of the mids or amelia class);
Match or weight each imputed dataset using matchthem() or weightthem(), resulting in an object of the mimids or wimids class;
Check the extent of balance of covariates across the matched datasets (using functions in cobalt);
Fit the statistical model of interest on each matched dataset by the with() function, resulting in an object of the mimira class; and
Pool the estimates from each model into a single set of estimates and standard errors, resulting in an object of the mipo class.

Usage

## S3 method for class 'mimids'
with(data, expr, cluster, ...)

## S3 method for class 'wimids'
with(data, expr, ...)

Arguments

`data`	An `mimids` or `wimids` object, typically produced by a previous call to the `matchthem()` or `weightthem()`.
`expr`	An expression (usually a call to a modeling function like `glm()`, `coxph()`, `svyglm()`, etc.) to evaluate for each imputed data set. See Details.
`cluster`	When a function from survey (e.g., `svyglm()`) is supplied in `expr`, whether the standard errors should incorporate clustering due to dependence between matched pairs. This is done by supplying the variable containing pair membership to the `ids` argument of `link[survey:svydesign]{svydesign()}`. If unspecified, it will be set to `TRUE` if subclasses (i.e., pairs) are present in the output and there are 20 or more unique subclasses. It will be ignored for matching methods that don't return subclasses (e.g., matching with replacement).
`...`	Additional arguments to be passed to `expr`.

Details

with() applies the supplied model in expr to the matched or weighrd imputed datasets, automatically incorporating the (matching) weights when possible. The argument to expr should be of the form glm(y ~ z, family = quasibinomial), for example, excluding the data or weights argument, which are automatically supplied.
Functions from the survey package, such as svyglm(), are treated a bit differently. No svydesign objcect needs to be supplied because with() automatically constructs and supplies it with the imputed dataset and estimated weights. When cluster = TRUE (or with() detects that pairs should be clustered; see Arguments above), pair membership is supplied to the ids argument of svydesign().
For generalized linear models, it is always recommended to use svyglm() rather than glm() in order to correctly compute standard errors. For Cox models, coxph() will produce correct standard errors when used with weighting but svycoxph() will produce more accurate standard errors when matching is used.

Value

An object of the mimira class containing the output of the analyses.

Author(s)

Farhad Pishgar and Noah Greifer

References

Stef van Buuren and Karin Groothuis-Oudshoorn (2011). mice: Multivariate Imputation by Chained Equations in R. Journal of Statistical Software, 45(3): 1-67. https://www.jstatsoft.org/v45/i03/

Examples

#Loading libraries
library(MatchThem)
library(survey)

#Loading the dataset
data(osteoarthritis)

#Multiply imputing the missing values
imputed.datasets <- mice::mice(osteoarthritis, m = 5)

#Matching in the multiply imputed datasets
matched.datasets <- matchthem(OSP ~ AGE + SEX + BMI + RAC + SMK,
                                imputed.datasets,
                                approach = 'within',
                                method = 'nearest')

#Analyzing the matched datasets
models <- with(matched.datasets,
               svyglm(KOA ~ OSP, family = binomial),
               cluster = TRUE)

MatchThem

Matching and Weighting Multiply Imputed Datasets

v1.0.0

GPL (>= 2)

Authors

Farhad Pishgar [aut, cre], Noah Greifer [aut], Clémence Leyrat [ctb], Elizabeth Stuart [ctb]

Initial release