Skip to content

r.futures.simulation

Wrapper for r.futures.pga to ensure forward compatibility.

Simulates landuse change using FUTure Urban-Regional Environment Simulation (FUTURES).

r.futures.simulation [-s] developed=name subregions=name [subregions_potential=name] predictors=name [,name,...] development_pressure=name n_dev_neighbourhood=integer development_pressure_approach=string gamma=float scaling_factor=float output=name [output_series=basename] devpot_params=name demand=name [separator=character] patch_sizes=name num_neighbors=integer discount_factor=float seed_search=string compactness_mean=float compactness_range=float [num_steps=integer] [potential_weight=name] [incentive_power=float] [random_seed=integer] [memory=float] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.futures.simulation developed=name subregions=name predictors=name development_pressure=name n_dev_neighbourhood=integer development_pressure_approach=gravity gamma=float scaling_factor=float output=name devpot_params=name demand=name patch_sizes=name num_neighbors=4 discount_factor=float seed_search=probability compactness_mean=float compactness_range=float

grass.script.run_command("r.futures.simulation", developed, subregions, subregions_potential=None, predictors, development_pressure, n_dev_neighbourhood, development_pressure_approach="gravity", gamma, scaling_factor, output, output_series=None, devpot_params, demand, separator="comma", patch_sizes, num_neighbors=4, discount_factor, seed_search="probability", compactness_mean, compactness_range, num_steps=None, potential_weight=None, incentive_power=1, random_seed=None, memory=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.futures.simulation", developed="name", subregions="name", predictors="name", development_pressure="name", n_dev_neighbourhood=integer, development_pressure_approach="gravity", gamma=float, scaling_factor=float, output="name", devpot_params="name", demand="name", patch_sizes="name", num_neighbors=4, discount_factor=float, seed_search="probability", compactness_mean=float, compactness_range=float)

Parameters

developed=name [required]
    Raster map of developed areas (=1), undeveloped (=0) and excluded (no data)
subregions=name [required]
    Raster map of subregions
subregions_potential=name
    Raster map of subregions used with potential file
    If not specified, the raster specified in subregions parameter is used
predictors=name [,name,...] [required]
    Names of predictor variable raster maps
    Listed in the same order as in the development potential table
development_pressure=name [required]
    Raster map of development pressure
n_dev_neighbourhood=integer [required]
    Size of square used to recalculate development pressure
development_pressure_approach=string [required]
    Approaches to derive development pressure
    Allowed values: occurrence, gravity, kernel
    Default: gravity
gamma=float [required]
    Influence of distance between neighboring cells
scaling_factor=float [required]
    Scaling factor of development pressure
output=name [required]
    State of the development at the end of simulation
output_series=basename
    Basename for raster maps of development generated after each step
    Name for output basename raster map(s)
devpot_params=name [required]
    CSV file with development potential parameters for each region
    Each line should contain region ID followed by parameters (intercepts, development pressure, other predictors). First line is ignored, so it can be used for header
demand=name [required]
    CSV file with number of cells to convert for each step and subregion
separator=character
    Field separator
    Separator used in input CSV files
    Default: comma
patch_sizes=name [required]
    File containing list of patch sizes to use
num_neighbors=integer [required]
    The number of neighbors to be used for patch generation (4 or 8)
    Allowed values: 4, 8
    Default: 4
discount_factor=float [required]
    Discount factor of patch size
seed_search=string [required]
    The way location of a seed is determined (1: uniform distribution 2: development probability)
    Allowed values: random, probability
    Default: probability
compactness_mean=float [required]
    Mean value of patch compactness to control patch shapes
compactness_range=float [required]
    Range of patch compactness to control patch shapes
num_steps=integer
    Number of steps to be simulated
potential_weight=name
    Raster map of weights altering development potential
    Values need to be between -1 and 1, where negative locally reducesprobability and positive increases probability.
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
    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.
memory=float
    Memory in GB
-s
    Generate random seed (result is non-deterministic)
    Automatically generates random seed for random number generator (use when you don't want to provide the seed option)
--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

developed : str, required
    Raster map of developed areas (=1), undeveloped (=0) and excluded (no data)
    Used as: input, raster, name
subregions : str, required
    Raster map of subregions
    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
predictors : str | list[str], required
    Names of predictor variable raster maps
    Listed in the same order as in the development potential table
    Used as: input, raster, name
development_pressure : str, required
    Raster map of development pressure
    Used as: input, raster, name
n_dev_neighbourhood : int, required
    Size of square used to recalculate development pressure
development_pressure_approach : str, required
    Approaches to derive development pressure
    Allowed values: occurrence, gravity, kernel
    Default: gravity
gamma : float, required
    Influence of distance between neighboring cells
scaling_factor : float, required
    Scaling factor of development pressure
output : str, required
    State of the development at the end of simulation
    Used as: output, raster, name
output_series : str, optional
    Basename for raster maps of development generated after each step
    Name for output basename raster map(s)
    Used as: output, raster, basename
devpot_params : str, required
    CSV file with development potential parameters for each region
    Each line should contain region ID followed by parameters (intercepts, development pressure, other predictors). First line is ignored, so it can be used for header
    Used as: input, file, name
demand : str, required
    CSV file with number of cells to convert for each step and subregion
    Used as: input, file, name
separator : str, optional
    Field separator
    Separator used in input CSV files
    Used as: input, separator, character
    Default: comma
patch_sizes : str, required
    File containing list of patch sizes to use
    Used as: input, file, name
num_neighbors : int, required
    The number of neighbors to be used for patch generation (4 or 8)
    Allowed values: 4, 8
    Default: 4
discount_factor : float, required
    Discount factor of patch size
seed_search : str, required
    The way location of a seed is determined (1: uniform distribution 2: development probability)
    Allowed values: random, probability
    Default: probability
compactness_mean : float, required
    Mean value of patch compactness to control patch shapes
compactness_range : float, required
    Range of patch compactness to control patch shapes
num_steps : int, optional
    Number of steps to be simulated
potential_weight : str, optional
    Raster map of weights altering development potential
    Values need to be between -1 and 1, where negative locally reducesprobability and positive increases probability.
    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
    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.
memory : float, optional
    Memory in GB
flags : str, optional
    Allowed values: s
    s
        Generate random seed (result is non-deterministic)
        Automatically generates random seed for random number generator (use when you don't want to provide the seed option)
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.pga will be renamed to r.futures.simulation. This module is only a wrapper for r.futures.pga for forward compatibility.

SEE ALSO

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

REFERENCES

AUTHOR

Anna Petrasova, NCSU GeoForAll

SOURCE CODE

Available at: r.futures.simulation source code (history)
Latest change: Friday Feb 21 10:10:05 2025 in commit 7d78fe3