Matchby: Grouped Multivariate and Propensity Score Matching
In Matching: Multivariate and Propensity Score Matching with Balance Optimization

Matchby

R Documentation

Grouped Multivariate and Propensity Score Matching

Description

This function is a wrapper for the Match function which separates the matching problem into subgroups defined by a factor. This is equivalent to conducting exact matching on each level of a factor. Matches within each level are found as determined by the usual matching options. This function is much faster for large datasets than the Match function itself. For additional speed, consider doing matching without replacement—see the replace option. This function is more limited than the Match function. For example, Matchby cannot be used if the user wishes to provide observation specific weights.

Usage

Matchby(Y, Tr, X, by, estimand = "ATT", M = 1, ties=FALSE, replace=TRUE,
        exact = NULL, caliper = NULL, AI=FALSE, Var.calc=0,
        Weight = 1, Weight.matrix = NULL, distance.tolerance = 1e-05,
        tolerance = sqrt(.Machine$double.eps), print.level=1, version="Matchby", ...)

Arguments

`Y`	A vector containing the outcome of interest. Missing values are not allowed.
`Tr`	A vector indicating the observations which are in the treatment regime and those which are not. This can either be a logical vector or a real vector where 0 denotes control and 1 denotes treatment.
`X`	A matrix containing the variables we wish to match on. This matrix may contain the actual observed covariates or the propensity score or a combination of both.
`by`	A "factor" in the sense that `as.factor(by)` defines the grouping, or a list of such factors in which case their interaction is used for the grouping.
`estimand`	A character string for the estimand. The default estimand is "ATT", the sample average treatment effect for the treated. "ATE" is the sample average treatment effect (for all), and "ATC" is the sample average treatment effect for the controls.
`M`	A scalar for the number of matches which should be found. The default is one-to-one matching. Also see the `ties` option.
`ties`	A logical flag for whether ties should be handled deterministically. By default `ties==TRUE`. If, for example, one treated observation matches more than one control observation, the matched dataset will include the multiple matched control observations and the matched data will be weighted to reflect the multiple matches. The sum of the weighted observations will still equal the original number of observations. If `ties==FALSE`, ties will be randomly broken. If the dataset is large and there are many ties, setting `ties=FALSE` often results in a large speedup. Whether two potential matches are close enough to be considered tied, is controlled by the `distance.tolerance` option.
`replace`	Whether matching should be done with replacement. Note that if `FALSE`, the order of matches generally matters. Matches will be found in the same order as the data is sorted. Thus, the match(es) for the first observation will be found first and then for the second etc. Matching without replacement will generally increase bias so it is not recommended. But if the dataset is large and there are many potential matches, setting `replace=false` often results in a large speedup and negligible or no bias. Ties are randomly broken when `replace==FALSE`—see the `ties` option for details.
`exact`	A logical scalar or vector for whether exact matching should be done. If a logical scalar is provided, that logical value is applied to all covariates of `X`. If a logical vector is provided, a logical value should be provided for each covariate in `X`. Using a logical vector allows the user to specify exact matching for some but not other variables. When exact matches are not found, observations are dropped. `distance.tolerance` determines what is considered to be an exact match. The `exact` option takes precedence over the `caliper` option.
`caliper`	A scalar or vector denoting the caliper(s) which should be used when matching. A caliper is the distance which is acceptable for any match. Observations which are outside of the caliper are dropped. If a scalar caliper is provided, this caliper is used for all covariates in `X`. If a vector of calipers is provided, a caliper value should be provide for each covariate in `X`. The caliper is interpreted to be in standardized units. For example, `caliper=.25` means that all matches not equal to or within .25 standard deviations of each covariate in `X` are dropped.
`AI`	A logical flag for if the Abadie-Imbens standard error should be calculated. It is computationally expensive to calculate with large datasets. `Matchby` can only calculate AI SEs for ATT. To calculate AI errors with other estimands, please use the `Match` function. See the `Var.calc` option if one does not want to assume homoscedasticity.
`Var.calc`	A scalar for the variance estimate that should be used. By default `Var.calc=0` which means that homoscedasticity is assumed. For values of `Var.calc > 0`, robust variances are calculated using `Var.calc` matches.
`Weight`	A scalar for the type of weighting scheme the matching algorithm should use when weighting each of the covariates in `X`. The default value of 1 denotes that weights are equal to the inverse of the variances. 2 denotes the Mahalanobis distance metric, and 3 denotes that the user will supply a weight matrix (`Weight.matrix`). Note that if the user supplies a `Weight.matrix`, `Weight` will be automatically set to be equal to 3.
`Weight.matrix`	This matrix denotes the weights the matching algorithm uses when weighting each of the covariates in `X`—see the `Weight` option. This square matrix should have as many columns as the number of columns of the `X` matrix. This matrix is usually provided by a call to the `GenMatch` function which finds the optimal weight each variable should be given so as to achieve balance on the covariates. For most uses, this matrix has zeros in the off-diagonal cells. This matrix can be used to weight some variables more than others. For example, if `X` contains three variables and we want to match as best as we can on the first, the following would work well: `> Weight.matrix <- diag(3)` `> Weight.matrix[1,1] <- 1000/var(X[,1])` `> Weight.matrix[2,2] <- 1/var(X[,2])` `> Weight.matrix[3,3] <- 1/var(X[,3])` This code changes the weights implied by the inverse of the variances by multiplying the first variable by a 1000 so that it is highly weighted. In order to enforce exact matching see the `exact` and `caliper` options.
`distance.tolerance`	This is a scalar which is used to determine if distances between two observations are different from zero. Values less than `distance.tolerance` are deemed to be equal to zero. This option can be used to perform a type of optimal matching
`tolerance`	This is a scalar which is used to determine numerical tolerances. This option is used by numerical routines such as those used to determine if a matrix is singular.
`print.level`	The level of printing. Set to '0' to turn off printing.
`version`	The version of the code to be used. The "Matchby" C/C++ version of the code is the fastest, and the end-user should not change this option.
`...`	Additional arguments passed on to `Match`.

Details

Matchby is much faster for large datasets than Match. But Matchby only implements a subset of the functionality of Match. For example, the restrict option cannot be used, Abadie-Imbens standard errors are not provided and bias adjustment cannot be requested. Matchby is a wrapper for the Match function which separates the matching problem into subgroups defined by a factor. This is the equivalent to doing exact matching on each factor, and the way in which matches are found within each factor is determined by the usual matching options.

Note that by default ties=FALSE although the default for the Match in GenMatch functions is TRUE. This is done because randomly breaking ties in large datasets often results in a great speedup. For additional speed, consider doing matching without replacement which is often much faster when the dataset is large—see the replace option.

There will be slight differences in the matches produced by Matchby and Match because of how the covariates are weighted. When the data is broken up into separate groups (via the by option), Mahalanobis distance and inverse variance will imply different weights than when the data is taken as whole.

Value

`est`	The estimated average causal effect.
`se.standard`	The usual standard error. This is the standard error calculated on the matched data using the usual method of calculating the difference of means (between treated and control) weighted so that ties are taken into account.
`se`	The Abadie-Imbens standard error. This is only calculated if the `AI` option is `TRUE`. This standard error has correct coverage if `X` consists of either covariates or a known propensity score because it takes into account the uncertainty of the matching procedure. If an estimated propensity score is used, the uncertainty involved in its estimation is not accounted for although the uncertainty of the matching procedure itself still is.
`index.treated`	A vector containing the observation numbers from the original dataset for the treated observations in the matched dataset. This index in conjunction with `index.control` can be used to recover the matched dataset produced by `Matchby`. For example, the `X` matrix used by `Matchby` can be recovered by `rbind(X[index.treated,],X[index.control,])`.
`index.control`	A vector containing the observation numbers from the original data for the control observations in the matched data. This index in conjunction with `index.treated` can be used to recover the matched dataset produced by `Matchby`. For example, the `Y` matrix for the matched dataset can be recovered by `c(Y[index.treated],Y[index.control])`.
`weights`	The weights for each observation in the matched dataset.
`orig.nobs`	The original number of observations in the dataset.
`nobs`	The number of observations in the matched dataset.
`wnobs`	The number of weighted observations in the matched dataset.
`orig.treated.nobs`	The original number of treated observations.
`ndrops`	The number of matches which were dropped because there were not enough observations in a given group and because of caliper and exact matching.
`estimand`	The estimand which was estimated.
`version`	The version of `Match` which was used.

Author(s)

Jasjeet S. Sekhon, UC Berkeley, sekhon@berkeley.edu, https://www.jsekhon.com.

References

Sekhon, Jasjeet S. 2011. "Multivariate and Propensity Score Matching Software with Automated Balance Optimization.” Journal of Statistical Software 42(7): 1-52. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.18637/jss.v042.i07")}

Diamond, Alexis and Jasjeet S. Sekhon. 2013. "Genetic Matching for Estimating Causal Effects: A General Multivariate Matching Method for Achieving Balance in Observational Studies.” Review of Economics and Statistics. 95 (3): 932–945. https://www.jsekhon.com

Abadie, Alberto and Guido Imbens. 2006. “Large Sample Properties of Matching Estimators for Average Treatment Effects.” Econometrica 74(1): 235-267.

Imbens, Guido. 2004. Matching Software for Matlab and Stata.

Examples

#
# Match exactly by racial groups and then match using the propensity score within racial groups
#

data(lalonde)

#
# Estimate the Propensity Score
#
glm1  <- glm(treat~age + I(age^2) + educ + I(educ^2) +
             hisp + married + nodegr + re74  + I(re74^2) + re75 + I(re75^2) +
             u74 + u75, family=binomial, data=lalonde)


#save data objects
#
X  <- glm1$fitted
Y  <- lalonde$re78
Tr <- lalonde$treat

# one-to-one matching with replacement (the "M=1" option) after exactly
# matching on race using the 'by' option.  Estimating the treatment
# effect on the treated (the "estimand" option defaults to ATT).
rr  <- Matchby(Y=Y, Tr=Tr, X=X, by=lalonde$black, M=1);
summary(rr)

# Let's check the covariate balance
# 'nboots' is set to small values in the interest of speed.
# Please increase to at least 500 each for publication quality p-values.
mb  <- MatchBalance(treat~age + I(age^2) + educ + I(educ^2) + black +
                    hisp + married + nodegr + re74  + I(re74^2) + re75 + I(re75^2) +
                    u74 + u75, data=lalonde, match.out=rr, nboots=10)

Matching documentation built on Oct. 14, 2024, 5:09 p.m.