segstats
Residential segregation and diversity indices for urban analysis.
segstats computes the classic segregation indices from a table of population
counts by zone (census tracts, neighbourhoods, mahalle) and, when zone polygons are
available, their spatial counterparts. It covers the five dimensions of Massey &
Denton (1988), multigroup indices, spatially adjusted measures, local indices per
zone, and Monte Carlo inference. It needs only NumPy. Geometry comes from plain
GeoJSON; shapely and GDAL are not required.
pip install segstats # numpy only
pip install "segstats[pandas]" # + DataFrame input
Requires Python 3.9 or newer.
Looking for more? The PySAL
segregationpackage is a fuller alternative. It adds many more indices, decomposition, network distances, multiscalar profiles and comparative inference, but needs the full geospatial stack.segstatsis a small, dependency-light toolkit whose numbers are checked against hand calculations and PySAL (see Validation).
Quickstart
import segstats as ss
# counts only: CSV with columns tract, black, total
data = ss.read_csv("tracts.csv", id_column="tract", groups=["black"], total_column="total")
x, t = data.two_group("black") # group counts and zone totals
ss.dissimilarity(x, t) # 0 = even, 1 = complete segregation
ss.profile(data, group="black") # every aspatial index at once
# counts + polygons (GeoJSON in lon/lat is projected to metres on the fly)
data = ss.read_geojson("tracts.geojson", id_property="GEOID", counts=data)
ss.profile(data, group="black", center=(28.98, 41.01), bandwidth=1000)
# Is D higher than random allocation would give?
res = ss.permutation_test(data, "D", group="black", n_permutations=999, seed=1)
res.statistic, res.null_mean, res.p_value
# 95% bootstrap CI of the spatial information theory index (1 km Gaussian kernel)
ci = ss.bootstrap_ci(data, "SH", bandwidth=1000, seed=1)
ci.ci_low, ci.ci_high
# local measures
ss.location_quotient(data.counts) # zones x groups
ss.local_entropy(data.counts) # normalised diversity per zone
See examples/quickstart.py for a runnable synthetic city.
Command line
segstats list # all indices and their inputs
segstats indices tracts.csv --id tract --groups black --total total --group black
segstats indices tracts.csv --id tract --groups black --total total \
--geojson tracts.geojson --geo-id GEOID --group black \
--center 28.98,41.01 --bandwidth 1000 --permutations 999 --bootstrap 999 --seed 1
segstats local tracts.geojson --id GEOID --groups black,white,asian -o local.csv
--format table|json|csv controls the output. A GeoJSON file can hold the counts in
its feature properties, or a CSV table can be joined to polygons with --geojson.
Indices
Two-group indices compare a group of interest (x) with everyone else (y = t - x). Multigroup indices use all count columns.
| Name | Index | Dimension | Inputs | Source |
|---|---|---|---|---|
D |
Dissimilarity | evenness | counts | Duncan & Duncan 1955 |
G |
Gini | evenness | counts | Massey & Denton 1988 |
H |
Entropy / Theil H | evenness | counts | Theil & Finizza 1971 |
A |
Atkinson (shape b) | evenness | counts | Atkinson 1970 |
MD, MH |
Multigroup D and H | evenness | counts | Reardon & Firebaugh 2002 |
xPx |
Isolation | exposure | counts | Bell 1954; M&D 1988 |
xPy |
Interaction | exposure | counts | M&D 1988 |
V |
Correlation ratio (eta squared) | exposure | counts | Bell 1954; White 1986 |
DEL |
Delta | concentration | area | Duncan, Cuzzort & Duncan 1961 |
ACO, RCO |
Absolute / relative concentration | concentration | area | M&D 1988 |
ACE, RCE |
Absolute / relative centralization | centralization | centre | M&D 1988 |
ACL, RCL |
Absolute / relative clustering | clustering | distances | M&D 1988 |
SP |
Spatial proximity | clustering | distances | White 1983 |
D_adj |
Adjusted D (contiguity) | spatial evenness | contiguity | Morrill 1991 |
D_w, D_s |
Boundary-weighted and shape-adjusted D | spatial evenness | boundaries | Wong 1993 |
SD, SH |
Spatial dissimilarity and information theory index | spatial evenness | neighbourhood | Reardon & O'Sullivan 2004 |
Local indices: location_quotient, local_entropy, local_spatial_entropy
(entropy of each zone's kernel-weighted local environment), and
local_dissimilarity_contribution.
API overview
| Area | Functions |
|---|---|
| Plain arrays | dissimilarity(x, t), gini, entropy, atkinson(x, t, b), isolation, interaction, correlation_ratio, multigroup_dissimilarity(counts), multigroup_entropy, exposure_matrix, delta(x, t, area), absolute_concentration, relative_concentration, absolute_centralization(x, area, dist), relative_centralization(x, t, dist), absolute_clustering(x, t, c), relative_clustering, spatial_proximity, proximity_matrix(d, area, scale), morrill_dissimilarity(x, t, C), wong_dissimilarity_w(x, t, B), wong_dissimilarity_s(x, t, B, perimeter, area), local_environment(counts, W), spatial_dissimilarity(counts, W), spatial_entropy(counts, W) |
| Data | ZoneData, read_csv, read_geojson, from_dataframe, ZoneGeometry (area, perimeter, centroids, contiguity("queen"/"rook"), boundary_lengths(), distances()) |
| Weights | distance_matrix, kernel_weights(d, bandwidth, kernel), with_self, row_standardize |
| By name | compute(data, "D", group), profile(data, group), statistic(...), INDICES, IndexOptions |
| Inference | permutation_test(data, index, group, null="labels"/"zones"), bootstrap_ci(data, index, group, method="multinomial"/"zones"), random_allocation |
IndexOptions holds the options shared by the registry: Atkinson b, center or
center_distance, decay_scale (distance unit of exp(-d), default 1000 for km
when coordinates are metres), clustering ("proximity" or "contiguity" matrix for
ACL), bandwidth and kernel (gaussian, exponential, biweight, box) for the
Reardon & O'Sullivan neighbourhood (default: the zone plus its contiguous
neighbours), and contiguity (queen/rook).
Method and sources
Notation: x_i, y_i, t_i are the group, rest-of-population and total counts of zone i; capitals are city totals; p_i = x_i / t_i, P = X / T; a_i is the zone area.
- D = ½ Σ |x_i/X − y_i/Y|. G = ΣΣ t_i t_j |p_i − p_j| / (2T²P(1−P)), computed in O(n log n) from sorted proportions. H = Σ t_i (E − E_i) / (E T) with Shannon entropies E, E_i (natural log). A = 1 − P/(1−P) · |Σ (1−p_i)^(1−b) p_i^b t_i / (P T)|^(1/(1−b)). (Massey & Denton 1988, eqs. 1–4.)
- xPx = Σ (x_i/X)(x_i/t_i), xPy = Σ (x_i/X)(y_i/t_i), V = (xPx − P)/(1 − P).
- Multigroup D = Σ_m Σ_i t_i |π_im − π_m| / (2 T I), with I = Σ π_m(1 − π_m), and Theil's H (Reardon & Firebaugh 2002).
- DEL = ½ Σ |x_i/X − a_i/A|. ACO and RCO compare the group's area-weighted mean zone size with that of the n₁ smallest and the n₂ largest zones holding X people (Massey & Denton 1988, eqs. 10–11; same convention for n₁ and n₂ as PySAL).
- ACE = Σ X_{i−1}A_i − Σ X_i A_{i−1} and RCE = Σ X_{i−1}Y_i − Σ X_i Y_{i−1} over zones sorted by distance to the centre (cumulative shares). Zones at equal distance form one step, so the result does not depend on input order.
- SP = (X Pxx + Y Pyy)/(T Ptt), RCL = Pxx/Pyy − 1, with Pxx = ΣΣ x_i x_j c_ij / X² and c_ij = exp(−d_ij / scale), d_ii = (0.6 a_i)^0.5 (Massey & Denton 1988; White 1983). ACL follows Massey & Denton eq. 14 with the chosen c matrix.
- D(adj) = D − ΣΣ c_ij |p_i − p_j| / ΣΣ c_ij (binary contiguity; Morrill 1991).
D(w) = D − ΣΣ w_ij |p_i − p_j| with w_ij = b_ij / ΣΣ b_kl, the normalised
shared-boundary length. D(s) additionally multiplies each term by
½(PA_i + PA_j)/max(PA), PA = perimeter/area (Wong 1993). The normalisation follows
the R package
seg(Hong, O'Sullivan & Sadahiro 2014). Zones with no population are left out of the adjustment term. - Spatial D and H (Reardon & O'Sullivan 2004): each zone's local environment is π̃_im = Σ_j w_ij x_jm / Σ_j w_ij t_j, with kernel weights that include the zone itself. Then H̃ = 1 − Σ t_i Ẽ_i / (T E) and D̃ = Σ_m Σ_i t_i |π̃_im − π_m| / (2 T I). Identity weights reproduce the aspatial indices.
- Inference.
null="labels"is random allocation: individuals' group labels are shuffled while zone sizes and group totals stay fixed (exact multivariate hypergeometric draws).null="zones"shuffles whole zone compositions among locations, which tests the spatial arrangement only. p = (1 + #{sim ≥ obs})/(1 + R). The bootstrap redraws each zone from a multinomial with its observed shares (geometry fixed) and reports percentile intervals.
Validation
The tests check every index against values worked out by hand: complete segregation
gives 1, an even distribution gives 0, and a four-zone city has exact fractions
(D = 5/9, ACO = 14/15, RCO = 77/92, ACE = 79/120, ...). Thirteen two-group indices
and the multigroup D and H also match PySAL segregation 2.6.0 to 1e-9 on an
irregular eight-zone layout. Wong's D(w) matches PySAL when given PySAL's boundary
matrix. On polygons that meet at T-junctions, PySAL's vertex-based contiguity misses
some neighbours, while segstats measures collinear edge overlap directly.
References
- Massey, D. S. & Denton, N. A. (1988). The dimensions of residential segregation. Social Forces 67(2), 281–315. https://doi.org/10.2307/2579183
- Bell, W. (1954). A probability model for the measurement of ecological segregation. Social Forces 32(4), 357–364.
- Duncan, O. D. & Duncan, B. (1955). A methodological analysis of segregation indexes. American Sociological Review 20(2), 210–217.
- Atkinson, A. B. (1970). On the measurement of inequality. Journal of Economic Theory 2(3), 244–263.
- White, M. J. (1983). The measurement of spatial segregation. American Journal of Sociology 88(5), 1008–1018.
- White, M. J. (1986). Segregation and diversity measures in population distribution. Population Index 52(2), 198–221.
- Morrill, R. L. (1991). On the measure of geographic segregation. Geography Research Forum 11, 25–36.
- Wong, D. W. S. (1993). Spatial indices of segregation. Urban Studies 30(3), 559–572.
- Reardon, S. F. & Firebaugh, G. (2002). Measures of multigroup segregation. Sociological Methodology 32, 33–67.
- Reardon, S. F. & O'Sullivan, D. (2004). Measures of spatial segregation. Sociological Methodology 34, 121–162.
- Hong, S.-Y., O'Sullivan, D. & Sadahiro, Y. (2014). Implementing spatial segregation measures in R. PLoS ONE 9(11), e113767.
- Allen, R., Burgess, S., Davidson, R. & Windmeijer, F. (2015). More reliable inference for the dissimilarity index of segregation. The Econometrics Journal 18(1), 40–66.
- Cortese, C. F., Falk, R. F. & Cohen, J. K. (1976). Further considerations on the methodological analysis of segregation indices. American Sociological Review 41(4), 630–637.
Limitations
- Distance units. The
exp(-d)proximity behind SP, RCL and ACL depends on the distance unit.decay_scaledefaults to 1000 (km for metric coordinates). Massey & Denton do not fix a unit, so report the scale you use. - Geometry. Polygons are planar. Lon/lat GeoJSON is projected with a local equirectangular approximation, which is fine at city scale. Reproject large regions beforehand. Contiguity needs clean topology: gaps wider than the tolerance (1e-9 of the extent) break adjacency. Distances are measured between area-weighted centroids.
- Ties. ACO and RCO sort zones by area. When several zones have exactly the same area, the core set follows input order (as in PySAL, whose tie order is arbitrary).
- Small-unit bias. D, H and the other indices are biased upward in small zones.
Use the permutation null mean (
res.excess) to judge it. The percentile bootstrap does not correct this bias. - Integer counts. The permutation tests and the multinomial bootstrap need whole-number counts. Weighted or estimated (e.g. ACS) counts must be rounded, and their sampling error is not modelled.
- Not included: network distances, multiscalar profiles, decomposition,
comparative (two-city) tests and the distance-decay exposure indices. PySAL
segregationcovers these. D_sfollows Wong (1993) with the full zone perimeter. The R packageseguses only the shared part of the perimeter, which you can pass explicitly.
Development
pip install -e ".[dev,pandas]"
pytest --cov=segstats
ruff check . && ruff format --check src tests && mypy src
License
MIT © 2026 Yusuf Eminoğlu. See LICENSE. To cite segstats, see CITATION.cff.
Academic citation
@software{eminoglu_segstats,
author = {Eminoğlu, Yusuf},
title = {segstats},
year = {2026},
version = {0.1.1},
doi = {10.5281/zenodo.24235590},
url = {https://gitlab.com/geophilo1/segstats_sdk}
}
See also CITATION.cff.
Metadata
Release files for segstats 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| segstats-0.1.1.tar.gz | 54.6 kB | Without provenance | Details for segstats-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| segstats-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for segstats-0.1.1-py3-none-any.whl |
Total release size: 96.1 kB
Release files / segstats-0.1.1.tar.gz
| Download URL | segstats-0.1.1.tar.gz |
|---|---|
| Size | 54.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
29c2bdac7c138698c9f796b23a3a6e947b001d0112a55b8224dd91f2e7011cfa
|
|
BLAKE2b-256 checksum How to use checksums |
7b7b55e559af6cddb656e16ab1f2d29f4dba1016c001a59747146bb2c8ccc0e8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Release files / segstats-0.1.1-py3-none-any.whl
| Download URL | segstats-0.1.1-py3-none-any.whl |
|---|---|
| Size | 41.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7b13e36e893be5085f6ee0d1bce5db59e1322eeccfd4a1fab3855d2cd87958b8
|
|
BLAKE2b-256 checksum How to use checksums |
45cc449cf3fd19821003e44f8e7f830a4e45e5943345862d222da38a9013895d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Security for segstats 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.