.-
help for ^glcurve5^                         St. Jenkins - Ph. Van Kerm
.-

Derivation of generalised Lorenz curve ordinates with unit record data
----------------------------------------------------------------------

^glcurve5^ varname [^fw^eights ^aw^eights] [^if^ exp] [^in^ range],
        [^gl^var^(^glname^)^ ^p^var^(^pname^) s^ortvar^(^sname^) replace
         by(^groupvar^) sp^lit^ nogr^aph gph_options]

^aweight^s and ^fweight^s are allowed; see help @weights@.


Description
-----------

Important notice: ^glcurve5^ is an outdated release of ^glcurve^. It is availab
> le through
the SSC archive for users of Stata 5 and Stata 6 only. Stata 7 users should use
>  ^glcurve7^.
The up-to-date release is available for Stata 8 users as ^glcurve^. All modules
>  are available
on the SSC archive.


Given variable varname, call it x with c.d.f. F(x), ^glcurve5^ either draws
its Generalised Lorenz curve or generates two new variables containing
the Generalised Lorenz ordinates for x, i.e. GL(p) at each p = F(x) (or both).
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). ^glcurve5^ can also be used
to derive many other related concepts such as concentration curves and
'Three Is of Poverty' (TIP) curves, with appropriate definition of varname,
order of cumulation (set with sortvar option), and normalisation (e.g. by
the mean of varname). For example, the 'ordinary' Lorenz curve
L(p) = GL(p)/mean(x). See References for other examples.

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


Options
-------

^p^var^(^pvarname^)^ generates the variable pvarname containing the
        x-ordinates of the created Generalized Lorenz curve.

^gl^var^(^glvarname^)^ generates the variable glvarname containing the
        y-ordinates of the created Generalized Lorenz curve.

^replace^ allows the variables specified in ^gl^var^(^glname^)^ and
        ^p^var^(^pname^)^ to be overwritten if they are already existing.
        Otherwise "glname" and "pname" must be new variable names.

^s^ortvar^(^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 lorenz ordinates are to be computed
        separately for each subgroups defined by "groupvar". "groupvar"
        must be numeric.

^sp^lit specifies that *a series of new variables* are created containing
        the lorenz ordinates for each subgroup specified by -by(varname)-
        (^sp^lit can not be used without ^by()^). If ^sp^lit is specified,
        then the string in ^gl^var^(^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"). To avoid problems, the maximum number of digits of the
        X's ought to be 3 or less (otherwise the length of "name" must be
        reduced to less than 4 characters accordingly).

^nogr^aph avoids the automatic display of a crude graph made out of the created
        variables. ^nogr^aph is assumed if ^by(^.^)^ is specified without
        ^sp^lit.

gph_options are standard -graph, twoway- options.


Examples
--------

. ^glcurve5 x, gl(gl1) p(p1)^
. ^gr gl1 p1, xlab ylab s(.) c(l)^

. ^glcurve5 x [w=wgt] if x > 0, gl(gl2) p(p2)^

. ^glcurve5 x, gl(gl2) p(p2) s(y) by(state) split replace graph^

. ^su x^
. ^ge rl1 = gl1/_result(3)^
. ^gr p1 rl1 p1, xlab ylab s(..) c(ll)^


Authors
-------

Stephen P. Jenkins <stephenj@@essex.ac.uk>
Institute for Social and Economic Research
University of Essex, Colchester CO4 3SQ, U.K.

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


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

@sumdist@, if installed.