Skip to main content

segstats

PyPI version Python versions pipeline License: MIT

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 segregation package is a fuller alternative. It adds many more indices, decomposition, network distances, multiscalar profiles and comparative inference, but needs the full geospatial stack. segstats is 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_scale defaults 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 segregation covers these.
  • D_s follows Wong (1993) with the full zone perimeter. The R package seg uses 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.0},
  url     = {https://gitlab.com/geophilo1/segstats_sdk}
}

See also CITATION.cff.

Metadata

Release files for segstats 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for segstats 0.1.0
File Size Uploaded Provenance Actions
segstats-0.1.0.tar.gz 54.5 kB Without provenance Details for segstats-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for segstats 0.1.0
File Interpreter ABI Platform Actions
segstats-0.1.0-py3-none-any.whl Python 3 none any Details for segstats-0.1.0-py3-none-any.whl

Total release size: 95.9 kB

Release files / segstats-0.1.0.tar.gz

Download URL segstats-0.1.0.tar.gz
Size 54.5 kB
Tags Source
SHA-256 checksum
How to use checksums
10fc99b0e510b88ff173c9d82b4d72b9386847abf95a7cec880cda5d438eda6a
BLAKE2b-256 checksum
How to use checksums
edb988802a026767ef696dbef5f96e571173419ab23bc187969faa53bd9dbacb
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.0-py3-none-any.whl

Download URL segstats-0.1.0-py3-none-any.whl
Size 41.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
97aac7cae0d45801919b219a123b835750131c1ceb3f48c4721338eb66cac36a
BLAKE2b-256 checksum
How to use checksums
5ffbfd8123bfab30d394543a7ba196a61dae187995839091e659b5691abd4c84
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.0

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page