R: Nearest Neighbor Matching

method_nearest {MatchIt} | R Documentation

## Nearest Neighbor Matching

### Description

In `matchit()`, setting `method = "nearest"` performs greedy nearest neighbor matching. A distance is computed between each treated unit and each control unit, and, one by one, each treated unit is assigned a control unit as a match. The matching is "greedy" in the sense that there is no action taken to optimize an overall criterion; each match is selected without considering the other matches that may occur subsequently.

This page details the allowable arguments with `method = "nearest"`. See `matchit()` for an explanation of what each argument means in a general context and how it can be specified.

Below is how `matchit()` is used for nearest neighbor matching:

    matchit(formula,
            data = NULL,
            method = "nearest",
            distance = "glm",
            link = "logit",
            distance.options = list(),
            estimand = "ATT",
            exact = NULL,
            mahvars = NULL,
            antiexact = NULL,
            discard = "none",
            reestimate = FALSE,
            s.weights = NULL,
            replace = TRUE,
            m.order = NULL,
            caliper = NULL,
            ratio = 1,
            min.controls = NULL,
            max.controls = NULL,
            verbose = FALSE, ...)

### Arguments

`formula` | a two-sided `formula()` object containing the treatment and covariates to be used in creating the distance measure used in the matching.
`data` | a data frame containing the variables named in `formula`. If not found in `data`, the variables will be sought in the environment.
`method` | set here to `"nearest"`.
`distance` | the distance measure to be used. See `distance` for allowable options. Can be supplied as a distance matrix.
`link` | when `distance` is specified as a string and not `"mahalanobis"`, an additional argument controlling the link function used in estimating the distance measure. See `distance` for allowable options with each option.
`distance.options` | a named list containing additional arguments supplied to the function that estimates the distance measure as determined by the argument to `distance`.
`estimand` | a string containing the desired estimand. Allowable options include `"ATT"` and `"ATC"`. See Details.
`exact` | for which variables exact matching should take place.
`mahvars` | for which variables Mahalanobis distance matching should take place when a distance measure other than `"mahalanobis"` is used (e.g., for caliper matching or to discard units for common support). If specified, the distance measure will not be used in matching.
`antiexact` | for which variables ant-exact matching should take place.
`discard` | a string containing a method for discarding units outside a region of common support. Only allowed when `distance` is not `"mahalanobis"` and not a matrix.
`reestimate` | if `discard` is not `"none"`, whether to re-estimate the propensity score in the remaining sample prior to matching.
`s.weights` | the variable containing sampling weights to be incorporated into propensity score models and balance statistics.
`replace` | whether matching should be done with replacement.
`m.order` | the order that the matching takes place. The default is `"data"` for `distance = "mahalanobis"` or when `distance` is supplied as a matrix, and `"largest"` otherwise. See `matchit()` for allowable options.
`caliper` | the width(s) of the caliper(s) used for caliper matching. See Details and Examples.
`std.caliper` | `logical`; when calipers are specified, whether they are in standard deviation units (`TRUE`) or raw units (`FALSE`).
`ratio` | how many control units should be matched to each treated unit for k:1 matching. For variable ratio matching, see section "Variable Ratio Matching" in Details below.
`min.controls, max.controls` | for variable ratio matching, the minimum and maximum number of controls units to be matched to each treated unit. See section "Variable Ratio Matching" in Details below.
`verbose` | `logical`; whether information about the matching process should be printed to the console. When `TRUE`, a progress bar implemented using RcppProgress will be displayed.
`...` | additional arguments that control the matching specification: `reuse.max` `numeric`; the maximum number of times each control can be used as a match. Setting `reuse.max = 1` correpsonds to matching without replacement (i.e., `replace = FALSE`), and setting `reuse.max = Inf` corresponds to traditional matching with replacement (i.e., `replace = TRUE`) with no limit on the number of times each control unit can be matched. Other values restrict the number of times each control can be matched when matching with replacement. `replace` is ignored when `reuse.max` is specified.

### Details

#### Mahalanobis Distance Matching

Mahalanobis distance matching can be done one of two ways:

1) If no propensity score needs to be estimated, `distance` should be set to `"mahalanobis"`, and Mahalanobis distance matching will occur on all the variables in `formula`. Arguments to `discard` and `mahvars` will be ignored, and a caliper can only be placed on named variables. For example, to perform simple Mahalanobis distance matching, the following could be run:

    matchit(treat ~ X1 + X2, method = "nearest",
            distance = "mahalanobis")

With this code, the Mahalanobis distance is computed using `X1` and `X2`, and matching occurs on this distance. The `distance` component of the `matchit()` output will be empty.

2) If a propensity score needs to be estimated for any reason, e.g., for common support with `discard` or for creating a caliper, `distance` should be whatever method is used to estimate the propensity score or a vector of distance measures, i.e., it should not be `"mahalanobis"`. Use `mahvars` to specify the variables used to create the Mahalanobis distance. For example, to perform Mahalanobis within a propensity score caliper, the following could be run:

    matchit(treat ~ X1 + X2 + X3, method = "nearest",
            distance = "glm", caliper = .25,
            mahvars = ~ X1 + X2)

With this code, `X1`, `X2`, and `X3` are used to estimate the propensity score (using the `"glm"` method, which by default is logistic regression), which is used to create a matching caliper. The actual matching occurs on the Mahalanobis distance computed only using `X1` and `X2`, which are supplied to `mahvars`. Units whose propensity score difference is larger than the caliper will not be paired, and some treated units may therefore not receive a match. The estimated propensity scores will be included in the `distance` component of the `matchit()` output. See Examples.

When sampling weights are supplied through the `s.weights` argument, the covariance matrix of the covariates used in the Mahalanobis distance is weighted by the sampling weights.

Mahalanobis distance matching can also be done by supplying a Mahalanobis distance matrix (e.g., the output of a call to `optmatch::match_on()`) to the `distance` argument. This makes it straightforward to use the robust rank-based Mahalanobis distance available in optmatch.

#### Estimand

The `estimand` argument controls whether control units are selected to be matched with treated units (`estimand = "ATT"`) or treated units are selected to be matched with control units (`estimand = "ATC"`). The "focal" group (e.g., the treated units for the ATT) is typically made to be the smaller treatment group, and a warning will be thrown if it is not set that way unless `replace = TRUE`. Setting `estimand = "ATC"` is equivalent to swapping all treated and control labels for the treatment variable. When `estimand = "ATC"`, the default `m.order` is `"smallest"`, and the `match.matrix` component of the output will have the names of the control units as the rownames and be filled with the names of the matched treated units (opposite to when `estimand = "ATT"`). Note that the argument supplied to `estimand` doesn't necessarily correspond to the estimand actually targeted; it is merely a switch to trigger which treatment group is considered "focal".

#### Variable Ratio Matching

`matchit()` can perform variable ratio "extremal" matching as described by Ming and Rosenbaum (2000). This method tends to result in better balance than fixed ratio matching at the expense of some precision. When `ratio > 1`, rather than requiring all treated units to receive `ratio` matches, each treated unit is assigned a value that corresponds to the number of control units they will be matched to. These values are controlled by the arguments `min.controls` and `max.controls`, which correspond to α and β, respectively, in Ming and Rosenbaum (2000), and trigger variable ratio matching to occur. Some treated units will receive `min.controls` matches and others will receive `max.controls` matches (and one unit may have an intermediate number of matches); how many units are assigned each number of matches is determined by the algorithm described in Ming and Rosenbaum (2000, p119). `ratio` controls how many total control units will be matched: `n1 * ratio` control units will be matched, where `n1` is the number of treated units, yielding the same total number of matched controls as fixed ratio matching does.

Variable ratio matching cannot be used with Mahalanobis distance matching or when `distance` is supplied as a matrix. The calculations of the numbers of control units each treated unit will be matched to occurs without consideration of `caliper` or `discard`. `ratio` does not have to be an integer but must be greater than 1 and less than `n0/n1`, where `n0` and `n1` are the number of control and treated units, respectively. Setting `ratio = n0/n1` performs a crude form of full matching where all control units are matched. If `min.controls` is not specified, it is set to 1 by default. `min.controls` must be less than `ratio`, and `max.controls` must be greater than `ratio`. See Examples below for an example of their use.

### Outputs

All outputs described in `matchit()` are returned with `method = "nearest"`. When `replace = TRUE`, the `subclass` component is omitted. `include.obj` is ignored.

### Note

Sometimes an error will be produced by Rcpp along the lines of `"function 'Rcpp_precious_remove' not provided by package 'Rcpp'"`. It is not immediately clear why this happens, though this thread appears to provide some insight. In a fresh R session, run `remove.packages(c("MatchIt", "Rcpp")); install.packages("MatchIt")`. This should sync MatchIt and Rcpp and ensure they work correctly.

### References

In a manuscript, you don't need to cite another package when using `method = "nearest"` because the matching is performed completely within MatchIt. For example, a sentence might read:

Nearest neighbor matching was performed using the MatchIt package (Ho, Imai, King, & Stuart, 2011) in R.

### See Also

`matchit()` for a detailed explanation of the inputs and outputs of a call to `matchit()`.

`method_optimal` for optimal pair matching, which is similar to nearest neighbor matching except that an overall distance criterion is minimized.

### Examples

    data("lalonde")

    # 1:1 greedy NN matching on the PS
    m.out1 <- matchit(treat ~ age + educ + race + nodegree +
                        married + re74 + re75, data = lalonde,
                      method = "nearest")
    m.out1
    summary(m.out1)

    # 3:1 NN Mahalanobis distance matching with
    # replacement within a PS caliper
    m.out2 <- matchit(treat ~ age + educ + race + nodegree +
                        married + re74 + re75, data = lalonde,
                      method = "nearest", replace = TRUE,
                      mahvars = ~ age + educ + re74 + re75,
                      ratio = 3, caliper = .02)
    m.out2
    summary(m.out2, un = FALSE)

    # 1:1 NN Mahalanobis distance matching within calipers
    # on re74 and re75 and exact matching on married and race
    m.out3 <- matchit(treat ~ age + educ + re74 + re75, data = lalonde,
                      method = "nearest", distance = "mahalanobis",
                      exact = ~ married + race,
                      caliper = c(re74 = .2, re75 = .15))
    m.out3
    summary(m.out3, un = FALSE)

    # 2:1 variable ratio NN matching on the PS
    m.out4 <- matchit(treat ~ age + educ + race + nodegree +
                        married + re74 + re75, data = lalonde,
                      method = "nearest", ratio = 2,
                      min.controls = 1, max.controls = 12)
    m.out4
    summary(m.out4, un = FALSE)

    # Some units received 1 match and some received 12
    table(table(m.out4$subclass[m.out4$treat == 0]))

[Package MatchIt version 4.3.3 Index]