help hoishapley Alejandro Hoyos

hoishapley - Shapley Decomposition of the Human Opportunity Index

hoishapley
depvar
[if]
[in]
[weight]
[,
shapley(varlist of circumstances or globals)
globals
shapleyc(list of categorical circumstances)
eliminate
fix
filehoi(filename)
format(xls or dta)
fileshapley(filename)
adjust1([var[= #] ...])
controls(varlist)
simulated]

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

Description

hoishapley computes the Shapley decomposition of the Human Opportunity Index (HOI), it includes the estimation of the basic statistics like Coverage
of Basic Opportunities (C), the Dissimilarity Index (D), and the Human Opportunity Index (HOI). The decomposition allows the identification of the marginal/average contribution
of each circumstance to inequality in access to opportunities.

Options

shapley(varlist of circumstances or globals) computes the Shapley decomposition of the HOI using the list of circumstances included in varlist of circumstances or globals. If the option globals is specified then varlist of globals must contain a list of globals previously defined which aggregate circumstances into broader categories.

globals indicates that the list included in shapley(varlist of circumstances or globals) is a list of globals previously defined by the user.

shapleyc(list of categorical circumstances) is used to add to the list of circumstances defined in shapley( ) categorical variables such as region or ethnicity. For each categorical circumstance listed, a set of dummy variables for each category is created and by default the first category is omitted. This option should not be used with globals.

eliminate indicates that in each iteration of the Shapley decomposition procedure a new logit model is estimated using the circumstances included in the set of the specific iteration. This alternative provides the marginal contribution to the inequality index of adding a circumstance. The default.

fix is an alternative to eliminate. It indicates that in each iteration of the Shapley decomposition procedure, the full logit model specification is used adjusting to the mean the circumstances not included in the set of the specific iteration. This alternative provides the average contribution to the inequality index of adding a circumstance.

filehoi(filename) allows to save the basic statistics of the HOI and the contribution of each circumstance in an Excel or Stata file. The format is defined by the option format. Please only include a filename without extension.

format(xls or dta) specified the format of the file filehoi. The default format is Excel.

fileshapley(filename) allows to save the results of running all the iterations of the Shapley decomposition in a Stata dataset. Please only include a filename without extension.

adjust1([var[= #] ...]) provides the specifications of the first adjusted predictions. The estimate is computed for each variables, setting the variables specified in [var[= #] ...] to their mean or to the specified number if the = # part is specified.
Variables used for the estimation but not included in adjust variable list are left at their current values, observation by observation.

controls(list of variables) the list of controls are used in the estimation of the logit model in each of the iterations but are not considered as sources of inequality. The controls are kept constant at the mean.

simulated allows to create hypothetical individuals with the characteristics defined in the adjust1 option. This option does not force the coverage rate to be equal to the proportion of the sample with access to the opportunity. This option does not work with the fix option.

Output

Human Opportunity Index (HOI) Human Opportunity Index

D-Index (D) Dissimilarity Index

Penalty Difference between the coverage and the HOI

Coverage (C) Coverage of Basic Opportunities

Contributions share of the D-Index that is explained for each one of the circumstances. All the contributions add up to 100

Examples

Suppose you have a dataset with electricity {0-no access, 1-access}, male {0-female, 1-male}, male_head {0-female head, 1-male head}, eduyears_head {0,1,2,...,15}, siblings {0,1,2...,10}, log_income [0...1000], region , location , age {6,7,...,16}, year {2001, 2005, 2010}.

The following command will produce the HOI for electricity using male, male_head, eduyears_head, sibligns, and log_income as circumstances for children 6 to 16 in 2001 using the elimination method (the default).

. hoishapley electricity [fw=sweight] if year==2001, shapley(male male_head eduyears_head sibligns log_income)

The following command will produce the HOI for electricity using male, male_head, eduyears_head, sibligns, log_income, region, and location as circumstances for children 10 to 14 in 2001 using the fix method.

. hoishapley electricity [fw=sweight] if (age>=10 & age<=14) & year == 2001, shapley(male male_head eduyears_head sibligns log_income) shapleyc(region location) fix

Alternatively, the previous result can be obtained by:

. tab region, gen(reg_)

. tab location, gen(loc_)

. hoishapley electricity [fw=sweight] if (age>=10 & age<=14) & year == 2001, shapley(male male_head eduyears_head sibligns log_income reg_2 reg_3 reg_4 reg_5 loc_2) fix

The following commands will produce the HOI for electricity using four dimensions: gender (male), parents (male_head, eduyears_head), family (sibligns, log_income), and geographic (region, location) for children 6 to 16 in 2001 using the elimination method (the default).

. global gender = "male"

. global parents = "male_head eduyears_head"

. global family = "sibligns log_income"

. global geographic = "reg_2 reg_3 reg_4 reg_5 loc_2"

. hoishapley electricity [fw=sweight] year == 2001, shapley(gender parents family geographic) globals

The following command will produce the HOI for electricity using male, male_head, eduyears_head, sibligns, and log_income for children 10 years old in 2001 using the elimination method (the default). But using the sample of children 6 to 16 years. The output will be saved in a Stata file called hoi_shapley_elec.dta

. hoishapley electricity [fw=sweight] if year==2001, shapley(male male_head eduyears_head sibligns log_income) adjust1(edad=10) controls(edad) hoishapley(hoi_shapley_elec) format(dta) simulated

Saved Results

hoishapley return results in r() format. Type return list after estimation.

Thanks for citing hoishapley as follows

A. Hoyos, 2013.
"HOISHAPLEY: Stata module to decompose the Human Opportunity Index," Statistical Software Components, Boston College Department of Economics.

References

Alejandro Hoyos and Ambar Narayan, 2011. "Inequality of opportunities among children: how much does gender matter?" Background paper for the World Development Report 2012.
http://siteresources.worldbank.org/INTPOVERTY/Resources/Role_of_Gender_WDR_bground_June_27,_2011.pdf

Jose Molinas Vega, Ricardo Paes de Barros, Jaime Saavedra Chanduvi, et all, 2010. "Do Our Children Have a Chance? The 2010 Human Opportunity Report for Latin
America and the Caribbean - Conference Edition", World Bank: Washington, DC.
http://www.worldbank.org/lacopportunity/

Ricardo Paes de Barros, Francisco H.G. Ferreira, Jose Molinas Vega, Jaime Saavedra Chanduvi, et all, 2008. "Measuring Inequality
of Opportunities in Latin America and the Caribbean", World Bank: Washington, DC.
http://siteresources.worldbank.org/LACEXT/Resources/258553-1222276310889/Book_HOI.pdf

Anthony F. Shorrocks, 2013. "Decomposition procedures for distributional analysis: a unified framework based on the Shapley value" The Journal of Economic Inequality
March 2013, Volume 11, Issue 1, pp 99-126.

Acknowledgements

Numerous people have provided feedback and advice and the author is very grateful for their comments. In
particular I would like to thank: Ambar Narayan, Jose R. Molinas Vega, Jaime Saavedra, Ricardo Paes de Barros, Javier Escobal, Carlos Rondon, Sailesh Tiwari,
Shabana Mitra, Gabriel Facchini, João Pedro Azevedo, Oscar Eduardo Barriga, Carlos Eduardo Velez, Ana Luisa Gouvea Abras. The usual disclaimer
applies.

Authors

Alejandro Hoyos
ahoyossuarez@worldbank.org

Remark

Please note that hoishapley uses the user written packages catenate on its calculations.
User's can download it from ssc.