
Bind Projected Coordinates to a Fitted Response Field
Source:R/response_field_geometry.R
response_field_geometry.RdCheck the coordinates used to fit a spatial response field and package
them, with their CRS, into a small descriptor for raster prediction. A
response field is a spatially correlated random effect on the response,
separate from the kernel scales of effect. To map such a model, each
raster cell needs its own field value, and the descriptor tells
predict.multiScaleR() how to compute it from cell coordinates.
Arguments
- object
A
multiScaleRresult frommultiScale_optim()with the defaultbackend = "refit", whose fitted model is one of:a
glmmTMBmodel with one shared exponential, Gaussian or Matern field, such asexp(pos + 0 | grp), and no other random effects. The family must be Gaussian, Poisson, NB2 or Gamma with a log link, or binomial with a logit link.a distance-removal model with a fixed-range abundance field from
fit_gdr_response_field().
- coords
Numeric matrix or data frame with two finite projected coordinate columns (x, y), one row per fitting row in the original row order. Repeated locations repeat their coordinates. For
glmmTMB, use the coordinates passed toglmmTMB::numFactor(), in the same units. For a distance-removal field, use exactly thecoordspassed tofit_gdr_response_field(). Those are block locations, which can be coarser than the survey points used for the kernel covariates.- crs
The projected CRS of
coords, as an EPSG code (for example32617) or any input accepted bysf::st_crs(). It must have two horizontal axes and linear units that matchcoords. Geographic, geocentric, vertical and compound CRSs are rejected. Prediction rasters must use an equivalent CRS. Nothing is transformed or rescaled, so choose the projected CRS before fitting.- batch_size
Positive integer, default 128. The largest number of raster cells passed to each native prediction call. Smaller batches use less memory but repeat the native setup more often.
- max_memory_mb
Positive number, default 512. A conservative budget, in MiB, for the dense arrays of each prediction batch. A batch whose estimate exceeds the budget stops before native prediction. Lower
batch_sizeif that happens. This is a planning estimate, not an operating-system memory cap. For a distance-removal field, the budget set infit_gdr_response_field()also applies.
Value
A multiScaleR_field_geometry object, a small list that stores no
model, coordinates or predictions. It contains:
schema_version, and for distance-removal fieldsprovider("native_GDR_fixed_range"),rangeandrange_estimated(FALSE).crs(WKT text) andunits, the linear units of the CRS.For
glmmTMBfields,positionandgroup, the names of the position and group columns, with the fittedgroup_valueandgroup_levels.training_locations(distinct field locations) andtraining_rows.provider_version, theglmmTMBorTMBversion.batch_sizeandmax_memory_mb, the prediction controls.reference_sha256,binding_sha256anddefinition_sha256, SHA-256 fingerprints of the coordinates, of the fitted context and of the descriptor itself. Prediction stops if any of them no longer matches, so recreate the descriptor after refitting or changing its inputs.
Map a fitted field
Pass the descriptor to predict.multiScaleR() through
raster_args = list(field_geometry = geometry). Prepare the layers with
kernel_scale.raster() using scale_center = TRUE and
match_buffer = TRUE. Each cell then supplies its own projected
coordinates to the field, and prediction runs on one core, in batches of
batch_size cells. No covariance among cells is computed or stored.
Several rows in raster_args$const give one band (or fit and SE pair) per
scenario row, in row order.
glmmTMB fields
Every raster cell is a new field position, so set
native_args = list(allow.new.levels = TRUE) in predict.multiScaleR().
Without it, prediction stops before the first batch. All cells use the
single fitted field group, and a scenario that names another group stops.
Supply ordinary site and offset scenarios as usual. A position or group
scenario passed to kernel_scale.raster() is replaced by the cell
coordinates during prediction. Do not substitute a constant coordinate.
On the response scale, predictions are the expected count for Poisson and
NB2 models, the mean for Gaussian and Gamma models, and the per-trial
probability for binomial models, including binomial models fitted to
success and failure counts.
Distance-removal fields
Use type = "lambda" for density. Each cell gets the field value predicted
at its center from the fitted block values, with the range held fixed.
allow.new.levels is not used. See fit_gdr_response_field() for the
full workflow, including scale-of-effect estimation with the field.
What the standard errors include
Standard errors are conditional on the selected kernel scales. They include
the fitted coefficient and field uncertainty, and for distance-removal
fields the extra field variance between blocks. They add no observation
noise and no kernel-scale uncertainty. re.form = NA gives a zero-field
reference, not an average over the field. Checking the coordinates does
not establish that the field is well estimated or that its intervals are
calibrated.
Examples
# \donttest{
if (requireNamespace("glmmTMB", quietly = TRUE)) {
# Give the bundled landscape (in meters) a projected CRS
land <- terra::rast(system.file("extdata", "landscape.tif",
package = "multiScaleR"))[["land2"]]
terra::crs(land) <- "EPSG:32617"
data("surv_pts")
pts <- terra::vect(surv_pts)
terra::crs(pts) <- "EPSG:32617"
pts <- pts[seq(1, 100, by = 2)] # 50 survey points
xy <- terra::crds(pts)
# Counts depend on habitat at a 400 m scale plus a correlated field
set.seed(3)
truth <- kernel_scale.raster(land, sigma = 400, kernel = "gaussian",
verbose = FALSE)
x2 <- as.numeric(scale(terra::extract(truth, pts, ID = FALSE)[, 1]))
field <- drop(t(chol(0.25 * exp(-as.matrix(stats::dist(xy)) / 800))) %*%
stats::rnorm(nrow(xy)))
inputs <- kernel_prep(pts = pts, raster_stack = land, max_D = 1200,
kernel = "gaussian", verbose = FALSE)
df <- data.frame(counts = stats::rpois(nrow(xy), exp(1 + 0.6 * x2 + field)),
inputs$kernel_dat)
df$pos <- glmmTMB::numFactor(xy[, 1], xy[, 2]) # field positions (m)
df$grp <- factor("all") # one shared field
m0 <- glmmTMB::glmmTMB(counts ~ land2 + exp(pos + 0 | grp),
family = poisson(), data = df,
start = list(theta = c(log(0.5), log(500))))
fit <- multiScale_optim(m0, inputs, n_cores = 1, verbose = FALSE)
# Bind the fitting coordinates and their CRS to the fitted field
geometry <- response_field_geometry(fit, coords = xy, crs = 32617)
print(geometry$training_locations) # 50 distinct field locations
# Expected counts with conditional SEs for a 10 x 10 cell window
layers <- kernel_scale.raster(land, multiScaleR = fit,
scale_center = TRUE, match_buffer = TRUE, clamp = TRUE, verbose = FALSE,
site_values = list(pos = as.character(df$pos[1]), grp = "all"))
window <- terra::crop(layers, terra::ext(1500, 1700, 1500, 1700))
attr(window, "multiScaleR_projection") <-
attr(layers, "multiScaleR_projection")
map <- predict(fit, window, se.fit = TRUE, uncertainty = "conditional",
native_args = list(allow.new.levels = TRUE),
raster_args = list(field_geometry = geometry))
print(map) # bands: fit (expected count) and se.fit
}
#> [1] 50
#> class : SpatRaster
#> size : 10, 10, 2 (nrow, ncol, nlyr)
#> resolution : 20, 20 (x, y)
#> extent : 1500, 1700, 1500, 1700 (xmin, xmax, ymin, ymax)
#> coord. ref. : WGS 84 / UTM zone 17N (EPSG:32617)
#> source(s) : memory
#> names : fit, se.fit
#> min values : 2.103838, 0.379276
#> max values : 3.97472, 0.585109
# }