Metrics of Difference for Comparing Pairs of Maps or Pairs of Variables

Description

Metrics of difference for comparing pairs of variables or pairs of maps representing real or categorical variables at original and multiple resolutions.

Details

Author(s)

Robert Gilmore Pontius Jr. <rpontius@clarku.edu>, Ali Santacruz <amsantac@unal.edu.co>

Maintainer: Ali Santacruz <amsantac@unal.edu.co>

Mean Absolute Deviation (MAD)

Description

Provides a method to compare the quantity difference and allocation difference between two images of the same real variable at the original resolution or at multiple resolutions. The output provides a stacked graph and an accompanying numerical table for the Mean Absolute Deviation (MAD) for the difference due to quantity, the difference due to stratum-level allocation, and difference due to pixel-level allocation. The output also indicates which image has a smaller average. A scatterplot indicating the distribution of values in relation to the 1:1 line can be produced with MADscatterplot

Usage

MAD(grid1, grid2, strata = NULL, eval = "original")

Arguments

Value

a dataframe containing the multiples of the original resolution, the corresponding aggregated resolution, the difference due to quantity, the difference due to stratum-level allocation, and the difference due to pixel-level allocation.

References

Pontius Jr., R.G., Thontteh, O., Chen, H. 2008. Components of information for multiple resolution comparison between maps that share a real variable. Environmental and Ecological Statistics 15 (2), 111-142.

See Also

MADscatterplot

Examples

old.par <- par(no.readonly = TRUE)
grid1 <- rast(system.file("external/GRID1_INT.rst", package = "diffeR"))
grid2 <- rast(system.file("external/GRID2_INT.rst", package = "diffeR"))
strata <- rast(system.file("external/strata_int.rst", package = "diffeR"))
MAD(grid1, grid2, strata, eval = "original")
MAD(grid1, grid2, strata, eval = "multiple")

## Not run: 
veg_obs1 <- rast(system.file("external/veg_obs1.rst", package = "diffeR")) 
veg_pre1 <- rast(system.file("external/veg_pre1.rst", package = "diffeR")) 
veg_mask1 <- rast(system.file("external/veg_mask1.rst", package = "diffeR")) 
MADscatterplot(veg_obs1, veg_pre1, veg_mask1) 
MAD(veg_obs1, veg_pre1, veg_mask1, eval = "multiple") 

## End(Not run)
par(old.par)

MAD scatterplot

Description

Generates a scatterplot indicating the distribution of values from two images in relation to the 1:1 line

Usage

MADscatterplot(grid1, grid2, strata = NULL)

Arguments

Value

a ggplot object corresponding to the scatterplot

See Also

MAD

Examples

old.par <- par(no.readonly = TRUE)
grid1 <- rast(system.file("external/GRID1_INT.rst", package = "diffeR"))
grid2 <- rast(system.file("external/GRID2_INT.rst", package = "diffeR"))
strata <- rast(system.file("external/strata_int.rst", package = "diffeR"))
MADscatterplot(grid1, grid2, strata)

veg_obs1 <- rast(system.file("external/veg_obs1.rst", package = "diffeR")) 
veg_pre1 <- rast(system.file("external/veg_pre1.rst", package = "diffeR"))
veg_mask1 <- rast(system.file("external/veg_mask1.rst", package = "diffeR")) 
MADscatterplot(veg_obs1, veg_pre1, veg_mask1) 
par(old.par)

Category Components plot

Description

If comparison and reference (raster) maps are provided, this function creates the Category Components plot from the comparison between the comparison map (or map at time t) and the reference map (or map at time t+1). If a square contingency table (matrix) is provided instead of raster maps, then this function creates the Category Components plot from the comparison between the comparison variable (or variable at time t) and the reference variable (or variable at time t+1).

Usage

categoryComponentsPlot(comp = NULL, ref = NULL, ctmatrix = NULL, 
                       units = NULL, population = NULL, 
                       fontSize = NULL, breaks = waiver(), 
                       labels = waiver(), limits = NULL)

Arguments

Details

Users may enter as input either a square contingency table (ctmatrix) or a comparison and a reference raster maps (comp and ref, respectively).

The first column of population must contain integer identifiers of each category, corresponding to the categories in the comparison and reference variables. The second column corresponds to the population totals for each category.

Value

a stacked barplot showing for each category the quantity, exchange and shift components of difference between the comparison map/variable (or map/variable at time t) and the reference map/variable (or map/variable at time t+1)

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.

See Also

diffTablej

Examples

comp <- rast(system.file("external/comparison.rst", package = "diffeR"))
ref <- rast(system.file("external/reference.rst", package = "diffeR"))
categoryComponentsPlot(comp, ref)

ctmat <- crosstabm(comp, ref)
categoryComponentsPlot(ctmatrix = ctmat, units = "pixels")

Category Sources plot

Description

If comparison and reference (raster) maps are provided, this function creates the Category Sources plot from the comparison between the comparison map (or map at time t) and the reference map (or map at time t+1). If a square contingency table (matrix) is provided instead of raster maps, then this function creates the Category Sources plot from the comparison between the comparison variable (or variable at time t) and the reference variable (or variable at time t+1).

Usage

categorySourcesPlot(comp = NULL, ref = NULL, ctmatrix = NULL, 
                    analysis = "error", units = NULL, 
                    population = NULL, fontSize = NULL, 
                    breaks = waiver(), labels = waiver(), 
                    limits = NULL)

Arguments

Details

Users may enter as input either a square contingency table (ctmatrix) or a comparison and a reference raster maps (comp and ref, respectively).

The first column of population must contain integer identifiers of each category, corresponding to the categories in the comparison and reference variables. The second column corresponds to the population totals for each category.

Value

a stacked barplot showing for each category the agreement and the omission and comission components of difference between the comparison map/variable (or map/variable at time t) and the reference map/variable (or map/variable at time t+1)

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.

Examples

comp <- rast(system.file("external/comparison.rst", package = "diffeR"))
ref <- rast(system.file("external/reference.rst", package = "diffeR"))
categorySourcesPlot(comp, ref)

ctmat <- crosstabm(comp, ref)
categorySourcesPlot(ctmatrix = ctmat, units = "Pixels")

create a composite matrix

Description

provide a method to create a composite matrix from the crosstabulation of a comparison map (or map at time t) and a reference map (or map at time t+1), both aggregated at a given factor

Usage

composite(comp, ref, factor)

Arguments

Details

the pixel definition in a composite matrix interpretes class membership as the proportion of a pixel that belongs to a class. The pixel contains information about only the quantity of each category (Kuzera and Pontius 2008).

Value

a matrix showing the contingency table derived from the crosstabulation of a comparison map (or map at time t) and a reference map (or map at time t+1), both aggregated at a given factor. Output values are given as proportion (0 to 1)

References

Kuzera, K., Pontius Jr., R.G. 2008. Importance of matrix construction for multiple-resolution categorical map comparison. GIScience & Remote Sensing 45 (3), 249-274.

See Also

memberships

Examples

comp <- rast(system.file("external/comparison.rst", package = "diffeR"))
ref <- rast(system.file("external/reference.rst", package = "diffeR"))
composite(comp, ref, factor = 2)

create a contingency table between a comparison raster map (rows) and a reference raster map (columns)

Description

create a contingency table, also called cross-tabulated matrix, between a comparison raster map (rows), or map at time t, and a reference raster map (columns), or map at time t+1

Usage

crosstabm(comp, ref, percent = FALSE, population = NULL)

Arguments

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

a matrix showing the cross-tabulation between the comparison map (or map at time t) and the reference map (or map at time t+1)

See Also

memberships

Examples

comp <- rast(system.file("external/comparison.rst", package = "diffeR"))
ref <- rast(system.file("external/reference.rst", package = "diffeR"))
crosstabm(comp, ref)

# Population-adjusted square contingency table
(population <- matrix(c(1, 2, 3, 2000, 4000, 6000), ncol = 2))
crosstabm(comp, ref, population = population)

# Population-adjusted square contingency table, output as percentage
crosstabm(comp, ref, percent = TRUE, population = population)

Overall difference metrics and difference metrics at the category level or between pairs of categories

Description

Overall difference metrics (overallAllocD, overallDiff, overallDiffCatj, overallExchangeD, overallQtyD, overallShiftD) and difference metrics at the category level (exchangeDj, quantityDj, shiftDj, omissionj, commisionj, agreementj) or between pairs of categories (exchangeDij) calculated using a square contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1)

Usage

exchangeDij(ctmatrix)
exchangeDj(ctmatrix)
overallAllocD(ctmatrix)
overallDiff(ctmatrix)
overallDiffCatj(ctmatrix)
overallExchangeD(ctmatrix)
overallQtyD(ctmatrix)
overallShiftD(ctmatrix)
quantityDj(ctmatrix)
shiftDj(ctmatrix)
omissionj(ctmatrix)
comissionj(ctmatrix)
agreementj(ctmatrix)

Arguments

Details

exchangeDij calculates the exchange matrix between pairs of categories from a square contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1). Exchange consists of a transition from category i to category j in some observations and a transition from category j to category i in an identical number of other observations.

exchangeDj calculates exchange difference at the category level from a square contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1). Exchange consists of a transition from category i to category j in some observations and a transition from category j to category i in an identical number of other observations.

overallAllocD calculates overall allocation difference from a square contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1). Allocation difference is defined as the amount of difference between a reference variable and a comparison variable that is due to the less than maximum match in the spatial allocation of the categories, given the proportions of the categories in the reference and comparison variables. Allocation difference is equivalent to the addition of the exchange and shift components of difference (i.e., allocation difference can be disaggregated into exchange and shift components).

overallDiff calculates overall difference from a square contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1). Overall difference is equivalent to the addition of the quantity and allocation components of difference (i.e., overall difference can be disaggregated into quantity and allocation components).

overallDiffCatj calculates overall difference at the category level from a square contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1). Overall difference is equivalent to the addition of the quantity and allocation components of difference (i.e., overall difference can be disaggregated into quantity and allocation components).

overallExchangeD calculates overall exchange difference from a square contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1). Exchange consists of a transition from category i to category j in some observations and a transition from category j to category i in an identical number of other observations.

overallQtyD calculates overall quantity difference from a square contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1). Quantity difference is defined as the amount of difference between the reference variable and a comparison variable that is due to the less than maximum match in the proportions of the categories.

overallShiftD calculates overall shift difference from a square contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1). Shift refers to the difference remaining after subtracting quantity difference and exchange from the overall difference.

quantityDj calculates quantity difference at the category level from a square contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1). Quantity difference is defined as the amount of difference between the reference variable and a comparison variable that is due to the less than maximum match in the proportions of the categories.

shiftDj calculates shift difference at the category level from a contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1). Shift refers to the difference remaining after subtracting quantity difference and exchange from the overall difference.

omissionj calculates omission error at the category level from a contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1). Omission error refers to observations in the reference variable that were classified in a category other than their true or known category, in other words, observations of a known category that were excluded from that category due to misclassification.

comissionj calculates comission error at the category level from a contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1). Commission error refers to observations that were incorrectly classified and do not belong in the category in which they were assigned according to the classification.

agreementj calculates agreement at the category level from a contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1).

Value

exchangeDij returns a matrix containing exchange occurring between pairs of categories from the comparison variable and the reference variable. Exchange is shown in the lower triangle of the output matrix.

exchangeDj returns a numeric vector containing the exchange difference between the comparison variable and the reference variable at the category level.

overallAllocD returns the overall allocation difference between the comparison variable and the reference variable.

overallDiff returns the overall difference between the comparison variable and the reference variable.

overallDiffCatj returns a numeric vector containing overall difference between the comparison variable and the reference variable at the category level.

overallExchangeD returns the overall exchange difference between the comparison variable and the reference variable.

overallQtyD returns the overall quantity difference between the comparison variable and the reference variable.

overallShiftD returns the overall shift difference between the comparison variable and the reference variable.

quantityDj returns a numeric vector containing the quantity difference between the comparison variable and the reference variable at the category level.

shiftDj returns a numeric vector containing the shift difference between the comparison variable and the reference variable at the category level.

omissionj returns a numeric vector containing the omission disagreement between the comparison variable and the reference variable at the category level.

comissionj returns a numeric vector containing the comission disagreement between the comparison variable and the reference variable at the category level.

agreementj returns a numeric vector containing the agreement between the comparison variable and the reference variable at the category level.

For all the functions above, the output values are given in the same units as ctmatrix.

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.

See Also

diffTablej

Examples

comp <- rast(system.file("external/comparison.rst", package = "diffeR"))
ref <- rast(system.file("external/reference.rst", package = "diffeR"))
ctmatCompRef <- crosstabm(comp, ref)

exchangeDij(ctmatCompRef)
exchangeDj(ctmatCompRef)
overallAllocD(ctmatCompRef)
overallDiff(ctmatCompRef)
overallDiffCatj(ctmatCompRef)
overallExchangeD(ctmatCompRef)
overallQtyD(ctmatCompRef)
overallShiftD(ctmatCompRef)
quantityDj(ctmatCompRef)
shiftDj(ctmatCompRef)
omissionj(ctmatCompRef)
comissionj(ctmatCompRef)
agreementj(ctmatCompRef)

calculates difference metrics at the category level from a square contingency table

Description

calculates quantity, exchange and shift components of difference, as well as the overall difference, at the category level from a contingency table derived from the crosstabulation between a comparison variable (or variable at time t), and a reference variable (or variable at time t+1).

Quantity difference is defined as the amount of difference between the reference variable and a comparison variable 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 observations and a transition from category j to category i in an identical number of other observations. Shift refers to the difference remaining after subtracting quantity difference and exchange from the overall difference.

Usage

diffTablej(ctmatrix, digits = 0, analysis = "error")

Arguments

Value

data.frame containing difference metrics at the category level between a comparison variable (rows) and a reference variable (columns). Output values are given in the same units as ctmatrix

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

comp <- rast(system.file("external/comparison.rst", package = "diffeR"))
ref <- rast(system.file("external/reference.rst", package = "diffeR"))
ctmatCompRef <- crosstabm(comp, ref)
diffTablej(ctmatCompRef)

# Adjustment to population assuming a stratified random sampling
(population <- matrix(c(1, 2, 3, 2000, 4000, 6000), ncol = 2))
ctmatCompRef <- crosstabm(comp, ref, percent = TRUE, population = population)
diffTablej(ctmatCompRef)

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

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)

produces membership values for each category in the input raster at a specified aggregated resolution

Description

Calculates membership values for each category in the input raster at a specified aggregated resolution

Usage

memberships(grid, fact = 2)

Arguments

Value

a RasterBrick object containing membership values for each category in the input raster at a specified aggregated resolution

See Also

composite

Examples

ref <- rast(system.file("external/reference.rst", package = "diffeR"))
plot(ref)
memb.ref <- memberships(ref, fact = 2)
names(memb.ref) <- c("ref.1", "ref.2", "ref.3")
plot(memb.ref)

Overall Components plot

Description

If comparison and reference (raster) maps are provided, this function creates the Overall Components plot from the comparison between the comparison map (or map at time t) and the reference map (or map at time t+1). If a square contingency table (matrix) is provided instead of raster maps, then this function creates the Overall Components plot from the comparison between the comparison variable (or variable at time t) and the reference variable (or variable at time t+1).

Usage

overallComponentsPlot(comp = NULL, ref = NULL, ctmatrix = NULL, 
                      units = NULL, population = NULL, 
                      graphics_system = 'ggplot2')

Arguments

Details

Users may enter as input either a square contingency table (ctmatrix) or a comparison and a reference raster maps (comp and ref, respectively).

The first column of population must contain integer identifiers of each category, corresponding to the categories in the comparison and reference variables. The second column corresponds to the population totals for each category.

Value

a stacked barplot showing the quantity, exchange and shift components of difference between the comparison map/variable (or map/variable at time t) and the reference map/variable (or map/variable at time t+1)

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.

Examples

comp <- rast(system.file("external/comparison.rst", package = "diffeR"))
ref <- rast(system.file("external/reference.rst", package = "diffeR"))
overallComponentsPlot(comp, ref)

ctmat <- crosstabm(comp, ref)
overallComponentsPlot(ctmatrix = ctmat, units = "pixels")

Overall Sources plot

Description

If comparison and reference (raster) maps are provided, this function creates the Overall Sources plot from the comparison between the comparison map (or map at time t) and the reference map (or map at time t+1). If a square contingency table (matrix) is provided instead of raster maps, then this function creates the Overall Sources plot from the comparison between the comparison variable (or variable at time t) and the reference variable (or variable at time t+1).

Usage

overallSourcesPlot(comp = NULL, ref = NULL, ctmatrix = NULL, 
                   analysis = "error", units = NULL, 
                   population = NULL, fontSize = NULL, 
                   colorValues = NULL, breaks = waiver(), 
                   labels = waiver(), limits = NULL)

Arguments

Details

Users may enter as input either a square contingency table (ctmatrix) or a comparison and a reference raster maps (comp and ref, respectively).

The first column of population must contain integer identifiers of each category, corresponding to the categories in the comparison and reference variables. The second column corresponds to the population totals for each category.

Value

a stacked barplot showing the omission and comission components of difference between the comparison map/variable (or map/variable at time t) and the reference map/variable (or map/variable at time t+1)

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.

Examples

comp <- rast(system.file("external/comparison.rst", package = "diffeR"))
ref <- rast(system.file("external/reference.rst", package = "diffeR"))
overallSourcesPlot(comp, ref)

ctmat <- crosstabm(comp, ref)
overallSourcesPlot(ctmatrix = ctmat, units = "pixels")

corrects sample counts to population counts in a square contingency table

Description

Converts sample count to population count in the square contingency table, assuming a stratified random sampling

Usage

sample2pop(ctmatrix, population)

Arguments

Details

The first column of population must contain integer identifiers of each category, corresponding to the categories in the comparison and reference variables. The second column corresponds to the population totals for each category.

Value

matrix representing a population-adjusted square contingency table for the crosstabulation between a comparison variable (rows) and a reference variable (columns). Output values are given in the same units as ctmatrix

See Also

crosstabm

Examples

comp <- rast(system.file("external/comparison.rst", package = "diffeR"))
ref <- rast(system.file("external/reference.rst", package = "diffeR"))

# Sample square contingency table
(ctmatCompRef <- crosstabm(comp, ref))

# Population-adjusted square contingency table
(population <- matrix(c(1, 2, 3, 2000, 4000, 6000), ncol = 2))
sample2pop(ctmatCompRef, population = population)

# The square contingency table can also be adjusted directly using the 
# crosstabm function
crosstabm(comp, ref, population = population)