*! version 3.0 26 january 2018

help file for rankseg version 3.0

Title

rankseg -- compute rank-order segregation measures with finite sample-bias correction

Syntax

rankseg
varlist
[if] [in]
, ORDers(numlist) index
[options]

Required Index Specifications

orders(numlist) Specifies the polyunomial order used in estimation

hseg | rseg Specifies which segregation indices are computed

Note: at least one of the index options (hseg | rseg) must be specified.

Optional Index Specifications

by(varname) Specifies that segregation indices are to be calculated within each value of varname

unit(varname) Specifies that segregation is to be calculated between observations with distinct values of varname

Output Options

file(filename) Specifies name of new file containing rank-order segregation values

tfile(filename) Specifies name of new file containing binary segregation values at each threshold

nodisplay Supppresses output display

replace Specifies that file and tfile should overwrite existing files

Bias-Correction Options

adjust Specifies the finite sample bias adjustment should be used

popcounts Specifies that variables in varlist describe population counts

sampcounts Specifies that variables in varlist describe sample counts

rate(varname) Specifies the variable containing the within-unit sampling rate

tsize(varname) Specifies the variable containinng the within-unit population size

nsize(varname) Specifies the variable containing the within-unit sample size

wreplacement Specifies sampling was done with replacement (default is without replacement)

weights are not allowed. use tsize option to weight units.

Description

rankseg calculates rank-order segregation indices for the variables in varlist.
The by and unit options allow specification of the organization level
at which segregation is to be calculated. The generate, file, and
tfile options allow index values for each value of the by-group variable(s)
to be output to either the current file or new files. The bias-correction options
perform finite sample bias adjustments to the computed indices. adjust must be specified to bias-correct the estimates.
rankseg requires the seg command to be installed.

Options

Required Index Specifications

orders(numlist) specifies the polynomial orders to be used in computing rank-order
segregation. numlist must include non-negative integers, all of which must
be less than K-1, where K is the number of ordered variables in varlist. If
order 0 is specified, rankseg will compute the ordinal segregation indices
described in Reardon (2009).

hseg specifies that the Rank-Order Information Theory Index is to be calculated. If
tfile(filename) is specified, the (binary) Theil Entropy Diversity Index is also calculated at each
threshold and saved to filename.

rseg specifies that the Rank-Order Variance Ratio Index is to be calculated. If
tfile(filename) is specified, the (binary) Simpson Diversity Index is also calculated at each
threshold and saved to filename.

Optional Index Specifications

by(varlist) specifies that the indices are to be calculated within varlist.
If the by option is not sepcified, then segregation is calculated over the
entire set of observations.

unit(varname) specifies that segregation is to be calculated between
observations with distinct values of varname. Observations are
grouped on the unit variable, and segregation is calculated between these units. This
is used, for example, if each observation is a census block group (a subunit of a census tract) and one
wants to calculate segregation between tracts. If the unit variable option
is not specified, then each observation is treated as a separate unit. Note: The
unit option cannot be used with the adjust option. Instead,
the data should be collapsed to the unit-level (and sampling rates or
sample sizes should be computed for each unit) before running rankseg.

Output Options

nodisplay specifies that output should be surpressed. If two or more
variables are listed in the by option, nodisplay is the default.

file(filename) specifies that the values of the indices requested are to
be written to a separate file. Note: rankseg reserves several variable
names as defaults: Total,
nunits, hOrdNum, abd rOrdNum, where OrdNum is an interger
value from the the order option.
This can cause a conflict if a variable specified in the by option uses one
of these reserved names.

tfile(filename) specifies that the pairwise values of the indices at each
threshold are to be written to a separate file.

replace, when specified with the file or tfile option, forces rankseg
to overwrite the file(s) specified in the file and tfile options, if they
already exist. If replace is not specified and the file(s) already exist,
they will not be overwritten.

Bias-Correction Options

adjust specifies that finite sampling bias adjustments should be used. This
option is only available for indices h and r. See Reardon, Bischoff, Owens, and
Townsend (2018) for more on the bias adjustment.

popcounts specifies that the counts in varlist are population counts, as
opposed to sample counts. popcounts is the default when sampcounts is not
specified. If popcounts is specified, but nsize, rate, and wreplacement
are not specified, seg assumes self-weighting sampling
with replacement. This option may not be specified with sampcounts or tsize.

sampcounts specifies that the counts in varlist are sample counts, as opposed to
population counts. If neither popcounts or sampcounts is specified,
popcounts is assumed. If sampcounts is specified, but tsize, rate, and
wreplacement are not specified, seg assumes self-weighting
sampling with replacement. This option may not be specified with popcounts or
nsize.

rate(varname) indicates the variable containing the unit-level sampling rate. When
popcounts and nsize are specified, rate is redundant and is not allowed. When
sampcounts and tsize are specified, rate is redundant and is not allowed.

tsize(varname) indicates the variable containing the within-unit population size. tsize
may not be specified with popcounts. When sampcounts and rate
are specified, tsize is redundant and is not allowed.
See above for restrictions using this option with other bias-correction options.

nsize(varname) indicates the variable containing the within-unit sample size. nsize
may not be specified with sampcounts. When popcounts and rate
are specified, nsize is redundant and is not allowed.
See above for restrictions using this option with other bias-correction options.

wreplacement specifies that sampling was done with replacement (default is
without replacement).

Remarks

The varlist variables should be non-negative integer counts of mutually exclusive
ordered categories (e.g. counts by income category). The variables should be listed
in the order of the categories. The by option is used to specify the level of
organization within which segregation is to be calculated, and the unit option
is used to specify the level of organization between which segregation is to be
calculated.

Observations with missing values on any of the variables in varlist are dropped,
as are observation with missing values on by, unit, rate, nsize, or
tsize if these are specified.

rankseg uses the user-written seg command, so seg must be installed.

rankseg calculates the indices using the formulas in Reardon (2011). The adjust
option uses the formulas in Reardon, Bischoff, Owens, and Townsent (2018).

To adjust the segregation measures h and/or r for finite sampling bias,
specify adjust. The adjust option requires rankseg to be passed or
to calculate both the unit total (the sum of varlist by unit) and the unit-level
sampling rate. In most cases, this means passing rankseg:

popcounts in combination with either a sampling rate variable (passed through
rate(varname)) or a unit-level sampling count variable (passed using
nsize(varname)); or

sampcounts in combination with either a sampling rate variable (passed
through rate(varname)) or a unit-level total count variable (passed using
tsize(varname)).

If adjust is specified without any other bias-correction options, or
with popcounts or sampcounts only, seg assumes self-weighting
sampling with replacement. seg assumes that varlist represents
popcounts when neither popcounts nor sampcounts is specified
(and the above outlined rules for passing popcounts with other
bias-correction options are enforced).

See the helpfile for seg for more on how the segregation indices are calculated.

Examples

Suppose the data contain household counts counts by income category and
census tract, with variables counry and msa
identifying the county and metropolitan area of each tract, and
with variables inc01, inc02,... inc16 containing within-tract
household counts for 16 ordered income categories. Then

. rankseg inc01-inc16, order(4) h

calculates the between-tract rank-order information theory index
among all tracts in the data set, using a 4th order polynomial.

. rankseg inc01-inc16, order(4 5 6) h r by(msa) u(county)

calculates for each metropolitan area the between-county rank-order
information theory index and the rank order variance ratio index,
and outputs them to the variables h4, h5, and h6 and r4,
r5, and r6.

Suppose the data are based on samples rather than population counts, and suppose
that the variable srate contains the sampling rate of students in a given
school. Then

. rankseg inc01-inc16, order(4) h r by(msa) adjust sampcounts rate(srate) tfile(c:\outfile.dta)

calculates for each metropolitan area the between-county rank-order
information theory index and the rank order variance ratio index, as well as bias-adjusted
versions of these indices, and outputs both to the the file "c:\outfile.dta". Because the option
tfile was specified, the rank-order indices variables, which are named h4, h4_adj,
r4, and r4_adj, will be output with the pairwise values of the indices at each
threshold; the names will be h, h_adj, r, and r_adj

Authors

sean f. reardon

sean.reardon@stanford.edu

Joseph B. Townsend

townsend.joseph@gmail.com

References

Reardon, S.F. (2011). "Measures of Income Segregation". CEPA Working Paper.

Reardon, S.F. (2009). "Measures of Ordinal Segregation". Research on Economic Inequality, 17: 129-155.

Reardon, S.F., Bischoff, K., Owens, A., & Townsend, J.B. 2018. "Has Income Segregation Really Increased? Bias and Bias Correction in Sample-Based Segregation Estimates."