cv_plot: Visualising folds created by blockCV in ggplot

In blockCV: Spatial and Environmental Blocking for Cross-Validation

Visualising folds created by blockCV in ggplot

Description

This function visualises the folds create by blockCV. It also accepts a raster layer to be used as background in the output plot. The output of cv_plot() is a ggplot object, so it can be customised with standard ggplot2 layers. For example, you can add a title, change the theme, or modify colours and scales.

Usage

cv_plot(
  cv,
  x,
  r = NULL,
  nrow = NULL,
  ncol = NULL,
  num_plots = 1:10,
  max_pixels = 3e+05,
  remove_na = TRUE,
  raster_colors = gray.colors(10, alpha = 1),
  points_colors = c("#E69F00", "#56B4E9"),
  points_alpha = 0.7,
  bg_alpha = 0.1,
  label_size = 4,
  combine_folds = FALSE,
  fold_colors = NULL
)

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) or SpatialPoints object of the spatial sample data used for creating the cv object. This is required for point-based objects such as cv_cluster, cv_group, cv_buffer, cv_nndm, and cv_knndm; it can be omitted for cv_spatial objects.
r	a terra SpatRaster object (optional). If provided, it will be used as background of the plots. It also supports stars, raster, or path to a raster file on disk.
nrow	integer; number of rows for facet plot
ncol	integer; number of columns for facet plot
num_plots	a vector of indices of folds; by default the first 10 are shown (if available). You can choose any of the folds to be shown e.g. 1:3 or c(2, 7, 16, 22)
max_pixels	integer; maximum number of pixels used for plotting r
remove_na	logical; whether to remove excluded points in cv_buffer from the plot
raster_colors	character; a character vector of colours for raster background e.g. terrain.colors(20)
points_colors	character; two colours to be used for train and test points
points_alpha	numeric; the opacity of points
bg_alpha	numeric; opacity of the background points (response 0) when the cv object was built with presence_bg = TRUE (see ‘Details’). Lower values fade them so the presences (response 1) stand out; set bg_alpha = points_alpha to disable the fading. Values above points_alpha are capped at points_alpha (with a warning) so the background is never drawn more prominent than the presences. Has no effect for objects that are not presence-background. The default is 0.1.
label_size	integer; size of fold labels when a cv_spatial object is used.
combine_folds	logical; if TRUE, all folds are shown in a single map with points coloured by their fold ID instead of separate train/test facets. Only available for cv_spatial, cv_cluster, cv_group and cv_knndm objects.
fold_colors	character; a vector of colours for the folds when combine_folds = TRUE; by default a qualitative palette is generated for the number of folds.

Details

The bg_alpha argument only applies to objects created with presence_bg = TRUE. There the cv response holds 1 for presences and 0 for background points – locations sampled across the study area to represent the available conditions rather than confirmed absences – and the background points are drawn faded so the presences stand out. This point-level “background” is unrelated to the raster r used as a map backdrop.

Value

a ggplot object

See Also

cv_distance and cv_similarity to evaluate the folds; cv_spatial, cv_cluster, cv_buffer, cv_nndm and cv_knndm to create them

Examples

library(blockCV)

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

# spatial clustering
sc <- cv_cluster(x = pa_data, k = 5)

# now plot the create folds
cv_plot(cv = sc,
        x = pa_data, # sample points
        nrow = 2,
        points_alpha = 0.5)

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