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.
decorrelate_data(
formula,
data,
spcov_params,
xcoord,
ycoord,
randcov_params,
partition_factor,
ordering,
local,
...
)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
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).
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.
An object from spcov_params() that contains the
spatial covariance parameters used by the spatial decorrelation transformation.
The name of the column in data representing the x-coordinate.
Can be quoted or unquoted. Not required if data is an sf object.
The name of the column in data representing the y-coordinate.
Can be quoted or unquoted. Not required if data is an sf object.
An object from randcov_params() that contains the
random effect variances used by the spatial decorrelation transformation.
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.
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".
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.
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.
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
decorrelate() spcov_params() randcov_params()
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))
Run the code above in your browser using DataLab