cv_nndm: Use the Nearest Neighbour Distance Matching (NNDM) to...
In blockCV: Spatial and Environmental Blocking for Cross-Validation

cv_nndm

R Documentation

Use the Nearest Neighbour Distance Matching (NNDM) to separate train and test folds

Description

A fast implementation of the Nearest Neighbour Distance Matching (NNDM) algorithm (Milà et al., 2022) in C++. Similar to cv_buffer, this is a variation of leave-one-out (LOO) cross-validation. It tries to match the nearest neighbour distance distribution function between the test and training data to the nearest neighbour distance distribution function between the target prediction and training points (Milà et al., 2022).

Usage

cv_nndm(
  x,
  column = NULL,
  r = NULL,
  size,
  pred_points = NULL,
  model_domain = NULL,
  num_sample = 10000L,
  sampling = "random",
  min_train = 0.05,
  presence_bg = FALSE,
  add_bg = FALSE,
  num_bins = 4L,
  plot = interactive(),
  report = interactive()
)

Arguments

`x`	a simple features (sf) or SpatialPoints object of spatial sample data (e.g., species data or ground truth sample for image classification).
`column`	character; indicating the name of the column in which response variable (e.g. species data as a binary response i.e. 0s and 1s) is stored. This is required when `presence_bg = TRUE`, otherwise optional.
`r`	a terra SpatRaster object of a predictor variable (optional). This defines the area that the model is going to predict; prediction points are sampled from it when neither `pred_points` nor `model_domain` is supplied. One of `r`, `pred_points`, or `model_domain` is required.
`size`	numeric value of the range of spatial autocorrelation (the `phi` parameter). This distance should be in metres (or in the coordinate units of `x` when its CRS is undefined). The range could be explored by `cv_spatial_autocor`. For residual-based guidance, add model residuals to `x` and pass that residual column to `cv_spatial_autocor`.
`pred_points`	a simple features (sf) object of prediction points (optional). If provided, these are used directly as the prediction locations instead of sampling from `r` or `model_domain`.
`model_domain`	an sf polygon of the prediction area (optional). If provided (and `pred_points` is not), prediction points are sampled from it.
`num_sample`	integer; the number of sample points from predictor (`r`) to be used for calculating the G function of prediction points.
`sampling`	either `"random"` or `"regular"` for sampling prediction points. When `sampling = "regular"`, the actual number of samples might be less than `num_sample` for non-rectangular rasters (points falling on no-value areas are removed).
`min_train`	numeric; between 0 and 1. A constraint on the minimum proportion of train points in each fold.
`presence_bg`	logical; whether to treat data as species presence-background data. For all other data types (presence-absence, continuous, count or multi-class responses), this option should be `FALSE`.
`add_bg`	logical; add background points to the test set when `presence_bg = TRUE`. We do not recommend this according to Radosavljevic & Anderson (2014). Keep it `FALSE`, unless you mean to add the background pints to testing points.
`num_bins`	integer; the number of quantile bins used to stratify a continuous numeric `column`. The default is `4`. Set `num_bins = NULL` to disable binning and treat every unique value as a separate class (the behaviour prior to version 3.3). If quantile breaks are tied, fewer bins may be used. The raw response values are not modified; bins are only used for fold balancing and record summaries.
`plot`	logical; whether to plot the G functions. Defaults to `interactive()`.
`report`	logical; whether to print summary of records in each fold. Defaults to `interactive()`.

Details

When working with presence-background data (presences and background points sampled across the study area to represent the available conditions rather than confirmed absences, specified by presence_bg = TRUE), only presence records are used for specifying the folds (recommended). The testing fold comprises only the target presence point (optionally, all background points within the distance are also included when add_bg = TRUE; this is the distance that matches the nearest neighbour distance distribution function of training-testing presences and training-presences and prediction points; often lower than size). Any non-target presence points inside the distance are excluded. All points (presence and background) outside of distance are used for the training set. The methods cycles through all the presence data, so the number of folds is equal to the number of presence points in the dataset.

For all other types of data (including presence-absence, count, continuous, and multi-class) set presence_bg = FALSE, and the function behaves similar to the methods explained by Milà and colleagues (2022).

Value

An object of class S3. A list of objects including:

folds_list - a list containing the folds. Each fold has two vectors with the training (first) and testing (second) indices
k - number of the folds
size - the distance band to separate training and testing folds)
exclusion - a data.frame with one row per fold: the fold number, the row index of its test point in x (test_id), and the exclusion_distance matched to that point. Unlike cv_buffer, where the exclusion distance is the constant size, NNDM matches a distinct radius to each test point: every point within exclusion_distance of the test point is held out, and the points beyond it form the training set. Note this is not capped by size: the matching only thins neighbours closer than size, so a point whose nearest neighbour already lies beyond size is left untouched and reports its (larger) natural nearest-neighbour distance
column - the name of the column if provided
presence_bg - whether this was treated as presence-background data
records - a table with the number of points in each category of training and testing

References

C. Milà, J. Mateu, E. Pebesma, and H. Meyer, Nearest Neighbour Distance Matching Leave-One-Out Cross-Validation for map validation, Methods in Ecology and Evolution (2022).

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/bio_5.tif", package = "blockCV")
covar <- terra::rast(path)

nndm <- cv_nndm(x = pa_data,
                column = "occ", # optional
                r = covar,
                size = 350000, # size in metres no matter the CRS
                num_sample = 10000,
                sampling = "regular",
                min_train = 0.1)

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