{smcl}
{* *! version 1.0.1 26Oct2016}{...}
{* *! version 1.0.0 28May2016}{...}

{title:Title}

{p2colset 5 15 20 2}{...}
{p2col:{hi:covbal} {hline 2}} Covariate balance statistics  {p_end}
{p2colreset}{...}


{marker syntax}{...}
{title:Syntax}


{p 8 17 2}
{cmd:covbal} {cmd:}{it:{help varname:treatvar}} {it:{help varlist:varlist}} {ifin} 
[{cmd:,} {opt w:t}({it:{help varname:varname}}) {opt abs:olute} {opt f:ormat}({cmd:(%}{it:{help format:fmt}}) {opt s:aving}({it:{help filename:filename}, replace}) ]


{synoptset 19 tabbed}{...}
{synopthdr}
{synoptline}
{synopt:{opt w:t}{cmd:(}{it:{help varname:varname}}{cmd:)}} weight used for calculating weighted statistics {p_end}
{synopt:{opt abs:olute}}produce absolute standardized differences; default is signed standardized differences {p_end}
{synopt:{opt f:ormat}{cmd:(%}{it:{help format:fmt}}{cmd:)}}display format for statistics; default format is {cmd:%9.0g}{p_end}
{synopt:{opt s:aving}{cmd:(}{it:{help filename:filename}}{cmd:)}}specify filename where the statistics, generated by {cmd:covbal}, are to be saved. The suboption "replace" is allowed{p_end}
{synoptline}
{p2colreset}{...}
{p 4 6 2}
{opt by} is allowed; see {manhelp by D}.{p_end}


{p 4 6 2}
{p2colreset}{...}				
	
{title:Description}

{pstd}
{cmd:covbal} produces a table of distributional test statistics (means, variances, and skewness) for each covariate specified, and assesses balance 
between treatment groups in the means (using the standardized difference) and in the variances (using the variance ratio). 


{title:Remarks}

{pstd} While there is no empirical evidence to support the use of any particular cutpoint on the standardized difference to define imbalance, Normand et al.(2001)
suggest that a standardized difference greater than 0.10 is indicative of imbalance and Rubin (2001) suggests a cut-off of 0.25. Alternatively, since the standardized 
difference is a version of Cohen’s d statistic for effect size (Cohen 1988), one could also argue for a cut-off of 0.20, which Cohen termed a "small" effect. Perhaps 
the most helpful advise is to strive to achieve standardized differences as close to zero as possible (Linden & Samuels, 2013). 

{pstd} 
As balance is not only a property of the sample means of a covariate but of the overall distribution, higher-order sample moments of the distribution should be evaluated as well. 
Rubin (2001) proposes the use of the ratio of treated and control variances as a balance measure of the second moment, where balance is defined by values close to 1.0 and 
variables are out of balance if the variance ratio is greater than 2.0 or less than 0.5.

{pstd} 
Covariate imbalances may occur at any point along the distribution, and may not be captured by comparisons of means and variances (Linden 2015). It is therefore highly recommended 
to supplement these numerical measures of balance with graphical displays of the distribution -- in particular using quantile-quantile plots (see {helpb qqplot} or {helpb qqplot3}, if installed).    


{title:Options}

{p 4 8 2}
{cmd:wt(}{it:varname}{cmd:)} specifies the weight variable used for balancing covariates.

{p 4 8 2}
{cmd:absolute} produces the absolute value of the standardized difference; the default is the signed value of the standardized difference.

{p 4 8 2}
{cmd:format(%}{it:fmt}{cmd:)} specifies the format to be used for all statistics. The maximum width of the specified format should not exceed
   nine characters; default format is {cmd:%9.0g}.

{p 4 8 2}
{cmd:saving(}{it:filename}{cmd:)} specifies the filename where the statistics generated by {cmd:covbal} will be saved. {cmd:replace}, used with 
{cmd:saving}, specifies that {it:{help filename}} can be replaced if it already exists.
	

{title:Examples}

{pstd}
Load example data{p_end}
{p 4 8 2}{stata "webuse cattaneo2, clear":. webuse cattaneo2, clear}{p_end}

{pstd}Estimate propensity score for {cmd:mbsmoke} as the treatment, and generate inverse probability of treatment weights (IPTW) {p_end}
{p 4 8 2}{stata "logit mbsmoke mmarried c.mage c.mage#c.mage fbaby i.medu":. logit mbsmoke mmarried c.mage c.mage#c.mage fbaby i.medu}{p_end}
{p 4 8 2}{stata "predict pscore, pr":. predict pscore, pr}{p_end}
{p 4 8 2}{stata "gen iptw = cond(mbsmoke, 1/pscore, 1/(1-pscore))":. gen iptw = cond(mbsmoke, 1/pscore, 1/(1-pscore))}{p_end}

{pstd}Run {cmd:covbal} on unweighted data {p_end}
{p 4 8 2}{stata "covbal mbsmoke mmarried mage fbaby medu":. covbal mbsmoke mmarried mage fbaby medu}{p_end}

{pstd}Rerun {cmd:covbal} on weighted data {p_end}
{p 4 8 2}{stata "covbal mbsmoke mmarried mage fbaby medu, wt(iptw)":. covbal mbsmoke mmarried mage fbaby medu, wt(iptw)}{p_end}

{pstd}Same as above, but reporting the standardized differences as absolute values, and changing the format to %9.3f {p_end}
{p 4 8 2}{stata "covbal mbsmoke mmarried mage fbaby medu, wt(iptw) abs for(%9.3f)":. covbal mbsmoke mmarried mage fbaby medu, wt(iptw) abs for(%9.3f)}{p_end}

{pstd}Reviewing covariate balance by strata of the propensity score {p_end}
{p 4 8 2}{stata "xtile strata = pscore, nq(5)":. xtile strata = pscore, nq(5)}{p_end}
{p 4 8 2}{stata "bys strata: covbal mbsmoke mmarried mage fbaby medu if strata !=., abs for(%9.3f)":. bys strata: covbal mbsmoke mmarried mage fbaby medu if strata !=., abs for(%9.3f)}{p_end}

{pstd}Saving the output in file named "output" in the default directory {p_end}
{p 4 8 2}{stata "covbal mbsmoke mmarried mage fbaby medu, wt(iptw) abs for(%9.3f) saving(output)":. covbal mbsmoke mmarried mage fbaby medu, wt(iptw) abs for(%9.3f) saving(output)}{p_end}

{pstd}Open the saved file and review summary statistics for the standardized differences and variance ratios {p_end}
{p 4 8 2}{stata "use output, clear":. use output, clear}{p_end}
{p 4 8 2}{stata "sum stdiff varratio":. sum stdiff varratio}{p_end}


{title:Stored results}

{pstd}
{cmd:covbal} stores the following in {cmd:r()}, which can be displayed by typing {cmd: return list} after {cmd:covbal} is finished (see {help return}):

{synoptset 15 tabbed}{...}
{p2col 5 15 19 2: Scalars}{p_end}
{synopt:{cmd:r(varcnt)}}number of covariates assessed{p_end}
{synopt:{cmd:r(masd)}}mean of the absolute standardized differences{p_end}
{synopt:{cmd:r(mvr)}}mean of the variance ratios{p_end}

{synoptset 15 tabbed}{...}
{p2col 5 15 19 2: Matrices}{p_end}
{synopt:{cmd:r(table)}}balance table{p_end}

{p2colreset}{...}


{title:References}

{p 4 8 2}
Cohen, J. (1988) {it:Statistical Power Analysis for the Behavioral Sciences, 2nd edn.} Hillsdale, NJ: Lawrence Erlbaum.

{p 4 8 2}
Flury, B. K. & Reidwyl, H. (1986) Standard distance in univariate and multivariate analysis. {it:The American Statistician}, 40, 249–251.

{p 4 8 2}
Linden, A. (2015) Graphical displays for assessing covariate balance in matching studies. {it:Journal of Evaluation in Clinical Practice}, 21, 242–247.

{p 4 8 2}
Linden, A. & Samuels, S. J. (2013) Using balance statistics to determine the optimal number of controls in matching studies. {it:Journal of Evaluation in Clinical Practice}, 
19, 968–975.  

{p 4 8 2}
Normand, S. L. T., Landrum, M. B., Guadagnoli, E., Ayanian, J. Z., Ryan, T. J., Cleary, P. D. & McNeil, B. J. (2001) Validating recommendations for coronary angiography 
following an acute myocardial infarction in the elderly: a matched analysis using propensity scores. {it:Journal of Clinical Epidemiology}, 54, 387–398.

{p 4 8 2}
Rubin, D. B. (1973) Matching to remove bias in observational studies. {it:Biometrics}, 29, 159–184.

{p 4 8 2}
Rubin, D. B. (2001) Using propensity scores to help design observational studies: application to the tobacco litigation. {it:Health Services & Outcomes Research Methodology}, 
2, 169–188. 
    



{marker citation}{title:Citation of {cmd:covbal}}

{p 4 8 2}{cmd:covbal} is not an official Stata command. It is a free contribution
to the research community, like a paper. Please cite it as such: {p_end}

{p 4 8 2}
Linden, Ariel (2016). covbal: Stata module for generating covariate balance statistics. {browse "http://ideas.repec.org/c/boc/bocode/s458188.html":http://ideas.repec.org/c/boc/bocode/s458188.html}
{p_end}


{title:Author}

{p 4 8 2}	Ariel Linden{p_end}
{p 4 8 2}	President, Linden Consulting Group, LLC{p_end}
{p 4 8 2}	Ann Arbor, MI, USA{p_end}
{p 4 8 2}{browse "mailto:alinden@lindenconsulting.org":alinden@lindenconsulting.org}{p_end}
{p 4 8 2}{browse "http://www.lindenconsulting.org"}{p_end}


{title:Acknowledgments} 

{p 4 4 2}
I wish to thank Nicholas J. Cox for reviewing {cmd:covbal} and making valuable improvements to the code.{p_end}
         

{title:Also see}

{p 4 8 2} Online: {helpb tebalance}, {helpb tabstat}, {helpb qqplot}, {helpb pbalchk} (if installed), {helpb imbalance} (if installed) {helpb qqplot3} (if installed){p_end}