segstats 0.1.0__tar.gz

segstats-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-09
+### Added
+- Evenness: dissimilarity D, Gini, entropy (Theil H), Atkinson; multigroup D and H.
+- Exposure: isolation xPx, interaction xPy, correlation ratio (eta squared), exposure matrix.
+- Concentration: delta, absolute and relative concentration.
+- Centralization: absolute and relative centralization (ties in distance grouped).
+- Clustering: absolute clustering, relative clustering, spatial proximity, negative
+  exponential proximity matrix.
+- Spatial evenness: Morrill D(adj), Wong D(w) and D(s), Reardon & O'Sullivan spatial
+  dissimilarity and spatial information theory index with kernel or contiguity
+  neighbourhoods.
+- Local measures: location quotients, local entropy, local spatial entropy, per-zone
+  contributions to D.
+- Pure-Python GeoJSON geometry: areas, perimeters, centroids, queen/rook contiguity and
+  shared boundary lengths (T-junctions handled), on-the-fly lon/lat projection.
+- Index registry (`compute`, `profile`, `statistic`), random-allocation and zone-shuffle
+  permutation tests, multinomial and zone bootstrap confidence intervals.
+- CSV / GeoJSON / pandas input and the `segstats` command-line tool.

segstats-0.1.0/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Eminoğlu"
+    given-names: "Yusuf"
+    email: "geospacephilo@gmail.com"
+    orcid: "https://orcid.org/0009-0005-6000-2934"
+title: "segstats"
+version: "0.1.0"
+date-released: "2026-11-09"
+license: "MIT"
+repository-code: "https://gitlab.com/geophilo1/segstats_sdk"
+url: "https://pypi.org/project/segstats/"
+abstract: "Residential segregation and diversity indices for urban analysis: the five Massey-Denton dimensions (evenness, exposure, concentration, centralization, clustering), multigroup indices, spatial evenness measures (Morrill, Wong, Reardon-O'Sullivan), local diversity measures, random-allocation permutation tests and bootstrap confidence intervals."
+keywords:
+  - segregation
+  - residential segregation
+  - dissimilarity index
+  - entropy
+  - urban analysis
+  - spatial statistics

segstats-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Eminoğlu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

segstats-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include pyproject.toml
+include src/segstats/py.typed
+recursive-include src/segstats *.py
+recursive-include tests *.py
+recursive-include examples *.py

segstats-0.1.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: segstats
+Version: 0.1.0
+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: Issues, https://gitlab.com/geophilo1/segstats_sdk/-/work_items
+Project-URL: Changelog, https://gitlab.com/geophilo1/segstats_sdk/-/blob/main/CHANGELOG.md
+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: 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
+
+# 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](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)](LICENSE)
+
+**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`](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
+```
+
+## License
+
+MIT © 2026 Yusuf Eminoğlu. See [LICENSE](LICENSE). To cite segstats, see
+[CITATION.cff](CITATION.cff).
+
+## Academic citation
+
+```bibtex
+@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`.

segstats-0.1.0/README.md

@@ -0,0 +1,244 @@
+# 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](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)](LICENSE)
+
+**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`](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
+```
+
+## License
+
+MIT © 2026 Yusuf Eminoğlu. See [LICENSE](LICENSE). To cite segstats, see
+[CITATION.cff](CITATION.cff).
+
+## Academic citation
+
+```bibtex
+@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`.