cv_similarity: Compute similarity measures to evaluate possible...

In blockCV: Spatial and Environmental Blocking for Cross-Validation

Compute similarity measures to evaluate possible extrapolation in testing folds

Description

This function evaluates environmental similarity between training and testing folds, helping to detect potential extrapolation in the testing data. It supports three similarity outputs: MESS, L1, and L2. The L1 and L2 options are distance-based similarity scores.

Usage

cv_similarity(
  cv,
  x,
  r,
  num_plots = seq_along(cv$folds_list),
  method = "MESS",
  type = "distribution",
  num_sample = 10000L,
  seed = NULL,
  jitter_width = 0.1,
  points_size = 2,
  points_alpha = 0.7,
  points_colors = NULL,
  progress = interactive(),
  plot = TRUE
)

Arguments

cv	a blockCV cv_* object; a cv_spatial, cv_cluster, cv_group, cv_buffer, cv_nndm, or cv_knndm
x	a simple features (sf) object of the spatial sample points used for creating the cv object.
r	a terra SpatRaster object of environmental predictor that are going to be used for modelling. This is used to calculate similarity between the training and testing points.
num_plots	a vector of indices of folds for plotting (default uses all).
method	the similarity method: MESS, L1, or L2. Read the details section.
type	character; "distribution" (default) draws the per-fold similarity distributions, while "map" plots the sample points in geographical space and colours each test point by its similarity value, showing where extrapolation occurs.
num_sample	number of random raster samples used for the L1/L2 baseline.
seed	integer; an optional random seed. The L1/L2 baseline is built from a random raster sample (num_sample); set seed to make the result reproducible.
jitter_width	numeric; the width of jitter points.
points_size	numeric; the size of points.
points_alpha	numeric; the opacity of points
points_colors	character; a character vector of colours for the diverging value scale. Defaults to a red-grey-blue ramp (red = novel/negative, blue = similar/positive) centred at zero.
progress	logical; whether to show a progress bar while computing fold similarities. Defaults to interactive().
plot	logical; whether to draw the plot (default TRUE). The plot object is always built and returned in $plot either way (so it can be customised or arranged); plot = FALSE only suppresses drawing it now.

Details

The MESS is calculated as described in Elith et al. (2010). MESS represents how similar a point in a testing fold is to a training fold (as a reference set of points), with respect to a set of predictor variables in r. The negative values are the sites where at least one variable has a value that is outside the range of environments over the reference set, so these are novel environments.

When using the L1 (Manhattan) or L2 (Euclidean) score options (experimental), the function performs the following steps for each test sample:

• 1. Calculates the minimum distance between each test sample and all training samples in the same fold using the selected metric (L1 or L2).

• 2. Calculates a baseline distance: the average of the minimum distances between a set of random background samples (defined by num_sample) from the raster and all training/test samples combined.

• 3. Computes a similarity score by subtracting the test sample’s minimum distance from the baseline average. A higher score indicates the test sample is more similar to the training data, while lower or negative scores indicate novelty.

This provides a simple, distance-based similarity score, not a raw distance: values below zero indicate test samples that are farther from their training data than the random-background baseline. Note that this approach is experimental.

When the supplied cv object was built with presence_bg = TRUE, the similarity is computed on the presences only: the background points (locations sampled to represent the available conditions rather than confirmed absences) are excluded from both the training and testing sets of every fold, matching the framing used in cv_distance. This is read automatically from cv.

Value

an object of class cv_similarity: a list with

• extrapolation - a per-fold data.frame with the number of test points, the percentage flagged as novel (similarity value below zero), the minimum and median similarity, and – for method = "MESS" – the most limiting variable (the covariate most often driving the novelty).

• overall - the overall novelty rate (percentage of test points below zero) across the plotted folds.

• plot - the ggplot (a per-fold distribution, or a spatial map for type = "map"), always built whether or not it is drawn.

The plot is drawn when plot = TRUE (default). Printing the object shows a compact text summary rather than redrawing the plot; call plot() on the returned object to redraw it.

References

Elith, J., Kearney, M., & Phillips, S. (2010). The art of modelling range-shifting species: The art of modelling range-shifting species. Methods in Ecology and Evolution, 1(4), 330–342.

See Also

cv_spatial, cv_cluster, cv_buffer, and cv_nndm; cv_plot to visualise, and cv_distance to evaluate, the folds

Examples

library(blockCV)

# import presence-absence species data
points <- read.csv(system.file("extdata/", "species.csv", package = "blockCV"))
# make an sf object from data.frame
pa_data <- sf::st_as_sf(points, coords = c("x", "y"), crs = 7845)

# load raster data
path <- system.file("extdata/au/", package = "blockCV")
files <- list.files(path, full.names = TRUE)
covars <- terra::rast(files)

# hexagonal spatial blocking by specified size and random assignment
sb <- cv_spatial(x = pa_data,
                 column = "occ",
                 size = 450000,
                 k = 5,
                 iteration = 1)

# compute extrapolation
cv_similarity(cv = sb, r = covars, x = pa_data, method = "MESS")

blockCV documentation built on Aug. 20, 2026, 5:10 p.m.