Skip to content

r.futures.calib

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

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] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.futures.calib development_start=name development_end=name patch_threshold=0 patch_sizes=name nprocs=1 subregions=name demand=name

grass.script.run_command("r.futures.calib", development_start, development_end, repeat=None, compactness_mean=None, compactness_range=None, discount_factor=None, patch_threshold=0, patch_sizes, calibration_results=None, nprocs=1, random_seed=1, development_pressure=None, incentive_power=None, potential_weight=None, predictors=None, n_dev_neighbourhood=None, devpot_params=None, num_neighbors=None, seed_search=None, development_pressure_approach=None, gamma=None, scaling_factor=None, num_steps=None, subregions, subregions_potential=None, demand=None, memory=None, separator="comma", flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.futures.calib", development_start="name", development_end="name", patch_threshold=0, patch_sizes="name", nprocs=1, subregions="name", demand="name")

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
    Allowed values: 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)
    Allowed values: 4, 8
seed_search=string
    The way location of a seed is determined
    Allowed values: random, probability
    random: uniform distribution
    probability: development potential
development_pressure_approach=string
    Approaches to derive development pressure
    Allowed values: 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
-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
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

development_start : str, required
    Name of input binary raster map representing development in the beginning
    Raster map of developed areas (=1), undeveloped (=0) and excluded (no data)
    Used as: input, raster, name
development_end : str, required
    Name of input binary raster map representing development in the end
    Raster map of developed areas (=1), undeveloped (=0) and excluded (no data)
    Used as: input, raster, name
repeat : int, optional
    How many times is the simulation repeated
compactness_mean : float | list[float] | str, optional
    Patch compactness mean to be tested
compactness_range : float | list[float] | str, optional
    Patch compactness range to be tested
discount_factor : float | list[float] | str, optional
    Patch size discount factor
patch_threshold : float, required
    Minimum size of a patch in meters squared
    Default: 0
patch_sizes : str, required
    Output file with patch sizes
    Used as: output, file, name
calibration_results : str, optional
    Output file with calibration results
    Used as: output, file, name
nprocs : int, required
    Number of parallel processes
    Default: 1
random_seed : int, optional
    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 : str, optional
    Raster map of development pressure
    Used as: input, raster, name
incentive_power : float, optional
    Exponent to transform probability values p to p^x to simulate infill vs. sprawl
    Values > 1 encourage infill, < 1 urban sprawl
    Allowed values: 0-10
potential_weight : str, optional
    Raster map of weights altering development potential
    Values need to be between -1 and 1, where negative locally reduces probability and positive increases probability.
    Used as: input, raster, name
predictors : str | list[str], optional
    Names of predictor variable raster maps
    Used as: input, raster, name
n_dev_neighbourhood : int, optional
    Size of square used to recalculate development pressure
devpot_params : str | list[str], optional
    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
    Used as: input, file, name
num_neighbors : int, optional
    The number of neighbors to be used for patch generation (4 or 8)
    Allowed values: 4, 8
seed_search : str, optional
    The way location of a seed is determined
    Allowed values: random, probability
    random: uniform distribution
    probability: development potential
development_pressure_approach : str, optional
    Approaches to derive development pressure
    Allowed values: occurrence, gravity, kernel
gamma : float, optional
    Influence of distance between neighboring cells
scaling_factor : float, optional
    Scaling factor of development pressure
num_steps : int, optional
    Number of steps to be simulated
subregions : str, required
    Raster map of subregions with categories starting with 1
    Used as: input, raster, name
subregions_potential : str, optional
    Raster map of subregions used with potential file
    If not specified, the raster specified in subregions parameter is used
    Used as: input, raster, name
demand : str, optional
    Control file with number of cells to convert
    Used as: input, file, name
memory : float, optional
    Memory for single run in GB
separator : str, optional
    Separator used in output patch file
    Special characters: pipe, comma, space, tab, newline
    Used as: input, separator, character
    Default: comma
flags : str, optional
    Allowed values: s, l
    s
        Derive patch sizes per subregions
    l
        Only create patch size distribution file
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

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.

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

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:

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.

NOTES

This module depends on addon r.object.geometry. Please install it with g.extension:

g.extension r.object.geometry

EXAMPLES

SEE ALSO

FUTURES overview, r.futures.pga, r.futures.devpressure, r.futures.demand, r.futures.potential, r.sample.category, r.object.geometry

REFERENCES

AUTHOR

Anna Petrasova, NCSU GeoForAll

SOURCE CODE

Available at: r.futures.calib source code (history)
Latest change: Thursday Mar 20 21:36:57 2025 in commit 7286ecf