Skip to main content

sprawlmetrics

PyPI Python pipeline License: MIT

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=4 is available.
  • LEI buffer = morphological dilation of the patch by buffer_cells cells (square or disc) minus the patch itself; cells outside the raster or the study area are left out. A_v counts 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=True also 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 exactly 3/π ≈ 0.955 and 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.0},
  url     = {https://gitlab.com/geophilo1/sprawlmetrics_sdk}
}

License

MIT, see LICENSE.

Metadata

Release files for sprawlmetrics 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 sprawlmetrics 0.1.0
File Size Uploaded Provenance Actions
sprawlmetrics-0.1.0.tar.gz 46.4 kB Without provenance Details for sprawlmetrics-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 84.3 kB

Release files / sprawlmetrics-0.1.0.tar.gz

Download URL sprawlmetrics-0.1.0.tar.gz
Size 46.4 kB
Tags Source
SHA-256 checksum
How to use checksums
e694234cce05b1c5f0898c0eb57c71dc99c5e2cda6ad6819a46a5f5b8012a659
BLAKE2b-256 checksum
How to use checksums
ac6201495db55d3668b4172503180c090230cf4fb3c5fc16475302fb8a2033fc
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.0-py3-none-any.whl

Download URL sprawlmetrics-0.1.0-py3-none-any.whl
Size 37.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9d0585e45e8656007ca280e5b11bbce5342a2208bda510c44fe1522a8d771ed8
BLAKE2b-256 checksum
How to use checksums
9d6103a8a3af2a7b75a6ca10b3711ecef3bb0f42ebcc888959b9b5cc1ebeaad3
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.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