decorrelate_data: Apply the Spatial Decorrelation Transformation to a Data...

In spmodel: Spatial Statistical Modeling and Prediction

Apply the Spatial Decorrelation Transformation to a Data Object

Description

Apply the spatial decorrelation transformation to a data object. This object contains the transformed explanatory and response variables which can be used to fit a machine learning model. This object also contains information needed to decorrelate prediction data.

Usage

decorrelate_data(
  formula,
  data,
  spcov_params,
  xcoord,
  ycoord,
  randcov_params,
  partition_factor,
  ordering,
  local,
  ...
)

Arguments

formula	A two-sided linear formula describing the fixed effect structure of the model, with the response to the left of the ~ operator and the terms on the right, separated by + operators. . on the right-hand side represents every variable in data except the response and the x-coordinate/y-coordinate columns (xcoord/ycoord, or, for an sf object, the geometry column), which are never included via . (though they may still be given explicitly).
data	A data frame or sf object object that contains the variables in fixed, random, and partition_factor as well as geographical information. If an sf object is provided with POINT geometries, the x-coordinates and y-coordinates are used directly. If an sf object is provided with POLYGON geometries, the x-coordinates and y-coordinates are taken as the centroids of each polygon.
spcov_params	An object from spcov_params() that contains the spatial covariance parameters used by the spatial decorrelation transformation.
xcoord	The name of the column in data representing the x-coordinate. Can be quoted or unquoted. Not required if data is an sf object.
ycoord	The name of the column in data representing the y-coordinate. Can be quoted or unquoted. Not required if data is an sf object.
randcov_params	An object from randcov_params() that contains the random effect variances used by the spatial decorrelation transformation.
partition_factor	A one-sided linear formula with a single term specifying the partition factor. The partition factor assumes observations from different levels of the partition factor are uncorrelated.
ordering	The data ordering applied. Available options include "grts", "maxmin", "middleout", "outsidein", "coordinate", "random", and "none". "grts" applies ordering using a spatially balanced GRTS sample via spsurvey::grts(). "maxmin" applies maximum minimum distance ordering via GPvecchia::order_maxmin_exact(). "middleout" applies middle out ordering via GPvecchia::order_middleout(). "outsidein" applies middle out ordering via GPvecchia::order_outsidein(). "coordinate" applies middle out ordering via GPvecchia::order_coordinate(..., coordinate = c(1, 2)), which orders from bottom-left to top-right of the spatial domain. "random" applies a completely random ordering. "none" applies no random ordering. The default is "maxmin" unless there are multiple observations at a single location, in which case the default is "grts".
local	A optional logical or list controlling the big data approximation. If omitted, local is set to TRUE or FALSE based on the sample size (the number of non-missing observations in data) – if the sample size exceeds 5,000, local is set to TRUE. Otherwise it is set to FALSE. If local is FALSE, no big data approximation is implemented. If a list is provided, the following arguments detail the big data approximation: method: The big data approximation method. If method = "all", all observations are used and size is ignored. If method = "distance", the size data observations closest (in terms of Euclidean distance) to the observation requiring prediction are used. If method = "covariance", the size data observations with the highest covariance with the observation requiring prediction are used. If random effects and partition factors are not used in estimation and the spatial covariance function is monotone decreasing, "distance" and "covariance" are equivalent. The default is "covariance". size: The number of data observations to use when method is "distance" or "covariance". The default is 30. parallel: If TRUE, parallel processing via the parallel package is automatically used. This can significantly speed up computations even when method = "all" (i.e., no big data approximation is used), as predictions are spread out over multiple cores. The default is FALSE. ncores: If parallel = TRUE, the number of cores to parallelize over. The default is the number of available cores on your machine. When local is a list, at least one list element must be provided to initialize default arguments for the other list elements. If local is TRUE, defaults for local are chosen such that local is transformed into list(size = 30, method = "covariance", parallel = FALSE).
...	Other arguments to the functions called by algorithm.

Details

The spatial decorrelation transformation is a preprocessing transformation that reduces the impacts of spatial dependence (i.e., covariance, correlation) on machine learning models. See decorrelate() and Heaton et al., 2025 for more details.

Value

A list with many elements that store information about the fitted model object. Importantly, the list contains the following elements:

• X: The original fixed effects design matrix (of explanatory variables)

• y: The original response variable

• tX: The spatially decorrelated transformed fixed effects design matrix

• ty: The spatially decorrelated transformed response variable

References

Matthew J. Heaton, Andrew Millane, and Jake S. Rhodes. 2025. A Scalable Spatial Decorrelation Preprocessing Approach for Machine and Deep Learning. Journal of Data Science. 1-15, DOI 10.6339/25-JDS1210

See Also

decorrelate() spcov_params() randcov_params()

Examples

params <- spcov_params("exponential", de = 1, ie = 0.2, range = 1e5)
decorr <- decorrelate_data(log_cond ~ temp, data = lake, spcov_params = params)
head(cbind(decorr$X, decorr$tX))
head(cbind(decorr$y, decorr$ty))

spmodel documentation built on Sept. 11, 2026, 1:07 a.m.