modEvA (version 3.5)

applyThreshold: Apply a threshold to model predictions

Description

This function applies a threshold value to the continuous predictions of a model, converting them to binary predictions -- 1 for values above the threshold, and 0 for values below it.

Usage

applyThreshold(model = NULL, obs = NULL, pred = NULL, thresh, right = FALSE, 
interval = 0.01, quant = 0, na.rm = TRUE)

Value

This function returns an object of the same class as 'pred' with the reclassified values after application of the threshold.

Arguments

model

a binary-response model object of class "glm", "gam", "gbm", "randomForest" or "bart". If this argument is provided, 'obs' and 'pred' will be extracted with mod2obspred. Alternatively, you can input the 'obs' and 'pred' arguments instead of 'model'.

obs

alternatively to 'model' and together with 'pred', a numeric vector of observed presences (1) and absences (0) of a binary response variable. Alternatively (and if 'pred' is a 'SpatRaster'), a two-column matrix or data frame containing, respectively, the x (longitude) and y (latitude) coordinates of the presence points, in which case the 'obs' vector will be extracted with ptsrast2obspred. This argument is ignored if 'model' is provided.

pred

alternatively to 'model' and together with 'obs', a vector with the corresponding predicted values of presence probability, habitat suitability, environmental favourability or alike. Must be of the same length and in the same order as 'obs'. Alternatively (and if 'obs' is a set of point coordinates), a 'SpatRaster' map of the predicted values for the entire evaluation region, in which case the 'pred' vector will be extracted with ptsrast2obspred. This argument is ignored if 'model' is provided.

thresh

numeric threshold value within the limits of 'pred', or a criterion under which to compute the threshold -- run modEvAmethods("getThreshold") for available options, and see Details in getThreshold for their description.

right

logical value indicating if the interval should be closed on the right (and open on the left) or vice versa, i.e., if the threshold value itself should be classified as 0 rather than 1. The default is FALSE.

interval

Argument to pass to optiThresh indicating the interval between the thresholds to test, if 'thresh' implies optimizing a threshold-based measure. The default is 0.01. Smaller values may provide more precise results but take longer to compute.

quant

Numeric value indicating the proportion of presences to discard if thresh="MTP" (minimum training presence). With the default value 0, MTP will be the threshold at which all observed presences are classified as such; with e.g. quant=0.05, MTP will be the threshold at which 5% presences will be classified as absences.

na.rm

Logical value indicating whether NA values should be ignored. Defaults to TRUE.

Author

A. Marcia Barbosa

Details

Several criteria have been proposed for selecting a threshold with which to convert continuous model predictions (of presence probability, habitat suitability or alike) into binary predictions of presence or absence. A threshold is required for computing threshold-based model evaluation metrics, such as those in threshMeasures. This function reclassifies the predictions of a model given a numeric threshold, or a threshold selection criterion implemented in getThreshold.

See Also

getThreshold, threshMeasures

Examples

# load sample models:
data(rotif.mods)

# choose a particular model to play with:
mod <- rotif.mods$models[[1]]

applyThreshold(model = mod, thresh = "maxTSS")


# you can also use applyThreshold with vectors of observed and predicted values:

presabs <- mod$y
prediction <- mod$fitted.values

applyThreshold(pred = prediction, thresh = "meanPred")

applyThreshold(obs = presabs, pred = prediction, thresh = "preval")

applyThreshold(obs = presabs, pred = prediction, thresh = "MTP")

applyThreshold(obs = presabs, pred = prediction, thresh = "MTP", 
quant = 0.05)


# 'obs' can also be a table of presence point coordinates
# and 'pred' a SpatRaster of predicted values