Construct a matched dataset from a 'matchit' object

Description Usage Arguments Details Value See Also Examples

View source: R/

Description and get_matches create a data frame with additional variables for the distance measure, matching weights, and subclasses after matching. This dataset can be used to estimate treatment effects after matching or subclassification. get_matches is most useful after matching with replacement; otherwise, is more flexible. See Details below for the difference between them.


8, group = "all", distance = "distance",
           weights = "weights", subclass = "subclass",
           data = NULL, include.s.weights = TRUE,
           drop.unmatched = TRUE)

get_matches(object, distance = "distance",
            weights = "weights", subclass = "subclass",
            id = "id", data = NULL, include.s.weights = TRUE)



a matchit object; the output of a call to matchit.


which group should comprise the matched dataset: "all" for all units, "treated" for just treated units, or "control" for just control units. Default is "all".


a string containing the name that should be given to the variable containing the distance measure in the data frame output. Default is "distance", but "prop.score" or similar might be a good alternative if propensity scores were used in matching. Ignored if a distance measure was not supplied or estimated in the call to matchit.


a string containing the name that should be given to the variable containing the matching weights in the data frame output. Default is "weights".


a string containing the name that should be given to the variable containing the subclasses or matched pair membership in the data frame output. Default is "subclass".


a string containing the name that should be given to the variable containing the unit IDs in the data frame output. Default is "id". Only used with get_matches; for, the units IDs are stored in the row names of the returned data frame.


a data frame containing the original dataset to which the computed output variables (distance, weights, and/or sublcass) should be appended. If empty, will attempt to find the dataset using the environment of the matchit object, which can make this unreliable if is used in a fresh R session or if the original dataset changed between calling matchit and It is always safest to supply a data frame, which should have as many rows as and be in the same order as the data in the original call to matchit. The same goes for get_matches, which calls internally.


logical; whether to multiply the estimated weights by the sampling weights supplied to matchit(), if any. Default is TRUE. If FALSE, the weights in the or get_matches output should be multiplied by the sampling weights before being supplied to the function estimating the treatment effect in the matched data.


logical; whether the returned data frame should contain all units (FALSE) or only units that were matched (i.e., have a matching weight greater than zero) (TRUE). Default is TRUE to drop unmatched units.

Details creates a dataset with one row per unit. It will be identical to the dataset supplied except that several new columns will be added containing information related to the matching. When drop.unmatched = TRUE, the default, units with weights of zero, which are those units that were discarded by common support or the caliper or were simply not matched, will be dropped from the dataset, leaving only the subset of matched units. The idea is for the output of to be used as the dataset input in calls to glm or similar to estimate treatment effects in the matched sample. Unless 1:1 matching without replacement was performed, it is important to include the weights in the estimation of the effect and its standard error. The subclasses, when created, can be used as fixed effects, random effects, or as clusters for clustered standard errors. Subclasses will only be included if there is a subclass component in the matchit object, which does not occur with matching with replacement, in which case get_matches should be used.

get_matches is similar to; the primary difference occurs when matching is performed with replacement, i.e., when units do not belong to a single matched pair. In this case, the output of get_matches will be a dataset that contains one row per unit for each pair they are a part of. For example, if matching was performed with replacement and a control unit was matched to two treated units, that control unit will have two rows in the output dataset, one for each pair it is a part of. Weights are computed for each row, and are equal to the inverse of the number of control units in each control unit's subclass. Unmatched units are dropped. An additional column with unit IDs will be created (named using the id argument) to identify when the same unit is present in multiple rows. This dataset structure allows for the inclusion of both subclass membership and repeated use of units, unlike the output of, which lacks subclass membership when matching is done with replacement. A match.matrix component of the matchit object must be present to use get_matches; in some forms of matching, it is absent, in which case should be used instead.


A data frame containing the data supplied in the data argument or in the original call to matchit with the computed output variables appended as additional columns, named according the arguments above. For, the group and drop.unmatched arguments control whether only subsets of the data are returned. See Details above for how and get_matches differ. Note that get_matches sorts the data by subclass and treatment status, unlike, which uses the order of the data.

If data or the original dataset supplied to matchit was a data.table or tbl, the output will have the same class, but the get_matches output will always be a base R data.frame.

See Also




# 4:1 matching w/replacement
m.out1 <- matchit(treat ~ age + educ + married +
                    race + nodegree + re74 + re75,
                  data = lalonde, replace = TRUE,
                  caliper = .05, ratio = 4)

m.data1 <-, data = lalonde,
                      distance = "prop.score")
dim(m.data1) #one row per matched unit
head(m.data1, 10)

g.matches1 <- get_matches(m.out1, data = lalonde,
                          distance = "prop.score")
dim(g.matches1) #multiple rows per matched unit
head(g.matches1, 10)

MatchIt documentation built on Nov. 14, 2020, 5:11 p.m.