help lorenz

Title

lorenz -- Lorenz and concentration curves

Syntax

Estimating Lorenz and concentration curves:

lorenz [estimate] varlist [if] [in] [weight]
[,
estimate_options
]

Computing contrasts between outcome variables or subgroups:

lorenz contrast [base]
[,
contrast_options
]

where base is the name of the outcome variable or the value of the
subpopulation to be used as base. base may also be #1, #2,
or #3, etc. to refer to the 1st, 2nd, or 3rd, etc. outcome variable
or subpopulation. See the contrast() option of
lorenz estimate for more details

Drawing a line graph of the results:

lorenz graph
[,
graph_options
]

estimate_options Description

Main
gap compute equality gap curves

sum compute total (unnormalized) Lorenz curves

generalized compute generalized Lorenz curves

absolute compute absolute Lorenz curves

percent report Lorenz ordinates as percentages

normalize(spec) normalize
Lorenz curves with respect to the specified total

gini also report Gini coefficient(s)

Percentiles
nquantiles(#) use # equally spaced percentiles (plus an additional
point at the origin); default is nquantiles(20)

percentiles(numlist) use
percentiles corresponding to the specified percentages

pvar(pvar) compute concentration curves
with respect to pvar

step determine Lorenz ordinates from step function; the default
is to employ linear interpolation

Over
over(varname) compute results for subpopulations defined by
the values of varname

total include overall results across all subpopulations; only
allowed with over()

Contrast/Graph
contrast[(spec)] compute
differences in Lorenz curves between outcome variables or subpopulations

graph[(options)] draw
line graph of the results; options are
graph_options as described below

SE/SVY
vce(vcetype) vcetype may
be analytic (the default), cluster clustvar,
bootstrap or jackknife

cluster(clustvar) synonym for
vce(cluster clustvar)

svy[(subpop)] take account
of survey design as set by svyset, optionally restricting
computations to subpop

nose supress computation of standard errors and confidence
intervals

Reporting
level(#) set confidence level; default is level(95)

noheader suppress output header

notable suppress output table

nogtable suppress table of Gini coefficients

display_options standard
reporting options as described in
[R] estimation options

pweights, iweights, and fweights are allowed; see weight.

contrast_options Description

ratio compute ratios instead of differences

lnratio compute logarithms of ratios instead of differences

graph[(options)] draw
line graph of the results; options are
graph_options as described below

display_options standard
reporting options as described in
[R] estimation options

graph_options Description

Main
proportion population axis in proportion, not percent

nodiagonal omit the equal distribution diagonal

diagonal(options) affect rendition
of the equal distribution diagonal

keep(list) select and order
results to be included as subgraphs

prange(min max) restrict range of percentiles
to be included in the graph

gini(%fmt) specify format for Gini
coefficients; default format is %9.3g

nogini omit Gini coefficients from subgraph labels

Labels/Rendering
connect_options affect rendition of the plotted lines

labels(labels) specify
custom labels for subgraphs

byopts(byopts) specify how
subgraphs are combined

overlay combine results in single graph instead of using
subgraphs

o#(options) affect rendition
of #th plot; for use with overlay

Confidence intervals
level(#) set confidence level; not allowed if ci() is
bc, bca, or percentile

ci(citype) choose type of
bootstrap CI; citype may be normal (the default), bc,
bca, or percentile

ciopts(options) affect
rendition of the plotted confidence areas; see help
graph twoway rarea

noci omit confidence intervals

Add plots
"addplot(addplot_option:plot)" add other plots to the graph

Y-Axis, X-Axis, Title, Caption, Legend, Overall
twoway_options any options other than by()
documented in [G] twoway_options

Description

lorenz estimate computes Lorenz and concentration curves from
individual-level data. The default is to compute standardized (relative)
Lorenz/concentration curves, but generalized and absolute
Lorenz/concentration curves are also supported. Furthermore, unnormalized
Lorenz/concentration curves (such that the estimates reflect cumulative
totals) or Lorenz/concentration curves that are normalized to a specified
total can be computed. Variance estimation for complex samples is
supported; for methodological details see
Jann (2016).

Given the results form lorenz estimate for several outcome variables
or subpopulations, lorenz contrast computes differences in
Lorenz/concentration curves between outcome variables or subpopulations.

lorenz graph plots the results from lorenz estimate or
lorenz contrast as a line diagram. Confidence intervals are included
as shaded areas.

lorenz without arguments replays the previous results. Reporting
options may be applied.

Options for lorenz estimate

Main

gap causes equality gap curves to be computed. Equality gap curves are
defined as EG(p) = p - L(p) where L(p) is the ordinate of
the (relative) Lorenz curve at percentile p. Only one
of gap, sum, generalized, and absolute is allowed.

sum causes unnormalized Lorenz curves to be computed such that the
Lorenz ordinates reflect cumulative sums of the outcome variable. Only one
of gap, sum, generalized, and absolute is allowed.

generalized causes generalized Lorenz curves to be computed. Only one
of gap, sum, generalized, and absolute is allowed.

absolute causes absolute Lorenz curves to be computed. Only one
of gap, sum, generalized, and absolute is allowed.

percent causes results to be expressed as percentages
instead of proportions. percent is not allowed in combination with
sum, generalized, and absolute.

normalize(spec) causes Lorenz ordinates to be normalized
with respect to the specified total (not allowed in combination with
sum, generalized, or absolute ). spec is

[over:] [total] [, average]

where over may be

. the subpopulation at hand (the default)
# the subpopulation identified by value #
## the #th subpopulation
total the total across all subpopulations

and total may be

. the total of the variable at hand (the default)
* the total of the sum across all analyzed outcome variables
varlist the total of the sum across the variables in varlist
# a total equal to #

total specifies the variable(s) from which the total is to be
computed, or sets the total to a fixed value. If multiple variables are
specified, the total across all specified variables is used (varlist may
contain external variables that are not among the list of analyzed outcome
variables). over selects the reference population from which the total
is to be computed; over is only allowed if the over() option has
been specified (see below). Suboption average causes subpopulation
sizes (sum of weights) to be taken into account, so that the results are
relative to the average outcome in the reference population; this is only
relevant if over is provided.

gini causes Gini coefficients (a.k.a. concentration indices if
pvar() is specified) to be computed and reported in a separate table.
Variance estimation for Gini coefficients is not supported.

Percentiles

nquantiles(#) specifies the number of (equally spaced) percentiles
to be used to determine the Lorenz ordinates (plus an additional point
at the origin). The default is nquantiles(20). This is equivalent to
typing percentiles(0(5)100).

percentiles(numlist) specifies, as percentages, the percentiles for
which the Lorenz ordinates are to be computed. The numbers in numlist
must be within 0 and 100. Shorthand conventions as described in help
numlist may be applied. For example, to compute Lorenz
ordinates from 0 to 100% in steps of 1 percentage point, type
percentiles(0(1)100). The numbers provided in percentiles() do
not need to be equally spaced and do not need to cover the whole
distribution. For example, to focus on the top 10% and use an increased
resolution for the top 1% you could type
percentiles(90(1)98 99(0.1)100).

pvar(pvar) causes concentration curves with
respect to variable pvar to be computed. That is, the ordinates of the curves
will be determined from observations sorted in ascending order of pvar
instead of the outcome variable. Values of the outcome variable will be
averaged within ties of pvar.

step causes the Lorenz ordinates to be determined from the step
function of cumulative outcomes. The default is to employ linear
interpolation in regions where the step function is flat.

Over

over(varname) reports results for each subpopulation defined by the
values of varname. Only one outcome variable is allowed if
over() is specified.

total causes additional overall results across all subpopulations to
be reported. total is only allowed if over() is specified.

Contrast/Graph

contrast[(spec)] causes differences in Lorenz curves
to be computed between outcome variables or between subpopulations,
where spec is

[base] [, ratio lnratio ]

To report contrasts as ratios instead of differences, specify the ratio
suboption; to report contrast as logarithms of ratios, specify the
lnratio suboption.

If over() is specified together with total, the default is to
use the overall total across subpopulations as base for the contrasts. In all
other cases, the default is to compute adjacent contrasts (i.e. using the
preceding outcome variable or subpopulation as base). Alternatively,
specify base to select the base for the contrasts.

In case of multiple outcome variables, base is the name of the outcome
variable to be used as base. For example,

. lorenz estimate y1990 y2000 y2010, contrast(y1990)

computes differences in Lorenz curves with respect to y1990.
Likewise, if over() is specified, base is the value of the
subpopulation to be used as base. For example,

. lorenz estimate wage, over(race) contrast(1)

computes differences with respect to race==1. Alternatively, base
may also be #1, #2, #3, etc. to use the 1st, 2nd, 3rd,
etc. outcome variable or subpopulation as the base for the contrasts. For
example,

. lorenz estimate wage, over(race) contrast(#2)

uses the second subpopulation as base for the contrasts.

graph[(options)] draws
a line graph of the results. options are as described for
lorenz graph below.

SE/SVY

vce(vcetype) determines how standard errors and confidence intervals
are computed. vcetype may be:

analytic
cluster clustvar
bootstrap [, bootstrap_options]
jackknife [, jackknife_options]

The default is vce(analytic), using approximate formulas for variance
estimation assuming independent data. For clustered data, specify
vce(cluster clustvar), where clustvar is the variable
identifying the clusters. Methods and formulas are based on Binder and
Kovacevic (1995; also see Kovacevic and Binder 1997). For bootstrap and
jackknife estimation, see help vce_option. Variance estimation
is not supported if iweights or fweights are specified.

cluster(clustvar) is a synonym for vce(cluster clustvar).

svy[(subpop)] causes the survey design to be taken
into account for variance estimation. Methods and formulas are based on
Binder and Kovacevic (1995). The data need to be set up for survey
estimation; see help svyset. Specify subpop to restrict survey
estimation to a subpopulation, where subpop is

[varname] [if]

The subpopulation is defined by observations for which varname!=0 and
for which the if condition is met. See help svy and
[SVY] subpopulation estimation for more information on subpopulation
estimation.

The svy option of lorenz only works if the variance
estimation method is set to Taylor linearization by svyset (the
default). For other variance estimation methods you can use the usual svy
prefix command. For example, you could type svy brr: lorenz ... to
use BRR variance estimation. lorenz does not allow the svy
prefix for Taylor linearization due to technical reasons. This is why the
svy option is provided.

nose suppresses the computation of standard errors and confidence
intervals. Use the nose option to speed-up computations, for example,
when applying a prefix command that uses replication techniques for variance
estimation, such as, e.g., svy jackknife. Option nose
is not allowed together with vce(), cluster(), or svy.

Reporting

level(#) specifies the confidence level, as a percentage, for
confidence intervals. The default is level(95) or as set by
set level.

noheader suppresses the output header; only the coefficient table is
displayed.

notable suppresses the coefficient table.

nogtable suppresses the table containing Gini coefficients.

display_options are standard reporting options such as cformat(),
pformat(), sformat(), or coeflegend. See
[R] estimation options.

Options for lorenz contrast

ratio causes contrasts to be reported as ratios. The default is to
report contrasts as differences.

lnratio causes contrasts to be reported as logarithms of ratios. The
default is to report contrasts as differences.

graph[(options)] draws
a line graph of the results. options are as described for
lorenz graph below.

display_options are standard reporting options such as cformat(),
pformat(), sformat(), or coeflegend. See
[R] estimation options.

Options for lorenz graph

Main

proportion scales the population axis in terms of proportions
(0 to 1). The default is to scale the axis in terms of percentages (0 to
100).

nodiagonal omits the equal distribution diagonal that is included by
default if graphing relative Lorenz or concentration curves. No equal
distribution diagonal is included if graphing equality gap curves or
total, generalized, or absolute Lorenz/concentration curves
or if graphing contrasts.

diagonal(options) affects the rendition of the equal distribution
diagonal. options are line_options as described in
[G] line_options.

keep(list) selects and orders the results to be included as
subgraphs. Use keep() if lorenz estimate has been applied to
multiple outcome variables or subpopulations. In case of multiple outcome
variables, list is a list of the names of the outcome variables to be
included. Example:

. lorenz estimate y1990 y2000 y2010
. lorenz graph, keep(y2010 y1990)

In case of over(), list is a list of the values of the
subpopulations to be included. list may also contain total for
the overall results (if overall results were requested). Example:

. lorenz estimate wage, over(race) total
. lorenz graph, keep(total 1 2)

Furthermore, list may also contain elements such as #1,
#2, #3, etc. to refer to the 1st, 2nd, 3rd, etc. outcome
variable or subpopulation. Example:

. lorenz estimate wage, over(race)
. lorenz graph, keep(#1 #3)

prange(min max) restricts the range of the points
to be included in the graph. Points whose abscissae lie outside
min and max will be omitted. min and max must
be within [0,100]. For example, to include only the upper half of the
distribution, type prange(50 100).

gini(%fmt) sets the format for the Gini coefficients included in the
subgraph or legend labels; see help format. The default format is
%9.3g. Gini coefficients will only be included if information on Gini
coefficients is available in the provided results (i.e. if the gini
option has been applied to lorenz estimate).

nogini suppresses the Gini coefficients. This is only relevant if the
gini option has been specified when calling lorenz estimate.

Labels/Rendering

connect_options are options that affect the rendition of the plotted
lines. See [G] connect_options.

labels(labels) specifies custom labels for the included subgraphs.
The default is to use the variable labels of the outcome variables or the
value labels of the subpopulations, respectively. labels is a list of
labels that are applied one-by-one to the subgraphs. Use quotes if a label
contains spaces, e.g. labels("label one" "label two" ...). Type
empty string to use the default label for a specific subgraph. For example,
labels("label 1" "" "label 3") specifies custom labels for the
first and third subgraphs, and uses default labels for the other subgraphs.

byopts(byopts) determines how subgraphs are combined. byopts
are as described in [G] by_option.

overlay causes results from the different outcome variables or
subpopulations to be included in the same graph instead of using separate
subgraphs.

o#(options) affects the rendition of the line of the #th outcome
variable or subpopulation if overlay has been specified. options are:

connect_options rendition of the plotted line
[no]ci whether to draw the confidence interval
ciopts(options) rendition of confidence interval (see below)

Confidence intervals

level(#) specifies the confidence level, as a percentage, for
confidence intervals. The default is the level that has been used when
running lorenz estimate. level() cannot be used together
with ci(bc), ci(bca), or ci(percentile). To change the
level for these confidence intervals, you need to specify level()
when running lorenz estimate.

ci(citype) chooses the type of CI to be plotted for results that have
been computed using the bootstrap technique. citype may be:

normal normal-based CIs; the default
bc bias-corrected CIs
bca bias-corrected and accelerated CIs
percentile percentile CIs

bca is only available if BCa confidence intervals have been requested
when running lorenz estimate.

ciopts(options) specifies options that affect the rendition of the
plotted confidence areas. options are area_options as described in
[G] area_options.

noci omits confidence intervals from the plot.

Add plots

addplot(plot) provides a way to add other plots to the generated
graph. See [G] addplot_option.

Y-Axis, X-Axis, Title, Caption, Legend, Overall

twoway_options are general twoway options, other than by(), as
documented in [G] twoway_options.

Examples

. sysuse nlsw88
. lorenz estimate wage
. lorenz graph, aspectratio(1)

. lorenz estimate wage, over(union)
. lorenz graph, aspectratio(1) overlay

. lorenz estimate wage, over(union) generalized
. lorenz graph, overlay

. lorenz estimate wage, over(union) generalized contrast(1)
. lorenz graph, yline(0)

For further examples see Jann (2016).

Stored results

lorenz estimate stores the following in e():

Scalars

e(N) number of observations

e(N_over) number of subpopulations

e(N_clust) number of clusters

e(k_eq) number of equations in e(b)

e(ngrid) number of points in estimation grid

e(df_r) sample degrees of freedom

e(rank) rank of e(V)

e(level) confidence level for CIs

Macros

e(cmd) lorenz

e(cmdline) command as typed

e(depvar) name(s) of outcome variable(s)

e(pvar) name of variable specified in pvar()

e(type) gap, sum, generalized, absolute or empty

e(percent) percent or empty

e(norm) # or names of reference variables or empty

e(normpop) total or overvar = # or empty

e(normavg) average or empty

e(percentiles) percentile thresholds

e(step) step or empty

e(gini) gini or empty

e(over) name of over() variable

e(over_namelist) values from over() variable

e(over_labels) labels from over() variable

e(total) total or empty

e(contrast) contrast or empty

e(baseval) + or value/name of base for contrasts

e(ratio) ratio or empty

e(lnratio) lnratio or empty

e(wtype) weight type

e(wexp) weight expression

e(clustvar) name of cluster variable

e(vce) vcetype specified in vce()

e(vcetype) title used to label Std. Err.

e(title) title in estimation output

e(properties) b V or b

Matrices

e(b) estimates (Lorenz ordinates)

e(V) variance-covariance matrix of estimates

e(p) population percentages (Lorenz abscissae)

e(_N) numbers of observations in subpopulations

e(G) Gini coefficients (if gini is specified)

Functions

e(sample) marks estimation sample

If the svy option is specified, various additional results as described
in help svy are stored in e().

References

Binder, D. A., M. S. Kovacevic (1995). Estimating Some Measures of Income
Inequality from Survey Data: An Application of the Estimating Equations
Approach. Survey Methodology 21(2): 137-145.

Jann, B. (2016). Estimating Lorenz and concentration curves. The
Stata Journal 16(4):837–866. (working paper)

Kovacevic, M. S., D. A. Binder (1997). Variance Estimation for
Measures of Income Inequality and Polarization - The Estimating Equations
Approach. Journal of Offcial Statistics 13(1): 41-58.

Author

Ben Jann, University of Bern, ben.jann@soz.unibe.ch

Thanks for citing this software as follows:

Jann, B. (2016). lorenz: Stata module to estimate and display lorenz
curves and concentration curves. Available from
http://ideas.repec.org/c/boc/bocode/s458133.html.

Also see

Online: help for
graph twoway line

From the SSC Archive:
pshare,
svylorenz,
alorenz,
clorenz,
glcurve,
ldtest