{smcl} {* March 2017}{...} {hline} help for {hi:welflossas (Version 1.0)}{right:Alicia Pérez-Alonso (March 2017)} {hline} {title:Well-being (monetary) gain/loss measures and social welfare loss indices and curves associated with segregation using either disaggregated or aggregated data for the quantitative variable.} {p 4 4 2} Disaggregated data: {it:quantvar} contains individual observations {p 8 17 2} {cmd:welflossas} {it:{help varname:unitvar}} {it:{help varname:groupvar}} {it:{help varname:quantvar}} {ifin} [{it:{help weight}}] [,{cmdab:st:ats:(}{it:statname}{cmd:)} {cmdab:thr:incl:(}{it:#}{cmd:)} {cmdab:nog:raph} {cmdab:f:ormat:(}{it:%{help format:fmt}}{cmd:)}] {p 4 4 2} Aggregated data I: all individuals belonging to the same unit have the same value in {it:quantvar} {p 8 17 2} {cmd:welflossas} {it:{help varname:unitvar}} {it:{help varname:groupvar}} {it:{help varname:quantvar}} {ifin} [{it:{help weight}}] [,{cmdab:ag:gregate:} {cmdab:thr:incl:(}{it:#}{cmd:)} {cmdab:nog:raph} {cmdab:f:ormat:(}{it:%{help format:fmt}}{cmd:)}] {p 4 4 2} Aggregated data II: a variable that contains an aggregated value for each unit is added from a second dataset to existing individual observations from the dataset currently in memory {p_end} {p 8 17 2} {cmd:welflossas} {it:{help varname:unitvar}} {it:{help varname:groupvar}} {ifin} [{it:{help weight}}] [,{cmdab:ag:gregate:} {cmdab:adds:tatus} {cmdab:callf:ile:(}{it:{help filename:filename1}}{cmd:)} {cmdab:callv:ar:(}{it:{help varname:quantvar}}{cmd:)} {cmdab:sav:ing:(}{it:{help filename:filename2}}{cmd:)} {cmdab:thr:incl:(}{it:#}{cmd:)} {cmdab:nog:raph} {cmdab:f:ormat:(}{it:%{help format:fmt}}{cmd:)}] {p_end} {p 4 4 2} {cmdab:st:ats()} is available only for disaggregated data. {pstd} {cmdab:adds:tatus} is available only for aggregated data. {pstd} {cmd:fweight}s, {cmd:aweight}s and {cmd:iweight}s are allowed. {cmd:iweight}s are not allowed by {cmdab:st:ats(}{it:median}{cmd:)}. See {help weight}. {pstd} {it:unitvar}, {it:groupvar}, and {it:quantvar} must be numeric. Zero-values of {it:quantvar} are automatically changed to missing values by the program. In case all observations of {it:quantvar} are missing for a specific value of {it:unitvar}, the program automatically excludes that value from the analysis. {p_end} {title:Description} {pstd} {cmd:welflossas} computes a family of indices measuring the well-being (monetary) gain/loss of a group associated with its segregation as proposed by Del Río and Alonso-Villar (2015) and Alonso-Villar and Del Río (2016). {cmd:welflossas} also computes the FGT indices and produces the Social Welfare Loss curves as proposed by Del Río and Alonso-Villar (2017). {p_end} {pstd} Microdata (individual observations) are required. {p_end} {p 8 12 2} {it:unitvar} is a categorical variable identifying organizational units (e.g. occupations, census tracts, schools,...). {p_end} {phang2} {it:groupvar} is a categorical variable identifying demographic groups (e.g. gender, race, gender x race,...). {p_end} {phang2} {it:quantvar} is a quantitative variable (e.g. wage, status,...). Values of {it:quantvar} are either disaggregated or aggregated by unit (e.g. status by occupation). Use the {cmdab:ag:gregate} option for aggregated values. If these data come from an external source, specify also {cmdab:adds:tatus} and its associated options. {p_end} {pstd} If the {cmdab:nog:raph} option is omitted, the default is to draw the Social Welfare Loss curves and the decomposition of the per capita earning gap ratio (displayed only for disaggregated data). {p_end} {title:Options} {p 4 8 2} {cmdab:ag:gregate} uses aggregated values by unit for {it:quantvar} at individual level, the default is to use disaggregated data. {phang} {cmdab:adds:tatus} performs a many-to-one merge on key variable {it:unitvar}; see {manhelp merge D}. {phang2} {cmdab:callf:ile:(}{it:{help filename:filename1}}{cmd:)} is for use with {cmdab:adds:tatus}; it specifies a valid {it:filename1} that contains the using dataset. {phang2} {cmdab:callv:ar:(}{it:{help varname:quantvar}}{cmd:)} is for use with {cmdab:adds:tatus}; it specifies the name of {it:quantvar} in the using dataset. {phang2} {cmdab:sav:ing:(}{it:{help filename:filename2}}{cmd:)} is for (optional) use with {cmdab:adds:tatus}; it stores the dataset currently in memory on disk under the name {it:filename2}{cmd:.dta}. {phang} {cmdab:st:ats:(}{it:statname}{cmd:)} specifies the statistic used to compute aggregated values of {it:quantvar} at unit level and within-unit for groups. Available statistics are {it:mean} and {it:median}. The default is equivalent to specifying {cmdab:st:ats(}{it:mean}{cmd:)}. {cmdab:st:ats()} requires disaggregated data because {it:mean} and {it:median} would produce the same output with aggregated data by unit (values of {it:quantvar} do not vary in within-unit for different groups). If all values of {it:quantvar} are missing for a certain group within a unit, the value of the statistic for the whole unit is automatically imputed.{p_end} {phang} {cmdab:thr:incl:(}{it:#}{cmd:)} specifies a threshold z>=0 which determines the level of losses that would be considered when computing FGT indices and producing Social Welfare Loss curves using Psi_{0} index. {cmdab:thr:incl(}{it:real 0}{cmd:)} is the default. {phang} {cmdab:nog:raph} suppresses display of default graphs. {phang} {cmdab:f:ormat:(}{it:%{help format:fmt}}{cmd:)} changes numeric format, the default is {cmdab:f:ormat(}{it:%9.4f}{cmd:).} {title:Reporting} {pstd} Notation: epsilon={c -(}0,1,2,3,4{c )-} is the constant elasticity of the assumed utility function that can be interpreted as a (relative) inequality aversion parameter in Psi_{epsilon} indices. alpha={c -(}0,1,2,3{c )-} is an inequality aversion parameter in FGT indices. See references below for some further notation and formulae.{p_end} {pstd} {ul:Measures of well-being (monetary) gain/loss associated with segregation:} {p 8 12 2} {c -} Psi_{c -(}epsilon{c )-}, family of indices to quantify the well-being gain/loss of a group associated with its segregation. {p 12 12 2} Note that Gamma=Psi_{c -(}0{c )-} measures the monetary gain/loss of a group associated with its segregation. {pstd}Available only for disaggregated data: {phang2} {c -} Omega_{c -(}epsilon{c )-}, the well-being gain/loss of a group due to within-unit status disparities with respect to other groups. {pmore2} Note that Delta=Omega_{c -(}0{c )-} measures the monetary gain/loss of the group associated with within-unit status disparities with respect to other groups. {phang2} {c -} WAD_{c -(}epsilon{c )-}, total well-being advantage/disadvantage (WAD) of a group: Psi_{c -(}epsilon{c )-} + Omega_{c -(}epsilon{c )-}. {phang2} {c -} seg-EGap, contribution of segregation to the per capita earning gap ratio (EGap=WAD_{c -(}0{c )-}) of the group: Psi_{c -(}0{c )-}/WAD_{c -(}0{c )-}. {phang2} If option {cmdab:nog:raph} is not specified: {phang2} {c -} Decomposition of the per capita earning gap ratio (EGap) in terms of segregation (Gamma) and within-unit status disparities (Delta). The graph currently displayed is saved to disk under the name {it:grEGap}{cmd:.gph}. {pstd} {ul:Measures of social welfare loss associated with segregation:} {phang2} {c -} FGT_{c -(}alpha{c )-}, the Foster-Greer-Thorbecke (FGT) family of poverty indices adapted to measure the social welfare loss that the society experiences due to segregation. {pmore2} Note that FGT_{c -(}0{c )-} is the headcount ratio, fraction of the population that belongs to groups that have well-being (monetary) losses associated with segregation. {phang2} If option {cmdab:nog:raph} is not specified: {phang2} {c -} WLAS_{c -(}epsilon{c )-}, Social Welfare Loss curves associated with segregation. The graph currently displayed is saved to disk under the name {it:grWLAS}{cmd:.gph}. {pstd} Each group's relative population share is also reported. {title:Saved results} {pstd} {cmd:welflossas} stores the following matrices in {cmd:r()}: {phang2} {cmd:r(measures)} : Measures of well-being (monetary) gain/loss associated with segregation {phang2} {cmd:r(xywlas)} : Coordinates of points on the WLAS curves {phang2} {cmd:r(FGT)} : FGT indices {phang2} {cmd:r(share)} : Population shares by group {title:Limits} {pstd} This program makes use of {cmd:tabulate} to produce a two-way table of frequency counts for the variables {it:unitvar} (rows) and {it:groupvar} (columns). The maximum dimension allowed for {it:unitvar} or {it:groupvar} is the maximum row or column dimension for {cmd:tabulate} (see {help limits}). {p_end} {title:Examples} {pstd} {ul:Disaggregated data:} {phang} . {stata use wlasdata.dta, clear } {phang} . {stata welflossas occ1990 raceh hw [aw=perwt]} {phang} . {stata ret list} {phang} . {stata mat list r(xywlas)} {phang} . {stata welflossas occ1990 raceh hw [aw=perwt], st(median) thr(15) nog} {pstd} {ul:Aggregated data I:} {phang} . {stata use wlasdata.dta, clear } {pstd}Create a new variable (mhw) containing the weighted mean wage for each distinct occupation {phang} . {stata gen mhw=. } {phang} . {stata "qui levelsof occ1990, local(levels)" } {cmd:. qui foreach l of local levels {c -(}} {cmd: summarize hw [aw=perwt] if occ1990 == `l', meanonly } {cmd: replace mhw = r(mean) if occ1990 == `l'} {cmd: {c )-}} {phang} . {stata welflossas occ1990 raceh mhw [aw=perwt], ag} {pstd} {ul:Aggregated data II:} {phang} . {stata use wlasdata.dta, clear } {phang} . {stata welflossas occ1990 raceh [aw=perwt], ag adds callf(wlas2data) callv(mhw) sav(wlas3data) nog} {title:Author} {pstd}{browse "https://sites.google.com/site/aliciaperezalonso/": Alicia Pérez-Alonso} {break} Facultad de Estudios Estadísticos{break} Universidad Complutense de Madrid{break} Avda. Puerta de Hierro s/n, 28040 Madrid, Spain. {title:References} {phang} Del Río, C. and Alonso-Villar, O. (2017), Segregation and Social Welfare: A Methodological Proposal with an Application to the U.S., Social Indicators Research, forthcoming. DOI: 10.1007/s11205-017-1598-0 {phang} Alonso-Villar, O. and Del Río, C. (2016), {browse "http://onlinelibrary.wiley.com/doi/10.1111/roiw.12224/abstract": Local segregation and well-being}, The Review of Income and Wealth. DOI: 10.1111/roiw.12224 {phang} Del Río, C. and Alonso-Villar, O. (2015), {browse "http://link.springer.com/article/10.1007/s13524-015-0390-5?wt_mc=email.event.1.SEM.ArticleAuthorAssignedToIssue": The Evolution of Occupational Seggregation in the United States, 1940-2010: Gains and Losses of Gender-Race/Ethnicity Groups}, Demography, vol. 52(3), pp. 967-988. DOI:10.1007/s13524-015-0390-5 {title:Also see} {p 4 13 2} {help localseg} if installed; {help dicseg} if installed