Extracts the raster cells around each survey point, records
the distance from the point to each cell, and computes a first set of
kernel-weighted covariates. Fit your starting model to those covariates,
then pass the model and the returned object to multiScale_optim(). This
is the first step of every multiScaleR workflow, shown in
vignette("v01-quickstart", package = "multiScaleR").
Usage
kernel_prep(
pts,
raster_stack,
max_D,
kernel = c("gaussian", "exp", "expow", "fixed"),
scale_vars = NULL,
sigma = NULL,
shape = NULL,
projected = TRUE,
progress = FALSE,
verbose = TRUE,
bin = TRUE,
nbins = 256L,
store_cell_data = TRUE
)Arguments
- pts
Survey point locations as a
SpatVector(terra) orsfobject, in a projected coordinate system whose units matchmax_D. Row names are kept as point IDs.- raster_stack
A
SpatRaster(terra) with one or more layers, on the same projection aspts. Withoutscale_vars, each layer becomes a covariate with the layer's name, so the names must match the model formula. Layer names cannot be"x", which is reserved for internal coordinate data. The raster must cover a buffer ofmax_Daround every point.- max_D
Positive numeric scalar. Radius, in map units, of the circle around each point within which raster cells are extracted. It is also the upper bound of the sigma search, and kernels are cut off at this distance. Set it above the largest plausible scale of effect, at least about 3.3 times the largest plausible sigma for a Gaussian kernel. If an estimate comes back near
max_D, increase it and runkernel_prep()again. See the section on choosingmax_Din multiScaleR-kernels.- kernel
Character. Distance-weighting function used for every covariate:
"gaussian"(default),"exp"(negative exponential),"expow"(exponential power, which also estimates a shape), or"fixed"(equal weight within a radius). The weight functions are given in multiScaleR-kernels. To compare kernels, runkernel_prep()once per kernel.- scale_vars
Optional covariate specifications created with
msr_vars(). Omit it to make each raster layer one kernel-weighted mean. Supply it to define derived covariates, such as a kernel mean and a landscape or surface metric from the same layer.- sigma
Optional numeric vector of starting sigma values, in map units, one per covariate whose scale is estimated (one per raster layer when
scale_varsis omitted). Default:NULL, which starts every sigma atmax_D / 2. The default is recommended. These values set the covariates inkernel_datand are not the starting values ofmultiScale_optim(), which chooses its own.- shape
Optional numeric vector of starting shape values for
kernel = "expow", with the same length assigma. Default:NULL, which starts every shape at 2 (the Gaussian form). Ignored for other kernels.- projected
Logical. Whether
ptsandraster_stackuse projected (planar) coordinates. Only projected coordinates are supported, soFALSEis an error. Default:TRUE.- progress
Logical. Show progress bars during extraction and weighting. Default:
FALSE.- verbose
Logical. Print status messages. Default:
TRUE.- bin
Logical. If
TRUE(default), summarize each kernel mean's cell values into distance bins.multiScale_optim()then evaluates kernel means from the bins instead of every cell, which is much faster and no longer depends onmax_D, at the cost of a negligible approximation. The analytic backends andmultiScale_bayes()require it for kernel means. Landscape and surface metrics are never binned.FALSEforces exact cell-by-cell evaluation.- nbins
Integer, at least 2. Number of equal-width distance bins when
bin = TRUE. More bins increase accuracy and memory. The default (256) reproduces exact optimization results to several significant figures. Ignored whenbin = FALSE.- store_cell_data
Logical. If
TRUE(default), the per-cell distances (d_list) and values (raw_cov) are kept. IfFALSE, they are dropped after binning, often shrinking the object by one to two orders of magnitude. This lean mode needsbin = TRUEand only kernel means. With landscape or surface metrics, orbin = FALSE, the cell data are kept and a message says so. The bins suffice for optimization,profile_sigma(), and the final refit.
Value
An object of class multiScaleR_data, a list. Its full structure
is described in multiScaleR_data. The parts you use directly:
kernel_dat: data frame with one row per point and one column per covariate. Values are centered and scaled (mean 0, standard deviation 1) at the starting sigma. Combine it with your response data to fit the starting model.scl_params: list with themeanandsdused for that scaling, in the covariates' own units.kernel,max_D,min_D, andscale_vars: the settings passed on tomultiScale_optim()andkernel_scale.raster().
Printing the object reports the number of points and covariates, the
kernel, the number of cells extracted around the first point ("Number of
elements"), whether binning is on, the minimum distance (min_D, about one
cell width and the lower bound of the sigma search), the maximum distance
(max_D), and the unit conversion (distances are stored divided by
max_D).
Prepare the points and rasters
Points and rasters must share a defined, projected CRS. Every distance,
including max_D and any sigma you supply, is in the linear unit of
that projection, usually meters. Landscape and surface metrics also need
square cells. Row names of pts are kept throughout, so model data can be
joined back to the points.
Each point's buffer is the circle of radius max_D, and every cell it
intersects is extracted, including partly covered boundary cells, which
keep their full kernel weight. Missing cells drop out of each weighted
mean, and the remaining weights renormalize. Extraction runs in batches of
25 points to limit the peak memory of temporary tables. Point order,
returned values, and distances are not affected.
Manage memory
A larger max_D extracts more cells per point. Check the size of the
object and the memory needed for parallel optimization with
estimate_multiscale_ram(). When every covariate is a kernel mean,
store_cell_data = FALSE keeps only the bins.
Related preparation functions
To assign each observation to a different annual raster while estimating
one pooled landscape relationship, use kernel_prep_by_group(). To
prepare inputs for unmarked models, see prepare_unmarked_data().
See also
multiScale_optim(), msr_vars(), multiScaleR-kernels,
multiScaleR_data, estimate_multiscale_ram().
vignette("v02-user-guide", package = "multiScaleR") explains each
argument on a worked example.
Examples
## Survey points and a binary habitat raster bundled with the package
data("pts")
data("count_data")
hab <- terra::rast(system.file("extdata", "hab.tif",
package = "multiScaleR"))
kernel_inputs <- kernel_prep(pts = pts,
raster_stack = hab,
max_D = 250, # map units (meters)
kernel = "gaussian",
verbose = FALSE)
# 75 points, one covariate, cells within 250 m of each point
kernel_inputs
#>
#> There are 75 observations at 1 spatial covariate(s):
#> hab
#>
#> The specified kernel is:
#> gaussian
#>
#> Number of elements:
#> 2052
#> Distance binning:
#> enabled (256 distance bins per covariate)
#> Minimum Distance:
#> 10
#> Maximum Distance:
#> 250
#> Unit Conversion:
#> 250
# Standardized kernel-weighted habitat at the starting sigma (125 m)
head(kernel_inputs$kernel_dat)
#> hab
#> 1 -0.4206979
#> 2 1.7520402
#> 3 0.5073754
#> 4 -0.8959421
#> 5 -0.1734359
#> 6 0.8108489
# Fit the starting model that multiScale_optim() will optimize
df <- data.frame(count_data["y"], kernel_inputs$kernel_dat)
mod <- glm(y ~ hab, family = poisson, data = df)
## Lean mode keeps only the distance bins
lean_inputs <- kernel_prep(pts = pts, raster_stack = hab, max_D = 250,
store_cell_data = FALSE, verbose = FALSE)
# Object sizes in megabytes
c(full = as.numeric(object.size(kernel_inputs)),
lean = as.numeric(object.size(lean_inputs))) / 1e6
#> full lean
#> 2.547640 0.328192
