*! version 2.0.0 11nov2024

Title

i_ineq -- Individual decomposition of inequality measures

Syntax

i_ineq
varname
[if] [in]
[weight]
,
group(varname)
[options]

Main
* group(varname) grouping variable

measure(string) inequality measure: gini (default), theill, or theilt

generate(string) stub name for generated variables

replace replace existing variables

* group() is required.

pweights are allowed; see weight.

Description

i_ineq computes individual components of three inequality measures
(Gini index, Theil's L, and Theil's T) and their group-based decompositions.
The function takes as input an outcome variable (such as income), a grouping
variable, and an optional sampling weight. It returns three new variables
containing individual contributions and their between-group and within-group
components.

The Gini index (or Gini coefficient) is a widely used measure of inequality
that ranges from 0 (perfect equality) to 1 (maximum inequality). Theil's L
(also known as Theil's second measure or mean log deviation) and Theil's T
(also known as Theil's first measure or Theil entropy index) are members of
the generalized entropy family of inequality measures.

This command implements the individual decomposition methods described in
Liao (2022), which allow researchers to examine the contribution of each
individual to overall inequality and to decompose these contributions into
between-group and within-group components.

Options

Main

group(varname) specifies the grouping variable for the decomposition.
This variable should contain integers representing different groups (e.g.,
gender coded 1 & 2, race categories, income quintiles). The decomposition
will separate the inequality into between-group and within-group components
based on this grouping. This option is required.

measure(string) specifies which inequality measure to compute. Options are:

gini - Gini index (default). Computes individual components of
the Gini coefficient. Note that the Gini decomposition is computationally
intensive for large datasets.

theill - Theil's L index (mean log deviation). Requires all
values to be positive. Generally less sensitive to changes at the upper tail
of the distribution.

theilt - Theil's T index (Theil entropy index). Requires all
values to be positive though zeros are allowed (see Remarks below).
Generally more sensitive to changes at the upper tail of the distribution.

generate(string) specifies an (optional, user-chosen) stub name for the
three generated variables. If not specified, default names will be used based
on the measure:

For gini: g_i, g_ikb, g_ikw

For theill: tl_i, tl_ib, tl_iw

For theilt: tt_i, tt_ib, tt_iw

If you specify generate(myineq), the variables will be named
myineq_i, myineq_b, and myineq_w.

replace allows overwriting existing variables with the same names as
the output variables.

Examples

Setup

. sysuse auto, clear

Basic Gini decomposition by car origin

. i_ineq price, group(foreign)

Theil L decomposition by car origin

. i_ineq price, group(foreign) measure(theill) generate(tl)

Theil T decomposition by car origin

. i_ineq price, group(foreign) measure(theilt) generate(tt)

Using with weights (with "auto weight" as a fake sampling weight variable)

. i_ineq price [pweight=weight], group(foreign)

Visualize individual contributions

. i_ineq price, group(foreign)

. scatter g_i price, by(foreign)

Compare between and within components by group

. i_ineq price, group(foreign)

. tabstat g_ikb g_ikw, by(foreign) statistics(sum)

Multiple group analysis

. egen price_quartile = cut(price), group(4)

. i_ineq mpg, group(price_quartile)

Stored results

i_ineq stores the following in r():

Scalars

r(N) number of observations

r(groups) number of groups

r(overall) overall inequality index

r(between) between-group component

r(within) within-group component

r(ratio) ratio of between to total inequality

Macros

r(measure) inequality measure used

r(varlist) outcome variable

r(group) grouping variable

The command creates three new variables in the dataset:

Variables

prefix_i individual contribution to overall inequality

prefix_b between-group component of individual contribution

prefix_w within-group component of individual contribution

Note: For each observation, prefix_i = prefix_b + prefix_w

Remarks

Interpretation of results:

The overall inequality index is the sum of all individual contributions
(prefix_i). This can be decomposed into:

1. Between-group inequality: Sum of prefix_b across all
observations. This measures inequality that arises from differences in mean
outcomes between groups.

2. Within-group inequality: Sum of prefix_w across all
observations. This measures inequality that arises from differences in
outcomes within each group.

The r(ratio) result gives the proportion of total inequality that is
due to between-group differences. A higher ratio indicates that group
membership explains a larger share of overall inequality.

Handling of zero and negative values:

The three measures handle zero and negative values differently:

Gini index: Can handle all values including zeros and negatives.
No observations are excluded.

Theil L: Requires strictly positive values. Observations with
zero or negative values are automatically excluded with a note displayed.

Theil T: Can include zero values but excludes negative values.
This follows the information theory principle that 0*log(0) = 0 by definition
(Shannon 1948; Cover and Thomas 2006). This allows Theil T to correctly
measure extreme inequality situations, such as when one person has all
income while others have none. In such cases, Theil T = ln(N), its maximum
value. See Liao (2016) for detailed discussion including the two references above.

Computational considerations:

The Gini decomposition is computationally intensive, especially for large
datasets, as it requires O(n²) comparisons. For datasets with more than a few
thousand observations, computation may take several minutes. The Theil measures
(L and T) are much faster, requiring only O(n) operations.

Missing values:

Observations with missing values in either the outcome variable or the grouping
variable are excluded from the analysis.

References

Liao, T. F. 2016. "Evaluating Distributional Differences in Income Inequality with
Sampling Weights." Socius: Sociological Research for a Dynamic World
2: 1-7. Extensions to/Supplementary Material for: "Evaluating Distributional Differences
in Income Inequality." Socius: Sociological Research for a Dynamic World
2: 1-14.https://doi.org/10.1177/2378023115627462

Liao, T. F. 2022. "Individual Components of Three Inequality Measures for
Analyzing Shapes of Inequality." Sociological Methods & Research
51(3): 1325-1356.
https://doi.org/10.1177/0049124119875961

Author

Tim F. Liao

University of Illinois Urbana-Champaign

tfliao@illinois.edu

This Stata implementation is ported from the R package iIneq.

Also see

Online: summarize, tabstat, egen