Metadata-Version: 2.4
Name: segstats
Version: 0.1.2
Summary: Residential segregation and diversity indices for urban analysis: the five Massey-Denton dimensions, multigroup and spatial indices (Reardon-O'Sullivan, Wong, Morrill), local measures, permutation tests and bootstrap CIs.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/geophilo1/segstats_sdk
Project-URL: Repository, https://gitlab.com/geophilo1/segstats_sdk
Project-URL: Documentation, https://gitlab.com/geophilo1/segstats_sdk#readme
Project-URL: Issues, https://gitlab.com/geophilo1/segstats_sdk/-/work_items
Project-URL: Changelog, https://gitlab.com/geophilo1/segstats_sdk/-/blob/main/CHANGELOG.md
Project-URL: SDK dashboard, https://geophilo.com/sdk-dashboard/
Project-URL: DOI, https://doi.org/10.5281/zenodo.24235590
Keywords: segregation,residential-segregation,dissimilarity-index,entropy,diversity,massey-denton,spatial-statistics,urban-analysis,urban-planning,census,geojson,gis
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Sociology
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Other Audience
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Provides-Extra: pandas
Requires-Dist: pandas>=1.3.0; extra == "pandas"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <a href="https://geophilo.com/sdk-dashboard/"><img src="https://geophilo.com/assets/sdk_icons/segstats_sdk.svg" width="120" height="120" alt="segstats icon"></a>
</p>

# segstats

[![PyPI version](https://img.shields.io/pypi/v/segstats.svg)](https://pypi.org/project/segstats/)
[![Python versions](https://img.shields.io/pypi/pyversions/segstats.svg)](https://pypi.org/project/segstats/)
[![pipeline status](https://gitlab.com/geophilo1/segstats_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/segstats_sdk/-/pipelines)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://gitlab.com/geophilo1/segstats_sdk/-/blob/main/LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24235590.svg)](https://doi.org/10.5281/zenodo.24235590)
[![Downloads](https://static.pepy.tech/badge/segstats/month)](https://pepy.tech/project/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.

```bash
pip install segstats            # numpy only
pip install "segstats[pandas]"  # + DataFrame input
```

Requires Python 3.9 or newer.

> **Looking for more?** The PySAL
> [`segregation`](https://github.com/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

```python
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`](https://gitlab.com/geophilo1/segstats_sdk/-/blob/main/examples/quickstart.py) for a runnable synthetic city.

### Command line

```bash
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

```bash
pip install -e ".[dev,pandas]"
pytest --cov=segstats
ruff check . && ruff format --check src tests && mypy src
```

## Related Geophilo SDKs

- [landmix](https://pypi.org/project/landmix/): land-use mix and diversity indices (entropy, Herfindahl-Hirschman, Simpson, Hill numbers) for zones and grids.
- [homeafford](https://pypi.org/project/homeafford/): housing affordability metrics such as price-to-income, cost burden and residual income.
- [arealinterp](https://pypi.org/project/arealinterp/): areal interpolation between incompatible zone systems.
- [geomask](https://pypi.org/project/geomask/): geographic masking of confidential point data with k-anonymity, privacy and utility metrics.

## License

MIT © 2026 Yusuf Eminoğlu. See [LICENSE](https://gitlab.com/geophilo1/segstats_sdk/-/blob/main/LICENSE). To cite segstats, see
[CITATION.cff](https://gitlab.com/geophilo1/segstats_sdk/-/blob/main/CITATION.cff).

## Academic citation

```bibtex
@software{eminoglu_segstats,
  author  = {Eminoğlu, Yusuf},
  title   = {segstats},
  year    = {2026},
  version = {0.1.2},
  doi     = {10.5281/zenodo.24235590},
  url     = {https://gitlab.com/geophilo1/segstats_sdk}
}
```

See also `CITATION.cff`.
