Metadata-Version: 2.5
Name: landuse-projector
Version: 0.3.0
Summary: Land-use change projection with patch-generating cellular automata
Project-URL: Homepage, https://github.com/NarenKarthikBM/landuse-projector
Project-URL: Source, https://github.com/NarenKarthikBM/landuse-projector
Project-URL: Issues, https://github.com/NarenKarthikBM/landuse-projector/issues
Project-URL: Documentation, https://github.com/NarenKarthikBM/landuse-projector/tree/main/docs
Author: Naren Karthik B M
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: GIS,cellular automata,land use,land-use change,random forest,simulation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Requires-Dist: numba>=0.61
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6
Requires-Dist: rasterio>=1.3.10
Requires-Dist: scikit-learn>=1.5
Requires-Dist: scipy>=1.13
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: matplotlib>=3.8; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: tune
Requires-Dist: optuna>=3.6; extra == 'tune'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == 'viz'
Description-Content-Type: text/markdown

# 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:

```yaml
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`.
