R: Construct a matched dataset from a 'matchit' object

match.data {MatchIt} | R Documentation

## Construct a matched dataset from a `matchit` object

### Description

`match.data()` 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, `match.data()` is more flexible. See Details below for the difference between them.

### Usage

    match.data(object,
               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)

### Arguments

`object` | a `matchit` object; the output of a call to `matchit()`.
`group` | 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"`.
`distance` | 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()`.
`weights` | a string containing the name that should be given to the variable containing the matching weights in the data frame output. Default is `"weights"`.
`subclass` | 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"`.
`id` | 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 `match.data()`, the units IDs are stored in the row names of the returned data frame.
`data` | a data frame containing the original dataset to which the computed output variables (`distance`, `weights`, and/or `subclass`) should be appended. If empty, `match.data()` and `get_matches()` will attempt to find the dataset using the environment of the `matchit` object, which can be unreliable; see Notes.
`include.s.weights` | `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 `match.data()` 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.
`drop.unmatched` | `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

`match.data()` 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 `match.data()` to be used as the dataset input in calls to `glm()` or similar to estimate treatment effects in the matched sample. It is important to include the weights in the estimation of the effect and its standard error. The subclass column, when created, contains par or subclass membership and should be used to estimate the effect and its standard error. 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. See `vignette("estimating-effects")` for information on how to use `match.data()` output to estimate effects.

`get_matches()` is similar to `match.data()`; 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 `match.data()`, 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 `match.data()` should be used instead. See `vignette("estimating-effects")` for information on how to use `get_matches()` output to estimate effects after matching with replacement.

### Value

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 `match.data()`, the `group` and `drop.unmatched` arguments control whether only subsets of the data are returned. See Details above for how `match.data()` and `get_matches()` differ. Note that `get_matches` sorts the data by subclass and treatment status, unlike `match.data()`, which uses the order of the data.

The returned data frame will contain the variables in the original data set or dataset supplied to `data` and the following columns:

`distance` | The propensity score, if estimated or supplied to the `distance` argument in `matchit()` as a vector.
`weights` | The computed matching weights. These must be used in effect estimation to correctly incorporate the matching.
`subclass` | Matching strata membership. Units with the same value are in the same stratum.
`id` | The ID of each unit, corresponding to the row names in the original data or dataset supplied to `data`. Only included in `get_matches` output. This column can be used to identify which rows belong to the same unit since the same unit may appear multiple times if reused in matching with replacement.

These columns will take on the name supplied to the corresponding arguments in the call to `match.data()` or `get_matches()`. See Examples for an example of rename the `distance` column to `"prop.score"`.

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

In addition to their base class (e.g., `data.frame` or `tbl`), returned objects have the class `matchdata` or `getmatches`. This class is important when using `rbind()` to append matched datasets.

### Note

The most common way to use `match.data()` and `get_matches()` is by supplying just the `matchit` object, e.g., as `match.data(m.out)`. A data set will first be searched in the environment of the `matchit` formula, then in the calling environment of `match.data()` or `get_matches()`, and finally in the `model` component of the `matchit` object if a propensity score was estimated.

When called from an environment different from the one in which `matchit()` was originally called and a propensity score was not estimated (or was but with `discard` not `"none"` and `reestimate = TRUE`), this syntax may not work because the original dataset used to construct the matched dataset will not be found. This can occur when `matchit()` was run within an `lapply()` or `purrr::map()` call. The solution, which is recommended in all cases, is simply to supply the original dataset to the `data` argument of `match.data()`, e.g., as `match.data(m.out, data = original_data)`, as demonstrated in the Examples.

### See Also

`matchit()`

`rbind.matchdata()`

`vignette("estimating-effects")` for uses of `match.data()` and `get_matches()` in estimating treatment effects.

### Examples

    data("lalonde")

    # 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 <- match.data(m.out1, 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)

[Package MatchIt version 4.3.3 Index]