-------------------------------------------------------------------------------
help for richness
-------------------------------------------------------------------------------

Command to compute measures of (income) richness as defined by Peichl, Schaefer
>  and Scheicher (2008)

     Basic syntax:

        richness varlist [if exp] [in range] [weight = exp] [, rline(rl) |
              rval(rv) rnumber(rn) rlfix]

        aweights and fweights are allowed; see help weights.

Description:

 richness computes the following richness measures based on the (income)
     distribution for each varname of varlist:

     - headcount ratio: fraction of people above the richness line,

     - FGTT1(a): a series of concave (T1 axiom) FGT richness indices with
     parameters alpha = 0.1, 0.3 and 1.

     - Cha(b): a series of concave (T1 axiom) Chakravaty richness indices
     with parameters beta = 0.1, 0.3, 1, 3and 10.

     - FGTT2(a): a series of convex (T2 axiom) FGT richness indices with
     parameters alpha = 1 and 2.

     - RMed: absolute Medeiros (2006) richness index.

 The richness line is either directly specified by the user or computed
     relative to the median or mean of varname, see under "options" below.

 For the calculation of income richness, the income may not be negative.
     Therefore, cases with varname less than zero are omitted in the
     calculation, whereas values of zero are used for the calculation.


Options:

 There are two ways of defining the richness line:

     rline(rl) manually defines a number rl as the (absolute) richness line
     (can be any positive number, macro or scalar).
     If rline is not used, the richness line is computed relatively (see
     below).

     The relative calculation of the richness line is based on a multiplier
     of a parameter of the distribution of varname.
     rnumber(rn) defines the multiplier rn, which can be any positive number
     and has to be specified in percent but without the "%" symbol (eg. 200,
     which is the default value, and not "200%" if you want to specify a
     richness line of 200%).
     rval(rv) defines the distributional parameter rv, which can be either
     median (default) or mean.
     rlfix specifies that the richness line of the first variable of varlist
     is fixed and used for all other variables of varlist.

 If none of the options is specified, a default richness line of 200% of the
 median is assumed.
 If both ways (absolute and relative) are specified, the (absolute) richness
 line defined by rline is used.

The output and saved results

 richness displays a matrix of the computed results and stores the following
     results in r():

     RR_varname is the matrix with the stored results for varlist,

     Rline_varname is the value of the (computed or specified) richness line
        for varname,

     R_HCR_varname is the headcount index (as a decimal) for varname,

     R_FGTT1_x_varname is the concave FGT (T1 axiom) index with alpha =
        0.1(x=10), 0.3(x=30) and 1(x=100) for varname,

     R_Cha_x_varname is the Chakravaty index with beta = 0.1(x=10),
        0.3(x=30), 1(x=100), 3(x=300) and 10(x=1000) for varname,

     R_FGTT2_alpha_varname is the convex FGT (T2 axiom) index with alpha = 1
        or 2 for varname.

     R_Med_varname is the absolute Medeiros index for varname.

Examples

richness income
richness income if sex=1 [fw=weight], rline(10000)
richness income if sex=1 & region = 2 [fw=weight], rval(mean)
richness income if sex=1 & region = 2 [fw=weight], rval(mean) rnumber(300)
richness income1 income2, rlfix 



Acknowledgements

 Thanks to Stephen Jenkins and Joe Newton for useful suggestions and
     feedback.

References

 Peichl, Andreas, Schaefer, Thilo and Scheicher, Christoph (2006): Measuring
     Richness and Poverty - A micro data application to Germany and the
     EU-15, CPE discussion papers No. 06-11, University of Cologne.

 Peichl, Andreas, Schaefer, Thilo and Scheicher, Christoph (2008): Measuring
     Richness and Poverty - A micro data application to Europe and Germany,
     IZA discussion paper 3790.

Author

   Andreas Peichl
   IZA Institute for the Study of Labor, Bonn, Germany
   peichl@iza.org
   www.iza.org

Authors previous version

   Andreas Peichl & Thilo Schaefer
   Cologne Center for Public Economics
   University of Cologne, Germany
   a.peichl@uni-koeln.de, schaefer@fifo-koeln.de
   www.cpe-cologne.de

Version 2.0.0 2008-11-18