method_optimal  R Documentation 
In matchit()
, setting method = "optimal"
performs optimal pair
matching. The matching is optimal in the sense that that sum of the absolute
pairwise distances in the matched sample is as small as possible. The method
functionally relies on \pkgfunoptmatchfullmatch.
Advantages of optimal pair matching include that the matching order is not required to be specified and it is less likely that extreme withinpair distances will be large, unlike with nearest neighbor matching. Generally, however, as a subset selection method, optimal pair matching tends to perform similarly to nearest neighbor matching in that similar subsets of units will be selected to be matched.
This page details the allowable arguments with method = "optmatch"
.
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 optimal pair matching:
matchit(formula, data = NULL, method = "optimal", distance = "glm", link = "logit", distance.options = list(), estimand = "ATT", exact = NULL, mahvars = NULL, antiexact = NULL, discard = "none", reestimate = FALSE, s.weights = NULL, ratio = 1, min.controls = NULL, max.controls = NULL, verbose = FALSE, ...)
formula 
a twosided formula object containing the treatment and covariates to be used in creating the distance measure used in the matching. This formula will be supplied to the functions that estimate the distance measure. 
data 
a data frame containing the variables named in 
method 
set here to 
distance 
the distance measure to be used. See 
link 
when 
distance.options 
a named list containing additional arguments
supplied to the function that estimates the distance measure as determined
by the argument to 
estimand 
a string containing the desired estimand. Allowable options
include 
exact 
for which variables exact matching should take place. 
mahvars 
for which variables Mahalanobis distance matching should take
place when 
antiexact 
for which variables antexact matching should take place. Antiexact matching is processed using \pkgfunoptmatchantiExactMatch. 
discard 
a string containing a method for discarding units outside a
region of common support. Only allowed when 
reestimate 
if 
s.weights 
the variable containing sampling weights to be incorporated into propensity score models and balance statistics. 
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 

... 
additional arguments passed to \pkgfunoptmatchfullmatch.
Allowed arguments include The arguments 
Mahalanobis distance matching can be done one of two ways:
If no propensity score needs to be estimated, distance
should be
set to "mahalanobis"
, and Mahalanobis distance matching will occur
using all the variables in formula
. Arguments to discard
and
mahvars
will be ignored. 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.
If a propensity score needs to be estimated for common support with
discard
, 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 after discarding units outside the common support of the
propensity score in both groups, the following could be run:
matchit(treat ~ X1 + X2 + X3, method = "nearest", distance = "glm", discard = "both", 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 identify the common support. The
actual matching occurs on the Mahalanobis distance computed only using
X1
and X2
, which are supplied to mahvars
. The estimated
propensity scores will be included in the distance
component of the
matchit()
output.
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 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".
matchit()
can perform variable
ratio matching, which involves matching a different number of control units
to each treated unit. When ratio > 1
, rather than requiring all
treated units to receive ratio
matches, the arguments to
max.controls
and min.controls
can be specified to control the
maximum and minimum number of matches each treated unit can have.
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 can be used with any distance
specification.
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 restricted 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 the Examples section of
method_nearest()
for an example of their use, which is the same
as it is with optimal matching.
All outputs described in matchit()
are returned with
method = "optimal"
. When include.obj = TRUE
in the call to
matchit()
, the output of the call to optmatch::fullmatch()
will be
included in the output. When exact
is specified, this will be a list
of such objects, one for each stratum of the exact
variables.
Optimal pair matching is a restricted form of optimal full matching
where the number of treated units in each subclass is equal to 1, whereas in
unrestricted full matching, multiple treated units can be assigned to the
same subclass. \pkgfunoptmatchpairmatch is simply a wrapper for
\pkgfunoptmatchfullmatch, which performs optimal full matching and is the
workhorse for method_full
. In the same way, matchit()
uses optmatch::fullmatch()
under the hood, imposing the restrictions that
make optimal full matching function like optimal pair matching (which is
simply to set min.controls >= 1
and to pass ratio
to the
mean.controls
argument). This distinction is not important for
regular use but may be of interest to those examining the source code.
The option "optmatch_max_problem_size"
is automatically set to
Inf
during the matching process, different from its default in
optmatch. This enables matching problems of any size to be run, but
may also let huge, infeasible problems get through and potentially take a
long time or crash R. See \pkgfunoptmatchsetMaxProblemSize for more details.
In a manuscript, be sure to cite the following paper if using
matchit()
with method = "optimal"
:
Hansen, B. B., & Klopfer, S. O. (2006). Optimal Full Matching and Related Designs via Network Flows. Journal of Computational and Graphical Statistics, 15(3), 609–627. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1198/106186006X137047")}
For example, a sentence might read:
Optimal pair matching was performed using the MatchIt package (Ho, Imai, King, & Stuart, 2011) in R, which calls functions from the optmatch package (Hansen & Klopfer, 2006).
matchit()
for a detailed explanation of the inputs and outputs of
a call to matchit()
.
optmatchfullmatch, which is the workhorse.
method_full
for optimal full matching, of which optimal pair
matching is a special case, and which relies on similar machinery.
data("lalonde")
#1:1 optimal PS matching with exact matching on race
m.out1 < matchit(treat ~ age + educ + race + nodegree +
married + re74 + re75, data = lalonde,
method = "optimal", exact = ~race)
m.out1
summary(m.out1)
#2:1 optimal matching on the scaled Euclidean distance
m.out2 < matchit(treat ~ age + educ + race + nodegree +
married + re74 + re75, data = lalonde,
method = "optimal", ratio = 2,
distance = "scaled_euclidean")
m.out2
summary(m.out2, un = FALSE)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.