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