poMeasures: Strictly presence-only measures of model evaluation

In modEvA: Model Evaluation and Analysis

Strictly presence-only measures of model evaluation

Description

THIS FUNCTION IS EXPERIMENTAL AND IMPLEMENTS METHODS THAT ARE STILL UNDER SCIENTIFIC REVIEW. It computes a set of truly presence-only bin-dependent and bin-independent evaluation metrics for model predictions. The function evaluates how the continuous predicted values (at presence sites only) relate to the number or density of observed presences, using correlation-based measures and distributional comparisons. Optional diagnostic plots are also produced.

Usage

  poMeasures(
    model = NULL,
    obs = NULL,
    pred = NULL,
    n.bins = 100,
    bin.width = "default",
    method = "spearman",
    rm.dup.classes = NA,
    rm.dup.points = FALSE,
    simplif = FALSE,
    plot = TRUE,
    plot.lines = TRUE,
    plot.values = TRUE,
    cex.values = 1,
    plot.digits = 3,
    main = c("Presence-only bin-based", "Presence-only density-based"),
    na.rm = TRUE,
    verbosity = 2,
    ...
  )

Arguments

model	optional 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 (e.g. for external test data) instead of 'model'.
obs	alternatively to 'model' and (optionally) 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. If used, rows where obs = 0 or pixels with no presence points are removed before calculations.
pred	alternatively to 'model' and (optionally) together with 'obs', a vector with the corresponding predicted values of habitat suitability, environmental favourability or alike (presence probability is not appropriate for these measures, unless model training prevalence equals 0.5). If 'obs' is provided, 'pred' must be of the same length and in the same order. Alternatively (and if 'obs' is a set of point coordinates), a 'SpatRaster' map of the predicted values (at presence sites only, unless 'obs' coordinates are provided), in which case the 'pred' vector will be extracted with ptsrast2obspred. This argument is ignored if 'model' is provided.
n.bins	argument to pass to getBins indicating the number of bins in which to divide the data.
bin.width	argument to pass to getBins indicating the width of the moving window. The default is 1/10th of the 'pred' range.
method	argument to pass to cor.test specifying the correlation method to use for POGI. The default is "spearman", as in the initial publication on the Boyce index on which these measures are inspired, but "kendall" or "pearson" could be more informative in many cases.
rm.dup.classes	(placeholder, as in Boyce, but currently not used here).
rm.dup.points	if TRUE and if 'pred' is a SpatRaster and if there are >1 points within the same pixel, a maximum of one point per pixel is used to compute the presences. See examples in ptsrast2obspred. The default is FALSE.
simplif	logical value (default FALSE) indicating whether to return just a simplified output containing only the value estimate for each measure, with no associated statistics.
plot	Logical; if TRUE (default), plot the values on which the measures are based.
plot.lines	(if plot=TRUE) logical value (default TRUE) indicating whether or not to add lines connecting the points in the moving bins plot. Missing value (NA) bins are not connected (see lines).
plot.values	logical (default TRUE), whether or not to show the measure values on the plots.
cex.values	Character expansion (size) for plot values text.
plot.digits	(if plot=TRUE and plot.values=TRUE) number of digits (default 3) to which the values in the plots should be rounded.
main	(if plot=TRUE) main titles for the two plots.
na.rm	Logical (default TRUE) indicating if missing values should be removed from computations.
verbosity	integer specifying the amount of console messages to display. Defaults to the maximum implemented; lower numbers (down to 0) decrease the number of messages.
...	(if plot=TRUE) additional graphical parameters that can be passed to plot().

Details

This function evaluates model predictions using strictly presence-only data, as described by Barbosa (submitted).

When pred is a SpatRaster, presence coordinates must be supplied via obs as a SpatVector or a two-column coordinate matrix/data frame.

Value

A list with the following components:

bins	A data frame containing bin statistics from getBins.
Nbins	Number of bins with (not missing, non-NA) data.
bPOGI	bin-based Presence-Only Gradient Index.
dPOGI	density-based (bin-independent) Presence-Only Gradient Index.
PODS	Presence-Only Distributional Shift (PODS).
N	Number of predicted values (at presence sites if 'obs' provided).

If plot = TRUE, two diagnostic plots are also produced.

References

Barbosa A.M. (under review) Strictly presence-only measures for evaluating gradient consistency in species distribution model predictions.

See Also

getBins, Boyce, cor.test, wilcox.test

Examples

# load sample models:
data(rotif.mods)

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

# compute the PO measures:
# poMeasures(model = mod)


# you can also use vectors of observed and predicted values
# instead of a model object:

obs <- mod$y
pred <- mod$fitted.values

poMeasures(obs = obs, pred = pred)


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

modEvA documentation built on April 27, 2026, 3 a.m.