clampVars: Clamp variables

In fuzzySim: Fuzzy Similarity in Species Distributions

Clamp variables

Description

This function is a wrapper (with additional input options) for terra::clamp, which caps each variable, in a table or a (multilayer) raster, to the extreme values observed in a reference (e.g. model training) dataset. Values below the reference minimum are set to that minimum (or to NA), and values above the reference maximum are set to that maximum (or NA).

Clamping may help prevent overly unreliable extrapolation when projecting a model beyond the training conditions. The trade-off is that this assumes the response remains completely flat beyond those training thresholds, which is not entirely realistic either (e.g. Pinilla-Buitrago et al., 2026). Thus, a "clamping mask" should normally also be computed, i.e. the difference between the model predictions obtained with the original and the clamped variables, to show where and by how much the predictions are changed by clamping.

Usage

  clampVars(vars, ref, values = TRUE)

Arguments

vars	A SpatRaster or an object inheriting class 'data.frame' containing the variables to be clamped, one in each layer or column, with names matching the corresponding variables in 'ref'.
ref	The reference (e.g. model training) dataset that defines the clamping limits for the (subset of) variables to be clamped in 'vars'. It can be: a SpatRaster or an object inheriting class data.frame containing, in separate layers or columns, the reference (e.g. model training) values for the variables in 'vars', or just two rows with the minimum and maximum value for each variable a SpatVector of points with the reference or training localities (both presences and pseudoabsences/background points), in which case 'vars' must be a SpatRaster and should have values at all those localities a model object of class maxnet or a class implemented in modEvA::mod2obspred (except randomForest, which does not store predictor values), from which the extreme training values of the predictor variables will be taken.
values	logical value to pass to terra::clamp. If FALSE, 'vars' values outside the 'ref' range become NA; if TRUE (default), they get the extreme values found in 'ref'

Details

If 'ref' is a SpatVector of points, it is used in a terra::mask of the 'vars' SpatRaster, and values are then extracted from the raster predictors.

Clamping of variables to stay within the range of model training values was originally implemented in Maxent (Phillips et al., 2006), but its rationale is applicable to other models. It can be recommended when projecting a model in space or time, to avoid extrapolating beyond the known responses.

Future versions of this function might implement custom or one-sided clamping (Pinilla-Buitrago et al., 2026).

Value

The function returns an object of the same general type as 'vars', i.e. a SpatRaster or a data.frame of the clamped 'vars'.

Author(s)

A. Marcia Barbosa

References

Phillips S.J., Anderson R.P. & Schapire R.E. (2006) Maximum entropy modeling of species geographic distributions. Ecological Modelling 190, 231-259. https://doi.org/10.1016/j.ecolmodel.2005.03.026

Pinilla-Buitrago G.E., Kass J.M. & Anderson R.P. (2026) Extrapolation strategy matters when transferring ecological niche models: new visualization tools for informed decisions. Ecography n/a, e08590. https://doi.org/10.1002/ecog.08590

See Also

terra::clamp, predict

Examples

## Not run: 
  # RASTER EXAMPLE:

  library(terra)

  elev <- terra::rast(system.file("ex/elev.tif", package = "terra"))
  slope <- terra::terrain(elev, v = "slope")
  vars <- c(elev, slope)
  terra::plot(vars)


  ## With SpatVector points as reference data:

  set.seed(1)
  pts <- terra::spatSample(vars, 100, na.rm = TRUE, as.points = TRUE)
  terra::plot(vars[[1]])
  terra::points(pts)

  vars_clamped <- clampVars(vars, pts)
  names(vars_clamped) <- paste0(names(vars_clamped), "_clamp")
  plot(c(vars, vars_clamped), axes = FALSE)


  ## With a data frame as reference data:

  terra::plot(vars)

  vals <- terra::extract(vars, pts)
  head(vals)

  vars_clamped <- clampVars(vars, vals)
  terra::plot(vars_clamped)

## End(Not run)

  # DATA FRAME EXAMPLE:

  cars
  ref <- data.frame(speed = c(6, 22), dist = c(12, 56))
  # you can use more rows, or fewer columns

  cars_clamp <- clampVars(cars, ref)
  cars_clamp


  # MODEL EXAMPLE:

  iris$Species <- ifelse(iris$Species == "virginica", NA,
                         ifelse(iris$Species == "setosa", 1, 0))
  mod <- glm(Species ~ Sepal.Length + Sepal.Width + Petal.Length,
             data = iris, family = binomial)

  iris_clamp <- clampVars(iris, mod)
  iris_clamp

  # try also with 'values = FALSE'

fuzzySim documentation built on Oct. 13, 2026, 3:02 a.m.