urbanscaling
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 anybeta0, 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=Truedrops them. Onlyfit_nlsaccepts zeros in the indicator. Leitão et al. (2016) show that how zeros and the error model are treated can change conclusions aboutbeta, so compare estimators. diagnoseflags outliers at|t| > 3and influential cities at Cook'sD > 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_sensitivitycompares 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.1},
doi = {10.5281/zenodo.24235550},
url = {https://gitlab.com/geophilo1/urbanscaling_sdk}
}
License
MIT, see LICENSE.
Metadata
Release files for urbanscaling 0.1.1
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 |
|---|---|---|---|---|
| urbanscaling-0.1.1.tar.gz | 50.4 kB | Without provenance | Details for urbanscaling-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| urbanscaling-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for urbanscaling-0.1.1-py3-none-any.whl |
Total release size: 91.5 kB
Release files / urbanscaling-0.1.1.tar.gz
| Download URL | urbanscaling-0.1.1.tar.gz |
|---|---|
| Size | 50.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7fbb59234c1d867bab362028eb6710416b61aa74f9093295541c7044a5f41ac4
|
|
BLAKE2b-256 checksum How to use checksums |
75677e37bafe6b92f3de4a1294713599d4635e9e8ab089b613c57e6e76f03764
|
| 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.1-py3-none-any.whl
| Download URL | urbanscaling-0.1.1-py3-none-any.whl |
|---|---|
| Size | 41.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8f2e9b8c449ea98b4fb15ecd5007ba64c21196d1208d163d6d0e5142ad3440dc
|
|
BLAKE2b-256 checksum How to use checksums |
438ebb3c5db4c0495f4fd96a6c2b202d284a163f8a3da60af52f638ee52100aa
|
| 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.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.