r.futures.potsurface
Module for computing development potential surface from CSV file created by r.futures.potential and predictors
r.futures.potsurface input=name subregions=name output=name [separator=character] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.futures.potsurface input=name subregions=name output=name
grass.script.run_command("r.futures.potsurface", input, subregions, output, separator="comma", overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.run_command("r.futures.potsurface", input="name", subregions="name", output="name")
grass.tools.Tools.r_futures_potsurface(input, subregions, output, separator="comma", overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.r_futures_potsurface(input="name", subregions="name", output="name")
This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.
Parameters
input=name [required]
CSV file with coefficients
subregions=name [required]
Raster map of subregions
output=name [required]
Output probability raster
separator=character
Separator used in input CSV file
Special characters: pipe, comma, space, tab, newline
Default: comma
--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
CSV file with coefficients
Used as: input, file, name
subregions : str, required
Raster map of subregions
Used as: input, raster, name
output : str, required
Output probability raster
Used as: output, raster, name
separator : str, optional
Separator used in input CSV file
Special characters: pipe, comma, space, tab, newline
Used as: input, separator, character
Default: comma
overwrite : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
input : str | io.StringIO, required
CSV file with coefficients
Used as: input, file, name
subregions : str | np.ndarray, required
Raster map of subregions
Used as: input, raster, name
output : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
Output probability raster
Used as: output, raster, name
separator : str, optional
Separator used in input CSV file
Special characters: pipe, comma, space, tab, newline
Used as: input, separator, character
Default: comma
overwrite : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
Returns:
result : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned. If an array type (e.g., np.ndarray) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.
Raises:
grass.tools.ToolError: When the tool ended with an error.
DESCRIPTION
Tool r.futures.potsurface is a support tool for computing development probability surface based on maps and coefficients selected by r.futures.potential. It computes the initial probability surface used in the patch growing algorithm in r.futures.simulation. It is not necessary to use this tool, however it is useful to inspect the potential surface to better understand the input data and how the predictors influence the probability. The values range from 0 (unlikely to be developed) to 1 (high probability of development).
The inputs are the output file from r.futures.potential and the name of the subregions raster map.
EXAMPLES
r.futures.potsurface input=potential.csv subregions=counties output=pot_surface

Figure: We can visualize the potential surface in 3D and drape
raster representing developed (red) and undeveloped (green) cells
over it.
REFERENCES
- 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
- Sanchez, G.M., A. Petrasova, A., M.M. Skrip, E.L. Collins, M.A. Lawrimore, J.B. Vogler, A. Terando, J. Vukomanovic, H. Mitasova, and R.K. Meentemeyer. 2023. Spatially interactive modeling of land change identifies location-specific adaptations most likely to lower future flood risk. Sci Rep 13, 18869. DOI: https://doi.org/10.1038/s41598-023-46195-9
SEE ALSO
FUTURES, r.futures.simulation, r.futures.parallelpga, r.futures.potential, r.futures.devpressure, r.futures.demand, r.futures.calib, r.futures.gridvalidation, r.futures.validation, r.sample.category
AUTHORS
Corresponding author: Anna Petrasova, akratoc ncsu edu, Center for Geospatial Analytics, NCSU
Original standalone version: Ross K. Meentemeyer, Wenwu Tang, Monica A. Dorning, John B. Vogler, Nik J. Cunniffe, Douglas A. Shoemaker (Department of Geography and Earth Sciences, UNC Charlotte) Jennifer A. Koch (Center for Geospatial Analytics, NCSU)
Port to GRASS and GRASS-specific additions: Vaclav Petras, NCSU GeoForAll
Development pressure, demand, calibration, validation, preprocessing tools and maintenance: Anna Petrasova, NCSU GeoForAll
Climate forcing submodel:
Anna Petrasova,
NCSU GeoForAll
Georgina Sanchez,
Center for Geospatial Analytics, NCSU
Zoning:
Margaret Lawrimore,
Center for Geospatial Analytics, NCSU
Anna Petrasova,
NCSU GeoForAll
SOURCE CODE
Available at: r.futures.potsurface source code
(history)
Latest change: Friday Apr 17 16:26:46 2026 in commit bc11ef4