-------------------------------------------------------------------------------
help for glcurve7                                               (TSJ-1: gr0001)
-------------------------------------------------------------------------------

Derivation of generalised Lorenz curve ordinates with unit record data
[An update of glcurve for Stata 7]

        glcurve7 varname [weight] [if exp] [in range] [, pvar(newvarname)
               glvar(newvarname) sortvar(varname) by(varname) split nograph
               replace lorenz atip(string) rtip(string) graph_options ]

aweights and fweights are allowed; see help weights.


Description

Important notice: As of Oct. 2004, ^glcurve7^ is an outdated release of
^glcurve^ (available for Stata 7 users). The up-to-date release is available
for Stata 8 users as ^glcurve^ (available on the SSC archive and on the Stata
Journal website).

Given a variable varname, call it x with c.d.f. F(x), glcurve7 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). glcurve7 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 varname, order of
cumulation (set with the sortvar option), and normalisation (e.g. by the mean
of varname). Alternatively glcurve7 with the lorenz, atip or rtip option can be
used directly to draw the related Lorenz, concentration and TIP curves.

Comparisons of pairs of distributions (and dominance checks) can be undertaken
by using the by() (with or without the split) options. It can also be made
manually by 'stacking' the data (see stack).

Options

pvar(pvarname) generates the variable pvarname containing the x-ordinates of
    the created curve.

glvar(glvarname) generates the variable glvarname containing the y-ordinates of
    the created curve.

sortvar(sname) specifies the sort variable.  By default, the data are sorted
    (and cumulated) in ascending order of varname. If the sortvar option is
    specified, sorting and cumulation is in ascending order of variable sname.

by(groupvar) specifies that the ordinates are to be computed separately for
    each subgroups defined by groupvar. groupvar must be numeric.

split specifies that *a series of new variables* are created containing the
    ordinates for each subgroup specified by by(groupvar) split can not be used
    without by(). If split is specified, then the string glname in
    glvar(glname) (truncated after 4 characters) is used as a prefix to create
    new variables glname_X1, glname_X2,... (where X1, X2, ... are the values
    taken by groupvar).

nograph avoids the automatic display of a crude graph made out of the created
    variables. nograph is assumed if by() is specified without split.

replace allows the variables specified in glvar(glvarname) and pvar(pvarname)
    to be overwritten if they are already existing. Otherwise glvarname and
    pvarname must be new variable names.

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).

rtip(povline) and atip(povline) require that the ordinates of TIP curves are
    computed instead of generalised Lorenz ordinates.  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. atip() draws 'absolute' TIP
    curves (by cumulating max(z-x,0)) and rtip() draws 'relative' TIP curves
    (by cumulating max(1-(x/z),0)).

graph_options are standard graph, twoway options.

Examples

        . glcurve7 x, gl(gl1) p(p1) nograph
        . graph gl1 p1, xlab ylab s(i) c(l)

        . glcurve7 x [fw=wgt] if x > 0, gl(gl2) p(p2) lorenz

        . glcurve7 x, gl(gl2) p(p2) replace sort(y) by(state) split

        . glcurve7 x, gl(gl3) p(p3) atip(10000)

        . glcurve7 x, gl(gl3) p(p3) atip(plinevar)

Authors

     Philippe VAN KERM <philippe.vankerm@fundp.ac.be>
     University of Namur, Department of Economics
     Rempart de la Vierge 8
     B-5000 Namur, Belgium.

     Stephen P. JENKINS <stephenj@essex.ac.uk>
     ISER, University of Essex
     Colchester CO4 3SQ, U.K.

References

     Cowell, F.A. (1995). Measuring Inequality (second edition).
          Prentice-Hall/Harvester-Wheatsheaf, Hemel Hempstead.

     Jenkins, S.P. and Lambert, P.J. (1997). "Three 'I's of Poverty Curves,
          With An Analysis of UK Poverty Trends", Oxford Economic Papers, 49,
          317-327.

     Lambert, P.J. (1993). The Distribution and Redistribution of Income - A
          Mathematical Analysis. Second edition, Manchester University Press,
          Manchester and New York.

     Shorrocks A.F. (1983). "Ranking Income Distributions", Economica, 197,
          3-17.

Also see

 Manual:  [R] lorenz
    STB:  STB-49 sg107.1, STB-48 sg107
On-line:  help for sumdist (if installed)