NAME
r.futures.calib - Module for calibrating patch characteristics used as input to r.futures.pga
KEYWORDS
raster,
patch
SYNOPSIS
r.futures.calib
r.futures.calib --help
r.futures.calib [-sl] development_start=name development_end=name [repeat=integer] [compactness_mean=float[,float,...]] [compactness_range=float[,float,...]] [discount_factor=float[,float,...]] patch_threshold=float patch_sizes=name [calibration_results=name] nprocs=integer [random_seed=integer] [development_pressure=name] [incentive_power=float] [potential_weight=name] [predictors=name[,name,...]] [n_dev_neighbourhood=integer] [devpot_params=name[,name,...]] [num_neighbors=integer] [seed_search=string] [development_pressure_approach=string] [gamma=float] [scaling_factor=float] [num_steps=integer] subregions=name [subregions_potential=name] [demand=name] [memory=float] [separator=character] [--overwrite] [--help] [--verbose] [--quiet] [--ui]
Flags:
- -s
- Derive patch sizes per subregions
- -l
- Only create patch size distribution file
- --overwrite
- Allow output files to overwrite existing files
- --help
- Print usage summary
- --verbose
- Verbose module output
- --quiet
- Quiet module output
- --ui
- Force launching GUI dialog
Parameters:
- development_start=name [required]
- Name of input binary raster map representing development in the beginning
- Raster map of developed areas (=1), undeveloped (=0) and excluded (no data)
- development_end=name [required]
- Name of input binary raster map representing development in the end
- Raster map of developed areas (=1), undeveloped (=0) and excluded (no data)
- repeat=integer
- How many times is the simulation repeated
- compactness_mean=float[,float,...]
- Patch compactness mean to be tested
- compactness_range=float[,float,...]
- Patch compactness range to be tested
- discount_factor=float[,float,...]
- Patch size discount factor
- patch_threshold=float [required]
- Minimum size of a patch in meters squared
- Default: 0
- patch_sizes=name [required]
- Output file with patch sizes
- calibration_results=name
- Output file with calibration results
- nprocs=integer [required]
- Number of parallel processes
- Default: 1
- random_seed=integer
- Seed for random number generator
- The same seed can be used to obtain same results or random seed can be generated by other means.
- Default: 1
- development_pressure=name
- Raster map of development pressure
- incentive_power=float
- Exponent to transform probability values p to p^x to simulate infill vs. sprawl
- Values > 1 encourage infill, < 1 urban sprawl
- Options: 0-10
- potential_weight=name
- Raster map of weights altering development potential
- Values need to be between -1 and 1, where negative locally reduces probability and positive increases probability.
- predictors=name[,name,...]
- Names of predictor variable raster maps
- n_dev_neighbourhood=integer
- Size of square used to recalculate development pressure
- devpot_params=name[,name,...]
- Development potential parameters for each region
- Each line should contain region ID followed by parameters. Values are separated by whitespace (spaces or tabs). First line is ignored, so it can be used for header
- num_neighbors=integer
- The number of neighbors to be used for patch generation (4 or 8)
- Options: 4, 8
- seed_search=string
- The way location of a seed is determined
- Options: random, probability
- random: uniform distribution
- probability: development potential
- development_pressure_approach=string
- Approaches to derive development pressure
- Options: occurrence, gravity, kernel
- gamma=float
- Influence of distance between neighboring cells
- scaling_factor=float
- Scaling factor of development pressure
- num_steps=integer
- Number of steps to be simulated
- subregions=name [required]
- Raster map of subregions with categories starting with 1
- subregions_potential=name
- Raster map of subregions used with potential file
- If not specified, the raster specified in subregions parameter is used
- demand=name
- Control file with number of cells to convert
- memory=float
- Memory for single run in GB
- separator=character
- Separator used in output patch file
- Special characters: pipe, comma, space, tab, newline
- Default: comma
Module
r.futures.calibration is part of
FUTURES,
land change model.
It is used for calibrating certain input variables for patch growing
algorithm
r.futures.pga, specifically patch size and compactness parameters.
The calibration process is conducted to match observed urban growth patterns
to those simulated by the model, including the sizes and shapes of new development.
The calibration is achieved by varying the values of the patch parameters,
comparing the distribution of simulated patch sizes to those observed
for the reference period, and choosing the values that provide the closest match.
For the details about calibration see below.
This module depends on addon
r.object.geometry.
As part of the calibration process, module
r.futures.calibration
produces patch size distribution file specified in
patch_sizes parameter,
which contains sizes (in cells) of all new patches observed
in the reference period. The format of this file is one patch size per line.
If flag
-s is used, patch sizes will be analyzed per each subregion,
and written as a CSV file with columns representing patch library for each
subregion and header containing
the categories of subregions.
FUTURES uses this file to determine the size of the simulated patches.
Often the length of the reference time period does not match
the time period which we are trying to simulate.
We use the
discount factor to alter the size of simulated patches
so that after the reference period they closely match the observed patterns.
During the simulation, this factor is multiplied by the patch sizes listed in the patch size file.
The values of
discount factor can vary between 0 and 1,
for example value 0.6 was used by Meentemeyer et al. 2013.
The shapes of patches simulated by FUTURES are governed
by the patch compactness parameter (Meentemeyer et al. 2013, Eq. 1).
This variable doesn't represent actual patch compactness, it is rather
an adjustable scaling factor that controls patch compactness
through a distance decay effect.
By specifying the mean and range of this parameter in module
r.futures.pga, we allow for variation in patch shape.
As the value of the parameter increases, patches become more compact.
Calibration is achieved by varying the values specified in
compactness_mean
and
compactness_range and comparing the distribution
of the simulated patch compactness (computed as
patch perimeter / (2 * sqrt(pi * area)))
to those observed for the reference period.
Meentemeyer et al. 2013 used mean 0.4 and range 0.08.
Calibration requires the development binary raster in the beginning
and end of the reference period (
development_start and
development_end)
to derive the patch sizes and compactness.
It is possible to set the minimum number of cells of a patch in
patch_threshold
to ignore too small patches.
For each combination of values provided in
compactness_mean,
compactness_range and
discount_factor, it runs
module
r.futures.pga which creates new development pattern.
From this new simulated development, patch characteristics are derived
and compared with the observed characteristics by histogram comparison
and an error (histogram distance) is computed.
Since
r.futures.pga is a stochastic module, multiple
runs (specified in
repeat) are recommended, the error is then averaged.
Calibration results are saved in a CSV file specified in
calibration_results:
discount_factor,compactness_mean,compactness_range,area_error,compactness_error,combined_error
0.10,0.60,0.10,0.92,0.70,0.81
0.10,0.80,0.10,0.92,0.76,0.84
0.10,0.20,0.10,0.93,0.78,0.85
0.10,0.50,0.10,0.89,0.82,0.86
0.10,1.00,0.10,0.94,0.84,0.89
0.10,0.90,0.10,0.92,0.86,0.89
0.10,0.70,0.10,0.96,0.83,0.90
0.10,0.10,0.10,1.00,1.00,1.00
The first three columns represent the combination of calibrated parameters.
The last column is the average of the normalized area and compactness errors
for each combination. The first line shows the combination with lowest error.
Providing too many values in compactness_mean,
compactness_range and discount_factor results in very long computation.
Therefore it is recommended to run r.futures.calibration
on high-end computers, with more processes running in parallel using nprocs parameter.
Also, it can be run on smaller regions, under the assumption
that patch sizes and shapes are close to being consistent across the entire study area.
For all other parameters not mentioned above, please refer to
r.futures.pga documentation.
This module depends on addon
r.object.geometry.
Please install it with g.extension:
g.extension r.object.geometry
FUTURES overview,
r.futures.pga,
r.futures.devpressure,
r.futures.demand,
r.futures.potential,
r.sample.category,
r.object.geometry
-
Meentemeyer, R. K., Tang, W., Dorning, M. A., Vogler, J. B., Cunniffe, N. J., & Shoemaker, D. A. (2013).
FUTURES: Multilevel Simulations of Emerging
Urban-Rural Landscape Structure Using a Stochastic Patch-Growing Algorithm.
Annals of the Association of American Geographers, 103(4), 785-807.
DOI: 10.1080/00045608.2012.707591
- Dorning, M. A., Koch, J., Shoemaker, D. A., & Meentemeyer, R. K. (2015).
Simulating urbanization scenarios reveals
tradeoffs between conservation planning strategies.
Landscape and Urban Planning, 136, 28-39.
DOI: 10.1016/j.landurbplan.2014.11.011
- Petrasova, A., Petras, V., Van Berkel, D., Harmon, B. A., Mitasova, H., & Meentemeyer, R. K. (2016).
Open Source Approach to Urban Growth Simulation.
Int. Arch. Photogramm. Remote Sens. Spatial Inf. Sci., XLI-B7, 953-959.
DOI: 10.5194/isprsarchives-XLI-B7-953-2016
Anna Petrasova,
NCSU GeoForAll
SOURCE CODE
Available at:
r.futures.calib source code
(history)
Latest change: Wednesday Mar 30 10:17:35 2022 in commit: 25b0a9981b66c443a1c1af1d5f26182c93268b45
Main index |
Raster index |
Topics index |
Keywords index |
Graphical index |
Full index
© 2003-2024
GRASS Development Team,
GRASS GIS 8.4.1dev Reference Manual