```-------------------------------------------------------------------------------
help for adecomp                                             Joao Pedro Azevedo
Minh Cong Nguyen
Viviane Sanfelice
-------------------------------------------------------------------------------

adecomp - Shapley Decomposition by Components of a Welfare Measure

adecomp welfarevar components [weight] [if exp] [in exp], by(varname)
equation(c#[operator]c#[operator]c#[operator]...[operator]cN)
[ indicator(string) varpl(varname) mpl(numlist) gic(#)
group(varname) id(varname) rank(string) strata(varlist)
percentile(#) oneway std ]

fweights and aweights are allowed; see help weights. See help weight.

Description

adecomp implements the shapley decomposition of changes in a welfare
indicator as proposed by Azevedo, Sanfelicce and Minh (2012). Following
property of a welfare aggregate to construct a counterfactual
unconditional distribution of the welfare aggregate by changing each
component at a time to calculate their contribution to the observed
changes in poverty and inequality.

Given that the distribution of a observable welfare measure (i.e. income
or consumption) for period 0 and period 1 are known, we can construct
counterfactual distributions for period 1 by substituting the observed
level of the indicators c in period 0, one at a time. For each
counterfactual distribution, we can compute the poverty or inequality
measures, and interpret those counterfactuals as the poverty or
inequality level that would have prevailed in the absence of a change in
that indicator.

As much of the micro-decomposition literature, approaches of this nature
traditionally suffer from path-dependence (See Essama-Nssah (2012),
Fortin et al (2011) and Ferreira (2010) for recent reviews of the
literature), in other words, the order in which the cumulative effects
are calculated matters . One of the major contributions of Azevedo,
Sanfelicce and Minh (2012) is the implementation of the best known remedy
for path-dependence which is to calculate the decomposition across all
possible paths and then take the average between them. These averages are
also known as the Shapley-Shorrocks estimates of each component, implying
that we estimate every possible path to decompose these components and
then take the average of these estimates (See Shapley (1953) and
Shorrocks (1999)).

There is one remaining caveat to this approach: the counterfactual income
distributions on which these decompositions suffer from
equilibrium-inconsistency. Since we are modifying only one element at a
time, the counterfactuals are not the result of an economic equilibrium,
but rather a statistical exercise in which we assume that we can in fact
modify one factor at a time and keep everything else constant.

For further examples of implementations of this approach please see
Azevedo, Inchausete and Sanfelice (2012).

Thanks for citing adecomp as follows

Azevedo, Joao Pedro, Viviane Sanfelice and Minh Cong Nguyen (2012)
Shapley Decomposition by Components of a Welfare Measure. World Bank.
(mimeo)

Where

welfarevar is the welfare aggregate variable.

components are the components used to construct the welfare variable, and
which will be for the decomposition.

by is the comparison indicator. It must take two categorical values and
is usually defines two points in time or two geographic locations, which
the difference of the indicator of choice is being decomposed.

equation() captures the relationship between welfarevar and components.
The component variables in varlist must be denoted by c#, and must be
separated by an arithmetic operator.

Options

indicator(string) poverty and inequality indicators. fgt0, fgt1, fgt2,
gini and theil are the currently supported options.

varpl(varname) poverty line variable. It must be specified when fgt0,
fgt1 and/or fgt2 indicators are used.

mpl(numlist) allow to calculate the poverty indicators by multiple of the
poverty line. It can be specified when fgt0, fgt1 and/or fgt2 indicators
are used.

gic(#) use as indicator the percentual change on the average of
welfarevar in which one of its # percentile, i.e., decomposing the Growth
Incidence Curve of welfarevar. You need to specify a number of bins

group(varname) the indicators are calculated by each group of groupvar.
Differ from the if option because do not restrict the database. Groupvar
must be a numeric and discrete variable.

id(varname) to specify the identificator variable in case of balanced
panel data. The observed value of the unit of analysis is going to be
used when changing the distribution.

strata(varlist) allow the transposition of distributions be made within
groups created using the variables listed in varlist.

rank(string) specific the rank of which variable must be used when
changing the distribution.  It can be a varname or typing components the
rank of each component is going to be used. Default is welfarevar rank.

percentile(#) used # percentile of componentvar to change the
distribution. Default is to rescale the dataset in each period.

oneway decomposition is made only one way from period 0 to period 1.
Default is both ways.

std Returns the standard deviation of the effect, besides the average.

Saved Results

adecomp returns results in r() format.
By typing return list, the following results are reported:

Scalars
r(path)             number of paths of the shapley decomposition
r(component)        number of components of the decomposition
r(N)                number of observations utilized on the calculation

Matrices
r(b)                average effect of each components based on all
paths.
r(sd)               standard deviation of the effects based on all
paths. If option std is specify.
r(gic)              average effect of each components based on all
paths when the indicators are the changes on
welfarevar() by bin.
r(sd_gic)           standard deviation of each components based on all
paths when the indicators are the changes on
welfarevar() by bin. If option std is specify.

Obs: On the reported matrices
Index label: 0 - FGT(0); 1 - FGT(1); 2 - FGT(2); 3 - Gini; 4 - Theil.
Effect label: 1 represents the first component listed on the command, and
so on. Total of components plus 1 represents the total change on the
indicator and plus 2 denotes the residual, when this option is specified.

Important: To guarantee precision, we recommend to use double when create
variables.

Examples

. adecomp percapitainc laborinc nonlaborinc, by(year) equation(c1+c2)
indicator(fgt0 fgt1 fgt2 gini theil) varpl(pline)

. adecomp percapitainc laborinc nonlaborinc, by(year) equation(c1+c2)
in(fgt0) varpl(pline) gic(100)

. adecomp percapitainc laborinc nonlaborinc, by(year) equation(c1+c2)
indicator(fgt0) varpl(pline) mpl(1 3.5)

. adecomp percapitainc laborinc nonlaborinc, by(year) equation(c1+c2)
indicator(fgt0 fgt1 fgt2 gini theil) varpl(pline) gic(100)
strata(urban)

. adecomp percapitainc laborinc nonlaborinc, by(year) equation(c1+c2)
indicator(fgt0 fgt1 fgt2 gini theil) varpl(pline) gic(100)
id(hh_id)

. adecomp percapitainc laborinc nonlaborinc [w=weight], by(year)
equation(c1+c2) indicator(fgt0 fgt1 fgt2) varpl(pline)
group(region)

. adecomp percapitainc laborinc nonlaborinc if (region == 1), by(year)
equation(c1+c2) indicator(gini)

transferinc othersinc, by(year) equation(c1*(c2+c3+c4+c5+c6))
indicator(fgt0) varpl(pline)

(click to run the example below)

. adecomp ipcf_ppp ila_ppp itran_ppp ijubi_ppp icap_ppp others ///
. [w=pondera], by(ano) eq(c1+c2+c3+c4+c5)  ///
. varpl(lp_2usd_ppp) in(fgt0 fgt1 fgt2 gini theil)

. mat result = r(b)
. mat colnames  result = indicator effect rate
. drop _all
. svmat double result, n(col)
. label define indicator 0 "FGT0" 1 "FGT1" 2 "FGT2" 3 "Gini" 4 "Theil"
. label values indicator indicator
. label define effect ///
1 "Labor" ///
2 "Transfer" ///
3 "Pension" ///
4 "Capital" ///
5 "Others" ///
6 "Total change"
. label values effect effect
. local total 6
. gen aux=rate if  effect==`total'
. egen total_effect=sum(aux) , by(indicator)
. drop aux
. gen share_effect= -100*rate/abs(total_effect)

. keep if effect!=6
. graph bar share_effect , over(effect, label(labsize(*0.6))) ///
by(indicator)   blabel(bar, format(%16.1fc) size(*.98)) ///
ytitle(Share of the component effect in the total change)

References

Azevedo, Joao Pedro, Gabriela Inchauste, and Viviane Sanfelice.
Forthcoming. Decomposing the Recent Inequality Decline in Latin America.
World Bank (mimeo).

Azevedo, Joao Pedro, Gabriela Inchauste, Sergio Olivieri, Jaime Saavedra,
and Hernan Winkler. Forthcoming. “Is Labor Income Responsible for Poverty
Reduction? A Decomposition Approach.” World Bank Policy Research Working
Paper.

Azevedo, Joao Pedro, Viviane Sanfelice and Minh Cong Nguyen (2012)
Shapley Decomposition by Components of a Welfare Measure. World Bank.
(mimeo)

Barros, Ricardo Paes de. Carvalho, Mirela de. Franco, Samuel. Mendoça,
Rosane (2006). "Uma Análise das Principais Causas da Queda Recente na
Desigualdade de Renda Brasileira." In: Revista Econômica. Volume 8,
número 1, p.117-147. Universidade Federal Fluminense. Rio de Janeiro.

Essama-Nssah, B. (2012). "Identification of Sources of Variation in
Poverty Outcomes", World Bank Policy Research Working Papers, No. 5954.

Ferreira Francisco H.G. (2010) "Distributions in Motion: Economic Growth,
Inequality and Poverty Dynamics".  World Bank Policy Research Working
Paper No. 5424.  The World Bank, Washington, D.C.

Fortin Nicole, Lemieux Thomas and Firpo Sergio. (2011). "Decomposition
Methods in Economics".  In: Ashenfelter Orley and Card David (eds)
Handbook of Labor Economics, Vol. 4A , pp. 1-102. Northolland,
Amsterdam..

Inchauste, Gabriela , João Pedro Azevedo, Sergio Olivieri, Jaime
Saavedra, and Hernan Winkler (2012) When Job Earnings Are behind Poverty
Reduction. Economic Premise, November 2012, Number 97. World Bank:

Shapley, L. (1953). "A value for n-person games", in: H. W. Kuhn and A.
W. Tucker (eds.), Contributions to the Theory of Games, Vol. 2
(Princeton, N.J.: Princeton University Press).

Shorrocks, Anthony (2012) Decomposition procedures for distributional
analysis: a unified framework based on the Shapley value. Journal of

World Bank (2012) The Effect Of Women'S Economic Power: in Latin America
and the Caribbean. LAC Poverty and Labor Brief. World Bank: Washington

Authors

Joao Pedro Azevedo, jazevedo@worldbank.org

Minh Cong Nguyen, mnguyen3@worldbank.org

Viviane Sanfelice, vsanfelice@worldbank.org

Acknowledgements

The authors would like to thank Gabriela Inchauste, Samuel Freije, Andres
Castaneda and Gabriel Facchini for their valuable suggestions. The code
from Samuel Franco and Sergio Oliveri were used for inspiration in a few
passages of this ado and should be greatfully acknowledged.

All errors and ommissions are of exclusive responsability of the authors.

This program was developed by the  LAC Team for Statistical Development
(2012), in the Latin American and Caribbean Poverty Reduction and
Economic Managment Group of the World Bank.

Also see

Online:  help for apoverty; ainequal; wbopendata; mpovline; drdecomp;
skdecomp (if installed)

```