{smcl}
{* 18feb2001/27oct2004}{...}
{hline}
help for {hi:glcurve}{right: (SJ4-4: gr0001_1; SJ1-1: gr0001; STB-49: sg107_1; STB-48: sg107)}
{hline}

{title:Derivation of generalised Lorenz curve ordinates with unit record data}

{p 8 17 2}{cmd:glcurve}
{it:varname} 
[{it:weight}] 
[{cmd:if} {it:exp}] 
[{cmd:in} {it:range}] 
[{cmd:,}
{cmdab:p:var}{cmd:(}{it:newvarname}{cmd:)} 
{cmdab:gl:var}{cmd:(}{it:newvarname}{cmd:)} 
{cmdab:so:rtvar}{cmd:(}{it:varname}{cmd:)} 
{cmd:by}{cmd:(}{it:varname}{cmd:)} 
{cmdab:sp:lit}
{cmdab:nogr:aph}
{cmd:replace}
{cmdab:l:orenz}
{cmd:atip}{cmd:(}{it:string}{cmd:)} 
{cmd:rtip}{cmd:(}{it:string}{cmd:)} 
{cmd:plot}{cmd:(}{it:plot}{cmd:)}
{it:graph_options}  
]

{p 4 4 2}{cmd:aweight}s and {cmd:fweight}s are allowed; see help {help weights}.


{title:Description} 

{p 4 4 2}Given a variable {it:varname}, call it x with c.d.f. F(x),
{cmd:glcurve} draws its Generalised Lorenz curve and/or generates two new
variables containing the Generalised Lorenz ordinates for x, i.e.  GL(p) at
each p = F(x).  For a population ordered in ascending order of x, a graph of
GL(p) against p plots the cumulative total of x divided by population size
against cumulative population share GL(1) = mean(x). {cmd:glcurve} can also be
used to derive many other related concepts such as Lorenz curves, concentration
curves and 'Three Is of Poverty' (TIP) curves, with appropriate definition of
{it:varname}, order of cumulation (set with the {cmd:sortvar} option), and
normalisation (e.g. by the mean of {it:varname}). Alternatively {cmd:glcurve}
with the {cmd:lorenz}, {cmd:atip} or {cmd:rtip} option can be used directly to
draw the related Lorenz, concentration and TIP curves.   

{p 4 4 2}Comparisons of pairs of distributions (and dominance checks) can be
undertaken by using the {cmd:by()} (with or without the {cmd:split}) options.
It can also be made manually by 'stacking' the data (see help on {help stack}). 


{title:Options}

{p 4 8 2}{cmd:pvar(}{it:pvarname}{cmd:)} generates the variable {it:pvarname}
containing the x coordinates of the created curve.

{p 4 8 2}{cmd:glvar(}{it:glvarname}{cmd:)} generates the variable
{it:glvarname} containing the y coordinates of the created curve.

{p 4 8 2}{cmd:sortvar(}{it:sname}{cmd:)} specifies the sort variable.  By
default, the data are sorted (and cumulated) in ascending order of
{it:varname}. If the {cmd:sortvar} option is specified, sorting and cumulation
is in ascending order of variable {it:sname}.

{p 4 8 2}{cmd:by(}{it:groupvar}{cmd:)} specifies that the coordinates are to be
computed separately for each subgroup defined by {it:groupvar}. {it:groupvar}
must be an integer variable.

{p 4 8 2}{cmd:split} specifies that a series of new variables are created
containing the coordinates for each subgroup specified by
{cmd:by(}{it:groupvar}{cmd:)}. {cmd:split} can not be used without {cmd:by()}.
If {cmd:split} is specified, then the string {it:glname} in
{cmd:glvar(}{it:glname}{cmd:)} is used as a prefix to create new variables
{it:glname_X1}, {it:glname_X2},... (where X1, X2, ... are the values taken by
{it:groupvar}).

{p 4 8 2}{cmd:nograph} avoids the automatic display of a crude graph made out
of the created variables. {cmd:nograph} is assumed if {cmd:by()} is specified
without {cmd:split}.

{p 4 8 2}{cmd:replace} allows the variables specified in
{cmd:glvar(}{it:glvarname}{cmd:)} and {cmd:pvar(}{it:pvarname}{cmd:)} to be
overwritten if they already exist. Otherwise {it:glvarname} and
{it:pvarname} must be new variable names.    

{p 4 8 2}{cmd:lorenz} requires that the ordinates of the Lorenz curve are
computed instead of generalised Lorenz ordinates. The Lorenz ordinates of
variable x, L(p), are GL(p)/mean(x).

{p 4 8 2}{cmd:rtip(}{it:povline}{cmd:)} and {cmd:atip(}{it:povline}{cmd:)}
require that the ordinates of TIP curves are computed instead of generalised
Lorenz ordinates.  {it:povline} specifies the value of the poverty line: it can
be either a numeric value taken as the poverty line for all observations or a
variable name containing the value of the poverty line for each observation.
{cmd:atip()} draws 'absolute' TIP curves (by cumulating max(z-x,0)) and
{cmd:rtip()} draws 'relative' TIP curves (by cumulating max(1-(x/z),0)).    

{p 4 8 2}{cmd:plot(}{it:plot}{cmd:)} provides a way to add other plots to the
generated graph; see {help plot option}. 

{p 4 8 2}{it:graph_options} are standard {help twoway scatter} options.


{title:Examples}

{p 4 8 2}{cmd:. glcurve x, gl(gl1) p(p1) nograph}{p_end}
{p 4 8 2}{cmd:. line gl1 p1}

{p 4 8 2}{cmd:. glcurve x, lorenz plot(function equality = x)}

{p 4 8 2}{cmd:. glcurve x [fw=wgt] if x > 0, gl(gl2) p(p2) lorenz}

{p 4 8 2}{cmd:. glcurve x, gl(gl2) p(p2) replace sort(y) by(state) split}

{p 4 8 2}{cmd:. glcurve x, gl(gl3) p(p3) atip(10000)}

{p 4 8 2}{cmd:. glcurve x, gl(gl3) p(p3) atip(plinevar)}


{title:Acknowledgements} 

{p 4 4 2}Nicholas J. Cox helped with updating the code for our program from
Stata 7 ({help glcurve7}) to Stata 8.


{title:Authors}

{p 4 4 2}Philippe Van Kerm, CEPS/INSTEAD, Differdange, G.-D. Luxembourg{break}
philippe.vankerm@ceps.lu

{p 4 4 2}Stephen P. Jenkins, ISER, University of Essex{break}
stephenj@essex.ac.uk


{title:References}

{p 4 8 2}Cowell, F.A. 1995. {it:Measuring Inequality} (second edition).
Hemel Hempstead: Prentice-Hall/Harvester-Wheatsheaf.

{p 4 8 2}Jenkins, S.P. and Lambert, P.J. 1997. 
Three 'I's of poverty curves, with an analysis of UK poverty trends. 
{it:Oxford Economic Papers} 49: 317{c -}327.

{p 4 8 2}Lambert, P.J. 2001. 
{it:The Distribution and Redistribution of Income}
(third edition). Manchester: Manchester University Press.

{p 4 8 2}Shorrocks, A.F. 1983. Ranking income distributions.  
{it:Economica} 197: 3{c -}17.


{title:Also see}

{p 4 13 2} Manual:  {hi:[R] lorenz}{p_end}
{p 4 13 2}    STB:  {hi:STB-48 sg107}, {hi:STB-49 sg107.1}, {hi:SJ 1(1) gr0001}{p_end}
{p 4 13 2}On-line:  help for {help sumdist} (if installed)