Metadata-Version: 2.4
Name: urbanscaling
Version: 0.1.0
Summary: Urban scaling laws Y = Y0 N^beta: OLS, RMA, robust and nonlinear fits, bootstrap intervals, tests against linearity, SAMIs, city-definition sensitivity, residual diagnostics and panel scaling.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/geophilo1/urbanscaling_sdk
Project-URL: Repository, https://gitlab.com/geophilo1/urbanscaling_sdk
Project-URL: Issues, https://gitlab.com/geophilo1/urbanscaling_sdk/-/work_items
Project-URL: Changelog, https://gitlab.com/geophilo1/urbanscaling_sdk/-/blob/main/CHANGELOG.md
Keywords: urban-scaling,scaling-laws,allometry,power-law,sami,cities,urban-economics,agglomeration,reduced-major-axis,bootstrap,urban-planning,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

# urbanscaling

[![PyPI](https://img.shields.io/pypi/v/urbanscaling.svg)](https://pypi.org/project/urbanscaling/)
[![Python](https://img.shields.io/pypi/pyversions/urbanscaling.svg)](https://pypi.org/project/urbanscaling/)
[![pipeline](https://gitlab.com/geophilo1/urbanscaling_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/urbanscaling_sdk/-/pipelines)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://gitlab.com/geophilo1/urbanscaling_sdk/-/blob/main/LICENSE)

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

```bash
pip install urbanscaling
```

Requires Python 3.9 or newer.

## Quickstart

```python
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):

```python
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`](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| / 0.6745`, tuning `c = 1.345`; Huber's asymptotic covariance | Huber (1981); Holland & Welsch (1977) |
| 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

```bash
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

```bibtex
@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](LICENSE).
