                        Changes in version 4.0-2                        

Fixed

  - Fixed geographic grid crashes in cv_spatial_autocor(); issue #71.
  - Fixed predefined fold counts in cv_spatial() and Test/Train labels
    in cv_plot(); issue #72.
  - Fixed size limits, unit conversion, and slider bounds in
    cv_block_size(); issue #73.

                 Changes in version 4.0-1 (2026-09-28)                  

Added

  - Added points_size to cv_plot to control the size of sample points;
    issue #68.

Fixed

  - Fixed cv_cluster() handling of constant raster layers during scaling
    and improved errors for missing raster values; issue #70.

                 Changes in version 4.0-0 (2026-08-20)                  

Added

  - Added cv_knndm, a k-fold Nearest Neighbour Distance Matching method
    with "blocks", "hierarchical", and "kmeans" clustering options. It
    supports geographical and feature-space matching via space, and
    accepts prediction points via r, pred_points, or model_domain; issue
    #63.
  - Added cv_distance, a diagnostic for comparing an existing blockCV
    fold design with the nearest-neighbour distance distribution
    expected in the prediction domain. It returns a cv_distance object
    carrying the per-fold test-to-nearest-train distance table in
    $distances, the Wasserstein-1 distances in $W, and the plot in
    $plot; a plot argument (default TRUE) controls only whether the plot
    is drawn.
  - Added cv_summary, a one-call fold-quality diagnostic that gathers
    fold sizes and class prevalence, the cv_distance and cv_similarity
    diagnostics (when a raster or prediction domain is supplied), and a
    data.frame of warnings about degenerate folds (empty or single-class
    test folds, classes missing from training, tiny folds, severe class
    imbalance, and high leakage).
  - Added cv_group, a leave-group-out cross-validation using an existing
    grouping column (e.g. site, plot, campaign, or individual) so
    records that share a group are never split across train and test. k
    = NULL gives one fold per group; a smaller k merges the groups into
    k folds, optionally balanced (balance = TRUE).
  - Added balance to make fold balancing explicit in cv_spatial,
    cv_cluster, and cv_knndm. cv_cluster(balance = FALSE) keeps the
    previous single k-means behaviour; balance = TRUE uses the new
    k_multiplier argument to create candidate clusters for more even
    folds; issue #34.
  - Added presence-background balancing support so cv_spatial,
    cv_cluster, and cv_knndm can base fold balancing or matching on
    presences, preventing background points from dominating the split.
  - Added spatial_weight to cv_cluster for spatially-constrained
    environmental clustering. It adds a soft spatial compactness
    pressure by blending the (standardised) coordinates into the
    covariates before k-means, so the Euclidean distance becomes (1 - w)
    * d_env^2 + w * d_geo^2. spatial_weight = 0 (default) keeps the
    previous pure-environmental behaviour exactly, larger values give
    environmentally coherent folds that are also geographically
    separated, and 1 clusters on the coordinates alone.
  - Added support for continuous or count column values in cv_spatial,
    cv_cluster, cv_buffer, cv_nndm, and cv_knndm. Numeric columns are
    binned with num_bins (default 4) for fold balancing and records
    reports; num_bins = NULL restores per-value handling.
  - Added combine_folds and fold_colors to cv_plot for single-map fold
    plots in cv_spatial, cv_cluster, cv_group, and cv_knndm.
  - Added bg_alpha to cv_plot to control the opacity of background
    points in presence-background fold plots; it is capped at
    points_alpha (with a warning) so the background is never drawn more
    prominent than the presences, and the "background shown faded"
    caption appears only when the background is actually more
    transparent.
  - Added species_pb.csv, a presence-background example dataset used in
    the cv_buffer() and cv_cluster() examples.
  - Added a second tutorial covering cv_summary, cv_similarity,
    cv_distance, and block-size selection with cv_spatial_autocor and
    cv_block_size.
  - Added a fourth tutorial showing how to use blockCV folds with
    caret::trainControl() via index and indexOut; issue #48.

Changed

  - The minimum R version is now 3.6.0.
  - Renamed the num_plot argument of cv_similarity to num_plots, for
    consistency with cv_plot (a breaking change for existing code that
    set num_plot).
  - Removed the sp dependency (a retiring package) from
    cv_spatial_autocor. Longlat inputs now pass an explicit great-circle
    cutoff to automap::autofitVariogram instead of being converted to a
    sp object, so automap (>= 1.1-20) is now required.
  - Reworked the fold-balancing search behind cv_spatial (random
    selection) and now cv_cluster(balance = TRUE). The objective is now
    scored on the test folds only and normalised per class (a Pearson
    chi-square against an equal split), and it minimises empty test
    cells for classes with at least k records before minimising
    imbalance. This replaces the previous rule (raise the smallest cell,
    then lower the standard deviation of all train and test cells at
    once), which could keep a split that leaves a class missing from a
    test fold and let an abundant class dominate the score. Because a
    different candidate assignment now wins, folds for a given seed may
    differ from earlier versions.
  - cv_similarity now computes presence-background similarity from
    presences only, matching cv_distance, and adds seed for reproducible
    random baselines. L1/L2 distance-based scores now handle
    single-layer rasters, single-point folds, missing covariates, and
    constant predictors more robustly, and the MESS score now guards
    constant (zero-range) predictors. cv_similarity also validates that
    the rows of x line up with the fold indices in cv, matching
    cv_distance.
  - Reports, plots, and progress bars now run by default only in
    interactive sessions for cv_spatial, cv_buffer, cv_cluster, and
    cv_nndm; cv_similarity progress bars now do the same. Report flags
    now suppress printing only; fold record tables are still returned.
    Issue #57.
  - The print methods for the fold objects (cv_spatial, cv_buffer,
    cv_cluster, cv_group, cv_knndm, cv_nndm) and for cv_spatial_autocor
    now show an informative summary (method description, key settings,
    and the per-fold train/test record table) instead of only echoing
    the class name, matching the diagnostic print methods of
    cv_distance, cv_similarity, and cv_summary. Each returns the object
    invisibly. The cv_cluster print distinguishes spatial, environmental
    (feature-space), and spatially-constrained environmental clustering,
    and the returned object now carries the spatial_weight used. The
    cv_spatial object now carries the block_shape ("hexagon", "square",
    or "user-defined") and the selection used, both shown in its print.
    The cv_distance and cv_similarity prints now note when the object is
    presence-background, making it clear the distance/similarity/novelty
    statistics are computed on presence points only (background samples
    excluded).
  - Functions that need a suggested package now stop with a clear
    installation message instead of an interactive install prompt, so
    they behave consistently in scripts and non-interactive sessions.
  - cv_cluster now rejects categorical (factor) layers in r with a clear
    error instead of silently clustering their integer codes, since
    environmental clustering uses k-means (Euclidean distance) and
    supports only numeric covariates. It also warns when spatial
    (coordinate-based) clustering runs on geographic (lon/lat)
    coordinates, since k-means uses Euclidean distance; consider
    projecting x. It now also validates k against the number of
    available sample points (or sampled raster cells) before calling
    stats::kmeans, stopping with a clearer message instead of the
    cryptic "more cluster centers than distinct data points" error.
  - The cv_* functions now raise a clear error when x cannot be coerced
    to an sf object, instead of silently continuing with the invalid
    input and failing later with an unrelated message.
  - cv_nndm no longer requires r when pred_points or model_domain are
    supplied, now falls back to Euclidean distances with a warning when
    x has no CRS, and errors when x and r have mismatched coordinate
    reference systems; issue #58.
  - cv_nndm now returns exclusion, a table with one row per fold giving
    the fold number, the row index of its test point in x (test_id), and
    the exclusion_distance matched to that point, so it is clear which
    record is held out at what distance. Unlike cv_buffer, whose
    exclusion distance is the constant size, NNDM matches a distinct
    radius to each test point; the radius is not capped by size, as
    points whose nearest neighbour already lies beyond size are left
    unthinned and keep their larger natural nearest-neighbour distance.
  - cv_similarity now returns a cv_similarity object (a list with the
    per-fold extrapolation summary in $extrapolation, the overall
    novelty rate in $overall, and the plot in $plot) instead of a ggplot
    with the summary attached as an attribute. It gains a plot argument
    (default TRUE) that controls only whether the plot is drawn; the
    plot object is always built and returned. The overall novelty rate
    is shown in the title and the novel region is shaded, and a new type
    = "map" plots the sample points in space, colouring each test point
    by its similarity to show where extrapolation occurs.
  - Improved the fold-object plot() methods, now including cv_spatial,
    so they accept the original sample data and report missing data more
    clearly; issues #59 and #60.
  - cv_spatial avoids duplicate block-to-point intersection work when
    subsetting and assigning blocks; issue #40.

Removed

  - Removed the legacy v2.x functions: buffering, envBlock,
    foldExplorer, rangeExplorer, spatialAutoRange, and spatialBlock; use
    the cv_* equivalents in new code.

Fixed

  - Fixed a train/test leakage bug in cv_nndm(presence_bg = TRUE) where
    the test fold used the presence's position instead of its row index,
    holding out the wrong point and leaving it in both train and test.
  - Fixed plot.cv_spatial_autocor() so single-layer autocorrelation
    objects plot correctly and multi-layer plots include the stored map
    panel.
  - cv_plot and cv_similarity now stop with a clear message when none of
    the requested num_plots folds exist (e.g. num_plots = 99 for
    a 5-fold object), instead of silently reducing the selection to
    nothing and failing later with a confusing "undefined columns
    selected" error; out-of-range values are still dropped when at least
    one requested fold is valid.

                        Changes in version 3.2.0                        

  - Added two new distance-based similarity scores, L1 and L2, to the
    cv_similarity function
  - Fixed a warning in cv_similarity for colour aesthetics with ggplot
  - Fixed the summary method and plotting for cv_spatial_autocor

                        Changes in version 3.1.7                        

  - Temporarily added sp package dependency to avoid CRAN error as
    required by automap package [#55].

                        Changes in version 3.1.6                        

  - Resolved unclear error messages; issue #52 by A. Márcia Barbosa
  - Resolved ggplot testing failure; issue #54 by Teun van den Brand

                        Changes in version 3.1.5                        

  - Resolved background pattern artefacts in raster plotting; issue #50
    by Camila Neder.

                        Changes in version 3.1.4                        

  - Just the biomod2 example is updated in vignettes; and the link in
    help file

                        Changes in version 3.1.3                        

  - the biomod2 and gstat packages are added to the Suggests section
  - Some minor edits in messages

                        Changes in version 3.1.2                        

  - The iteration in cv_spatial and spatialBlock is increased to 100 to
    make the result matches with v2.1.4
  - Removed the requirement of C++11
  - Some warnings are added for the miss use of the column argument

                        Changes in version 3.1.1                        

  - some internal fix.
  - the extend parameter is now added to spatialBlock and the function
    now uses cv_spatial internally.
  - the user_blocks in cv_spatial is restricted to random and predefined
    and systematic selection.
  - no raster package dependency

                        Changes in version 3.1.0                        

  - the result of the cv_spatial function for square blocks now matches
    the one of version 2 function spatialBlock (i.e. fold assignment
    starts from top-right corner; this is not the case for hexagon
    blocks)
  - square spatial blocks can be expanded to ensure no points fall
    outside the border of the blocks. This can be controlled by extend
    parameter now.

                        Changes in version 3.0.3                        

  - fixing a bug in counting records in the reporting of cv_spatial

                        Changes in version 3.0.2                        

  - fixing fold numbering of cv_spatial to reproducibility of earlier
    versions

                        Changes in version 3.0.1                        

  - Massive performance improvement in the C++ code of cv_nndm function
    for large datasets

                         Changes in version 3.0                         

  - Dependency to rgdal and rgeos are removed, and overall less
    dependency
  - Function names have been changed, with all functions now starting
    with cv_
  - The old functions (v2.x) still work to allow appropriate time for
    adapting the new code
  - The CV blocking functions are now: cv_spatial, cv_cluster,
    cv_buffer, and cv_nndm
  - Spatial blocks now support hexagonal (default), rectangular, and
    user-defined blocks
  - A fast C++ implementation of Nearest Neighbour Distance Matching
    (NNDM) algorithm (Milà et al. 2022) is now added
  - The NNDM algorithm can handle species presence-background data and
    other types of data
  - The cv_cluster function generates blocks based on kmeans clustering.
    It now works on both environmental rasters and the spatial
    coordinates of sample points
  - The cv_spatial_autocor function now calculates the spatial
    autocorrelation range for both the response (i.e. the binary or
    continuous data) and a set of continuous raster covariates
  - The new cv_plot function allows for visualization of folds from all
    blocking strategies using ggplot facets
  - The terra package is now used for all raster processing and supports
    both stars and raster objects, as well as files on disk.
  - The new cv_similarity provides measures on possible extrapolation to
    testing folds

                 Changes in version 2.1.4 (2021-06-17)                  

  - fixed CRAN error for ggplot guide
  - added rgdal as a suggest
  - changed the crs of raster data in the package to avoid datum
    warnings

                        Changes in version 2.1.3                        

  - fix the warning for spatialBlock function on geographic coordinate
    system

                        Changes in version 2.1.2                        

  - predefined folds from user-defined blocks are noe accepted
  - add seed argument to spatialBlock to have consistent results where
    needed

                        Changes in version 2.1.0                        

  - snowfall package for parallel processing is replaces by future.apply
    package; #7
  - future.apply, shiny, shinydashboard, geosphere and ggplot2 packages
    moved to SUGGESTION packages. These are not install by default and
    the user is asked if needed. #7
  - RStoolbox is no longer used for clustering
  - an argument is added to envBlock function for sampling from raster
    layers
  - no dependency on sp package any more
  - doParallel = FALSE by default in spatialAutoRange function

                        Changes in version 2.0.1                        

  - print() and cat() are removed from the functions and verbose
    argument is added instead

                        Changes in version 2.0.0                        

  - most of the underlying functions are migrated to sf functions;
  - the parallel processing changed from foreach to snowfall;
  - the species argument in spatialBlock function accepts multi-class
    responses to find evenly distributed records in train and test
    folds;

                        Changes in version 1.1.0                        

  - change spatialAutoRange function to accepts rasters with low number
    of pixels; #2
  - the maskBySpecies = FALSE in spatialBlock function is no longer
    supported;
  - the numLimit argument in spatialBlock function is only accepts
    numeric values, and 0 means searching for evenly distributed folds;

                        Changes in version 1.0.1                        

  - add speciesData to spatialAutoRange function;
