Skip to content

r.futures.validation

Module for land change simulation validation and accuracy assessment

r.futures.validation simulated=name reference=name [original=name] [format=string] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.futures.validation simulated=name reference=name

grass.script.parse_command("r.futures.validation", simulated, reference, original=None, format="plain", verbose=None, quiet=None, superquiet=None)

Example:

gs.parse_command("r.futures.validation", simulated="name", reference="name", format="json")

grass.tools.Tools.r_futures_validation(simulated, reference, original=None, format="plain", verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_futures_validation(simulated="name", reference="name", format="json")

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

Parameters

simulated=name [required]
    Simulated land use raster
reference=name [required]
    Reference land use raster
original=name
    Original land use raster
    Required for kappa simulation
format=string
    Output format
    Allowed values: plain, shell, json
    Default: plain
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

simulated : str, required
    Simulated land use raster
    Used as: input, raster, name
reference : str, required
    Reference land use raster
    Used as: input, raster, name
original : str, optional
    Original land use raster
    Required for kappa simulation
    Used as: input, raster, name
format : str, optional
    Output format
    Allowed values: plain, shell, json
    Default: plain
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

simulated : str | np.ndarray, required
    Simulated land use raster
    Used as: input, raster, name
reference : str | np.ndarray, required
    Reference land use raster
    Used as: input, raster, name
original : str | np.ndarray, optional
    Original land use raster
    Required for kappa simulation
    Used as: input, raster, name
format : str, optional
    Output format
    Allowed values: plain, shell, json
    Default: plain
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 | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned.

Raises:

grass.tools.ToolError: When the tool ended with an error.

DESCRIPTION

Tool r.futures.validation allows to validate land change simulation results. It computes:

  • Allocation disagreement (total and per class), see Pontius et al, 2011
  • Quantity disagreement (total and per class), see Pontius et al, 2011
  • Cohen's Kappa
  • Kappa simulation, see van Vliet et al, 2011

This tool can be used for any number of classes. Input raster original represents the initial conditions and is needed for Kappa simulation and for change detection metrics.

When original is provided and the input rasters contain only binary categories (0 for undeveloped and 1 for developed), the tool additionally computes change detection metrics:

  • Hits: observed change correctly simulated as change
  • Misses: observed change incorrectly simulated as persistence
  • False alarms: observed persistence incorrectly simulated as change
  • Null successes: observed persistence correctly simulated as persistence
  • Figure of merit: hits / (hits + misses + false alarms)
  • Producer's accuracy: hits / (hits + misses)
  • User's accuracy: hits / (hits + false alarms)

These metrics are reported as proportions of the total number of cells. Cells already developed in the original raster are excluded from the change analysis and reported separately as initially developed. When more than two categories are present, these metrics are skipped.

EXAMPLES

Validate land change simulation output by computing quantity and allocation disagreement, kappa statistics, and change detection metrics.

First, reclassify the FUTURES simulation output (where -1 is undeveloped, 0 is initially developed, and 1 to N is the step when a cell became developed) to binary (0 = undeveloped, 1 = developed). Create a file reclass_rules.txt with the following content:

-1 = 0 undeveloped
0 thru 1000 = 1 developed

Then reclassify and run the validation:

r.reclass input=simulated_2016 output=simulated_2016_reclass rules=reclass_rules.txt
r.futures.validation simulated=simulated_2016_reclass reference=reference_2016 \
    original=orig_2001 format=json

Example output:

{
    "quantity_class_0": 0.015,
    "quantity_class_1": 0.015,
    "allocation_class_0": 0.023,
    "allocation_class_1": 0.023,
    "total_quantity": 0.015,
    "total_allocation": 0.023,
    "kappa": 0.852,
    "kappasimulation": 0.15,
    "misses": 0.032,
    "hits": 0.04,
    "false_alarms": 0.021,
    "null_successes": 0.507,
    "figure_of_merit": 0.4301,
    "producer": 0.5556,
    "user": 0.6557,
    "initially_developed": 0.4
}

REFERENCES

Validation references:

FUTURES 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.devpressure, r.futures.potential, r.futures.potsurface, r.futures.demand, r.futures.calib, r.futures.gridvalidation

For alternative validation metrics see r.confusionmatrix, r.kappa

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.validation source code (history)
Latest change: Friday Apr 17 16:26:46 2026 in commit bc11ef4