Skip to main content

urbanscaling

PyPI Python pipeline License: MIT

Urban scaling laws Y = Y0 N^beta: estimation, inference and diagnostics.

urbanscaling takes one value of an urban indicator per city (GDP, patents, road length, crime, wages, ...) together with the city's population, and estimates how the indicator scales with size:

  • Four estimators of beta: log-log OLS (Bettencourt et al. 2007), reduced (standardised) major axis, Huber-robust M-estimation and nonlinear least squares in linear space (Leitão et al. 2016).
  • Confidence intervals: analytic (t-based, classical or HC1 for OLS; Warton et al.'s exact interval for RMA) and bootstrap (pairs or residual; percentile, basic, normal and BCa).
  • Tests against linearity (beta = 1) or any beta0, with a sub-/linear/super-linear verdict; z test for comparing two exponents.
  • SAMIs, scale-adjusted metropolitan indicators (Bettencourt et al. 2010): ranking, z-scores, correlations across indicators, change and persistence over time.
  • Sensitivity to city definitions (Arcaute et al. 2015): refits across minimum population thresholds, top-k selections and alternative delineations.
  • Residual diagnostics: Jarque-Bera, Breusch-Pagan (Koenker), a curvature (RESET) test for a single power law, leverage, studentised residuals and Cook's distance.
  • Cross-sectional vs temporal scaling (Bettencourt et al. 2020): per-period and per-city fits and a pooled fixed-effects exponent with city-clustered standard errors.
  • Model exponents of Bettencourt (2013): alpha = D/(D+H), 1 - delta, 1 + delta.

It needs only NumPy (all distribution functions are implemented in the package). A command-line tool reads CSV or JSON and writes JSON or CSV.

Installation

pip install urbanscaling

Requires Python 3.9 or newer.

Quickstart

import numpy as np
import urbanscaling as us

rng = np.random.default_rng(0)
pop = np.exp(rng.uniform(np.log(5e4), np.log(2e7), 300))
gdp = 2.5e4 * pop**1.12 * np.exp(rng.normal(0, 0.25, 300))

fit = us.fit_ols(pop, gdp)                 # or fit_rma, fit_huber, fit_nls, fit_scaling(method=...)
fit.beta, fit.ci_beta, fit.r_squared       # exponent, 95 % CI, R^2 of the log-log fit
fit.regime()                               # 'superlinear' | 'linear' | 'sublinear'

us.beta_test(fit, 1.0).to_dict()           # t, p-value and verdict for H0: beta = 1
boot = us.bootstrap_fit(pop, gdp, n_boot=2000, seed=1)
boot.ci_bca, boot.ci_percentile

s = us.sami(pop, gdp, names=[f"c{i}" for i in range(300)])
s.top(5)                                   # cities furthest above the scaling line

us.diagnose(fit).to_dict()                 # normality, heteroscedasticity, curvature, outliers
us.threshold_sensitivity(pop, gdp, [5e4, 1e5, 5e5, 1e6]).summary()

Panel data (one row per city and year):

res = us.panel_scaling(city_ids, years, population, indicator, effects="twoway")
res.cross_sectional_records()   # beta per year
res.temporal_summary()          # distribution of per-city time-series exponents
res.within.to_dict()            # pooled fixed-effects exponent, clustered SE

See examples/quickstart.py for a runnable script.

Features

Area Functions / classes
Fitting fit_scaling(method=...), fit_ols(se="classical"|"hc1"), fit_rma, fit_huber(c=1.345), fit_nls(weights=...) -> ScalingFit
Inference bootstrap_fit -> BootstrapResult, beta_test -> BetaTest, compare_betas
SAMIs sami, sami_from_fit -> SAMIResult, sami_correlation, sami_change, sami_persistence
Sensitivity threshold_sensitivity, rank_sensitivity, definition_sensitivity -> SensitivityResult
Diagnostics diagnose -> Diagnostics, jarque_bera, breusch_pagan, curvature_test
Panel make_panel, cross_sectional_fits, temporal_fits, within_fit -> PanelFit, panel_scaling -> PanelResult
Theory theoretical_exponents(dimension, h)
I/O read_table (CSV/JSON), numeric_column, write_csv, write_json

All results have a JSON-safe to_dict(). Logarithms are natural; intercept is ln Y0.

Methods and sources

Method Definition Source
Scaling law, OLS ln Y = ln Y0 + beta ln N by least squares Bettencourt et al. (2007)
HC1 errors n/(n-2) (X'X)^-1 X' diag(e^2) X (X'X)^-1 White (1980); MacKinnon & White (1985)
RMA / SMA slope sign(r) s_y/s_x; CI beta (sqrt(B+1) -/+ sqrt(B)), B = (1-r^2) t^2/(n-2); test of beta0 via cor(lnY - beta0 lnN, lnY + beta0 lnN) Warton et al. (2006); Pitman (1939)
Huber IRLS, scale `median e
NLS min sum w_i (Y_i - Y0 N_i^beta)^2, Levenberg-Marquardt Leitão et al. (2016)
Bootstrap pairs / residual resampling; percentile, basic, normal, BCa (jackknife acceleration) Efron (1987); Efron & Tibshirani (1993)
SAMI xi_i = ln(Y_i / (Y0 N_i^beta)) Bettencourt et al. (2010)
Definition sensitivity refits across size thresholds and delineations Arcaute et al. (2015)
Normality JB = n/6 (S^2 + (K-3)^2/4), chi-square(2) Jarque & Bera (1987)
Heteroscedasticity n R^2 of e^2 on ln N, chi-square(1) Breusch & Pagan (1979); Koenker (1981)
Curvature F test of (ln N)^2 (equal to RESET with squared fitted values) Ramsey (1969)
Influence leverage, studentised residuals, Cook's distance Cook (1977)
Panel per-period and per-city fits; within (one- or two-way) estimator with cluster-robust SE Bettencourt et al. (2020); Arellano (1987)
Model exponents delta = H/(D(D+H)), area D/(D+H), infrastructure 1-delta, socio-economic 1+delta Bettencourt (2013)

Notes:

  • Rows with zero or negative values cannot enter a log-log fit. By default they raise an error; drop_invalid=True drops them. Only fit_nls accepts zeros in the indicator. Leitão et al. (2016) show that how zeros and the error model are treated can change conclusions about beta, so compare estimators.
  • diagnose flags outliers at |t| > 3 and influential cities at Cook's D > 4/n. These are conventions, not published critical values; both thresholds are parameters.
  • Delineating cities (from density rasters or commuting flows) is outside the package; definition_sensitivity compares datasets you supply for each definition.
  • No published exponents or SAMIs are bundled; supply your own data.

Command line

urbanscaling fit cities.csv --population pop --indicator gdp --name city \
    --method ols --se hc1 --bootstrap 2000 --seed 1 -o fit.json
urbanscaling sami cities.csv --population pop --indicator gdp --name city --csv sami.csv
urbanscaling sensitivity cities.csv --population pop --indicator gdp --thresholds 5e4,1e5,1e6
urbanscaling sensitivity cities.csv --population pop --indicator gdp --top-k 20,50,100
urbanscaling panel panel.csv --population pop --indicator gdp --city id --period year \
    --effects twoway --csv temporal.csv
urbanscaling theory --dimension 2 --h 1

Inputs are CSV (header row) or JSON (list of records or mapping of columns). Output is JSON on stdout or in -o; --csv writes the per-city table. python -m urbanscaling works too.

References

  • Arcaute, E., Hatna, E., Ferguson, P., Youn, H., Johansson, A. & Batty, M. (2015). Constructing cities, deconstructing scaling laws. Journal of the Royal Society Interface 12(102), 20140745. https://doi.org/10.1098/rsif.2014.0745
  • Arellano, M. (1987). Computing robust standard errors for within-groups estimators. Oxford Bulletin of Economics and Statistics 49(4), 431-434.
  • Bettencourt, L. M. A. (2013). The origins of scaling in cities. Science 340(6139), 1438-1441. https://doi.org/10.1126/science.1235823
  • Bettencourt, L. M. A., Lobo, J., Helbing, D., Kühnert, C. & West, G. B. (2007). Growth, innovation, scaling, and the pace of life in cities. PNAS 104(17), 7301-7306. https://doi.org/10.1073/pnas.0610172104
  • Bettencourt, L. M. A., Lobo, J., Strumsky, D. & West, G. B. (2010). Urban scaling and its deviations: revealing the structure of wealth, innovation and crime across cities. PLoS ONE 5(11), e13541. https://doi.org/10.1371/journal.pone.0013541
  • Bettencourt, L. M. A., Yang, V. C., Lobo, J., Kempes, C. P., Rybski, D. & Hamilton, M. J. (2020). The interpretation of urban scaling analysis in time. Journal of the Royal Society Interface 17(163), 20190846.
  • Breusch, T. S. & Pagan, A. R. (1979). A simple test for heteroscedasticity and random coefficient variation. Econometrica 47(5), 1287-1294.
  • Cook, R. D. (1977). Detection of influential observation in linear regression. Technometrics 19(1), 15-18.
  • Efron, B. (1987). Better bootstrap confidence intervals. Journal of the American Statistical Association 82(397), 171-185.
  • Efron, B. & Tibshirani, R. J. (1993). An Introduction to the Bootstrap. Chapman & Hall.
  • Holland, P. W. & Welsch, R. E. (1977). Robust regression using iteratively reweighted least-squares. Communications in Statistics - Theory and Methods 6(9), 813-827.
  • Huber, P. J. (1981). Robust Statistics. Wiley.
  • Jarque, C. M. & Bera, A. K. (1987). A test for normality of observations and regression residuals. International Statistical Review 55(2), 163-172.
  • Koenker, R. (1981). A note on studentizing a test for heteroscedasticity. Journal of Econometrics 17(1), 107-112.
  • Leitão, J. C., Miotto, J. M., Gerlach, M. & Altmann, E. G. (2016). Is this scaling nonlinear? Royal Society Open Science 3(7), 150649. https://doi.org/10.1098/rsos.150649
  • MacKinnon, J. G. & White, H. (1985). Some heteroskedasticity-consistent covariance matrix estimators with improved finite sample properties. Journal of Econometrics 29(3), 305-325.
  • Pitman, E. J. G. (1939). A note on normal correlation. Biometrika 31(1/2), 9-12.
  • Ramsey, J. B. (1969). Tests for specification errors in classical linear least-squares regression analysis. Journal of the Royal Statistical Society B 31(2), 350-371.
  • Warton, D. I., Wright, I. J., Falster, D. S. & Westoby, M. (2006). Bivariate line-fitting methods for allometry. Biological Reviews 81(2), 259-291.
  • White, H. (1980). A heteroskedasticity-consistent covariance matrix estimator and a direct test for heteroskedasticity. Econometrica 48(4), 817-838.

Academic citation

@software{eminoglu_urbanscaling,
  author  = {Eminoğlu, Yusuf},
  title   = {urbanscaling},
  year    = {2026},
  version = {0.1.0},
  url     = {https://gitlab.com/geophilo1/urbanscaling_sdk}
}

License

MIT, see LICENSE.

Metadata

Release files for urbanscaling 0.1.0

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

Source distribution (sdist)

Source distribution for urbanscaling 0.1.0
File Size Uploaded Provenance Actions
urbanscaling-0.1.0.tar.gz 50.3 kB Without provenance Details for urbanscaling-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 91.3 kB

Release files / urbanscaling-0.1.0.tar.gz

Download URL urbanscaling-0.1.0.tar.gz
Size 50.3 kB
Tags Source
SHA-256 checksum
How to use checksums
7aee1123cb681627e2255933edd9f0265025ae3e801a08555d43d6e9c4baf217
BLAKE2b-256 checksum
How to use checksums
1ef04d3d968c28ea7426b416b9671df8fc1d844d76e4164c3c7d3fe4376959a6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.18

Release files / urbanscaling-0.1.0-py3-none-any.whl

Download URL urbanscaling-0.1.0-py3-none-any.whl
Size 41.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ce3eca65cbb5c1741341afcfe9aa8cf75a00707cd16cd887b78b59206cd75e75
BLAKE2b-256 checksum
How to use checksums
357ab8908e38936b28e1acba6f8bba615f51c036c9d30c133fbf585bf2b58c93
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.18

Security for urbanscaling 0.1.0

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