cv_group: Leave-group-out cross-validation using an existing grouping...

In blockCV: Spatial and Environmental Blocking for Cross-Validation

Leave-group-out cross-validation using an existing grouping factor

Description

This function creates cross-validation folds from a grouping column that is already present in the data – for example a site, plot, campaign, or individual identifier. All records that share a group are always kept together, so a group is never split across the training and testing sets. This is the hierarchical / grouped ("leave-group-out") blocking that is not covered by the clustering functions: unlike cv_cluster (which builds groups with k-means) or cv_knndm (whose "hierarchical" option is agglomerative clustering), cv_group takes the groups as given.

Usage

cv_group(
  x,
  group_col,
  k = NULL,
  column = NULL,
  balance = FALSE,
  iteration = 100L,
  seed = NULL,
  biomod2 = TRUE,
  num_bins = 4L,
  report = interactive(),
  progress = 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).
group_col	character. The name of the column in x that holds the grouping factor (e.g. site, plot, campaign, or individual ID). Records sharing a value are kept together in the same fold. Missing values are not allowed.
k	integer (optional). The number of desired folds. When NULL (default) or greater than or equal to the number of groups, leave-group-out is used (one fold per group). When smaller than the number of groups, the groups are merged into k folds. See ‘Details’.
column	character (optional). 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. It is used to report whether all the folds contain all the classes and, when balance = TRUE, to balance those classes across the folds. Continuous numeric responses are binned into quantiles using num_bins before records are counted.
balance	logical. Only used when k is smaller than the number of groups. If TRUE, the groups are assigned to the k folds over iteration random attempts to balance the training/testing records (or the classes/bins of column when it is provided). If FALSE (default), the groups are distributed across the folds deterministically. Ignored for leave-group-out.
iteration	integer value. The number of random attempts to assign the groups to folds when balance = TRUE.
seed	integer; a random seed for reproducibility of the balancing search.
biomod2	logical. Creates a matrix of folds that can be directly used in the biomod2 package as a CV.user.table for cross-validation.
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.
report	logical; whether to print the report of the records per fold. Defaults to interactive().
progress	logical; whether to shows a progress bar for random fold selection. Defaults to interactive().

Details

The number of folds is controlled by k:

• k = NULL (default) or k greater than or equal to the number of groups – leave-group-out: every group forms its own fold and is left out once. In this mode balance has no effect because the folds are fixed by the groups.

• k less than the number of groups – the groups are merged into k folds. With balance = FALSE (default) the groups are distributed across the folds deterministically (keeping a similar number of groups per fold). With balance = TRUE the groups are assigned to the k folds over iteration random attempts, keeping the split that best balances the training/testing records (or the classes/bins of column when it is provided), mirroring the balancing used by cv_cluster.

In every case whole groups move together, so k < n_groups still yields folds that respect the grouping structure while giving fewer, larger folds than leave-group-out.

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

• folds_ids - a vector of values indicating the number of the fold for each observation (each number corresponds to the same point in x)

• biomod_table - a matrix with the folds to be used in biomod2 package

• k - number of the folds

• column - the name of the column if provided

• group_col - the name of the grouping column

• type - indicates whether leave-group-out or merged grouping was used

• records - a table with the number of points in each category of training and testing

See Also

cv_cluster and cv_spatial; cv_plot to visualise, and cv_distance and cv_similarity 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)

# add an example grouping column (e.g. survey site)
pa_data$site <- sample(paste0("site_", 1:8), nrow(pa_data), replace = TRUE)

# leave-group-out: one fold per site
lgo <- cv_group(x = pa_data,
                group_col = "site",
                column = "occ") # optional; name of the column with response

# merge the sites into 4 balanced folds
set.seed(6)
gm <- cv_group(x = pa_data,
               group_col = "site",
               column = "occ",
               k = 4,
               balance = TRUE)

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