*! version 3.0, January 2018

help file for seg version 3.0

Title

seg -- compute multiple-group diversity and segregation indices with
finite sample-bias correction

Syntax

seg
varlist
[if] [in]
,
index
[options]

Required Index Specifications

Specifies which segregation indices are computed

At least one of the index options (d | g | h | c | r | p | x | s | n) 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

base(num) Specifies that the entropy index of diversity should be
calculated using logarithms of base num, where num is an integer greater than 1.
The default is to use base M, where M is the number of groups specified in
varlist.

Output Options

file(filename) Specifies that the values of the indices requested
are to be written to a separate file with the name filename.

generate(genlist) Specifies variable names for segregation
indices

nodisplay Supppresses output display

replace Specifies that file 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

seg calculates multiple-group diversity and 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, and file 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.

genlist must have the form:
(index newvar [index newvar [index newvar [...]]])

where index indicates the index to be output, and newvar is the name
of the variable to be created. index must be one of the following:

t for total by-group counts

u for the number of units within each by-group

i for Normalized Simpson Interaction Diversity Index

e for Entropy Diversity Index

d for Dissimilarity Segregation Index

g for Gini Segregation Index

h for Information Theory Segregation Index

c for Sqsuared Coefficient of Variation Segregation Index

p for (n-group) Normalized Exposure Segregation Index

r for Relative Diversity Segregation Index

o for Hutchens' Square Root Segregation Index

x for Exposure Index

s for Isolation Index

n for 2-group Normalization Exposure Index

If the adjust option is specified, the h and/or r indices will be returned
with the corresponding bias-adjusted versions with the variable name newvar_adj.

If genlist is not specified, seg will assign the requested index the name
INDEXseg (e.g. Hseg if index h is specified). In this case, seg
will also return nunits, the number of units in a given by-group, and
Total, the total count in all units within a given by-group.

Options

Required Index Specifications

d specifies that the Dissimilarity Index is to be calculated. The Simpson
Diversity Indices are also calculated if this option is specified.

g specifies that the Gini Index is to be calculated. The Simpson Diversity
Indices are also calculated if this option is specified.

h specifies that the Theil Information Theory Index is to be calculated.
The Theil Entropy Diversity Index is also calculated if this option is
specified.

c specifies that the Squared Coefficient of Variation Index is to be
calculated. The Simpson Diversity Indices are also calculated if this option is
specified.

r specifies that the Relative Diversity Index is to be calculated. The
Simpson Diversity Indices are also calculated if this option is specified.

p specifies that the (multi-group) Normalized Exposure Index is to be
calculated. The Simpson Diversity Indices are also calculated if this option is
specified.

x specifies that the (two-group) Exposure Index is to be calculated. The
calculated exposure is the exposure of the group specified in var1 to the group
specified in var2. Other groups listed in varlist are included in the
calculation of the exposure index.

s specifies that the Isolation Index is to be calculated for the group
specified in var1. Other groups listed in varlist are included in the
calculation of the isolation index.

n specifies that the (two-group) Normalized Exposure Index is to be
calculated. The calculated exposure is the exposure of the group specified in
var1 to the group specified in var2. Other groups listed in varlist are
included inthe calculation of the normalized exposure index.

Optional Index Specifications

by(varlist) specifies that the indices are to be calculated within the
by 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 seg.

base(num) specifies that the entropy index of diversity should be
calculated using logarithms of base num, where num is an integer greater than 1.
The default is to use base M, where M is the number of groups specified in varlist.

Output Options

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

generate(genlist) specifies that the values of the indices indicated in genlist
are to be written to the current file, with variable names as indicated in genlist.
If the file option is also specified, generate will cause
the variables listed in genlist to be written to the new file(s) rather than to
the current file.

file(filename) specifies that the values of the indices requested are to
be written to a separate file. [Note: seg reserves several variable names as
defaults if none are specified in generate: total, nunits,
Dseg, Gseg, Hseg, Cseg, Rseg, Pseg, Xseg,
Sseg, Nseg, Idiv, and Ediv. This can cause a conflict if a
variable specified in the by option uses one of these reserved names. Conflicts
can be avoided in this case by using the generate option to specify new
names for the variables written to the new file.]

replace, when specified with the file or tfile option, forces seg 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. If this option is specified
with other indices, seg will return an error. 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 counts of mutually exclusive
categories (e.g. counts by race, sex, etc.). 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.

To adjust the segregation measures h and/or r for finite sampling bias,
specify adjust. The adjust option requires seg 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 seg:

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

seg calculates the indices as follows. For each unit, calculate the total
count within the unit as

t=SUM(varlist)

and the proportion of the unit within category n as

qn = varn/t.

The Simpson Interaction Diversity Index of each unit is then

Iu = SUM[qn * (1 - qn)]

The Normalized Interaction Index of each unit is then

NIu = [n/(n-1)] * Iu

The Entropy Diversity Index of each unit is then

Eu = SUM[qn * LOG(1/qn)].

The corresponding Diversity indices of each by-group (Ig, NIg, & Eg) are calculated similarly

Ig = SUM[Qn * (1 - Qn)]

NIg = [n/(n-1)] * Ig

Eg = SUM[Qn * LOG(1/Qn)]

where T and Qn are calculated over each by-group rather than each unit.

The multiple-group segregation indices of each by-group g are defined then as follows:

Dg = SUMn[SUMu[t * |Qn - qn|]] / (2 * T * Ig)

Gg = SUMn[SUMui[SUMuj[ti * tj * |qni - qnj|]]] / (2 * T * T * Ig)

Hg = 1 - [SUM((t/T)*Eu) / Eg].

Cg = SUMn[SUMu[t * (Qn - qn) * (Qn - qn)] / [T * Qn * (M - 1)]].

Rg = SUMn[SUMu[t * (Qn - qn) * (Qn - qn)] / (T * Ig)].

Pg = SUMn[SUMu[t * (Qn - qn) * (Qn - qn)] / [T * (1 - Qn)]].

Xg = SUMu((t * q1 * q2) / (T * Q1)].

Sg = SUMu((t * q1 * q1) / (T * Q1)].

Ng = 1 - Xg/Q2.

where M is the number of groups specified in varlist; where SUMn
indicates a sum over all n groups in varlist; and where SUMu (and SUMui or
SUMuj) indicates as sum over all units.

Seven of the segregation indices (D G H C R P N) have a minimum of 0
(no segregation) and a maximum of 1 (complete segregation). X has a minimum of
0 (no exposure) and an upper bound of 1 (complete exposure). S has a lower
bound of 0 (no isolation) and a maximum of 1 (complete isolation).

The bias-adjusted H and R are calculated as follows:

adjusted Hg = estimated Hg - (B / (2*Eg))

adjusted Rg = (estimated Rg - B) / (1 - B))

where B is defined as

B = (z / (t-bar - 1)) * ((1-r) / r)

where t-bar is defined as the unit-mean of the total of varlist within a
given by-group, r is the harmonic mean of the unit sampling rates, and z is
defined as

z = 1 + (1/t-bar)*((t-bar-1) / [(t-1)-harm] - 1)

where (t-1)-harm is the harmonic mean of (t-1)

Examples

Suppose the data contain racial enrollment counts by school, with variables
sch, dst, and msa identifying the school, district, and
metropolitan area of each school, and with white, black, hisp,
asian, and natam variables containing within-school enrollment
counts for 5 racial/ethnic groups. Then

. seg white black, d

calculates the between-school dissimilarity index between White and
Black students among all schools in the data set.

. seg white black hisp asian, g by(msa) u(dst) gen(g gwbha i iwbha)

calculates for each metropolitan area the between-district gini index
among White, Black, Hispanic, and Asian students, and outputs the gini index and
diversity of each metropolitan area to the variables gwbha and iwbha.

. seg white black, d g v h by(msa dst) file(c:\outfile.dta) replace

calculates and writes to file "c:\outfile.dta" the dissimilarity, gini,
variance ratio, and entropy indices (and the relevant diversity indices) between
White and Black students within each district in each metropolitan area.
Because two variables are listed in the BY option, the results will not be
displayed to the screen.

. seg white black hisp asian natam, x s n

calculates the white-black exposure index, the white isolation index,
and the normalized white-black exposure index among all schools in the data.
Note that this will give different results than

. seg white black, x s n

which will calculate the exposure and isolation indices ignoring all
students other than black and white students.

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

. seg white black, h r by(dst) gen(h h r r) file(c:\outfile.dta) adjust sampcounts rate(srate)

calculates for each district the between-school bias-adjusted Information Theory
Segregation Index (h) and the bias-adjusted Relative Diversity Segregation Index
(r) between white and black students, and outputs the results as variables h_adj
and r_adj into the file "c:\outfile.dta". Unadjusted versions of h and r
are also returned.

Authors

sean f. reardon

sean.reardon@stanford.edu

Joseph B. Townsend

townsend.joseph@gmail.com

References

James, David R. and Karl E. Taeuber. 1985. "Measures of Segregation." Sociological Methodology, 14:1-32.

Massey, Douglas S. and Nancy A. Denton. 1988. "The dimensions of racial segregation." Social Forces. 67:281-315.

Reardon, Sean F., and Glenn Firebaugh. 2002. "Measures of multigroup segregation." Sociological Methodology 32: 33-67.

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

White, Michael J. 1986. "Segregation and diversity measures in population distribution." Population Index 52:198-221.

Zoloth, Barbara S. 1976. "Alternative measures of school segregation." Land Economics 52:278-298.