Metadata-Version: 2.4
Name: ranksize
Version: 0.1.1
Summary: City-size distributions: Zipf rank-size regression with the Gabaix-Ibragimov correction, power-law tails by MLE with KS xmin selection and bootstrap goodness of fit, lognormal comparison by Vuong test, primacy and concentration indices, and rank clocks.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/geophilo1/ranksize_sdk
Project-URL: Repository, https://gitlab.com/geophilo1/ranksize_sdk
Project-URL: Issues, https://gitlab.com/geophilo1/ranksize_sdk/-/work_items
Project-URL: Changelog, https://gitlab.com/geophilo1/ranksize_sdk/-/blob/main/CHANGELOG.md
Keywords: zipf,rank-size,city-size-distribution,power-law,pareto,lognormal,primacy,gini,herfindahl,rank-clock,urban-systems,regional-science
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
Classifier: Topic :: Scientific/Engineering :: Information Analysis
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.21
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

# ranksize

[![PyPI](https://img.shields.io/pypi/v/ranksize.svg)](https://pypi.org/project/ranksize/)
[![Python](https://img.shields.io/pypi/pyversions/ranksize.svg)](https://pypi.org/project/ranksize/)
[![pipeline](https://gitlab.com/geophilo1/ranksize_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/ranksize_sdk/-/pipelines)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://gitlab.com/geophilo1/ranksize_sdk/-/blob/main/LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24235552.svg)](https://doi.org/10.5281/zenodo.24235552)

**City-size distributions: Zipf, power-law tails, primacy and rank dynamics.**

`ranksize` takes a list of city sizes (population, built-up area, employment, ...) and
answers the standard questions about a city system:

- **Zipf / rank-size regression** `ln(R - 1/2) = a - zeta ln S` with the Gabaix &
  Ibragimov (2011) correction and their standard error `zeta sqrt(2/n)`; a test of
  `zeta = 1`; the Rosen-Resnick quadratic term; the Hill estimator.
- **Power-law tail** by maximum likelihood with `xmin` chosen by the Kolmogorov-Smirnov
  criterion and a semi-parametric bootstrap goodness-of-fit p-value (Clauset, Shalizi &
  Newman 2009).
- **Alternative tails**: truncated lognormal and exponential fits and Vuong's
  likelihood-ratio test against the power law; full-sample lognormal (Eeckhout 2004).
- **Primacy and concentration**: Jefferson two-city index, four-city index and the general
  `S1/(S2+...+Sk)`, each with its value under exact Zipf; primate share, Gini, Lorenz
  curve, Hirschman-Herfindahl (raw and normalised) and Theil.
- **Rank dynamics over time** (Batty 2006): rank tables, rank-clock coordinates, mean
  absolute rank shift, Kendall's tau between censuses, top-N turnover and survival, and the
  Zipf exponent by period.

It needs only NumPy. A command-line tool reads CSV or JSON and writes JSON or CSV.

## Installation

```bash
pip install ranksize
```

Requires Python 3.9 or newer.

## Quickstart

```python
import ranksize as rs

sizes = [...]                          # one population per city

z = rs.rank_size(sizes, top=100)      # Gabaix-Ibragimov rank - 1/2 regression
z.zeta, z.se_gi, z.ci                 # exponent, GI standard error, normal 95 % CI
rs.zipf_test(z, 1.0)                  # H0: Zipf's law

pl = rs.fit_power_law(sizes)          # MLE alpha, KS-selected xmin
pl.alpha, pl.xmin, pl.n_tail          # zeta = alpha - 1
rs.power_law_gof(sizes, pl, n_sims=2500, seed=1).p_value
rs.vuong_test(sizes, pl, "lognormal").to_dict()

rs.jefferson_index(sizes), rs.four_city_index(sizes)
rs.concentration(sizes)               # primacy, Gini, HHI, Theil in one dict
```

Rank dynamics from a long table of `(city, period, size)`:

```python
t = rs.rank_table(city, year, population)
rs.rank_shift(t, top=100)             # mean |rank change|, Kendall tau, exits/entries
rs.top_n_survival(t, 100)             # share of the initial top 100 still there
rs.rank_clock(t, top=30)              # x, y coordinates for a rank-clock plot
rs.zipf_over_time(t, top=100)
```

See [`examples/quickstart.py`](examples/quickstart.py) for a runnable script.

## Features

| Area | Functions / classes |
| --- | --- |
| Rank-size | `rank_size -> ZipfFit`, `zipf_test`, `rank_size_quadratic`, `hill_estimator -> HillResult`, `hill_plot`, `ranks` |
| Power law | `fit_power_law -> PowerLawFit`, `power_law_gof -> GOFResult`, `ks_distance`, `sample_power_law` |
| Alternatives | `fit_lognormal -> LognormalFit`, `fit_exponential -> ExponentialFit`, `vuong_test -> Comparison`, `compare_alternatives` |
| Primacy | `jefferson_index`, `four_city_index`, `primacy_index(k)`, `zipf_benchmark(k)`, `primate_share` |
| Concentration | `gini`, `lorenz_curve`, `hhi`, `theil`, `concentration` |
| Dynamics | `rank_table -> RankTable`, `rank_clock`, `rank_shift`, `kendall_tau`, `top_n_survival`, `zipf_over_time` |
| I/O | `read_table` (CSV/JSON), `numeric_column`, `write_csv`, `write_json` |

Results have a JSON-safe `to_dict()`. Sizes must be positive; `drop_invalid=True` drops
missing or non-positive values instead of raising.

## Methods and sources

| Method | Definition | Source |
| --- | --- | --- |
| Rank-size regression | OLS of `ln(R - s)` on `ln S`, `s = 1/2` (or 0 for the classical form); `SE = zeta sqrt(2/n)` | Gabaix & Ibragimov (2011) |
| Quadratic rank-size | `ln(R - s) = a + b ln S + c (ln S)^2` | Rosen & Resnick (1980) |
| Hill estimator | `zeta = 1 / [(1/k) sum_{i<=k} ln S_(i) - ln S_(k+1)]`, `SE = zeta / sqrt(k)` | Hill (1975) |
| Power-law MLE | `alpha = 1 + n / sum ln(x_i/xmin)`, `SE = (alpha-1)/sqrt(n)` | Clauset et al. (2009), eqs. 3.1-3.2 |
| `xmin` | value minimising the KS distance between empirical and fitted tail CDFs | Clauset et al. (2009), sec. 3.3 |
| Goodness of fit | semi-parametric bootstrap; power law ruled out when `p <= 0.1` | Clauset et al. (2009), sec. 4.1 |
| Model comparison | `R = sum (ln p_PL - ln p_alt)`, `p = erfc(|R| / sqrt(2 n sigma^2))`, alternatives truncated at `xmin` | Vuong (1989); Clauset et al. (2009), sec. 5 and app. C |
| Lognormal (whole distribution) | `mu, sigma` of `ln S` | Eeckhout (2004) |
| Two-city index | `S1 / S2` | Jefferson (1939) |
| Four-city index | `S1 / (S2 + S3 + S4)` | standard in the primacy literature (origin credited inconsistently; no single source claimed) |
| Gini | `sum_i sum_j |x_i - x_j| / (2 n^2 mean)` (optional `n/(n-1)`) | Gini (1912) |
| HHI | `sum s_i^2`, normalised `(HHI - 1/n)/(1 - 1/n)` | Hirschman (1945); Herfindahl (1950) |
| Theil | `(1/n) sum (x/mu) ln(x/mu)` | Theil (1967) |
| Rank clock, rank shift | radius = rank, time clockwise; `mean |r_i(t) - r_i(t-1)|` | Batty (2006) |
| Kendall's tau | `tau_b` with ties | Kendall (1945) |

Notes:

- `zeta` (rank-size / Pareto exponent of the CCDF) and `alpha` (exponent of the density)
  are related by `alpha = zeta + 1`; Zipf's law is `zeta = 1`, `alpha = 2`.
- The `xmin` scan requires at least `MIN_TAIL = 10` observations in the tail by default.
  This is a computational guard chosen for this package, not a value from Clauset et al.;
  set `min_tail` to suit your data.
- Clauset et al. suggest about 2500 bootstrap simulations for p-values accurate to about
  0.01. With a few thousand cities each simulation re-scans `xmin`, so this takes minutes.
- The `significance` used to label a Vuong comparison as favouring one model is a user
  choice (default 0.05); the p-value is always reported.
- City sizes are treated as continuous. For integer counts with a small `xmin` (below about
  100) Clauset et al. (2009, sec. 3.1) recommend the discrete estimator instead; city
  populations are normally far above that range. The four-city and general `k`-city indices assume
  at least `k` cities.

## Command line

```bash
ranksize zipf cities.csv --size population --top 100 --hill 50
ranksize powerlaw cities.csv --size population --gof 2500 --seed 1 --scan-csv xmin_scan.csv
ranksize primacy cities.csv --size population --k 2,4,11
ranksize dynamics censuses.csv --size population --city id --period year --top 100 \
    --clock-csv clock.csv --ranks-csv ranks.csv
```

Inputs are CSV (header row) or JSON (list of records or mapping of columns); output is JSON
on stdout or in `-o`. `--drop-invalid` drops empty or non-positive sizes.
`python -m ranksize` works too.

## References

- Batty, M. (2006). Rank clocks. *Nature* 444(7119), 592-596.
  https://doi.org/10.1038/nature05302
- Clauset, A., Shalizi, C. R. & Newman, M. E. J. (2009). Power-law distributions in
  empirical data. *SIAM Review* 51(4), 661-703. https://doi.org/10.1137/070710111
- Eeckhout, J. (2004). Gibrat's law for (all) cities. *American Economic Review* 94(5),
  1429-1451.
- Gabaix, X. & Ibragimov, R. (2011). Rank - 1/2: a simple way to improve the OLS
  estimation of tail exponents. *Journal of Business & Economic Statistics* 29(1), 24-39.
- Gini, C. (1912). *Variabilità e mutabilità*. Bologna: Cuppini.
- Herfindahl, O. C. (1950). *Concentration in the Steel Industry*. PhD thesis, Columbia
  University.
- Hill, B. M. (1975). A simple general approach to inference about the tail of a
  distribution. *Annals of Statistics* 3(5), 1163-1174.
- Hirschman, A. O. (1945). *National Power and the Structure of Foreign Trade*. University
  of California Press.
- Jefferson, M. (1939). The law of the primate city. *Geographical Review* 29(2), 226-232.
- Kendall, M. G. (1945). The treatment of ties in ranking problems. *Biometrika* 33(3),
  239-251.
- Nelder, J. A. & Mead, R. (1965). A simplex method for function minimization. *The
  Computer Journal* 7(4), 308-313. (used for the truncated lognormal MLE)
- Rosen, K. T. & Resnick, M. (1980). The size distribution of cities: an examination of the
  Pareto law and primacy. *Journal of Urban Economics* 8(2), 165-186.
- Theil, H. (1967). *Economics and Information Theory*. North-Holland.
- Vuong, Q. H. (1989). Likelihood ratio tests for model selection and non-nested
  hypotheses. *Econometrica* 57(2), 307-333.

## Academic citation

```bibtex
@software{eminoglu_ranksize,
  author  = {Eminoğlu, Yusuf},
  title   = {ranksize},
  year    = {2026},
  version = {0.1.1},
  doi     = {10.5281/zenodo.24235552},
  url     = {https://gitlab.com/geophilo1/ranksize_sdk}
}
```

## License

MIT, see [LICENSE](LICENSE).
