ranksize
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 Swith the Gabaix & Ibragimov (2011) correction and their standard errorzeta sqrt(2/n); a test ofzeta = 1; the Rosen-Resnick quadratic term; the Hill estimator. - Power-law tail by maximum likelihood with
xminchosen 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
pip install ranksize
Requires Python 3.9 or newer.
Quickstart
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):
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 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 |
| 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 |
| 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) |
| Kendall's tau | tau_b with ties |
Kendall (1945) |
Notes:
zeta(rank-size / Pareto exponent of the CCDF) andalpha(exponent of the density) are related byalpha = zeta + 1; Zipf's law iszeta = 1,alpha = 2.- The
xminscan requires at leastMIN_TAIL = 10observations in the tail by default. This is a computational guard chosen for this package, not a value from Clauset et al.; setmin_tailto 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
significanceused 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 generalk-city indices assume at leastkcities.
Command line
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
@software{eminoglu_ranksize,
author = {Eminoğlu, Yusuf},
title = {ranksize},
year = {2026},
version = {0.1.2},
doi = {10.5281/zenodo.24235552},
url = {https://gitlab.com/geophilo1/ranksize_sdk}
}
Related Geophilo SDKs
- urbanscaling: urban scaling laws
Y = Y0 N^betawith OLS, RMA, robust fits and SAMIs. - sprawlmetrics: urban expansion and sprawl metrics from multi-date built-up rasters.
- shiftshare: location quotients, shift-share decompositions and economic base multipliers.
- cohortproj: cohort-component population projection, life tables and Leslie matrices.
License
MIT, see LICENSE.
Metadata
Release files for ranksize 0.1.2
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 |
|---|---|---|---|---|
| ranksize-0.1.2.tar.gz | 42.6 kB | Without provenance | Details for ranksize-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ranksize-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for ranksize-0.1.2-py3-none-any.whl |
Total release size: 76.5 kB
Release files / ranksize-0.1.2.tar.gz
| Download URL | ranksize-0.1.2.tar.gz |
|---|---|
| Size | 42.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
448252724c20f12946d91e7138f19f67671f0a054aaaccd531679074731b2287
|
|
BLAKE2b-256 checksum How to use checksums |
7045d086c3748a672009ae6d86e85cdf6b67ccee462b43711f0e71a5d8136cc6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Release files / ranksize-0.1.2-py3-none-any.whl
| Download URL | ranksize-0.1.2-py3-none-any.whl |
|---|---|
| Size | 33.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
077cc68f7291a8deb93d3e3e6c19926d0bcd163a49b3a7f639e17d2f04b16e6b
|
|
BLAKE2b-256 checksum How to use checksums |
0cd238c0f0242ec6232d9c5eca399130fd8d65bdc9ba0aa6c9801521372face4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Security for ranksize 0.1.2
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.