help ebalfithttp://github.com/benjann/ebalfit/

Title

ebalfit -- Entropy balancing as an estimation command

Syntax

Syntax 1: balance subsamples

ebalfit varlist [if] [in] [weight], by(varname)
[, options ]

Syntax 2: adjust sample to population

ebalfit varlist [if] [in] [weight], population([popsize:]numlist)
[, options ]

Replay results

ebalfit [, reporting_options ]

Generate predictions after estimation

predict [type] newvar [if] [in] [, w u pr pscore xb ]

w balancing weights (the default)
u raw balancing weights; w = u * weight
pr propensity scores
pscore synonym for pr
xb linear predictions

Generate influence functions after estimation

predict [type]
{stub* |
newvarlist}
[if] [in], ifs [ nocons noalpha ]

nocons skip IF for _cons
noalpha synonym for nocons

options description

Main
by(groupvar) identify subsamples (required in syntax 1)

swap swap subsamples (syntay 1 only)

pooled use pooled sample as reference (syntay 1 only)

population(spec) provide population values (required in syntax 2)

tau(spec) specify custom target sum of weights

scales(spec) specify scales to be used for standardization

targets(options) specify types of moments to be balanced

[no]adjust(numlist) select terms to be balanced

Reporting
level(#) set confidence level; default is level(95)

noheader suppress header

nowtable suppress summary table of balancing weights

notable suppress coefficient table

display_options standard
reporting options as described in
[R] estimation options

baltab display balancing table

VCE/SE
vce(vcetype) variance estimation
method; default is vce(robust)

cluster(clustvar) synonym for
vce(cluster clustvar)

nose synonym for vce(none)

Generate
generate(newvar) store balancing weights

ifgenerate(names) store influence functions

nodescribe suppress list of generated variables in output

replace allow replacing existing variables

Optimization
btolerance(#) balancing tolerance; default is 1e-6

ltype(ltype) type of loss function; default is
ltype(reldif)

etype(etype) evaluator type; default is
etype(bl)

iterate(#) maximum number of iterations;
default is as set by set maxiter

ptolerance(#) convergence tolerance for coefficient
vector; default is 1e-6

vtolerance(#) convergence tolerance for the minimization
criterion; default is 1e-7

difficult use a different stepping algorithm in nonconcave
regions

nostd omit standardization during estimation; not recommended

nolog do not display iteration log

relax do not return error if convergence or balancing is not achieved

nowarn do not display non-convergence/non-balancing
messages

varlist may contain factor variables; see fvvarlist.

fweights, iweights, and pweights are allowed; see weight.

Description

ebalfit is an estimation command to perform entropy balancing
(Hainmueller 2012). The goal of entropy balancing is to find a vector of
weights that balances the data between two subsamples with respect to
specific moments of a list of variables (e.g. means and variances). For
example, we might want to reweight a control group such that the means of
pre-treatment variables match the means in the treatment group. Likewise,
entropy balancing can be used to adjust the distribution of a sample to known
population values.

Entropy balancing can be expressed as a regression-like model with one
coefficient for each balancing constraint. ebalfit estimates such a
model including the variance-covariance matrix of the estimated parameters. The
balancing weights are then obtained as predictions from this model. The
variance-covariance matrix computed by ebalfit is based on influence
functions. The influence functions can be
stored for further use, for example, to correct the standard errors of
statistics computed from the reweighted data.

The heavy lifting is done by function mm_ebalance()
from the moremata package, which needs to be installed on the
system. See
ssc describe moremata.

For an alternative implementation of entropy balancing in Stata
see ebalance by Hainmueller and Xu (2011, 2013).

For methods and formulas implemented in ebalfit see
Jann (2021).

Options

Main

by(groupvar) is required in syntax 1. The
specified variable must be integer and nonnegative and must identify exactly
two groups. By default, the lower value identifies the subsample to be
reweighted and the higher value identifies the reference subsample; also see
option swap.

swap swaps the subsamples (only allowed in syntax 1). By default, the
lower value of groupvar identifies the subsample to be reweighted. Specify
swap to use the higher value of
groupvar as the subsample to be reweighted.

pooled uses the pooled sample across both groups as the reference
sample (only allowed in syntax 1). In this case, the selected subsample
will be reweighted with respect to the overall sample (rather than with
respect to the other subsample).

population(spec) is required in syntax 2. Use this option to specify
the size of the population as well the population averages to which the
sample should be reweighted. The syntax of spec is

[popsize:] numlist

where popsize is the size of the population and numlist provides
the population averages of the variables. numlist must contain one value
for each variable. If popsize is omitted, it will be set to the sum of
weights in the sample.

tau(spec) specifies a custom target sum of weights for the balancing
weights within the reweighted sample. spec may either be # (#>0)
or one of Wref (sum of base weights in the reference sample), W
(sum of base weights in the reweighted sample), Nref
(number of rows the reference sample), or N (number of rows the reweighted
sample). The default is Wref.

scales(spec) determines the scales to be used for standardization during
estimation (unless nostd is specified) and for computation of
standardized differences in the balancing table. spec
may either be a numlist containing custom values (one for each
term in the model; the values must be positive) or, alternatively,
main (use standard deviations from the main sample),
reference (use standard deviations from the reference sample),
average (use standard deviations averaged between the two samples),
waverage (use standard deviations averaged between the two
samples, weighted by sample size), pooled (use standard deviations
from the pooled sample). reference, average, waverage,
and pooled are only allowed in syntax 1. Standard deviations are
computed using population formulas (division by N rather than N-1). Scales
equal to 0 will be reset to 1. The default is main.

targets(options) specifies the types of moments to be balanced. options
are:

mean (the default)
variance (implies mean)
skeweness (implies mean and variance)
covariance (implies mean)

By default, only the means of the specified variables will be balanced. If you
type, for example, targets(variance), then the variances of the variables
will be balanced in addition to the means. Balancing of higher moments and
covariances is implemented by adding extra terms to
varlist before running the balancing algorithm. For example, variance will add
c.varname#c.varname for each continuous variable
in varlist (skipping omitted terms). Likewise, covariance will add
c.varname1#c.varname2 for each combination of
continuous variables. Factor variables will be ignored by
variance and skewness, but covariance will consider them
and add appropriate interaction terms such as
1.fvvar#c.varname (skipping base levels).

If option targets() is specified, interaction terms such as
i.fvvar#c.varname are not allowed in
varlist. However, interactions are allowed if option targets()
is omitted. For example, you could type

c.hours##c.tenure i.south i.south#c.tenure

to balance the means of hours and tenure, the covariance between
hours and tenure, the proportions of the levels of south,
as well as the averages of tenure within levels of south
(see [U] 11.4.3 Factor variables for details on notation). That is,
you can use custom interactions as an alternative to option
targets() if you want to have more control over the exact configuration
of moments to be balanced.

[no]adjust(numlist) selects the terms to be balanced. Use this
option if you want to construct weights such that only a subset of terms is
adjusted, while keeping the others fixed. numlist provides the indices
of the relevant terms. For example, in a model with three variables, to adjust
the means of the first two variables and keep the mean of the third variable
fixed, type adjust(1 2) or, equivalently, noadjust(3). Keeping
terms fixed leads to different results than excluding the terms from the
model.

Reporting

level(#) specifies the confidence level, as a percentage, for
confidence intervals. The default is level(95) or as set by
set level.

noheader suppresses the display of the header.

nowtable suppress the display of the summary table of balancing weights.

notable suppresses the display of the coefficient table.

display_options are standard reporting options to be applied to the
coefficient table, such as eform, cformat(), or
coeflegend; see [R] eform_option and
the Reporting options in [R] Estimation options.

baltab displays a balancing table in addition
to the table of coefficients. The balancing table contains for each term
the target value, the unbalanced value, the standardized difference between
the target value and the unbalanced value, the balanced value, and the
standardized difference between the target value and the balanced value.

VCE/SE

vce(vcetype) determines how standard errors are computed. vcetype may be:

robust
cluster clustvar
none

vce(robust), the default, computes standard
errors based on influence functions. Likewise, vce(cluster clustvar)
computes standard errors based on influence function allowing for intragroup
correlation, where clustvar specifies to which group each observation
belongs. vce(none) omits the computation of standard errors.

cluster(clustvar) can be used as a synonym for vce(cluster clustvar).

nose omits the computation of standard errors. Use this option to
save computer time. nose is a synonym for vce(none).

Generate

generate(newvar) stores the balancing weights in newvar. Alternatively,
use command predict to generate the balancing weights after estimation.

In syntax 1, weights will be filled in for both the reweighted
subsample and the reference subsample, using a copy of the base weights
for the latter (or 1 if there are no base weights).

ifgenerate(names) stores the influence functions of the
coefficients. names is either a list of (new) variable names
or stub* to create names stub1,
stub2, etc. Alternatively, use command predict with option
ifs to generate the influence functions after estimation. In any case, the
influence functions will be scaled in a way such that command total can be
used to estimate the variance-covariance matrix.

nodescribe suppresses the list of generated variables that is displayed
in the output by default when generate() or ifgenerate() is specified.

replace allows replacing existing variables.

Optimization

btolerance(#) sets the balancing tolerance. Balance is achieved if
the balancing loss is smaller than the balancing tolerance. The
default is btolerance(1e-6).

ltype(ltype) sets the type of loss function to be used to evaluate
balancing. ltype can be reldif (maximum relative difference), absdif (maximum
absolute difference), or norm (Euclidean norm of differences). The default is
reldif.

etype(etype) selects the evaluator to be used to fit the
coefficients. etype can be
bl (evaluator based on the balancing loss), wl (evaluator based
on distribution of weights), mm (method of moments evaluator), or
mma (method of moments evaluator including the intercept). The
default is bl. Irrespective of the choice of evaluator, balancing loss
will be used to evaluate the final fit.

iterate(#) specifies the maximum number of iterations. Error will be returned
if convergence is not reached within the specified maximum number of
iterations. The default is as set by set maxiter.

ptolerance(#) specifies the convergence tolerance for the coefficient
vector. Convergence is reached if ptolerance() or vtolerance()
is satisfied. See optimize() for details. The
default is ptolerance(1e-6).

vtolerance(#) specifies the convergence tolerance for the minimization
criterion. Convergence is reached if ptolerance() or vtolerance()
is satisfied. See optimize() for details. The
default is vtolerance(1e-7) in case of etype(bl) and
vtolerance(1e-10) else.

difficult uses a different stepping algorithm in nonconcave regions. See
the singular H methods in optimize() and
the description of the difficult option in maximize.

nostd omits standardization of the data during estimation. Specifying
nostd is not recommended.

nolog suppresses the display of progress information.

relax causes ebalfit to proceed even if convergence or balance
is not achieved. ebalfit uses formulas assuming balance when
computing influence functions and standard errors. The stored influence functions
and reported standard errors will be invalid if balance has not been achieved.

nowarn suppresses any "convergence not achieved" or "balance not achieved"
messages. This is only relevant if option relax has been specified.

Examples

Reweight the sample of unionized workers such that the proportion with college
degree as well as the averages of working hours,
work experience, and tenure are the same as for non-unionized workers.

. sysuse nlsw88, clear
. ebalfit i.collgrad hours ttl_exp tenure, by(union) swap baltab

As indicated by the balancing loss and illustrated in the balancing table, perfect
balance has been achieved. We can generate the balancing weights and confirm manually
that the weights balance the data:

. predict wbal
. tabstat collgrad hours ttl_exp tenure [aw=wbal], by(union) nototal
. drop wbal

Balance variances and covariances in addition to the means:

. ebalfit i.collgrad hours ttl_exp tenure, by(union) swap targets(variance covariance)
. predict wbal
. corr collgrad hours ttl_exp tenure if union==0, cov
. corr collgrad hours ttl_exp tenure [aw=wbal] if union==1, cov
. drop wbal

Again, perfect balance could be achieved. The slight differences between the
covariance tables for the two groups are because corr normalizes
the weights by the number of (physical) observations (if corr would
treat the sum of weights as the sample size, the results would be identical).

Reweight a sample to arbitrary target values (e.g. population averages obtained
from a census):

. ebalfit 1.collgrad hours ttl_exp tenure, population(1e7: .30 40 10 5) baltab

Stored results

ebalfit saves the following results in e().

Scalars

e(N) number of observations

e(W) sum of weights

e(N_clust) number of clusters (if vce(cluster))

e(k_eq) number of equations in e(b) (always equal to 1)

e(k_omit) number of omitted terms

e(loss) balancing loss at final fit

e(btolerance) setting from btolerance()

e(balanced) 1 if balance achieved, 0 else

e(tau) target sum of weights

e(wsum) sum of balancing weights

e(wavg) average of balancing weights

e(wmin) minimum of balancing weights

e(wmax) maximum of balancing weights

e(cv) coefficient of variation of balancing weights

e(deff) DEFF (design effect) of balancing weights

e(ptoleranc) setting from ptolerance()

e(vtolerance) setting from vtolerance()

e(maxiter) setting from iterate()

e(iter) number of iterations

e(value) value of minimization criterion at final fit

e(converged) 1 if convergence achieved, 0 else

e(df_m) model degrees of freedom (unless nose)

e(chi2) chi-squared value of model test (unless nose)

e(p) p-value for model test (unless nose)

e(rank) rank of e(V) (unless nose)

Macros

e(cmd) ebalfit

e(predict) ebalfit_p

e(cmdline) command as typed

e(varlist) names of balancing variables

e(by) name of variable identifying subsamples

e(balsamp) subsample to be reweighted

e(refsamp) reference subsample

e(adjust) indices of adjusted terms, or "." (all)

e(noadjust) indices of non-adjusted terms

e(ltype) reldif, absdif, or norm

e(etype) bl, wl, mm, or mma

e(difficult) difficult or empty

e(nostd) nostd or empty

e(scale) main, reference, average,
waverage, pooled, or user

e(generate) name of variable containing balancing weights

e(ifgenerate) names of variables containing influence functions

e(vce) vcetype specified in vce()

e(vcetype) title used to label Std. Err.

e(clustvar) name of cluster variable

e(wtype) weight type

e(wexp) weight expression

e(title) title in estimation output

e(properties) b or b V

Matrices

e(b) estimates

e(V) variance-covariance matrix of estimates (unless nose)

e(omit) indicator for omitted terms

e(scales) scales used for standardization

e(_N) number of (physical) observations in subsamples

e(_W) sum of weights in subsamples

e(baltab) balancing table

Functions

e(sample) estimation sample

References

Hainmueller, J. (2012). Entropy Balancing for Causal Effects: A
Multivariate Reweighting Method to Produce Balanced Samples in
Observational Studies. Political Analysis
20(1): 25-46. DOI: 10.1093/pan/mpr025

Hainmueller, J., Y. Xu (2011). EBALANCE: Stata module to perform Entropy
reweighting to create balanced samples. Statistical Software Components
S457326, Boston College Department of Economics. http://ideas.repec.org/c/boc/bocode/s457326.html.

Hainmueller, J., Y. Xu (2013). ebalance: A Stata Package for Entropy Balancing.
Journal of Statistical Software
54(7):1-18. DOI: 10.18637/jss.v054.i07

Jann, B. (2021). Entropy balancing as an estimation command. University of
Bern Social Sciences Working Papers 39. Available from
http://ideas.repec.org/p/bss/wpaper/39.html.

Author

Ben Jann, University of Bern, ben.jann@unibe.ch

Thanks for citing this software as

Jann, B. (2021). ebalfit: Stata module to perform entropy balancing. Statistical
Software Components S458975, Boston College Department of Economics. Available
from http://ideas.repec.org/c/boc/bocode/s458975.html.

or

Jann, B. (2021). Entropy balancing as an estimation command. University of
Bern Social Sciences Working Papers 39. Available from
http://ideas.repec.org/p/bss/wpaper/39.html.

Also see

Official Stata:
estcom,
teffects

SSC Archive:
ebalance,
kmatch,
moremata, mm_ebalance(),
mm_wbal(),
mm_ebal()