{smcl}
{* 12September2015}{...}
{hline}
help for {hi:svylorenz}{right:Stephen P. Jenkins (September 2015)}
{hline}


{title:Quantile group shares, cumulative shares (Lorenz ordinates), generalized Lorenz ordinates, and Gini coefficient}

{p 8 15 2}
{cmd:svylorenz} {it:varname}  [{cmd:if} {it:exp}]
 [{cmd:in} {it:range}] [{cmd:,} {cmdab:n:gp:(}{it:#}{cmd:)}
 {cmdab:qgp:(}{it:newvarname}{cmd:)}  {cmdab:sub:pop:(}{it:varname}{cmd:)}
 {cmdab:pv:ar:(}{it:newvarname}{cmd:)} {cmdab:lv:ar:(}{it:newvarname}{cmd:)}
 {cmdab:selv:ar:(}{it:newvarname}{cmd:)} {cmdab:glv:ar:(}{it:newvarname}{cmd:)}
 {cmdab:seglv:ar:(}{it:newvarname}{cmd:)} {cmdab:l:evel:(}{it:#}{cmd:)}   ]

{p 4 4 2}
Data must be {cmd:svyset} before using this command; see {help svyset}.


{title:Description}

{p 4 4 2}{cmd:svylorenz} computes distribution-free variance estimates
for quantile group shares of total {it:varname}, cumulative quantile 
group shares (cumulation is in ascending order of {it:varname}),
generalized Lorenz ordinates, and the Gini coefficient. The Lorenz curve, 
{it:L}({it:p}), is the graph of cumulative quantile group shares at each cumulative
population share {it:p} = {it:F}({it:varname}). The generalized Lorenz curve 
{it:GL}({it:p}) is the Lorenz curve scaled up at each {it:p} by mean {it:varname}. 
The Gini coefficient, {it:G}, is twice the area between the Lorenz curve 
and the line of perfect inequality, and ranges between 0 and 1. Higher values 
indicate greater inequality. Note that the Gini coefficient is calculated 
using all valid observations; it is {it:not} derived by approximation 
from the income shares.

{p 4 4 2}Beach and Davidson (1983) provide formulae for variance estimation
of shares, cumulative shares and generalized Lorenz ordinates, but for 
unweighted data with no complex survey design features. Beach and Kaliski (1986) 
extend these results to the case with sample weights that are fixed
and non-stochastic. Kovacevic and Binder (1997), using the estimating equations
approach, provide formulae for variance estimation of cumulative shares
allowing for probability weights and for complex survey design more generally. 
They also provide formulae for variance estimation of {it:G}. All these linearization 
methods rely on asymptotic approximations, and small sample properties are not well-known.

{p 4 4 2}{cmd:svylorenz} derives variance estimates using the methods of 
Kovacevic and Binder (1997) for cumulative shares and {it:G}, and derives
estimates for quantile group shares from those for cumulative shares using
a result of Beach and Kaliski (1986). Variance estimates for generalized Lorenz 
ordinates are derived by an application of the estimating equations approach of Binder and 
Kovacevic (1995) and Kovacevic and Binder (1997). For an alternative derivation,
see Zheng (2002).

{p 4 4 2}The point estimates computed by {cmd:svylorenz} are the same as the 
estimates that can be calculated using {cmd:sumdist}, {cmd:ineqdeco} and {cmd:ineqdec0}. 
By default, however, {cmd:svylorenz} uses observations with non-negative values of {it:varname}, 
{cmd:ineqdeco} uses observations with strictly positive values of {it:varname}, and 
{cmd:ineqdec0} and {cmd:sumdist} use observations with negative, zero, or positive values of {it:varname}.
Estimates of shares and their standard errors can also be derived using Ben Jann's program {cmd:pshare}, and 
{cmd:svylorenz} and {cmd:pshare} yield the same results. Each program has additional features not included in
the other.


{title:Options}

{p 4 8 2}{cmd:ngp(}{it:#}{cmd:)} specifies the number of quantile groups,
and must be an integer between 1 and 100. The default is 10.

{p 4 8 2}{cmd:qgp(}{it:newvarname}{cmd:)} creates a new variable in the 
current data set that identifies the quantile group membership of each 
observation.

{p 4 8 2}{cmd:subpop(}{it:varname}{cmd:)} specifies that estimates be 
computed for the single subpopulation defined by the observations for 
which {it:varname}!=0.  Typically, {it:varname}=1 defines the subpopulation and 
{it:varname}=0 indicates observations not belonging to the subpopulation.  
For observations whose subpopulation status is uncertain, {it:varname} should 
be set to missing.

{p 4 8 2}{cmd:level(}{it:#}{cmd:)} specifies the confidence level, as a 
percentage, for confidence intervals.  The default is level(95) or as 
set by {help set level}; see [U] 20.6 Specifying the width of confidence 
intervals.

{p 4 8 2}The following options may be used to graph Lorenz curves and 
generalized Lorenz curves (see also {cmd:glcurve} which is a more 
general program for this task):

{p 4 8 2}{cmd:pvar(}{it:newvarname}{cmd:)} creates a new variable in the 
current data set containing the values of {it:p_j} = {it:F}({it:x_j}) corresponding
to each {it:j} for each quantile group {it:j} = 1,...,{it:J}, plus 0. 

{p 4 8 2}{cmd:lvar(}{it:newvarname}{cmd:)} creates a new variable in the 
current data set containing the cumulative shares {it:L}({it:p_j}), 
plus {it:L}(0) = 0.

{p 4 8 2}{cmd:selvar(}{it:newvarname}{cmd:)} creates a new variable in the 
current data set containing the estimated standard errors of the cumulative 
shares. 

{p 4 8 2}{cmd:glvar(}{it:newvarname}{cmd:)} creates a new variable in the 
current data set containing the generalized Lorenz ordinates {it:GL}({it:p_j}), 
plus {it:GL}(0) = 0.

{p 4 8 2}{cmd:seglvar(}{it:newvarname}{cmd:)} creates a new variable in the 
current data set containing the estimated standard errors of the generalized
Lorenz ordinates. 


{title:Examples}

{p 8 12 2}{inp:. svyset psu_name [pw = wgt], strata(strata_name)}

{p 8 12 2}{inp:. svylorenz income}

{p 8 12 2}{inp:. svylorenz cYbhcg, ngp(20) pvar(p) lvar(l) selvar(sel)}

{p 8 12 2}{inp:. twoway (connect p p) (connect l p, sort) }

{p 4 4 2}Further examples are provided in the downloadable materials accompanying the
presentation by {browse "http://econpapers.repec.org/paper/bocasug06/16.htm":Jenkins (2006)}.


{title:Saved Results}

{p 4 17 2}Scalars: {p_end}

{p 4 17 2}{cmd:e(gini)}{space 8}{it:G} {p_end}
{p 4 17 2}{cmd:e(se_gini)}{space 5}asymptotic SE of {it:G} {p_end}
{p 4 17 2}{cmd:e(mean)}{space 8}mean of {it:varname} {p_end}
{p 4 17 2}{cmd:e(se_mean)}{space 5}asymptotic SE of the mean {p_end}
{p 4 17 2}{cmd:e(total)}{space 7}total of {it:varname} {p_end}
{p 4 17 2}{cmd:e(ngps)}{space 8}number of quantile groups {p_end}
{p 4 17 2}{cmd:e(q{it:j})}{space 10}quantile {it:j}, where {it:j} = 1, ..., {it:ngps} {p_end}
{p 4 17 2}{cmd:e(sh{it:j})}{space 9}share of {it:varname} held by each quantile group {it:j} {p_end}
{p 4 17 2}{cmd:e(se_sh{it:j})}{space 6}asymptotic SE of each group {it:j}'s share of {it:varname} {p_end}
{p 4 17 2}{cmd:e(cush{it:j})}{space 7}cumulative share of {it:varname} held by each quantile group {it:j} {p_end}
{p 4 17 2}{cmd:e(se_cush{it:j})}{space 4}asymptotic SE of each group {it:j}'s cumulative share of {it:varname} {p_end}
{p 4 17 2}{cmd:e(gl{it:j})}{space 9}generalized Lorenz ordinate of {it:varname} held by each quantile group {it:j} {p_end}
{p 4 17 2}{cmd:e(se_gl{it:j})}{space 6}asymptotic SE of each group {it:j}'s generalized Lorenz ordinate of {it:varname} {p_end}

{p 4 17 2}Matrices: {p_end}

{p 4 17 2}{cmd:e(quantiles)}{space 3}1 x ({it:ngps}{c -}1) vector of quantiles {p_end}
{p 4 17 2}{cmd:e(shares)}{space 6}1 x ({it:ngps}) vector of quantile group shares {p_end}
{p 4 17 2}{cmd:e(V_cush)}{space 6}({it:ngps}{c -}1) x ({it:ngps}{c -}1) variance-covariance 
matrix of cumulative shares {p_end}
{p 4 17 2}{cmd:e(V_gl)}{space 8}({it:ngps}) x ({it:ngps}) variance-covariance 
matrix of generalized Lorenz ordinates {p_end}


{title:Acknowledgements}

{p 4 4 2}Philippe Van Kerm provided helpful comments on early drafts of this program. 
Ben Jann alerted me to a bug in the calculation of standard errors for shares and cumulative
shares (Lorenz ordinates) and showed me how to fix it. (The SEs in the previous version of the
program were too large, so inference was too conservative.)


{title:References}

{p 4 8 2}Beach, C.M. and R. Davidson. 1983. Distribution-free statistical inference with
Lorenz curves and income shares. {it:Review of Economic Studies} 50: 723{c -}725.

{p 4 8 2}Beach, C.M. and S.F. Kaliski. 1986. Lorenz curve inference with sample weights: 
an application to the distribution of unemployment experience. {it:Applied Statistics} 35(1): 38{c -}45.

{p 4 8 2}Binder, D.A. and M.S. Kovacevic. 1995. Estimating some measures of income inequality
from survey data: an application of the estimating equations approach. 
{it: Survey Methodology} 21: 137{c -}145.

{p 4 8 2}Jenkins, S.P. 2006. Estimation and interpretation of measures of inequality,
poverty, and social welfare using Stata. Presentation at North American
Stata Users' Group Meetings 2006, Boston MA.
{browse "http://econpapers.repec.org/paper/bocasug06/16.htm"}.

{p 4 8 2}Kovaevic, M.S. and D.A. Binder. 1997. Variance estimation for measures of 
income inequality and polarization. {it:Journal of Official Statistics} 13(1): 41{c -}58. Full text
downloadable from {browse "http://www.jos.nu/Articles/abstract.asp?article=13141"}.

{p 4 8 2}Zheng, B. 2002. Testing Lorenz curves with non-simple random samples. 
{it:Econometrica} 70: 1235{c -}1243.


{title:Author}

{p 4 4 2}
Stephen P. Jenkins, London School of Economics. Email: s.jenkins@lse.ac.uk


{title:Also see}

{p 4 13 2}
{help svy}, {help svyset}, {help xtile} 

{p 4 13 2}
{cmd:ineqdeco}, {cmd:ineqdec0}, {cmd:sumdist}, {cmd:svygei}, {cmd:svyatk}, {cmd:glcurve}, {cmd:pshare}, if installed.
