Skip to content

r.futures.potential

Module for computing development potential as input to r.futures.pga

r.futures.potential [-d] input=name output=name [separator=character] columns=name [,name,...] developed_column=name subregions_column=name [random_column=string] [fixed_columns=string [,string,...]] [min_variables=integer] [max_variables=integer] nprocs=integer [dredge_output=name] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.futures.potential input=name output=name columns=name developed_column=name subregions_column=name nprocs=1

grass.script.run_command("r.futures.potential", input, output, separator="comma", columns, developed_column, subregions_column, random_column=None, fixed_columns=None, min_variables=1, max_variables=None, nprocs=1, dredge_output=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.futures.potential", input="name", output="name", columns="name", developed_column="name", subregions_column="name", nprocs=1)

Parameters

input=name [required]
    Name of input vector map
    Or data source for direct OGR access
output=name [required]
    Output Potential file
separator=character
    Separator used in output file
    Special characters: pipe, comma, space, tab, newline
    Default: comma
columns=name [,name,...] [required]
    Names of attribute columns representing sampled predictors
developed_column=name [required]
    Name of attribute column representing development
subregions_column=name [required]
    Name of attribute column representing subregions
random_column=string
    Random effect predictor
fixed_columns=string [,string,...]
    Predictor columns that will be used for all models when dredging
min_variables=integer
    Minimum number of predictors considered
    Allowed values: 1-20
    Default: 1
max_variables=integer
    Maximum number of predictors considered
    Allowed values: 1-20
nprocs=integer [required]
    Number of parallel processes for dredging
    Allowed values: 1-50
    Default: 1
dredge_output=name
    Output CSV file summarizing all models
-d
    Use dredge function to find best model
--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

input : str, required
    Name of input vector map
    Or data source for direct OGR access
    Used as: input, vector, name
output : str, required
    Output Potential file
    Used as: output, file, name
separator : str, optional
    Separator used in output file
    Special characters: pipe, comma, space, tab, newline
    Used as: input, separator, character
    Default: comma
columns : str | list[str], required
    Names of attribute columns representing sampled predictors
    Used as: input, dbcolumn, name
developed_column : str, required
    Name of attribute column representing development
    Used as: input, dbcolumn, name
subregions_column : str, required
    Name of attribute column representing subregions
    Used as: input, dbcolumn, name
random_column : str, optional
    Random effect predictor
fixed_columns : str | list[str], optional
    Predictor columns that will be used for all models when dredging
min_variables : int, optional
    Minimum number of predictors considered
    Allowed values: 1-20
    Default: 1
max_variables : int, optional
    Maximum number of predictors considered
    Allowed values: 1-20
nprocs : int, required
    Number of parallel processes for dredging
    Allowed values: 1-50
    Default: 1
dredge_output : str, optional
    Output CSV file summarizing all models
    Used as: output, file, name
flags : str, optional
    Allowed values: d
    d
        Use dredge function to find best model
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.potential implements POTENTIAL submodel as a part of FUTURES land change model. POTENTIAL is implemented using a set of coefficients that relate a selection of site suitability factors to the probability of a place becoming developed. This is implemented using the parameter table in combination with maps of those site suitability factors (mapped predictors). The coefficients are obtained by conducting multilevel logistic regression in R with package lme4 where the coefficients may vary by subregions. The best model is selected automatically using dredge function from package MuMIn (which has numerous caveats).

Module r.futures.potential can run it two modes. Without the -d flag, it uses all the given predictors to construct the model. With -d flag, it evaluates all the different combinations of predictors and picks the best one based on AIC.

Format

The format of the output file is a CSV file (use option separator to change default separator comma). The header contains the names of the predictor maps and the first column contains the identifiers of the subregions. The order of columns is important, the second column represents intercept, the third development pressure and then the predictors. Therefore the development pressure column must be specified as the first column in option columns.

ID,Intercept,devpressure_0_5,slope,road_dens_perc,forest_smooth_perc,...
37037,-1.873,12.595,-0.0758,0.0907,-0.0223,...
37063,-2.039,12.595,-0.0758,0.0907,-0.0223,...
37069,-1.795,12.595,-0.0758,0.0907,-0.0223,...
37077,-1.264,12.595,-0.0758,0.0907,-0.0223,...
37085,-1.925,12.595,-0.0758,0.0907,-0.0223,...
...

NOTES

Note that this module is designed to automate the FUTURES workflow by brute-force selection of model, which has numerous caveats.

In case there is only one subregion, R function glm is used instead of glmer.

EXAMPLES

SEE ALSO

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

REFERENCES

AUTHOR

Anna Petrasova, NCSU GeoForAll

SOURCE CODE

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