Land Use Projector

A Python tool for projecting land-use change. It fits development potential from land-use maps and driver rasters (random forest, gradient boosting, or a neural network), then allocates the demanded change with a cellular automaton: patch-based, or with self-adaptive inertia and roulette competition. The methods follow Liang et al. (2021) and Liu et al. (2017); see Citing.

Install

pip install landuse-projector            # Python 3.10 or newer
pip install "landuse-projector[viz,tune]"  # optional plots and tuning

Check it with lup --version.

Quick start

Write experiment.yaml next to a data/ folder with your maps and a folder of driver rasters:

classes: {1: Cropland, 2: Forest, 3: Built-up}
calibration: {t0: data/lulc_2010.tif, t1: data/lulc_2020.tif}
potential: {method: leas, drivers: data/drivers, n_trees: 50, sample_rate: 0.05}
demand: {method: from_map, map: data/lulc_2030_target.tif}
allocation:
  method: cars
  start: data/lulc_2020.tif
  neighbor_weights: [1.0, 0.5, 0.5]
  transition_matrix: [[1,1,1],[1,1,1],[0,0,1]]
validate: {observed: data/lulc_2030_target.tif}
seed: 1
runs: 3
output: out

Then run lup run experiment.yaml. Each run writes its simulation map and metrics under out/, with a summary.csv (one row per run), a provenance.json that records the config and versions, and a run.log. The same config and seed give identical results for any thread count.

Other commands: lup convert, expansion, persist, leas, cars, validate kappa, validate fom, benchmark, tune, import-cars. Run lup --help for all of them.

Documentation

• docs/guide.md: the config reference and commands.

Citing

Cite this software with CITATION.cff (GitHub shows a "Cite this repository" button). For the methodology, cite:

Liang, X., Guan, Q., Clarke, K. C., Liu, S., Wang, B., Yao, Y. (2021). Understanding the drivers of sustainable land expansion using a patch-generating land use simulation (PLUS) model: A case study in Wuhan, China. Computers, Environment and Urban Systems, 85, 101569.

The neural-network potential (potential.method: ann) and the self-adaptive inertia allocator (allocation.method: inertia) follow the method of the FLUS model:

Liu, X., Liang, X., Li, X., Xu, X., Ou, J., Chen, Y., Li, S., Wang, S., Pei, F. (2017). A future land use simulation model (FLUS) for simulating multiple land use scenarios by coupling human and natural effects. Landscape and Urban Planning, 168, 94-116.

License

BSD 3-Clause. See LICENSE.