Package 'diffeR'

Title: 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.
Authors: Robert Gilmore Pontius Jr. <[email protected]>, Ali Santacruz <[email protected]>
Maintainer: Ali Santacruz <[email protected]>
License: GPL (>= 2)
Version: 0.0-8
Built: 2025-02-02 03:40:32 UTC
Source: https://github.com/amsantac/differ

Help Index

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

Package: diffeR
Type: Package
Version: 0.0-8
Date: 2023-08-21
License: GPL (>= 2)
LazyLoad: yes
BugReports: https://github.com/amsantac/diffeR/issues

Author(s)

Robert Gilmore Pontius Jr. <[email protected]>, Ali Santacruz <[email protected]>

Maintainer: Ali Santacruz <[email protected]>

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

comp

object of class SpatRaster corresponding to a comparison map (or map at time t). See Details below

ref

object of class SpatRaster corresponding to a reference map (or map at time t+1). See Details below

ctmatrix

matrix representing a square contingency table between a comparison variable or variable at time t (rows) and a reference variable or variable at time t+1 (columns). See Details below

units

optional; character string indicating units of ctmatrix

population

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

text size (in pts)
breaks

One of:

  • NULL for no breaks

  • waiver() for the default breaks computed by the transformation object

  • A numeric vector of positions

  • A function that takes the limits as input and returns breaks as output

labels

One of:

  • NULL for no labels

  • waiver() for the default labels computed by the transformation object

  • A character vector giving labels (must be same length as breaks)

  • A function that takes the breaks as input and returns labels as output

limits

A numeric vector of length two providing limits of the scale. Use NA to refer to the existing minimum or maximum.

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

comp

object of class SpatRaster corresponding to a comparison map (or map at time t). See Details below

ref

object of class SpatRaster corresponding to a reference map (or map at time t+1). See Details below

ctmatrix

matrix representing a square contingency table between a comparison variable or variable at time t (rows) and a reference variable or variable at time t+1 (columns). See Details below

analysis

character string indicating type of analysis, either "error" (default) or "change"

units

optional; character string indicating units of ctmatrix

population

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

text size (in pts)
breaks

One of:

  • NULL for no breaks

  • waiver() for the default breaks computed by the transformation object

  • A numeric vector of positions

  • A function that takes the limits as input and returns breaks as output

labels

One of:

  • NULL for no labels

  • waiver() for the default labels computed by the transformation object

  • A character vector giving labels (must be same length as breaks)

  • A function that takes the breaks as input and returns labels as output

limits

A numeric vector of length two providing limits of the scale. Use NA to refer to the existing minimum or maximum.

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

comp

object of class SpatRaster corresponding to a comparison map (or map at time t)

ref

object of class SpatRaster corresponding to a reference map (or map at time t+1)

factor

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

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

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

percent

logical. If TRUE, output values are given as percentage. If FALSE, output values are given in pixel counts

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

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)

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)

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

ctmatrix

matrix representing a square contingency table between a comparison variable (rows) and a reference variable (columns)

digits

integer indicating the number of decimal places to be used

analysis

character string either "error" (default) or "change". The output table shows category-level omission error, agreement and comission error in the "error" analysis, and category-level gain, persistence and loss in the "change" analysis

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)

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

grid1

object of class SpatRaster corresponding to the first image

grid2

object of class SpatRaster corresponding to the second image

strata

object of class SpatRaster corresponding to the mask or strata image. Zero values are taken as no data (i.e., NA)

eval

default "original", return the MAD value for the original resolution; if "multiple", return the MAD values for multiple resolutions following a geometric sequence

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

grid1

object of class SpatRaster corresponding to the first image

grid2

object of class SpatRaster corresponding to the second image

strata

object of class SpatRaster corresponding to the mask or strata image. Zero values are taken as no data (i.e., NA)

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)

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

grid

object of class SpatRaster

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

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

comp

object of class SpatRaster corresponding to a comparison map (or map at time t). See Details below

ref

object of class SpatRaster corresponding to a reference map (or map at time t+1). See Details below

ctmatrix

matrix representing a square contingency table between a comparison variable (rows) and a reference variable (columns).. See Details below

units

character string indicating units of ctmatrix

population

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

graphics_system

character string indicating the graphics system for creating the plot, either "ggplot2" (default) or "graphics" (for base R graphics system)

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

comp

object of class SpatRaster corresponding to a comparison map (or map at time t). See Details below

ref

object of class SpatRaster corresponding to a reference map (or map at time t+1). See Details below

ctmatrix

matrix representing a square contingency table between a comparison variable (rows) and a reference variable (columns). See Details below

analysis

character string indicating type of analysis, either "error" (default) or "change"

units

character string indicating units of ctmatrix

population

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

fontSize

text size (in pts)

colorValues

a set of aesthetic values to map data values to. If this is a named vector, then the values will be matched based on the names. If unnamed, values will be matched in order (usually alphabetical) with the limits of the scale. Any data values that don't match will be given na.value.

breaks

One of:

  • NULL for no breaks

  • waiver() for the default breaks computed by the transformation object

  • A numeric vector of positions

  • A function that takes the limits as input and returns breaks as output

labels

One of:

  • NULL for no labels

  • waiver() for the default labels computed by the transformation object

  • A character vector giving labels (must be same length as breaks)

  • A function that takes the breaks as input and returns labels as output

limits

A numeric vector of length two providing limits of the scale. Use NA to refer to the existing minimum or maximum.

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

ctmatrix

matrix representing a sampling-derived square contingency table between a comparison variable (rows) and a reference variable (columns)

population

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

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)