Skip to main content

ranksize

PyPI Python pipeline License: MIT DOI

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

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) 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

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.1},
  doi     = {10.5281/zenodo.24235552},
  url     = {https://gitlab.com/geophilo1/ranksize_sdk}
}

License

MIT, see LICENSE.

Metadata

Release files for ranksize 0.1.1

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

Source distribution (sdist)

Source distribution for ranksize 0.1.1
File Size Uploaded Provenance Actions
ranksize-0.1.1.tar.gz 41.5 kB Without provenance Details for ranksize-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 74.9 kB

Release files / ranksize-0.1.1.tar.gz

Download URL ranksize-0.1.1.tar.gz
Size 41.5 kB
Tags Source
SHA-256 checksum
How to use checksums
d8bf87310dc4d977482655c2b3f4ef336dfaee10bda432855afc8ef4cc0c001e
BLAKE2b-256 checksum
How to use checksums
aba73ec1d693d39fdd798056f1e702c46d184473f04ccd220ad1da6e14cdc347
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.1-py3-none-any.whl

Download URL ranksize-0.1.1-py3-none-any.whl
Size 33.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0ced5affcf97619848193bfd7820f840ecc4920c4e835e2dff464e63b0bc7995
BLAKE2b-256 checksum
How to use checksums
f2b615ca02909b58ed6d8673f3714d94875d91da311f2ef7fff272965a2d72b1
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.1

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