differenceMR {diffeR}

calculates difference metrics between a reference map and a comparison map both consecutively aggregated at multiple resolutions

Description

calculates quantity, exchange and shift components of difference, as well as the overall difference, between a comparison raster map (or map at time t), and a reference raster map (or map at time t+1), both consecutively aggregated at multiple resolutions.

Quantity difference is defined as the amount of difference between the reference map and a comparison map that is due to the less than maximum match in the proportions of the categories. Exchange consists of a transition from category i to category j in some pixels and a transition from category j to category i in an identical number of other pixels. Shift refers to the difference remaining after subtracting quantity difference and exchange from the overall difference.

Usage

differenceMR(comp, ref, eval = "multiple", percent = TRUE, fact = 2, 
             population = NULL)

Arguments

comp

object of class SpatRaster corresponding to the comparison map, or map at time t

ref

object of class SpatRaster corresponding to the reference map, or map at time t+1

eval

default "original", return difference metrics between the input raster maps at the original resolution; if "multiple", return difference metrics at multiple resolutions aggregated according to a geometric sequence

percent

logical. If TRUE, output value is given as percentage. If FALSE, output value is given as proportion (0 to 1)

fact

positive integer. Aggregation factor expressed as number of cells in each direction (horizontally and vertically). Or two integers (horizontal and vertical aggregation factor). See aggregate() in the terra package for details

population

an n x 2 matrix provided to correct the sample count to population count in the square contingency table. See Details below

Details

For correcting the sample count to population count in the square contingency table, assuming a stratified random sampling, an n (number of categories) by 2 matrix can be provided in the population argument. The first column of population must contains integer identifiers of each category, corresponding to the categories in the comparison map (or map at time t) and reference map (or map at time t+1). The second column corresponds to the population totals for each map category

Value

data.frame containing quantity, exchange and shift components of difference, as well as the overall difference, between the comparison map and the reference map at multiple resolutions

References

Pontius Jr., R.G., Millones, M. 2011. Death to Kappa: birth of quantity disagreement and allocation disagreement for accuracy assessment. International Journal of Remote Sensing 32 (15), 4407-4429.

Pontius Jr., R.G., Santacruz, A. 2014. Quantity, exchange and shift components of difference in a square contingency table. International Journal of Remote Sensing 35 (21), 7543-7554.

Examples

## Not run: 
comp <- rast(system.file("external/comparison.rst", package = "diffeR"))
ref <- rast(system.file("external/reference.rst", package = "diffeR"))
differenceMR(comp, ref, eval = "original")
differenceMR(comp, ref, eval = "multiple", fact = 2)

## End(Not run)