*! version 1.4 of help file 25Apr2024 for -baltable.ado- Version 1.4, 25Apr2024

help for baltableVersion 1.4, 25Apr2024

Title

baltable - Balance table: Test for equal means of independent variables between two groups, e.g. a control and treatment group

Syntax

baltable indepvars [if] [in] [weight]
[using(filename)]
, by(varname)
[options]

Required option

Group variable (required)
by(varname) Binary (i.e. dichotomous) variable defining the
the two groups to be compared. Typically the variable equals 0
for the control or comparison group and 1 for the treatment
or experimental group.

Optional options

Test options
unequal Allow unequal variances for the t-tests
which are performed by Stata's ttest.
Default is to assume equal variances in the two groups.
Options unequal and heterogeneous are synonyms.

[no]joint Default is to test the joint null hypothesis that
all means are equal acoss the two groups using Stata's mvtest means.
Specifying nojoint suppresses the joint test.

heterogeneous Allow unequal variances and covariances for the
joint test using mvtest means. Default is to assume equal variances
and covariances in the two groups.
Options unequal and heterogeneous are synonyms.

p_upper or p_lower Present the p-value for a one-sided test.
Default is a two-sided test.

Table contents options
nostddev Suppress the rows displaying
standard deviations of the variables in indepvars.

nostderr Suppress the rows displaying
standard errors of the variable means.

nonobs Suppress the rows displaying
the number of observations or the degrees of freedom.

nostddiff Suppress the column displaying
the standardized difference between the means.

notstat Suppress the column displaying t-statistics
of the tests of the null hypotheses of equal means
between groups.

ponly Display only the means, their difference and the p-value
of the test that the means are identical.
Achieves the same result as specifying the five options:
nostddev, nostderr, nonobs, nostddiff and notstat.

nototals Suppress the column displaying
the statistics on the pooled sample consisting of both
the control and treatment groups.
For the most succinct output specify both ponly and nototals.

Factor variable management
fvexpand baltable's indepvars argument
accepts factor variables and time-series variables. By default,
these variables are stripped of their factor-variable
and/or time-series operators and the means of the base variables are compared between the two groups
as if they were continuous (i.e. cardinal) numeric variables.
Optionally the user may specify the option nolist, which
instructs baltable to expand each factor or time-series variable into
several dummy variables and interacted variables and then compare the means
of each expanded variable across the two groups. The options fvexpand and nolist
are synonyms.

Formatting options
format[(%fmt)] Display format
for means, standard deviations and standard errors.
Default format is %7.2f.

nformat[(%fmt)] Display format
for row(s) reporting the number of observations or the degrees of freedom.
Default format is %7.0f.

sformat[(%fmt)] Display format
for the column of standardized differences.
Default format is %7.1f%.

pformat[(%fmt)] Display format
for the column of p-values for rejection of the null hypothesis that the means are identical between the control and treatment group.
Default format is %7.14f%.

spacer Add a blank line between rows

extraspace(#) Specify the number of extra spaces between columns in SMCL and plain text.

verbose Display intermediate output.

Title options
title(string) Specify a title for the table

novarlabels Identify variables by their names
instead of by their labels

Export and saving options
using(filename.suffix)

The using() option specifies the file name and type to which the table is to be exported.
The document type is determined by the file's suffix.
For example, the option using(mybalancetbl.docx) specifies
that the table be exported as a MS Word document file named mybalancetbl
with suffix docx.
See etable's documentation of file suffixes
here.

exportopts(etable##exportopts:export_opts) Options to control detailed formatting of the exported table.
Except for the frequently used common option replace,
the options are specific to the document type.
See etable's documentation of export options by document type
here.

saving(filename,[replace]) Save the "collection" used to produce the table.
See help for collect_save.

Table structure options
nogrplabels By default the control and treatment group columns
are labeled with the valu labels assigned to the -by()- variable.
This option substitutes the values of thre treatment indicator for their value labels.

truncgrplbls(#) Truncate the labels appearing as the column headings
for the control and treatment groups to not exceed this number of characters. Default is 15.

wrap(#) Specify number of lines to allow for long stacked row headers.
See help for collect style row.

wrapon(wrapon) Specify how to break long stacked row headers.
wrapon may be word or length.
See help for collect style row.

wraplength(#) Specify maximum length for stacked row headers.
See help for collect style row.

split Split row header elements across columns.
This option is rarely used, because the table is more readable
when the row headers are stacked in a single column.
Default behavior is to stack the row headers.
See help for collect style row.

indepvars may include factor or time-series variables.
At least one explanatory variable is required.

by is required. weights are not allowed.

Description

baltable produces a customizable table of balance statistics
comparing the means of explanatory variables (i.e. "covariates")
between a control group and an experimental
group. The baltable matrix of returned results
allows the user to plot the balance statistics for explanatory variables,
using Ben Jann's coefplot
(Jann,2014).
All calculations are performed on the subset of observations not missing
for any of the variables in the analysis (i.e. casewise or listwise deletion).
Also see the discussion of listwise deletion in the help for missing values.

Using the Stata data set auto2, suppose that the binary variable foreign
represents a "treatment" with domestic cars being the "control" group
and foreign cars being the "treatment" group. Suppose the variables
mpg, price and weight are covariates measured pre-treatment
and we want to check balance in the covariates between the two groupsprior to treatment.
In this situation, the simplest baltable syntax is:

. sysuse auto2, clear
(1978 automobile data)

. baltable mpg price weight , by(foreign) ponly nototals
(current collection is baltable)

-+------------------
---------
| Car origin Balance Statistics
| Domestic Foreign Difference p-value*

-+------------------
---------
Mileage (mpg) | 19.83 24.77 4.95 0.0005
Price | 6072.42 6384.68 312.26 0.6802
Weight (lbs.) | 3317.12 2315.91 -1001.21 <0.0001

-+------------------
---------

*p-values for two-sided tests of Ho: mu_2==mu_1

Joint test that all means are equal: F( 3, 70.0) = 29.149; p-value = 0.0000

Assuming equal (co)variances between groups conserves the degrees of freedom.

Judging by the p-values in the last column,
the variable price is balanced across the two groups, but the variables mpg and weight are not.
To visualize the p-values, we retrieve baltable's results on the p-values
from its returned results table and plot them using coefplot.

. mat def balance = `r(balance)'

. mat def pvals = balance["p-value",.]

. coefplot matrix(pvals)

The examples
demonstrate more of the capabilities of baltable
and how to visualize its various results with coefplot.
See Syntax for a complete list of options.

Remarks

baltable's functionality is similar to that of by Stata 18's dtable
command, when used with the option group().
Unlike dtable, baltable shows all the relevant statistics for comparing
the two groups, including the standardized difference
(Rosenbaum and Rubin, 1985;
Bayoumi, 2022).
Following Rosenbaum and Rubin (ibid),
baltable expresses the standardized difference as a percentage
of the average standard deviation. The matrix of statistics returned
by baltable contains not only these percentages, but also
the absolute values of the standardized differences expressed
in units of the average standard deviation.
These absolute values are useful for plotting the balance results.

While dtable can compare multiple groups,
testing the null hypothesis for each variable that the means are identical across all groups,
baltable compares only two groups, typically a control and treatment group.
For comparing multiple treatment arms, several sequential executions of baltable
can compare any of the experimental groups to the control group
or any two groups against one another.

Examples

Setup

. sysuse auto2, clear

UNDER CONSTRUCTION.

Stored results in return

UNDER CONSTRUCTION.

Acknowledgements

I wrote this program for use by a class on impact evaluation taught
in 2023 and 2024 at the School of Economics, University of the Philippines, Diliman.
The author is grateful to UPSE's DE292 students for beta-testing.
Several other community-contributed commands are available to construct balance tables,
including the community-contributed balanceplot by Trenton D Mize, iebaltab
by Kristoffer Bjarkefur and Luiza Cardoso De Andrade, DIME Analytics, The World Bank Group
and stddiff by Ahmed Bayoumi.
baltable aims to emulate and extend their table-making functionality while
delegating the balance plotting to Ben Jann's program coefplot.
Unlike existing community-contributed balance table commands of which I am aware,
baltable uses Stata 17's collect table-making utilities and inherits
the power of their file exporting capabilities.

References

Bayoumi, Ahmed M. 2016, 2022. "STDDIFF: Stata module to compute Standardized differences
for continuous and categorical variables," Statistical Software Components S458275,
Boston College Department of Economics, revised 17 Dec 2022.
Click here to see a description with the option to install from SSC.

Bjarkefur, Kristoffer and Luiza Cardoso De Andrade. 2024 ietoolkit,
DIME Analytics, The World Bank Group.

Jann, Ben. 2014. coefplot documented in "Plotting regression coefficients and other estimates."
Stata Journal 14(4): 708-737.
https://doi.org/10.1177/1536867X1401400402

Larkin, Chris. 2018. Larkin's balance-plot accepts multiple treatment groups.
Click here to see a description.
-balance-plot- must be installed manually by downloading its files from Github
and then copying them into the directory identified by executing the command
personal from Stata's command line.

Rosenbaum, Paul R. and Donald Rubin. 1985. "Constructing a Control Group
Using Multivariate Matched Sampling Methods That Incorporate the Propensity Score."
The American Statistician.
https://www.jstor.org/stable/2683903

Mize, Trenton D. 2018. Mize's balanceplot accepts two treatment groups.
//raw.githubusercontent.com/tdmize/data/master/balanceplot")"':Click here to see a description with the option to install from Github

Author

Mead Over,
Center for Global Development, Washington, DC 20036 USA. Email:
MOver@CGDev.Org if you observe any
problems.