MatchBalance            package:Matching            R Documentation

_T_e_s_t_s _f_o_r _U_n_i_v_a_r_i_a_t_e _a_n_d _M_u_l_t_i_v_a_r_i_a_t_e _B_a_l_a_n_c_e

_D_e_s_c_r_i_p_t_i_o_n:

     This function provides a variety of univariate and multivariate
     tests to determine if balance exists.  The function does no
     matching. Matching is performed by the 'Match' function.
     'MatchBalance' is used to determine if 'Match' was successful in
     achieving balance.  Multivariate balance is determined by the use
     of a model.  This approach can be used regardless of the algorithm
     used to do the original matching.  For example, even if 'Match'
     was told NOT to use a propensity score, 'MatchBalance' can be used
     to test balance.

_U_s_a_g_e:

     MatchBalance(formul, data = NULL, match.out = NULL, ks = TRUE, mv = FALSE,
                  nboots=1000, nmc=nboots,  maxit = 1000,
                  weights=rep(1,nrow(data)), digits=5, verbose=1,
                  paired=TRUE, ...)

_A_r_g_u_m_e_n_t_s:

  formul: A formula denoting the model for which balance should be
          determined.  This model will be estimated by a binary
          logistic estimator. The dependent variable in the formula is
          usually the treatment indicator. Univariate balance tests
          will be conducted for each of the regressors included in this
          model. And the multivariate tests will be conducted on the
          predicted probabilities of treatment for both treated and
          control based on this formula. The predicted probability
          densities for both treated and control should be
          indistinguishable if balance has been achieved. Note that the
          model defined by this formula is estimated separately for the
          matched and unmatched datasets.

    data: A data frame which contains all of the variables in the
          formula.  If a data frame is not provided, the variables are
          obtained via lexical scoping.

match.out: The output object from the 'Match' function.  If this output
          is included, 'MatchBalance' will provide balance tests for
          both before and after matching. Otherwise balance tests will
          only be conducted for the raw data.

      ks: A logical flag for if the univariate bootstrap
          Kolmogorov-Smirnov (KS) test should be calculated.  If the ks
          option is set to true, the univariate KS test is calculated
          for all non-dichotomous variables.  The bootstrap KS test is
          consistent even for non-continuous variables.  See 'ks.boot'
          for more details.

      mv: A logical flag for if multivariate balance tests (the
          Kolmogorov-Smirnov and Chi-Square tests) should be
          calculated.

   maxit: The maximum number of iterations for the glm logistic
          procedure. 

 weights: A vector of observation specific weights.

  nboots: The number of bootstrap samples to be run.  If zero, no
          bootstraps are done.  Bootstrapping is highly recommended
          because the Kolmogorov-Smirnov test only provides correct
          coverage when bootstrapped due to the existence of nuisance
          parameters.  At least 500 'nboots' (preferably 1000) are
          recommended for publication quality p-values.  Also see the
          'nmc' option.

     nmc: The number of Monte Carlo simulations to be conducted for
          each Kolmogorov-Smirnov test calculated.  Monte Carlo
          simulations are highly recommended because the usual
          Kolmogorov-Smirnov test is not consistent when the densities
          being compared contain point masses.  At least 500 'nmc'
          (preferably 1000) are recommended for publication quality
          p-values. Also see the 'nboots' option.

  digits: The number of significant digits that should be displayed.

 verbose: The amount of printing to be done.  If zero, there is no
          printing.  If one, the results are summarized.  If two,
          details are printing such as the number of the bootstrap
          sample currently being estimated.

  paired: A flag for if the paired 't.test' should be used after
          matching.  Regardless of the value of this option, an
          unpaired 't.test' is done for the unmatched data because it
          is assumed that the unmatched data were not generated by a
          paired experiment.

     ...: Further arguments passed to 'balanceMV'.

_D_e_t_a_i_l_s:

     The function can be used to determine if matching was successful
     in achieving balance.  Two univariate tests are provided: the
     t-test and the bootstrap Kolmogorov-Smirnov (KS) test. The
     bootstrap KS test is highly recommended (see the 'ks' and 'nboots'
     options) because the bootstrap KS is consistent even for
     non-continuous covariates, and it is more powerful than the
     t-test.  Before matching the two sample t-test is used, and after
     matching the paired t-test is used.

     Two multivariate tests are provided.  The KS and Chi-Square null
     deviance tests.  The KS test is to be preferred over the
     Chi-Square test because the Chi-Square test is not testing the
     relevant hypothesis.  The null hypothesis for the KS test is of
     equal balance in the estimated probabilities between treated and
     control.  The null hypothesis for the Chi-Square test, however, is
     of all of the parameters being insignificant; a comparison of
     residual versus null deviance.  If the covariates being considered
     are discrete, this KS test is asymptotically nonparametric as long
     as the logit model does not produce zero parameter estimates.  The
     bootstrap-Monte Carlo version of the KS test is highly recommended
     because the usual KS test is not consistent when there are point
     masses in the distributions being compared, and the bootstrap is
     needed because parameters are being estimated in the logit model.

_V_a_l_u_e:

      mv: A return object from a call to 'balanceMV'

      uv: A return object from a call to 'balanceUV'.  The univariate
          tests performed on the last variable in 'formul' are
          returned.  For the other variables call 'balanceUV' directly.
           Note that the univariate test results for all of the
          variables in 'formul' are printed if 'verbose > 1'.

_A_u_t_h_o_r(_s):

     Jasjeet S. Sekhon, Harvard University, jasjeet_sekhon@harvard.edu,
     <URL: http://jsekhon.fas.harvard.edu/>

_R_e_f_e_r_e_n_c_e_s:

     Sekhon, Jasjeet S. 2004.  ``Balance Tests for Matching
     Estimators.'' Working Paper. <URL:
     http://jsekhon.fas.harvard.edu/matching>

     Abadie, Alberto.  2002.  ``Bootstrap Tests for Distributional
     Treatment Effects in Instrumental Variable Models.'' _Journal of
     the American Statistical Association_, 97:457 (March) 284-292.  

     Hall, Peter. 1992. _The Bootstrap and Edgeworth Expansion_.  New
     York: Springer-Verlag.

     Wilcox, Rand R. 1997. _Introduction to Robust Estimation_.  San
     Diego, CA: Academic Press.

     William J. Conover (1971), _Practical nonparametric statistics_.
     New York: John Wiley & Sons. Pages 295-301 (one-sample
     "Kolmogorov" test), 309-314 (two-sample "Smirnov" test).

     Shao, Jun and Dongsheng Tu. 1995. _The Jackknife and Bootstrap_.
     New York: Springer-Verlag.

_S_e_e _A_l_s_o:

     Also see 'Match', 'GenMatch', 'balanceMV', 'balanceUV', 'ks.boot',
      'GerberGreenImai', 'lalonde'

_E_x_a_m_p_l_e_s:

     #
     # Replication of Dehejia and Wahba psid3 model
     #
     # Dehejia, Rajeev and Sadek Wahba. 1999.``Causal Effects in Non-Experimental Studies: Re-Evaluating the
     # Evaluation of Training Programs.''Journal of the American Statistical Association 94 (448): 1053-1062.
     #
     data(lalonde)

     #
     # Estimate the propensity model
     #
     glm1  <- glm(treat~age + I(age^2) + educ + I(educ^2) + black +
                  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).
     # Estimating the treatment effect on the treated (the "estimand" option which defaults to 0).
     #
     rr  <- Match(Y=Y,Tr=Tr,X=X,M=1);

     #Let's summarize the output
     summary(rr)

     #
     # Let's check for balance
     # 'nboots' and 'nmc' are 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, nmc=10)

