Skip to content

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

Potential surface visualization
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