help for theildecoTim F. Liao, (June 2016)

Refined Theil index decomposition by group and quantile

Syntax

theildeco varname [weights] [if exp] [in range]
[, byg(groupvar) alpha(parameter}
method(parameter} quant(parameter} ]

fweights and aweights are allowed; see help weight.

Description

theildeco estimates a set of Theil inequality index decomposition by further
decomposing the within-group component. Either Theil's first, or T, index or Theil's
second, or L, index decomposition can be requested. These two indexes were initially
presented by Theil (1967) and have been widely applied in the social and economic
sciences. A further refinement of decomposing the within-group component is proposed
by Liao (2016a, 2016b). The refinement differentiates between shared versus different
dispersion in the within-group component (method 0). Alternatively, inequality is decomposed
by quantile first, and the between-group component of different quantiles can be contrasted.
The user can choose the number of quantiles, such as 4 (quartiles), 5 (quintiles), or 10
(deciles). This alternative method (method 1) is also discussed in Liao (2016a, 2016b). The
user may simply prefer to contrast two percentiles, such as the top 10% versus the remaining
90% (or method 2). The method option allows the user to choose any of the methods.

varname typically is an income variable recorded on the real scale though it can
be another continuous outcome variable. For computing Theil's L decomposition (when alpha is
set to 0), only values > 0 can be analyzed; for computing Theil's T decomposition (when
alpha is set to 1), only values >= 0 can be analyzed.

groupvar must take positive integer values only greater than 0 such as 1, 2, ..., G.
To create such a variable from an existing variable, use the egen function group.
By default, observations with missing values on groupvar are excluded from calculations.

Bootstrapped standard errors for any of the scalar estimates can be readily obtained using
bootstrap. These include the usual decompositon components as well as the refined
decomposition components and 2 times log ratios for contrasting between-group within-quantile
components. However, bootstrap may not work with sampling weights.

Options

byg passes on the group variable to compute inequality decompositions by
population group. This variable is required to obtain any Theil decomposition.

alpha sets the decomposition of Theil's L (alpha=0) or Theil's T (alpha=1,
the default).

method requests for the calculation of decomposition the use of method 0, method 1
(the default), or method 2. These methods are discussed earlier, with further details
presented in Liao (2016a, 2016b).

quant chooses number of quantiles to be used for method 1 (an integer) or
percentile (a value between 1 and 100) to be used for method 2. The default is 5.

Saved results

Depending on the method and quantile chosen, the saved results may include some or most
of the following:

Scalars

r(Theil) Theil's index before decomposition

r(between_T), between-group component of Theil's index

r(within_T), within-group component of Theil's index

r(between_Tq) between-quantile component of Theil's index

r(within_Tq) within-quantile component of Theil's index

r(TopMidlnR) 2 times log of the top-quantile between-group
to the mid-quantile between group ratio, a BIC-like
statistc

r(BotMidlnR) 2 times log of the bottom-quantile between-group
to the mid-quantile between group ratio, a BIC-like
statistc

r(TopBotlnR) 2 times log of the top-quantile between-group
to the bottom-quantile between group ratio, a BIC-like
statistc

Matrices

r(MeanY), mean of outcome variable

r(PopShare) population share of each group g

r(IncomeShare) income (outcome) share of each group g

r(GroupTheil) group-specific Theil's index

r(within_q_between) between-group component of within-quantile decomposition

r(within_q_within) within-group component of within-quantile decomposition

Examples

. theildeco x, byg(sex)

. theildeco x [aw = weight], byg(sex)

. theildeco x [aw = weight], byg(sex) a(0)

. theildeco x [aw = weight], byg(sex) a(0) m(1)

. theildeco x [aw = weight], byg(sex) a(0) m(1) q(4)

. theildeco x [aw = weight], byg(sex) a(1) m(1) q(10)

. theildeco x [aw = weight], byg(sex) a(1) m(2) q(90)

. bootstrap r(TopMidlnR): theildeco x,byg(g) a(1) m(1) q(3)

Examples Using the Auto Dataset

. use auto

. gen origin = foreign + 1

. theildeco mpg, byg(origin)

. theildeco mpg, byg(origin) a(0) m(1) q(3)

. theildeco mpg, byg(origin) a(1) m(2) q(50)

. bootstrap r(TopBotlnR), reps(100): theildeco mpg, byg(origin) a(1) m(2) q(50)

Author

Tim F. Liao <tfliao@illinois.edu>

University of Illinois at Urbana-Champaign

Acknowledgements

The author acknowledges benefiting from viewing various existing Stata ado files.
Comments and suggestions will be welcome for debugging and updating theildeco.

References

Liao, T.F.2016a.
Evaluating Distributional Differences in Income Inequality.
Socius
2: 1-14. (http://srd.sagepub.com/content/2/2378023115627462.full.pdf+html)

Liao, T.F.2016b.
Evaluating Distributional Differences in Income Inequality with Sampling Weights.
Socius
2 (supplements): 1-6.
(http://srd.sagepub.com/content/suppl/2016/06/23/2.0.2378023115627462.DC1/SociusTFLiaoExtensions16.pdf)

Theil, H. 1967.
Economics and Information Theory. Amsterdam: North-Holland Publishing Company.