GRASS logo


r.futures.calib - Module for calibrating patch characteristics used as input to r.futures.pga


raster, patch


r.futures.calib --help
r.futures.calib [-l] 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 [development_pressure=name] [incentive_power=float] [constrain_weight=name] [predictors=name[,name,...]] [n_dev_neighbourhood=integer] [devpot_params=name[,name,...]] [num_neighbors=integer] [seed_search=integer] [development_pressure_approach=string] [gamma=float] [scaling_factor=float] [num_steps=integer] subregions=name [demand=name] [--overwrite] [--help] [--verbose] [--quiet] [--ui]


Only create patch size distribution file
Allow output files to overwrite existing files
Print usage summary
Verbose module output
Quiet module output
Force launching GUI dialog


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)
How many times is the simulation repeated
Patch compactness mean to be tested
Patch compactness range to be tested
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
Output file with calibration results
nprocs=integer [required]
Number of parallel processes
Default: 1
Raster map of development pressure
Exponent to transform probability values p to p^x to simulate infill vs. sprawl
Values > 1 encourage infill, < 1 urban sprawl
Options: 0-10
Default: 1
Name of raster map representing development potential constraint weight for scenarios
Values must be between 0 and 1, 1 means no constraint
Names of predictor variable raster maps
Size of square used to recalculate development pressure
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
The number of neighbors to be used for patch generation (4 or 8)
Options: 4, 8
The way location of a seed is determined (1: uniform distribution 2: development probability)
Options: 1, 2
Approaches to derive development pressure
Options: occurrence, gravity, kernel
Influence of distance between neighboring cells
Scaling factor of development pressure
Number of steps to be simulated
subregions=name [required]
Raster map of subregions with categories starting with 1
Control file with number of cells to convert

Table of contents


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.

Patch size

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

Patch compactness

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 input and output

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:
Optimal values can be found by visual examination of the second and fifth columns.

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 region, 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.



FUTURES, r.futures.pga, r.futures.devpressure, r.futures.demand, r.futures.potential, r.sample.category



Anna Petrasova, NCSU OSGeoREL

Last changed: $Date: 2017-07-31 19:51:01 +0200 (Mon, 31 Jul 2017) $


Available at: r.futures.calib source code (history)

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2018 GRASS Development Team, GRASS GIS 7.4.1svn Reference Manual