sprawlmetrics
Urban expansion and sprawl metrics from multi-date binary built-up rasters.
sprawlmetrics takes two (or more) built-up / non-built-up rasters of the same grid, for
example classified Landsat or Sentinel-2 scenes or GHSL built-up layers, and computes the
standard indicators used in urban expansion studies:
- Growth: built-up area, total and annual growth rate (linear, compound, exponential), annual expansion area, and the urban expansion intensity index (UEII).
- Landscape Expansion Index (LEI; Liu et al. 2010): sorts every new patch into infilling, edge-expansion or outlying growth, and reports MEI and AWMEI.
- Patch metrics (FRAGSTATS definitions): number of patches, mean patch size, largest patch index, edge density, patch density, mean and area-weighted shape index, and patch compactness.
- Footprint compactness: normalised moment of inertia, exchange index and proximity index.
- Shannon entropy of built-up land across rings, sectors or any zones (Yeh & Li 2001).
- Density gradient: built-up density in concentric rings around a centre, with
Clark's (1951) negative exponential fit
D(r) = D0 exp(-b r). - SDG 11.3.1: land consumption rate, population growth rate and their ratio (LCRPGR).
- Per-zone summaries (districts, rings, grid cells), written as CSV.
It needs only NumPy. SciPy (optional) speeds up patch labelling, and rasterio (optional) reads and writes GeoTIFFs. A command-line tool is included.
Installation
pip install sprawlmetrics # NumPy only
pip install "sprawlmetrics[fast]" # + SciPy (faster connected-component labelling)
pip install "sprawlmetrics[raster]" # + rasterio (GeoTIFF and other GDAL rasters)
Requires Python 3.9 or newer.
Quickstart
import numpy as np
import sprawlmetrics as sm
# 0/1 rasters on the same 30 m grid (here: a synthetic city)
t1 = np.zeros((200, 200), dtype=np.uint8)
t1[80:120, 80:120] = 1
t2 = t1.copy()
t2[75:125, 75:125] = 1 # edge expansion around the core
t2[20:24, 150:154] = 1 # an outlying settlement
report = sm.compare(t1, t2, years=10, cell_size=30, ring_width=300,
population=(250_000, 310_000))
print(report.growth["annual_growth_rate_compound_pct"])
print(report.lei.summary()) # patch counts and areas by growth type, MEI, AWMEI
print(report.gradient_t2.fit) # Clark fit: D0, b, R²
print(report.sdg_11_3_1.ratio) # LCRPGR
import json
json.dumps(report.to_dict()) # JSON-safe (NaN -> null)
Single metrics are plain functions:
lei = sm.landscape_expansion_index(t1, t2, buffer_cells=1, cell_size=30)
lei.records() # one dict per new patch: area, A_o, A_v, LEI, type
lei.type_raster # 0 none, 1 infilling, 2 edge-expansion, 3 outlying
sm.patch_metrics(t2, cell_size=30).to_dict()
sm.compactness(t2, cell_size=30)
sm.zonal_entropy(t2, sm.ring_zones(t2.shape, (100, 100), 300, cell_size=30))
sm.density_gradient(t2, 300, centre=(100, 100), cell_size=30)
sm.expansion_intensity(area_t1=144.0, area_t2=225.0, total_area=3600.0, years=10)
sm.lcrpgr(area_t1=144.0, area_t2=225.0, pop_t1=250_000, pop_t2=310_000, years=10)
Reading rasters (.npy always works; GeoTIFF needs the raster extra):
built, valid, info = sm.load_built("built_2000.tif", built_values=[1]) # class code
built, valid, info = sm.load_built("ghsl_2020.tif", threshold=0.2) # share >= 20 %
info.cell_size # (xres, yres) from the GeoTIFF transform
Command line
sprawlmetrics compare built_2000.tif built_2020.tif --years 20 \
--built-values 1 --ring-width 1000 --centre 512,498 \
--zones districts.tif --population 1200000,1650000 \
--lei-raster lei_types.tif --lei-csv lei.csv --zones-csv zones.csv -o report.json
sprawlmetrics patches built_2020.tif --threshold 0.2
sprawlmetrics gradient built_2020.tif --ring-width 500 --csv rings.csv
sprawlmetrics lcrpgr --area1 144 --area2 225 --pop1 250000 --pop2 310000 --years 10
All commands print JSON (or write it with -o). .npy inputs work without rasterio; set
--cell-size for them.
API overview
| Area | Functions / classes |
|---|---|
| One call | compare(t1, t2, years, ...) -> SprawlReport (.to_dict()) |
| Growth | built_area, built_share, growth_rate, annual_growth_rate(method=...), annual_expansion_area, expansion_intensity |
| LEI | landscape_expansion_index -> LEIResult (mei, awmei, summary(), records(), type_raster), classify_lei |
| Patches | patch_metrics -> PatchMetrics, patch_table, shape_index, min_perimeter_cells, label |
| Compactness | compactness, normalized_moment_of_inertia, exchange_index, proximity_index, built_centroid |
| Entropy | shannon_entropy, zonal_entropy -> EntropyResult |
| Gradient | density_gradient -> GradientResult, fit_negative_exponential -> ExponentialFit |
| Zones | ring_zones, sector_zones, distance_grid, zonal_summary, write_csv |
| SDG 11.3.1 | land_consumption_rate, population_growth_rate, lcrpgr -> LCRPGRResult |
| I/O | read_raster, load_built, binarize, write_raster, RasterInfo |
Conventions: rasters are 2-D arrays, non-zero = built-up. cell_size is a cell side or an
(xres, yres) pair in map units, so areas come out in map units squared. Centres are
(row, col) indices (fractional values allowed). An optional valid mask marks the study
area; cells outside it count neither as land nor as built-up.
Methods and sources
| Metric | Definition | Source |
|---|---|---|
| Growth rate | 100 (A2 - A1) / A1 |
standard |
| Annual growth rate | linear 100 (A2-A1)/(A1 t); compound 100((A2/A1)^(1/t) - 1); exponential 100 ln(A2/A1)/t |
standard |
| UEII | 100 (A2 - A1) / (TA t), TA = land area of the unit |
Liu, Zhan & Deng (2005) |
| LEI | 100 A_o / (A_o + A_v) in a buffer ring around each new patch; infilling > 50, edge-expansion (0, 50], outlying = 0; MEI = mean(LEI), AWMEI = sum(LEI_i a_i)/A |
Liu et al. (2010) |
| Patch metrics | NP, CA, AREA_MN, LPI = 100 max(a)/A, ED = E/A * 10 000, PD = NP/A * 10^6, SHAPE = p / min p (raster form), SHAPE_MN, SHAPE_AM |
McGarigal et al. (FRAGSTATS) |
| Patch compactness | 2 sqrt(pi a) / p |
isoperimetric ratio |
| NMI | A^2 / (2 pi I), I = polar moment of inertia about the centroid |
Li et al. (2014) |
| Exchange, proximity | share of the footprint inside the equal-area circle; (2r/3) / mean distance |
Angel, Parent & Civco (2010) |
| Entropy | H = -sum p_i ln p_i, p_i = x_i / sum x, x_i = built-up density of zone i; relative H / ln n |
Yeh & Li (2001) |
| Density gradient | OLS of ln D on ring mid-distance: D(r) = D0 exp(-b r) |
Clark (1951) |
| SDG 11.3.1 | LCR = ln(Urb2/Urb1)/y, PGR = ln(Pop2/Pop1)/y, ratio LCR/PGR |
UN-Habitat SDG 11.3.1 metadata |
Raster details:
- Patches use the 8-cell rule by default (FRAGSTATS default);
connectivity=4is available. - LEI buffer = morphological dilation of the patch by
buffer_cellscells (square or disc) minus the patch itself; cells outside the raster or the study area are left out.A_vcounts every buffer cell not built at t1, including cells of other new patches. - Edge: the class edge for ED counts cell sides between built-up and valid non-built
cells;
count_boundary=Truealso counts sides on the raster border or against invalid cells. A patch's own perimeter (for SHAPE and compactness) always includes them. - ED is in map units of edge per hectare when cells are in metres (FRAGSTATS m/ha); PD is patches per 100 ha.
- NMI treats each cell as a uniform square, adding its own polar moment
c (xres² + yres²) / 12, so a square footprint scores exactly3/π ≈ 0.955and a disc approaches 1. - Ring k holds cells whose centre lies at
(k-1) w <= d < k w.
Relation to sdg11
The companion package sdg11 implements the full SDG
11.3.1 reporting workflow (degree-of-urbanisation delineation, interpretation and report
bundles). sprawlmetrics.lcrpgr uses the same formula for quick use inside sprawl
analyses; use sdg11 for official-style reporting.
Limitations
- The LEI buffer is raster-based; Liu et al. (2010) describe a vector buffer. With one-cell buffers the results match the usual raster implementations, but values for very small patches depend on the buffer shape and width.
- No reprojection or resampling: both dates must already be on the same grid.
- Entropy and gradient results depend on the chosen centre and ring width; report them.
- The negative exponential fit is OLS on log density and drops rings with zero density; it is not a maximum-likelihood fit.
- UEII class thresholds (e.g. "high-speed", "slow") vary between studies and are not built in.
- Not an official UN product; check SDG values against the current UN-Habitat metadata.
References
- Angel, S., Parent, J. & Civco, D. L. (2010). Ten compactness properties of circles: measuring shape in geography. The Canadian Geographer 54(4), 441-461.
- Clark, C. (1951). Urban population densities. Journal of the Royal Statistical Society, Series A 114(4), 490-496.
- Li, W., Chen, T., Wentz, E. A. & Fan, C. (2014). NMMI: A mass compactness measure for spatial pattern analysis of areal features. Annals of the AAG 104(6), 1116-1133.
- Liu, J., Zhan, J. & Deng, X. (2005). Spatio-temporal patterns and driving forces of urban land expansion in China during the economic reform era. Ambio 34(6), 450-455.
- Liu, X., Li, X., Chen, Y., Tan, Z., Li, S. & Ai, B. (2010). A new landscape index for quantifying urban expansion using multi-temporal remotely sensed data. Landscape Ecology 25, 671-682. https://doi.org/10.1007/s10980-010-9454-5
- McGarigal, K., Cushman, S. A. & Ene, E. FRAGSTATS v4: Spatial Pattern Analysis Program for Categorical Maps. University of Massachusetts, Amherst.
- UN-Habitat. SDG indicator metadata 11.3.1: Ratio of land consumption rate to population growth rate.
- Yeh, A. G.-O. & Li, X. (2001). Measurement and monitoring of urban sprawl in a rapidly growing region using entropy. Photogrammetric Engineering & Remote Sensing 67(1), 83-90.
Academic citation
@software{eminoglu_sprawlmetrics,
author = {Eminoğlu, Yusuf},
title = {sprawlmetrics},
year = {2026},
version = {0.1.1},
doi = {10.5281/zenodo.24235576},
url = {https://gitlab.com/geophilo1/sprawlmetrics_sdk}
}
License
MIT, see LICENSE.
Metadata
Release files for sprawlmetrics 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 |
|---|---|---|---|---|
| sprawlmetrics-0.1.1.tar.gz | 46.6 kB | Without provenance | Details for sprawlmetrics-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sprawlmetrics-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for sprawlmetrics-0.1.1-py3-none-any.whl |
Total release size: 84.4 kB
Release files / sprawlmetrics-0.1.1.tar.gz
| Download URL | sprawlmetrics-0.1.1.tar.gz |
|---|---|
| Size | 46.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9a37ea2078ce998fa681d9120196a2de286ecf8128f313b81a9d7aa725ff10f9
|
|
BLAKE2b-256 checksum How to use checksums |
8820d8f99d6f41a6513633a329ea2af27bd83fbd000f701d5226f457038d6f25
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Release files / sprawlmetrics-0.1.1-py3-none-any.whl
| Download URL | sprawlmetrics-0.1.1-py3-none-any.whl |
|---|---|
| Size | 37.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
69d082ec4a6d54585a92f9a8cef2944ef17d05df533debb4cec4ff99f7f84093
|
|
BLAKE2b-256 checksum How to use checksums |
499bdc668f91f6521bc14147758e5318c5019456cd75806574161b94118dbfc4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Security for sprawlmetrics 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.