Package 'TOC'

Title: Total Operating Characteristic Curve and ROC Curve
Description: Construction of the Total Operating Characteristic (TOC) Curve and the Receiver (aka Relative) Operating Characteristic (ROC) Curve for spatial and non-spatial data. The TOC method is a modification of the ROC method which measures the ability of an index variable to diagnose either presence or absence of a characteristic. The diagnosis depends on whether the value of an index variable is above a threshold. Each threshold generates a two-by-two contingency table, which contains four entries: hits (H), misses (M), false alarms (FA), and correct rejections (CR). While ROC shows for each threshold only two ratios, H/(H + M) and FA/(FA + CR), TOC reveals the size of every entry in the contingency table for each threshold (Pontius Jr., R.G., Si, K. 2014. <doi:10.1080/13658816.2013.862623>).
Authors: Robert G. Pontius <[email protected]>, Ali Santacruz, Amin Tayyebi, Benoit Parmentier, Kangping Si
Maintainer: Ali Santacruz <[email protected]>
License: GPL-3
Version: 0.0-6
Built: 2024-11-04 03:17:35 UTC
Source: https://github.com/amsantac/toc

Help Index

Total Operating Characteristic (TOC) Curve and ROC Curve

Description

Construction of the Total Operating Characteristic (TOC) Curve and the Receiver (aka Relative) Operating Characteristic (ROC) Curve for spatial and non-spatial data. The TOC method is a modification of the ROC method which measures the ability of an index variable to diagnose either presence or absence of a characteristic. The diagnosis depends on whether the value of an index variable is above a threshold. Each threshold generates a two-by-two contingency table, which contains four entries: hits (H), misses (M), false alarms (FA), and correct rejections (CR). While ROC shows for each threshold only two ratios, H/(H + M) and FA/(FA + CR), TOC reveals the size of every entry in the contingency table for each threshold (Pontius Jr., R.G., Si, K. 2014. The total operating characteristic to measure diagnostic ability for multiple thresholds. Int. J. Geogr. Inf. Sci. 28 (3), 570-583 <doi:10.1080/13658816.2013.862623>).

Details

Package: TOC
Type: Package
Version: 0.0-6
Date: 2023-02-09
License: GPL-3
LazyLoad: yes

Author(s)

Robert G. Pontius, Ali Santacruz, Amin Tayyebi, Benoit Parmentier, Kangping Si

Maintainer: Ali Santacruz

References

Pontius Jr., R.G., Kangpin, Si. 2014. The total operating characteristic to measure diagnostic ability for multiple thresholds. International Journal of Geographical Information Science 28 (3): 570-583. <doi:10.1080/13658816.2013.862623>

Pontius, G., Parmentier, B. 2014. Recommendations for using the Relative Operating Characteristic (ROC). Landscape Ecology 29 (3): 367-382. <doi:10.1007/s10980-013-9984-8>

See Also

TOC, plot

Plot an object of class Toc or Roc

Description

Plot a Total Operating Characteristic (TOC) curve or a Relative Operating Characteristic (ROC) curve

Usage

## S4 method for signature 'Toc'
plot(x, labelThres = FALSE, modelLeg = "Model", digits = 3, 
nticks = 5, digitsL = 1, posL = NULL, offsetL = 0.5, ...)
   

## S4 method for signature 'Roc'
plot(x, labelThres = FALSE, modelLeg = "Model", digits = 3, 
nticks = 5, digitsL = 1, posL = NULL, offsetL = 0.5, ...)

Arguments

x

An object of class Toc or Roc
labelThres

logical, default to FALSE. If TRUE, thresholds are labeled in the TOC plot

modelLeg

a character string for labeling the model in the legend

digits

integer indicating the number of decimal places (round) or significant digits (signif) to be used for labeling the numeric axes. Negative values are allowed. See Details in the round function

nticks

number of tickmarcks to be drawn along the axes

digitsL

integer indicating the number of decimal places (round) or significant digits (signif) to be used for labeling the thresholds. Negative values are allowed. See Details in the round function

posL

a position specifier for the text labels. Values of 1, 2, 3 and 4, respectively indicate positions below, to the left of, above and to the right of the corresponding coordinates

offsetL

when posL is specified, this value gives the offset of the label from the corresponding coordinate in fractions of a character width

...

additional parameters to be passed to plot, axis or text

Value

a plot showing the TOC or the ROC curve

References

Pontius Jr., R.G., Kangpin, Si. 2014. The total operating characteristic to measure diagnostic ability for multiple thresholds. International Journal of Geographical Information Science 28 (3): 570-583. <doi:10.1080/13658816.2013.862623>

Pontius, G., Parmentier, B. 2014. Recommendations for using the Relative Operating Characteristic (ROC). Landscape Ecology 29 (3): 367-382. <doi:10.1007/s10980-013-9984-8>

See Also

TOC, ROC

Examples

index <- rast(system.file("external/Prob_Map2.rst", package = "TOC"))
boolean <- rast(system.file("external/Change_Map2b.rst", package = "TOC"))
mask <- rast(system.file("external/MASK4.rst", package = "TOC"))

## create and plot the TOC curve
tocd <- TOC(index, boolean, mask, nthres = 100)
plot(tocd, main = "TOC curve")

## create and plot the ROC curve
rocd <- ROC(index, boolean, mask, nthres = 100)
plot(rocd, main = "ROC curve")

## label the thresholds in the plot
tocd <- TOC(index, boolean, mask, nthres = 10)
plot(tocd, labelThres = TRUE, cex = 0.8, posL = 4)

Construct the table for the ROC curve

Description

Construct the table for the Relative Operating Characteristic (ROC) curve for spatial or non-spatial data

Usage

## S4 method for signature 'numeric,numeric'
ROC(index, boolean, mask = NULL, nthres = NULL, thres = NULL, 
NAval = 0, progress = FALSE)

## S4 method for signature 'SpatRaster,SpatRaster'
ROC(index, boolean, mask = NULL, nthres = NULL, thres = NULL, 
NAval = 0, progress = FALSE)

Arguments

index

index object of class numeric or SpatRaster

boolean

boolean object of class numeric or SpatRaster

mask

mask object of class numeric or SpatRaster

nthres

an optional integer indicating the number of equal-interval thresholds to be evaluated for the ROC curve. See Details below

thres

an optional numeric vector of thresholds to be evaluated for the ROC curve. See Details below

NAval

value for nodata (NA values) in the mask object

progress

logical; if TRUE, a progress bar is shown

Details

thresholds are calculated as the unique values of the index object after masking out NA values (default option), if neither nthres nor thres is provided. The default option can be time-consuming if the amount of unique values in the index object (after masking out NA values) is large (e.g., greater than 1000). In the latter case, the user may prefer to enter specified thresholds (with the thres argument), or to indicate the number of equal-interval thresholds to be evaluated for the ROC curve (with the nthres argument)

Value

an object of class Roc containing the ROC table, the area under the curve (AUC), maximum AUC and minimum AUC

References

Pontius Jr., R.G., Kangpin, Si. 2014. The total operating characteristic to measure diagnostic ability for multiple thresholds. International Journal of Geographical Information Science 28 (3): 570-583. <doi:10.1080/13658816.2013.862623>

Pontius, G., Parmentier, B. 2014. Recommendations for using the Relative Operating Characteristic (ROC). Landscape Ecology 29 (3): 367-382. <doi:10.1007/s10980-013-9984-8>

See Also

plot

Examples

index <- rast(system.file("external/Prob_Map2.rst", package = "TOC"))
boolean <- rast(system.file("external/Change_Map2b.rst", package = "TOC"))
mask <- rast(system.file("external/MASK4.rst", package = "TOC"))

## thresholds can be defined by indicating the number of equal-interval thresholds 
rocd <- ROC(index, boolean, mask, nthres = 100)
rocd

## a vector of thresholds can also be used to define the thresholds
thresholds <- seq(min(unique(index)), max(unique(index)) + 1, 
                  by = ceiling(max(unique(index))/10))
rocd <- ROC(index, boolean, mask, thres = thresholds)
rocd

## all the unique values of the index object can be evaluated as thresholds 
## (default option)
## Not run: 
rocd <- ROC(index, boolean, mask, progress = TRUE)
rocd

## End(Not run)

## generate the ROC curve using non-spatial data (i.e., an object of class numeric)
## Not run: 
index <- rast(system.file("external/Prob_Map2.rst", package = "TOC"))
boolean <- rast(system.file("external/Change_Map2b.rst", package = "TOC"))
mask <- rast(system.file("external/MASK4.rst", package = "TOC"))

index <- values(index, mat = FALSE)
boolean <- values(boolean, mat = FALSE)
mask <- values(mask, mat = FALSE)
rocd <- ROC(index, boolean, mask, nthres = 100)
rocd

## End(Not run)

Construct a basic ROC table

Description

TOC internal function. Construct a basic ROC table

Usage

roctable(indval, boolval, maskval = NULL, nthres = NULL, 
         thres = NULL, NAval = 0, progress = FALSE, 
         ones.bool = NULL, zeros.bool = NULL)

Arguments

indval

numeric index vector

boolval

numeric boolean vector

maskval

numeric mask vector

nthres

an optional integer indicating the number of equal-interval thresholds to be evaluated for the TOC curve. See Details below

thres

an optional numeric vector of thresholds to be evaluated for the TOC curve. See Details below

NAval

value for nodata (NA values) in the mask map

progress

logical; if TRUE, a progress bar is shown

ones.bool

numeric value indicating total number of 1's in the boolean vector

zeros.bool

numeric value indicating total number of 0's in the boolean vector

Value

a data.frame with a basic ROC table and a numeric value for minimum value in the index vector

Note

This function is not meant to be called by users directly

scale the output TOC values and change units

Description

scale the 'Hits' and 'Hits+FalseAlarms' values in the TOC output table, as well as the prevalence and population, using a scaling factor. Labels for the modified units in the TOC object are changed to newUnits

Usage

## S4 method for signature 'Toc'
scaling(x, scalingFactor, newUnits)

Arguments

x

an object of class Toc

scalingFactor

numeric value to scale 'Hits' and 'Hits+FalseAlarms' values in the TOC output table, as well as the prevalence and population

newUnits

charater string for the new data units in the TOC object

Value

an object of class TOC

See Also

TOC, ROC

Examples

index <- rast(system.file("external/Prob_Map2.rst", package = "TOC"))
boolean <- rast(system.file("external/Change_Map2b.rst", package = "TOC"))
mask <- rast(system.file("external/MASK4.rst", package = "TOC"))
tocd <- TOC(index, boolean, mask, nthres = 100)
plot(tocd)

## scale units from square m to square km
tocd_sqkm <- scaling(tocd, scalingFactor = 1000000, newUnits = "square km")
plot(tocd_sqkm)

Construct the table for the TOC curve

Description

Construct the table for the Total Operating Characteristic (TOC) curve for spatial or non-spatial data. The TOC method is a modification of the ROC method which measures the ability of an index variable to diagnose either presence or absence of a characteristic. The diagnosis depends on whether the value of an index variable is above a threshold. Each threshold generates a two-by-two contingency table, which contains four entries: hits (H), misses (M), false alarms (FA), and correct rejections (CR). While ROC shows for each threshold only two ratios, H/(H + M) and FA/(FA + CR), TOC reveals the size of every entry in the contingency table for each threshold (Pontius Jr., R.G., Si, K. 2014. <doi:10.1080/13658816.2013.862623>).

Usage

## S4 method for signature 'numeric,numeric'
TOC(index, boolean, mask = NULL, nthres = NULL, thres = NULL, 
NAval = 0, P = NA, Q = NA, progress = FALSE, units = character(0))
## S4 method for signature 'SpatRaster,SpatRaster'
TOC(index, boolean, mask = NULL, nthres = NULL, thres = NULL, 
NAval = 0, P = NA, Q = NA, progress = FALSE)

Arguments

index

index object of class numeric or SpatRaster

boolean

boolean object of class numeric or SpatRaster

mask

mask object of class numeric or SpatRaster

nthres

an optional integer indicating the number of equal-interval thresholds to be evaluated for the TOC curve. See Details below

thres

an optional numeric vector of thresholds to be evaluated for the TOC curve. See Details below

NAval

value for nodata (NA values) in the mask object

P

count of reference presence observations in the population

Q

count of reference absence observations in the population

progress

logical; if TRUE, a progress bar is shown

units

character string indicating data units

Details

thresholds are calculated as the unique values of the index object after masking out NA values (default option), if neither nthres nor thres is provided. The default option can be time-consuming if the amount of unique values in the index object (after masking out NA values) is large (e.g., greater than 1000). In the latter case, the user may prefer to enter specified thresholds (with the thres argument), or to indicate the number of equal-interval thresholds to be evaluated for the TOC curve (with the nthres argument)

Value

an object of class Toc containing the TOC table, the area under the curve (AUC), maximum AUC and minimum AUC, the prevalence, the population and the data units (for data in the TOC table slot, and the prevalence and population slots)

References

Pontius Jr., R.G., Kangpin, Si. 2014. The total operating characteristic to measure diagnostic ability for multiple thresholds. International Journal of Geographical Information Science 28 (3): 570-583. <doi:10.1080/13658816.2013.862623>

Pontius, G., Parmentier, B. 2014. Recommendations for using the Relative Operating Characteristic (ROC). Landscape Ecology 29 (3): 367-382. <doi:10.1007/s10980-013-9984-8>

See Also

plot

Examples

index <- rast(system.file("external/Prob_Map2.rst", package = "TOC"))
boolean <- rast(system.file("external/Change_Map2b.rst", package = "TOC"))
mask <- rast(system.file("external/MASK4.rst", package = "TOC"))

## thresholds can be defined by indicating the number of equal-interval thresholds 
tocd <- TOC(index, boolean, mask, nthres = 100)
tocd

## a vector of thresholds can also be used to define the thresholds
thresholds <- seq(min(unique(index)), max(unique(index)) + 1, 
                  by = ceiling(max(unique(index))/10))
tocd <- TOC(index, boolean, mask, thres = thresholds)
tocd

## all the unique values of the index object can be evaluated as thresholds 
## (default option)
## Not run: 
tocd <- TOC(index, boolean, mask, progress = TRUE)
tocd

## End(Not run)

## generate the TOC curve using non-spatial data (i.e., an object of class numeric)
## Not run: 
index <- values(index, mat = FALSE)
boolean <- values(boolean, mat = FALSE)
mask <- values(mask, mat = FALSE)
tocd <- TOC(index, boolean, mask, nthres = 100)

## End(Not run)

Toc and Roc classes

Description

Toc and Roc classes

Objects from the Class

Objects can be created by calls of the form new("Toc", ...), or with the helper functions such as Toc.

Slots

Slots for Roc and Toc objects

table:

data.frame

AUC:

numeric; Area Under the Curve

maxAUC:

numeric; maximum AUC

minAUC:

numeric; minimum AUC

prevalence:

numeric; prevalence

population:

numeric; population

units:

character; units for data in the TOC table, prevalence and population

Examples

showClass("Toc")

Uncertainty in AUC calculation

Description

TOC internal function. It calculates uncertainty in AUC calculation

Usage

uncertainty(index, tocd)

Arguments

index

index vector

tocd

data.frame output from roctable

Value

a numeric value representing uncertainty in AUC calculation

Note

This function is not meant to be called by users directly