| Type: | Package |
| Title: | Estimate Scales of Effect for Spatial Ecological Models |
| Version: | 1.0.1 |
| Description: | Estimates the scale of effect, the distance over which a landscape variable influences an ecological response. Raster values around each sample location are weighted with a distance kernel, and the kernel scale that maximizes the likelihood of a fitted regression model is found. Works with linear, generalized linear, additive, and mixed models, with 'unmarked' occupancy, abundance, and distance-removal models, and with step-selection models, and fits Bayesian models in which scales vary among years or with covariates. Also provides kernel-weighted landscape and surface metrics, cross-validation, model selection tables, fast kernel smoothing of rasters for mapping predictions, and simulation of data with known scales of effect. For more details see Peterman (2026) <doi:10.1007/s10980-025-02267-x>. |
| License: | GPL-3 |
| Encoding: | UTF-8 |
| LazyData: | true |
| Imports: | digest, Rcpp, Matrix, cowplot, dplyr, fields, ggplot2, insight, stats, utils, tools, unmarked, exactextractr, crayon, parallel, optimParallel, AICcmodavg, methods, sf, graphics, grDevices |
| LinkingTo: | Rcpp, RcppArmadillo |
| Depends: | R (≥ 4.3), terra |
| Suggests: | bayesplot, glmmTMB, TMB, RTMB (≥ 2.0), tmbstan (≥ 1.2.1), rstan, posterior (≥ 1.6.0), knitr, landscapemetrics, geodiv, rmarkdown, MASS, lme4, lpSolve (≥ 5.6.23), gmp (≥ 0.7-5.1), mgcv, nlme, pkgload, processx, ps, pscl, survival, amt, spaMM, splines, testthat (≥ 3.0.0) |
| Config/testthat/edition: | 3 |
| URL: | https://wpeterman.github.io/multiScaleR/, https://github.com/wpeterman/multiScaleR |
| BugReports: | https://github.com/wpeterman/multiScaleR/issues |
| BuildVignettes: | true |
| VignetteBuilder: | knitr |
| Author: | Bill Peterman |
| Maintainer: | Bill Peterman <Peterman.73@osu.edu> |
| Config/roxygen2/version: | 8.0.0 |
| NeedsCompilation: | yes |
| Packaged: | 2026-11-19 16:16:25 UTC; peterman.73 |
| Repository: | CRAN |
| Date/Publication: | 2026-11-19 18:40:10 UTC |
multiScaleR: estimate scales of effect for spatial covariates
Description
The scale of effect is the distance over which a landscape variable influences an ecological response, such as how far from a pond the surrounding forest still affects salamander counts. multiScaleR estimates it directly. It weights the raster cells around each survey point with a distance kernel, and it chooses the kernel scale (sigma) that maximizes the likelihood of your regression model. You fit your model once at starting values, and multiScaleR does the search, reports each scale with its uncertainty, and helps you compare, check, and map the result.
Details
Start here
Work through vignette("v01-quickstart", package = "multiScaleR"), then
vignette("v02-user-guide", package = "multiScaleR"). Run
browseVignettes("multiScaleR") to see all 15 vignettes, which cover
mapping, landscape and surface metrics, year-specific rasters, fitting
methods, cross-validation, intervals, step selection, spatial fields,
distance-removal models, and Bayesian models. multiScaleR-glossary
defines the terms they use.
The basic workflow
| Step | Functions |
| 1. Describe the covariates | kernel_var(), landscape_var(), surface_var(), msr_vars() |
| 2. Prepare the points and rasters | kernel_prep(), kernel_prep_by_group(), estimate_multiscale_ram() |
| 3. Fit your model at starting values | Your usual function, such as glm() or unmarked::pcount() |
| 4. Estimate the scales | multiScale_optim() or multiScale_bayes() |
| 5. Read and check the fit | summary(), plot(), diagnostics(), profile_sigma(), kernel_dist(), plot_kernel() |
| 6. Compare models | aic_tab(), bic_tab(), cross_validate(), cv_tab(), select_cv() |
| 7. Predict and map | predict(), kernel_scale.raster(), plot_marginal_effects(), prepare_prediction()
|
Specialized models and tools
-
Choosing a fitting method: multiScaleR-fitting-methods describes each backend of
multiScale_optim(). -
Cross-validation for other model types:
cross_validate_glm(),cross_validate_clogit(),cross_validate_field(),cross_validate_mixed(),cross_validate_bayes(), with fold buildersspatial_cv_folds()andgrouped_cv_folds(). -
Occupancy and abundance models from
unmarked:prepare_unmarked_data(),validate_unmarked_data(). -
Distance-removal models:
prepare_gdr_histories(),prepare_gdr_intervals(),expand_gdr_intervals(),gdr_start_values(),make_gdr_refitter(),fit_gdr_response_field(),response_field_geometry(). -
Bayesian models, in which a scale may vary among years or with a covariate:
multiScale_bayes(),check_bayes_setup(),simulate_bayes_prior(),posterior_scales(),predict_scales(),diagnose_bayes_scales(),diagnose_bayes_probabilities(),diagnose_bayes_laplace(). -
Assessing NB2 scales over the full likelihood range:
scale_inference(). -
Simulating data with known scales of effect:
sim_rast(),sim_dat(),sim_dat_unmarked(),sim_dat_gdr().
Reference topics
| Topic | What it covers |
| multiScaleR-kernels | Kernel families, sigma and shape, hard radii, effective distance |
| multiScaleR-fitting-methods | Backends, their requirements, and the uncertainty each reports |
| multiScaleR-prediction | Prediction quantities and the uncertainty each route carries |
| multiScaleR-glossary | Definitions of the terms used in the documentation |
| multiScaleR | The fitted object from multiScale_optim() |
| multiScaleR_data | The prepared inputs from kernel_prep() |
| multiScaleR_bayes | The fitted object from multiScale_bayes() |
| multiScaleR_cv | Cross-validation results |
Experimental tools
These tools are experimental. Their arguments and results may change in a
later release without a deprecation period: cross_validate_bayes(),
cross_validate_mixed(), the count, binary, and positive families of
cross_validate_field(), diagnose_bayes_laplace(), and the
radius_grid argument of multiScale_optim().
Citation
Run citation("multiScaleR") for the paper describing the method.
Author(s)
Maintainer: Bill Peterman Peterman.73@osu.edu (ORCID)
Authors:
Bill Peterman Peterman.73@osu.edu (ORCID)
See Also
Useful links:
Report bugs at https://github.com/wpeterman/multiScaleR/issues
Examples
# Estimate the scale of effect of habitat on simulated counts
data(pts)
data(count_data)
hab <- terra::rast(system.file("extdata", "hab.tif",
package = "multiScaleR"))
inputs <- kernel_prep(pts = pts, raster_stack = hab, max_D = 250,
kernel = "gaussian", verbose = FALSE)
start_model <- glm(y ~ hab, family = poisson, data = count_data)
fit <- multiScale_optim(start_model, inputs, verbose = FALSE)
summary(fit) # sigma near the simulated value of 75 map units
Rank models by AIC or AICc
Description
Build a model-selection table ranked by AICc (the default) or
AIC for a list of fitted models. Each estimated scale of effect (sigma), and
each estimated kernel shape, counts as a parameter, so a scale-optimized
model competes fairly with fixed-scale or non-spatial alternatives in the
same list. Lists can mix multiScaleR objects with plain fitted models
such as glm objects.
vignette("v02-user-guide", package = "multiScaleR") compares kernels and
model structures with these tables, including an N-mixture model.
Usage
aic_tab(mod_list,
AICc = TRUE,
mod_names = NULL,
verbose = FALSE,
...)
Arguments
mod_list |
A list of fitted models: |
AICc |
Logical. If |
mod_names |
Optional character vector of model names, one per model
in |
verbose |
Logical. If |
... |
Not used. |
Value
A data frame of class "aictab" (from the AICcmodavg package),
sorted from the best (smallest) criterion value, with one row per model:
-
Modnames: model name, frommod_namesor the default label. -
K: number of estimated parameters. It counts the fitted likelihood parameters, including ancillary ones such as negative binomial dispersion (or native effective degrees of freedom for GAMs), plus each estimated scale and shape of amultiScaleRmodel. -
AICcorAIC: the information criterion. Smaller is better. -
Delta_AICcorDelta_AIC: difference from the best model. Models within about 2 units of the best are generally considered to have comparable support. -
ModelLik: relative likelihood of the model,exp(-0.5 * Delta). -
AICcWtorAICWt: Akaike weight, the relative support for each model within this set. Weights sum to 1. -
LL: maximized log-likelihood. -
Cum.Wt: cumulative Akaike weight.
When a likelihood was adjusted (see "Count parameters"), the table carries
a likelihood_adjustments attribute.
Count parameters
For a multiScaleR object, the log-likelihood and parameter count come
from the refit model in opt_mod, and each estimated sigma (and shape, for
kernel = "expow") is added to K. The AIC printed by the native model in
opt_mod leaves those parameters out. Hard-radius metrics in an "expow"
model add their estimated radius but no shape, and fixed-radius metrics add
neither. Plain models in the list get no sigma. Otherwise the native
log-likelihood degrees of freedom are used when available, so negative
binomial dispersion counts as one parameter. Missing or inconsistent
parameter metadata and non-finite log-likelihoods raise an error rather
than guessing from predictor names.
-
unmarkedmodels. The native AIC and log-likelihood determine the count. It includes every abundance or occupancy coefficient, every detection coefficient, factor contrasts, mixture parameters, and estimated random-effect standard deviations. Optimizer and TMB free-parameter metadata are checked for agreement when present. Latent abundances and realized random effects add nothing. For example, four abundance coefficients, three detection coefficients, and one random-effect standard deviation give eight native parameters, or nine with one estimated Gaussian scale. A table of fixed coefficients can therefore show fewer parameters than the fitted count. -
The
Kargument ofunmarked::pcount()is an upper bound for the abundance sum in the likelihood, not a parameter count. Check that the log-likelihood does not change when you refit with a larger bound. -
spaMM
HLfitmodels.spaMM::DoF()supplies the full count, including estimated residual, covariance, and correlation parameters. Realized random effects are not counted. The native default log-likelihood target is kept (p_vfor ordinary maximum likelihood,p_bvfor REML), so absolute REML criteria can differ from spaMM's marginal AIC, which usesp_v. -
mgcv negative binomial BAMs. The table checks the native fit against the normalized count likelihood. A retained outer scale flag can otherwise add one to both the reported log-likelihood and the parameter count, even though the family scale is one. Verified fits use the normalized likelihood and native effective degrees of freedom plus an estimated theta, with no extra scale parameter. A fixed theta adds no parameter. The
likelihood_adjustmentsattribute records the native and used likelihoods and regression-model counts for the affected models, before the scale and shape parameters are added. With large case weights, verification checks the native AIC arithmetic and a rescaled response-density comparison at the original tolerance, and records that method. Reported likelihoods keep the original weights. Unknown inconsistencies raise an error, and fitted coefficients, covariance, and diagnostics are unchanged.
Check that models are comparable
Information criteria compare models only when they describe the same
observations with comparable likelihoods. The table checks the number of
observations and, when native metadata can be recovered, the used row IDs,
response values, binomial trials, likelihood weights, and the likelihood's
response measure. Zero-weight GLM rows and removed unmarked sites are
excluded from the used observations. Binomial counts and proportions with
their trial weights are compared on the same count scale, and logical
FALSE/TRUE outcomes, including success and failure columns, compare as
0 and 1 when trial totals and weights agree. Fitted responses, covariance,
and parameter counts are not changed.
-
N-mixture models. Mixed
unmarked::pcount()models keep their native marginal likelihood. Two models can share sites and the original count matrix yet use different visits when a detection covariate has missing values. The table recovers the visits each model used from its component formulas, including formula-specific missing observations and omitted sites, and stops when they differ. Equal count matrices and site totals alone do not establish comparability, and missing or inconsistent used-response metadata raises an error without falling back on raw data. Null abundance models and detection-only models without site covariates keep the native site count and their original response-row identities. -
Distance-removal models.
gdistremoval()comparisons check both distance and removal histories and their stored survey protocol, including the primary-period layout, distance bins and units, and removal durations. Equal paired totals are not enough. Distances in meters and kilometers are converted to meters in the comparison copy, and the fitted objects keep their native units. Harmonize time units and event definitions before comparing, because a native frame does not store a removal-time unit. Mixture and distance-key alternatives may share the same observed target. Check sensitivity to the integration cutoff separately. -
Maximum likelihood and REML. ML and REML fits cannot be mixed, and REML comparisons require the same recoverable fixed-effect design.
-
Cox and conditional logistic models. Partial-likelihood comparisons require matching methods and equivalent stratum partitions.
These checks cannot certify metadata that a native provider does not store. You still need to establish that the likelihoods are scientifically comparable.
Sample size for AICc and BIC
-
unmarkedmodels. AICc and BIC use the retained site rows, not visits or random-effect realizations. When groups repeat across rows, this convention does not establish a valid small-sample correction or an effective independent sample size. -
Cox and conditional logistic models. AICc and BIC use the event count from the native log-likelihood metadata, so each supported choice set with one used step contributes one event, while every alternative row is still checked for comparability. This follows the native survival BIC convention. It does not adjust for dependence among steps or animals or establish that AICc is valid for a particular sampling design. Missing event-count metadata raises an error.
A finite criterion and an optimizer code of zero do not establish convergence, identifiability, or interval calibration. Read the native fit diagnostics, including the gradient and curvature when available.
Models the table rejects
-
Bayesian fits from
multiScale_bayes(). A posterior mode or penalized target is not a maximized sampling likelihood for AIC or BIC. Posterior predictive comparison needs a separate workflow with its own target and diagnostics. -
Cross-validation results, which hold held-out scores rather than a maximized likelihood. Use
cv_tab()orselect_cv(). -
Private spatial prototypes, which have no qualified maximized marginal likelihood. Conditional response densities and posterior objectives are not substitutes.
-
gdistremoval()models with active formula offsets or TMB zero inflation. These are rejected before fitting, model selection, or prediction. In the auditedunmarked1.5.2 provider, offsets did not enter the fitted likelihood, and the TMB ZIP likelihood ignored its zero-inflation parameter. These combinations need separate provider qualification. multiScaleR does not remove offsets, switch engines, alter parameter counts, or substitute uncertainty estimates. Offset-free C-engine ZIP models keep their native likelihood and parameter count.
The table itself is built with AICcmodavg::aictabCustom().
Author(s)
Bill Peterman
See Also
bic_tab(), multiScale_optim(), cv_tab() for comparisons by
held-out prediction, and
vignette("v08-cross-validation", package = "multiScaleR").
Examples
## Bundled counts simulated with a habitat scale of 75 map units
data("pts")
data("count_data")
hab <- terra::rast(system.file("extdata", "hab.tif", package = "multiScaleR"))
prepared <- kernel_prep(pts, hab, max_D = 300, sigma = 75, verbose = FALSE)
dat <- data.frame(y = count_data$y, prepared$kernel_dat)
fixed_model <- glm(y ~ hab, family = poisson(), data = dat)
null_model <- glm(y ~ 1, family = poisson(), data = dat)
spatial_model <- multiScale_optim(fixed_model, prepared, par = 75 / 300,
n_cores = 1, verbose = FALSE)
models <- list(spatial = spatial_model, fixed = fixed_model, null = null_model)
## The fixed model already uses the true 75-unit scale, so the spatial model
## reaches the same log-likelihood and pays for one extra parameter (sigma).
aic_tab(models, AICc = FALSE, mod_names = names(models))
aic_tab(models, AICc = TRUE, mod_names = names(models))
## K for a stored N-mixture fit: three abundance coefficients, one
## detection coefficient, and two estimated scales
nmix <- readRDS(system.file("extdata", "cache-user-guide-nmix.rds",
package = "multiScaleR"))
aic_tab(list(nmix), mod_names = "bin1 + cont2")
Rank models by BIC
Description
Build a model-selection table ranked by BIC (the Bayesian
information criterion) for a list of fitted models. As in aic_tab(), each
estimated scale of effect (sigma) and kernel shape counts as a parameter,
and lists can mix multiScaleR objects with plain fitted models.
Usage
bic_tab(mod_list,
mod_names = NULL,
verbose = FALSE,
...)
Arguments
mod_list |
A list of fitted models: |
mod_names |
Optional character vector of model names, one per model
in |
verbose |
Logical. If |
... |
Not used. |
Details
BIC penalizes each parameter by the log of the sample size rather than by 2, so it penalizes complexity more heavily than AIC once there are more than about 7 observations. It is often preferred when the goal is the single best-supported model rather than model averaging.
Every rule in aic_tab() applies here: the parameter count (including all
estimated components of unmarked models, spaMM degrees of freedom, and
the checked negative binomial BAM adjustment), the comparability checks
(responses, rows, weights, binomial outcomes, ML and REML, partial
likelihoods, used pcount() visits, and distance-removal protocols), the
sample-size conventions (retained site rows for unmarked models and
native event counts for Cox and conditional logistic models), and the
rejected models. Inapplicable hard-radius shape positions are excluded
from K. Calling the criterion BIC does not make a posterior target a
sampling likelihood, so Bayesian fits are rejected here too.
The table itself is built with AICcmodavg::bictabCustom().
Value
A data frame of class "bictab" (from the AICcmodavg package),
sorted from the best (smallest) BIC, with one row per model:
-
Modnames: model name. -
K: number of estimated parameters, counted as inaic_tab(): the fitted likelihood parameters (including ancillary ones such as negative binomial dispersion, or native effective degrees of freedom for GAMs) plus each estimated scale and shape of amultiScaleRmodel. -
BIC: the Bayesian information criterion. Smaller is better. -
Delta_BIC: difference from the best model. -
BICWt: BIC weight, the relative support for each model within this set. Weights sum to 1. -
Cum.Wt: cumulative BIC weight. -
LL: maximized log-likelihood.
A likelihood_adjustments attribute is added when a likelihood was
adjusted, as described in aic_tab().
Author(s)
Bill Peterman
See Also
aic_tab(), multiScale_optim(), and
vignette("v02-user-guide", package = "multiScaleR").
Examples
## Bundled counts simulated with a habitat scale of 75 map units
data("pts")
data("count_data")
hab <- terra::rast(system.file("extdata", "hab.tif", package = "multiScaleR"))
prepared <- kernel_prep(pts, hab, max_D = 300, sigma = 75, verbose = FALSE)
dat <- data.frame(y = count_data$y, prepared$kernel_dat)
fixed_model <- glm(y ~ hab, family = poisson(), data = dat)
null_model <- glm(y ~ 1, family = poisson(), data = dat)
spatial_model <- multiScale_optim(fixed_model, prepared, par = 75 / 300,
n_cores = 1, verbose = FALSE)
## BIC charges log(75), about 4.3, for the estimated sigma, versus 2 in AIC
bic_tab(list(spatial_model, fixed_model, null_model),
mod_names = c("spatial", "fixed", "null"))
Check Optional Software for Bayesian Scale Models
Description
Check whether the R packages that a multiScale_bayes() computation
method needs can be loaded and meet the package's minimum versions.
Nothing is installed, no model is fitted, and neither the compiler nor
sampling performance is tested.
Usage
check_bayes_setup(
method = c("sample", "laplace", "marginal", "prepare", "slice"),
correction = c("none", "importance"),
cores = 1L
)
## S3 method for class 'multiScaleR_bayes_setup'
print(x, ...)
Arguments
method |
Computation method to check, as in |
correction |
|
cores |
Requested number of worker processes; default 1. A value
greater than one also checks processx, which parallel fits need. It has
no effect for |
x |
A |
... |
Not used. Supplying any further argument is an error. |
Details
Preparation (method = "prepare") validates your data and
formulas before you install any sampling software. Installing the NUTS
packages from source can require a C++ compiler, which on Windows comes
with Rtools. vignette("v13-bayesian-scales", package = "multiScaleR")
covers installation, and
vignette("v15-bayesian-computation", package = "multiScaleR") compares
the methods.
Value
An object of class multiScaleR_bayes_setup, a list with these
elements.
-
method,correction: the settings checked. -
ready:TRUEwhen every listed package loads and meets its minimum version. -
packages: a data frame with one row per package and columnspackage,minimum(the minimum version, orNAwhen any version works), installedversion,loadable,meets_version,passed, and a diagnosticmessagethat says what to install or update. -
notes: what the check does and does not cover.
Printing the object lists the packages and the notes, and returns it invisibly. A passed check does not certify a working compiler, successful sampling, convergence, or adequate memory. Fit a small model next.
See Also
Examples
check_bayes_setup(method = "prepare") # always ready: nothing to install
# Packages for slice sampling on two workers. `ready` is FALSE when
# processx is missing. The message column says what to install.
setup <- check_bayes_setup(method = "slice", cores = 2)
setup$ready
setup$packages[c("package", "loadable", "passed")]
Simulated counts for the hab example
Description
Simulated counts at the 75 points in pts, for learning to estimate a
scale of effect with the hab.tif raster.
Usage
data(count_data)
Format
A data frame with 75 rows, one per point in pts, and 2 columns:
-
y: integer count at each point. -
hab: kernel-weighted mean of the binaryhab.tifraster around each point, centered and scaled to unit variance.
Details
Counts were simulated from a Poisson distribution with an
intercept of 0.5, a hab coefficient of 0.75 (log scale), and a Gaussian
scale of effect (sigma) of 75 map units. A fit that recovers a sigma near
75 and a coefficient near 0.75 is working as intended.
Source
Simulated for this package.
See Also
Examples
data(count_data)
head(count_data)
# Starting model: hab will be replaced by values at each candidate scale
glm(y ~ hab, family = poisson, data = count_data)
Cross-Validate Estimated Scales with Explicit Folds
Description
Estimate the scales of effect and the GLM coefficients again inside every fold, using only that fold's training rows, then score the predictions for the rows it holds out. A fold is one split of the data into analysis rows, which fit the model, and assessment rows, which are held out and predicted. Use this function to ask how well a scale-of-effect model predicts observations it never saw.
Usage
cross_validate(
formula,
data,
kernel_inputs,
folds,
family = c("gaussian", "poisson", "binomial", "nbinom2", "Gamma"),
backend = c("profile_glm", "refit", "joint_nb2"),
weights = NULL,
optim_args = list(),
glm_control = stats::glm.control(),
metrics = NULL,
keep_fits = FALSE,
keep_selection = FALSE,
theta = NULL,
dispersion = NULL
)
## S3 method for class 'multiScaleR_cv'
print(x, ...)
Arguments
formula |
Two-sided model formula, written as for |
data |
Data frame with one row per observation, holding the raw
responses and every nonspatial predictor. Its row names are the row IDs.
They must be unique and must be the same set of IDs as the row names of
|
kernel_inputs |
A |
folds |
Named list of explicit splits, for example from
|
family |
Character response family. Choose |
backend |
Fitting route for the scales, passed to
|
weights |
Optional case frequencies, one nonnegative whole number per
row of |
optim_args |
Named list of extra |
glm_control |
Named list of |
metrics |
Optional character vector of scores to record. The defaults
depend on |
keep_fits |
Logical. The default |
keep_selection |
Logical. |
theta |
Optional NB2 size parameter fixed in advance, one positive
number. The default |
dispersion |
Optional Gamma dispersion fixed in advance, one positive
number. The default |
x |
A |
... |
Not used. Reserved for future print controls. |
Value
cross_validate() returns a list of class multiScaleR_cv, with
class multiScaleR_distribution_cv added for "nbinom2" and "Gamma".
Read complete first, then summary (pooled scores), metrics (scores
per fold), predictions (one row per held-out observation),
fold_results, and training (the scales and coefficients estimated in
each fold). See multiScaleR_cv for every element and how to read
each score. print() shows how many folds were scored and the pooled
scores, and returns x invisibly.
How each fold is fitted
Suppose you estimated sigma, the kernel scale, once from all of the data
and then cross-validated only the regression. Every held-out row would
already have helped choose the scale that defines its own predictors, and
the scores would flatter the model. cross_validate() avoids this by
repeating the whole fit inside each fold, using the analysis rows alone.
Rebuild each spatial covariate from the raw cells at the starting scales in
kernel_inputs, then center and scale it with the analysis-row mean and standard deviation. Each covariate must have a positive, finite standard deviation in the analysis rows.Fit the initial GLM to the analysis rows.
Estimate the scales and coefficients with
multiScale_optim(). No fit to the full data is used as a starting point.Rebuild the assessment covariates with the fitted scales, the training standardization, and the training distance bins, then predict the expected response and score it.
The fold fails if the initial GLM, the final GLM, or the scale optimizer does not converge. Folds run one after another, and a failed fold is recorded and never retried.
Build the folds
Row names tie the pieces together. Before any fitting, the function checks that every split names known, unique IDs and that its analysis and assessment rows do not overlap. It cannot check ecological independence from the IDs you supply. Keep observations that share a site, animal, year, or other sampling unit on the same side of each split, and choose the design before you look at any scores.
Rows left out of a split, such as those removed by a buffer, are neither
fitted nor scored in that split. A row assessed in several splits is
scored each time, every occurrence enters the pooled scores, and
assessment_counts records how often each row was assessed. A factor level
present in the assessment rows but absent from the analysis rows makes that
fold fail at prediction. No zero effect is substituted.
vignette("v08-cross-validation", package = "multiScaleR") compares
random, grouped, spatial, and buffered fold designs on the same model.
Choose a family and scores
family | Link | Default metrics | Backend when unset |
"gaussian" | identity | rmse, mae | "profile_glm" |
"poisson" | log | rmse, mae, neg_log_score, deviance | "profile_glm" |
"binomial" | logit | neg_log_score, brier | "profile_glm" |
"nbinom2" | log | rmse, mae, neg_log_score | "profile_glm", or "refit" with a fixed theta |
"Gamma" | log | rmse, mae, neg_log_score | "refit"
|
Lower is better for every score. RMSE and MAE judge only the predicted
mean, in the units of the response. The negative log score judges the
whole predicted distribution, so it also penalizes a model that is too
confident. Binomial responses can be 0/1 numbers, logical values, a
two-level factor, or cbind(successes, failures). cross_validate_glm()
explains how binomial log and Brier scores are weighted, and
the multiScaleR_cv page defines every score.
Negative binomial and Gamma responses
Both families carry a nuisance parameter, a parameter of the response
distribution that is not part of the mean model. It is theta for NB2 and
the dispersion for Gamma. Unless you fix it with theta or dispersion,
each fold estimates it from the analysis rows and freezes it to score the
assessment rows. The negative log score therefore uses a complete,
normalized density that the held-out outcomes did not help shape. The
frozen value of each fold is stored in distribution and repeated in the
theta and dispersion columns of predictions.
An estimated nuisance parameter adds one to the native K, and a fixed one adds zero. The native
nobscounts rows with positive weight, not the sum of the weights.Estimated Gamma dispersion is the training deviance divided by the sum of the frequency weights, the value native Gamma AIC uses. It differs from the Pearson dispersion that
summary()uses for coefficient standard errors, and it does not replace that standard-error convention. A fixed Gamma dispersion is built into the Gamma density before fitting, so the likelihood, AIC, and K agree. Setting only thedispersionfield of a native Gamma family would leave its AIC estimating the dispersion from the deviance.NB2 responses must be nonnegative whole numbers and Gamma responses strictly positive, including rows with zero weight.
A theta warning from the native NB2 fit, such as a reached iteration limit, makes the fold fail. The warning is kept in
warnings.-
backend = "joint_nb2"starts the coefficients from a GLM with theta = 1 and then estimates theta jointly with the scales. That starting value is neither a fixed theta nor a prior. A fold reports an infinite theta, the exact Poisson limit, only when the joint fit verifies and flags that limit. A large finite theta never stands in for it.
A Gamma model for a strictly positive response uses the same call, and the
backend switches to "refit" on its own, for example
cross_validate(mass ~ habitat, dat, inputs, folds, family = "Gamma").
Compare NB2 and Poisson candidates with the negative log score on the same
counts. cv_tab() lists the comparisons each family allows.
Formula terms that learn from the data
Some formula terms learn constants from the data. scale() learns a mean
and standard deviation, poly() learns polynomial coefficients, and
splines::ns() and splines::bs() learn knots. In each fold these
constants come from the analysis rows and are reused unchanged for the
assessment rows. This holds with or without a base::, stats::, or
splines:: prefix, and inside arithmetic, I(), pointwise functions such
as log(), and offsets. For spatial covariates the constants come from the
final fitted training values, not the starting-scale values. Arguments you
fix in the formula, such as knots, stay fixed. Coefficients, standard
errors, likelihoods, and K are those of the native fit, and fits kept with
keep_fits = TRUE carry the same training constants.
Only these four functions are recognized, and only with numeric inputs and
supported arguments. An unsupported argument makes the fold fail. Any other
operation that learns from the data, such as mean(x) inside a formula or
your own transformation function, is not detected. Compute it within each
analysis split and apply it unchanged to the assessment rows, or the scores
will leak assessment information. For the same reason, do not supply
predictors standardized with all rows. Every variable must still be a
column of data or a prepared covariate. Variables are never taken from
the formula's environment.
With the default "profile_glm" backend, a spline of an optimized
covariate needs fixed knots and Boundary.knots and no df. Otherwise
the fold fails with a message that names the fix. backend = "refit"
accepts adaptive splines.
Keep optimized covariates in their own units
By default each fold centers and scales every optimized covariate with its
analysis-row mean and standard deviation, so a coefficient is the effect of
a one standard deviation change. With backend = "refit", the setting
optim_args = list(covariate_transform = "raw") skips that final step for
the optimized covariates. They keep the units of their kernel or metric
calculation, such as a kernel-weighted proportion of habitat. Use this when
a fixed spline knot or another formula constant is meant in those units.
The initial fit and every scale refit within a fold use the same units, and prediction applies a center of zero and a scale of one. Covariates whose scales are not optimized are still standardized with analysis-row values, and normalization applied upstream, such as the reference normalization of surface metrics, is unchanged. Assessment rows never choose the transformation, the knots, or the scale. Decide on raw units, and on any knots in those units, before you look at the results. Because a change of units can alter a constrained or nonlinear model, compare the two versions by their held-out scores rather than assume they are equivalent.
Use separate maps for groups of surveys
Inputs from kernel_prep_by_group(), which take each row's covariates
from its own map (for example, the map of its survey year), are supported.
Before fitting, the function checks that the named raster_group labels
align with the prepared row IDs. It records the map labels of each fold's
analysis and assessment rows in raster_groups. Standardization and
distance bins still come from the pooled analysis rows. The map labels are
fixed inputs. They add no random effects, no extra parameters, and no
scales that vary among maps. Group effects you write in the formula, such
as a year factor, keep their native fit, parameter count, and new-level
check. See vignette("v06-year-specific-rasters", package = "multiScaleR").
Distance bins and the extraction envelope
When kernel_inputs holds distance-binned summaries (kernel_prep() with
bin = TRUE, the default), each fold rebuilds them. The bin edges span
max_D plus half a cell diagonal, so cells that intersect the buffer but
whose centers lie just beyond max_D keep their values. These edges depend
on the declared geometry only, not on any data. The representative
distance of each bin is the mean cell distance in that bin over the
analysis rows, and the assessment rows reuse it. Inputs saved by older
versions of kernel_prep() lack the cell geometry and keep the stricter
rule that every cell center lies within max_D. If such inputs are
rejected, prepare them again with the current kernel_prep().
Check every fold before comparing models
Read complete first. TRUE means every planned fold was fitted and
scored. When a fold fails, complete is FALSE and the pooled scores in
summary are NA. The scores of the folds that finished, the failed
assessment rows, the diagnostics, and the warnings all stay available, and
errors names the stage and message of each failure. cv_tab() and
select_cv() refuse an incomplete result rather than rank a model on its
easier folds. A complete result says only that the calculations finished,
so inspect diagnostics and warnings before you rank models.
What the scores do and do not include
The predictions and scores treat each fold's fitted parameters as known.
They do not average over uncertainty in the coefficients or scales, give
prediction intervals, or establish calibration. Compare candidates only on
identical folds, assessment rows, responses, and weights, which cv_tab()
checks for you. The scores complement aic_tab() but are not AIC values
or Akaike weights. If you use the scores to choose a model, kernel, or
metric, the winning score is optimistic. Assess the chosen procedure with
an outer validation layer or an independent test set. select_cv() scores
a predeclared training-AIC rule without this bias, because the assessment
outcomes never choose the winner within a fold.
cross_validate() fits GLMs. For other model structures use
cross_validate_mixed() (a random intercept for repeated surveys),
cross_validate_clogit() (step selection), cross_validate_field() (a
spatial random field), or cross_validate_bayes() (Bayesian models). GAMs
and unmarked models have no cross-validation function.
cross_validate_glm() scores reference models without scales on the same
folds.
See Also
multiScaleR_cv for the returned object,
cross_validate_glm() for reference models, cv_tab() and select_cv()
to compare candidates, grouped_cv_folds() and spatial_cv_folds() to
build folds, and vignette("v08-cross-validation", package = "multiScaleR")
for the full workflow.
Examples
data("landscape_counts") # counts and one site-level covariate
data("surv_pts") # 100 survey locations
pts <- vect(surv_pts)
# Folds are lists of row IDs, so build and check them before any fitting.
# The simulated coordinates are in meters, and crs = 32617 declares that.
folds <- spatial_cv_folds(crds(pts), block_size = 1000, k = 3, crs = 32617)
folds # rows fitted (analysis) and held out (assessment) in each fold
land <- rast(system.file("extdata", "landscape.tif", package = "multiScaleR"))
inputs <- kernel_prep(pts = pts, raster_stack = land[[c("land1", "land2")]],
max_D = 1000, kernel = "gaussian", verbose = FALSE)
# Row names of dat match those of inputs$kernel_dat ("1" to "100")
dat <- data.frame(landscape_counts, inputs$kernel_dat)
# Scales and coefficients are estimated from the analysis rows of each fold
cv <- cross_validate(counts ~ site + land1 + land2, data = dat,
kernel_inputs = inputs, folds = folds,
family = "poisson", keep_selection = TRUE)
cv # pooled held-out scores, lower is better
cv$complete # TRUE: every fold was fitted and scored
# Sigma (map units) estimated in each fold. Similar values across folds
# suggest that no single block of surveys drives the estimated scales.
round(sapply(cv$training, function(fold) fold$scale_est$Mean))
# Compare with a reference model that has no landscape covariates
site_cv <- cross_validate_glm(counts ~ site, dat, folds, family = "poisson",
keep_selection = TRUE)
cv_tab(list(landscape = cv, site_only = site_cv), metric = "rmse")
Cross-Validate Bayesian Scale Models
Description
Refit a multiScale_bayes() model in each analysis split, then score the
held-out observations with the posterior predictive density. Observations
that share a predicted group, such as a held-out site or year, also share
its random effect when they are scored.
Usage
cross_validate_bayes(
formula,
data,
kernel_inputs,
folds,
scales = NULL,
family = c("nbinom2", "poisson", "binomial", "gaussian"),
row_id = NULL,
priors = list(),
method = c("slice", "sample", "laplace", "marginal"),
fit_args = list(),
assessment_group = NULL,
new_scale_levels = c("sample", "error", "zero"),
new_response_levels = c("sample", "error", "zero"),
new_group_draws = 1L,
bin_reference = c("training", "fixed"),
seed = NULL,
keep_fits = FALSE
)
Arguments
formula |
Two-sided response formula in |
data |
Data frame of raw observations and formula variables. Its
unique row names identify observations in |
kernel_inputs |
Prepared landscape inputs from |
folds |
Uniquely named list of splits. Each split holds nonempty,
disjoint character vectors |
scales |
Named list of scale formulas, as in |
family |
Response family, one of |
row_id |
Optional name of the column of |
priors |
Named list of prior settings passed to |
method |
Computation for every fold. The default |
fit_args |
Named list of further fitting arguments for
|
assessment_group |
Optional name of a column of |
new_scale_levels, new_response_levels |
What to do with a group level
that is absent from an analysis split, set separately for scale and
response random effects. The default |
new_group_draws |
Positive integer number of new-effect simulations per posterior vector when unseen levels are sampled; default 1. Raise it to reduce the simulation error of the average over new groups. See "Compare models". |
bin_reference |
|
seed |
Optional positive integer seed. It generates distinct fitting and scoring seeds for every fold, and your own random-number state is restored afterward. |
keep_fits |
Logical. The default |
Details
This function is experimental. Its arguments and results may change in a later release without a deprecation period.
Value
An object of class multiScaleR_bayes_cv, which inherits from
multiScaleR_cv (see multiScaleR_cv). It is a list with these
elements.
-
summary: a one-row data frame with the pooled score.estimateis the sum of joint negative log scores divided by the number of assessment observations (unitis"joint_block_density_per_observation"), so lower is better.n_assessment,n_scored,weight_sum, andcompletedescribe its basis.estimateisNAunless every fold scored. -
metrics: the same score for eachfold. -
predictions: one row per assessed observation, withfold,row_id,point_id,observed,trials,assessment_group, the posterior mean responseprediction(a per-trial probability for binomial models),marginal_neg_log_scorefor that observation alone,new_scale_levelandnew_response_levelflags, andeligible, which isTRUEonly in a scored fold. -
joint_scores: one row per fold and assessment block, with its sizenand jointneg_log_score. -
fold_results: one row per fold, withn_analysis,n_assessment, andstatus, which is"scored","diagnostic_failed", or"failed"(an error at any stage, recorded inerrors). -
diagnostics: for each fold, the fit's stored checks (raw), thediagnose_bayes_scales()report for sampled fits (derived), the overallpassedflag, and the importance records of corrected fits. -
errors,warnings: for each fold, the failingstageandmessage(orNULL), and the warnings captured during the fold. -
training: for each fold, the analysis rows and point IDs, the fit and score seeds, the frozen normalization (center,spread, and those of fixed-radius metrics), the bin distances and their reference, and the priors. -
prediction_contracts: for each fold, the unseen groups, the number of posterior vectors,new_group_draws, and whether importance weights were used. -
targets,folds,settings,assessment_counts,complete,call,integrity_sha256: the scored observations, the validated splits, the settings, how often each row was assessed, whether every fold scored, the call, and a checksum thatcv_tab()uses to detect altered records. -
fits: the complete fold fits whenkeep_fits = TRUE, andNULLotherwise.
What the score measures
The joint score of a block is the negative log of the posterior average of the product of the observation densities in that block. Lower is better. New effects are drawn once per group in each joint parameter vector and shared by every assessment observation in that group. For grouped binomial data, each observation contributes one normalized probability of its count of successes. The sum of the marginal row scores is a different target. The pooled score weights each block by its number of observations. It is the only cross-validation score in the package that averages over uncertainty in the coefficients, the scales, and the group effects.
Choose folds for your prediction question
Each fit learns the normalization, formula bases, coefficients, and
scales from its analysis rows only. Repeated visits can share one point
buffer. To predict new sites or years, hold out whole sites or years, for
example with grouped_cv_folds() on the site labels. Where groups cross,
make each assessment block cover the observations whose joint response you
want to predict.
vignette("v08-cross-validation", package = "multiScaleR") discusses fold
design.
Handle failed folds
A fold that fails its native or derived diagnostics is marked
"diagnostic_failed" and leaves the result incomplete, though its computed
scores stay available for investigation. Slice sampling without the
posterior package can score folds with diagnostics recorded as
unavailable, so install posterior to check mixing and simulation
precision. Laplace and marginal scores inherit the limits of their
approximation and its checks. Importance-corrected fits are scored with
their normalized candidate weights. Passing numerical checks does not
establish predictive calibration. Every fold runs the full fitting
method, so a run takes about as long as one fit per fold.
Compare models
Use cv_tab() with metric = "neg_log_score" to rank complete Bayesian
results computed on the same targets, folds, blocks, and new-level
policies. Poisson and NB2 results can be compared, because both score
probability mass on the same counts. Training AIC, AICc, and BIC selection
does not apply to posterior fits, so use an outer split to evaluate a
model-selection rule. The average over unseen group effects uses a finite
number of simulated effects. When two candidates score very closely, rerun
both with a larger new_group_draws and the same seed and fitting
settings, and treat the comparison as unresolved if the ranking changes.
See Also
multiScale_bayes(), grouped_cv_folds(),
spatial_cv_folds(), diagnose_bayes_scales(), cv_tab(),
multiScaleR_cv;
vignette("v08-cross-validation", package = "multiScaleR").
Examples
data("landscape_counts")
data("surv_pts")
land <- terra::rast(system.file("extdata", "landscape.tif",
package = "multiScaleR"))
# Keep the raw cells (the default) so each fold rebins from its own
# analysis points
inputs <- kernel_prep(pts = terra::vect(surv_pts), raster_stack = land[["land1"]],
max_D = 1700, kernel = "gaussian", verbose = FALSE)
# Two folds of alternating rows
folds <- grouped_cv_folds(rep(1:2, length.out = nrow(landscape_counts)),
k = 2, ids = rownames(landscape_counts))
# Very short slice chains keep this example quick. With the posterior
# package installed, they usually fail the diagnostics, so the folds are
# marked "diagnostic_failed" and the pooled score is NA. Use the default
# chains and iter in an analysis.
cv <- cross_validate_bayes(counts ~ land1, landscape_counts, inputs, folds,
family = "poisson",
priors = list(scale_median = 300),
method = "slice",
fit_args = list(chains = 2, iter = 200), seed = 1)
cv$fold_results # status of each fold
cv$joint_scores # joint negative log score of each assessment block
cv$summary # pooled score per observation, lower is better
Cross-Validate Conditional Choices in Complete Matched Sets
Description
Cross-validate a step-selection model or another conditional logistic model. In each fold, refit the coefficients, and optionally the scales of effect, using the analysis rows, then score the probability the model gives the used alternative among all alternatives of each held-out choice set. A choice set is one used alternative together with the available alternatives it was chosen from, for example one observed step and its random steps.
Usage
cross_validate_clogit(
formula,
data,
folds,
kernel_inputs = NULL,
backend = c("conditional_logit", "refit"),
method = c("exact", "efron", "breslow"),
cox_control = survival::coxph.control(),
optim_args = list(),
keep_fits = FALSE,
keep_selection = FALSE
)
## S3 method for class 'multiScaleR_choice_cv'
print(x, ...)
Arguments
formula |
Two-sided formula. The response is a numeric or logical
column coded 1 for the used alternative and 0 for the available ones.
The right side holds the predictors and one bare |
data |
Data frame with one row per alternative, holding the case
column, the set ID, and every predictor. Its row names are the row IDs
used by |
folds |
Named list of explicit splits of row IDs, as in
|
kernel_inputs |
Optional |
backend |
Scale-fitting route used with |
method |
Partial-likelihood method passed to |
cox_control |
Named list of |
optim_args |
Named list of extra |
keep_fits |
Logical. The default |
keep_selection |
Logical. |
x |
A |
... |
Not used. Reserved for future print controls. |
Value
A list of class multiScaleR_choice_cv, which inherits from
multiScaleR_cv. Its summary holds the negative log score of the
used alternative, averaged over held-out choice sets, and predictions
holds one row per alternative with its probability within its set. The
other elements follow cross_validate(). The conditional-choice section
of multiScaleR_cv lists every difference. print() shows how
many folds were scored and the pooled score, and returns x invisibly.
Build folds that keep choice sets whole
Before any fitting, the function rejects a split that divides a choice
set. Holding out whole choice sets measures transfer to new sets from the
same animals. To measure transfer to new animals, build the folds from
animal IDs instead. If step labels repeat across animals, first create a
globally unique set ID, such as interaction(animal, step, drop = TRUE),
and use that column in strata(). For spatial blocks, pass the set IDs or
the animal IDs as group to spatial_cv_folds(), so that no set crosses
a split boundary.
What the model can contain
Each set needs exactly one used alternative and at least one available
alternative. Weights, missing values, robust clustering (cluster()),
frailty and other special or penalized Cox terms, and general censored
survival responses are outside this function, and no rows are dropped
silently. Predictors that are constant within every set have no
identifiable coefficient. Native alias and convergence problems are kept
as failures rather than resolved by dropping terms or alternatives, and a
warning from the native training fit makes the fold fail. Every scored
fold checks that its native fit is unweighted and unpenalized, uses the
analysis rows and complete sets, and used the declared method, whether
or not fits or records are kept. Learned transformations follow the rules
described in cross_validate(). Their training constants add no stratum
effects and do not change the event count.
Estimate scales within the folds
With kernel_inputs, each fold rebuilds the spatial covariates from the
raw cells of its analysis rows, learns the standardization and the
representative bin distances there, and estimates the scales. The
assessment rows reuse those frozen references. Inputs from
kernel_prep_by_group() are fixed covariate maps and add no random
effects. Raw covariate units (covariate_transform = "raw" in
optim_args) require backend = "refit".
vignette("v04-landscape-metrics", package = "multiScaleR") shows a
search over a grid of radii on a full data set.
Read the scores
The score of a held-out set is the negative natural log of the probability the fitted model gives its used alternative, where the probabilities of a set's alternatives sum to 1. The pooled score averages over sets. A model without covariates or offsets gives each of k alternatives a probability of 1/k, so its score is log(k), or 1.099 for three alternatives. A useful covariate lowers the score. Scores are computed on the log scale, so a probability that prints as zero still has a finite score. Predictions use the saved training terms and assign no effect to the labels of new sets. These within-set probabilities differ from Bernoulli probabilities of use and from unnormalized relative selection strengths.
For a model with no estimated coefficients, survival's logLik() can
return NA. The function then checks survival's stored null
log-likelihood against the exact complete-set likelihood before using it,
with K = 0, for training-criterion selection. Missing or inconsistent
values remain failures. Other native fits are not altered.
Compare and select models
Use cv_tab() with metric = "neg_log_score" to rank choice models fitted
to the same sets, folds, and method. Use select_cv() to score a
training AIC, AICc, or BIC rule. Its sample size is the number of choice
sets (one event each), and K counts the coefficients and any estimated
scales and shapes. Choice scores cannot be mixed with scores from
Bernoulli GLMs. They treat fitted parameters as known, so they do not
integrate parameter or selection uncertainty, give intervals, or establish
calibration. vignette("v08-cross-validation", package = "multiScaleR")
includes a step-selection example.
See Also
cross_validate(), grouped_cv_folds(), spatial_cv_folds(),
cv_tab(), select_cv(), and multiScaleR_cv.
Examples
if (requireNamespace("survival", quietly = TRUE)) {
# 24 choice sets of three alternatives. The first of each set was used.
i <- 1:72
choices <- data.frame(step = (i - 1) %/% 3 + 1,
used = as.numeric(i %% 3 == 1),
habitat = sin(i * 1.7))
folds <- grouped_cv_folds(choices$step, k = 3) # whole sets held out
models <- list(
null = cross_validate_clogit(used ~ strata(step), choices, folds,
keep_selection = TRUE),
habitat = cross_validate_clogit(used ~ habitat + strata(step), choices,
folds, keep_selection = TRUE))
print(models$habitat) # natural-log loss per held-out choice set
# The null model scores log(3) = 1.099. Here habitat is unrelated to use,
# so it does not lower the score.
print(cv_tab(models, metric = "neg_log_score"))
# Model picked by training AICc in each fold
select_cv(models, criterion = "AICc")$selection$chosen
}
Cross-Validate a Spatial Response Field
Description
Cross-validate a model that adds a spatial random field to its fixed predictors. A spatial random field is a smooth surface of spatially correlated variation that the predictors do not explain. In each fold the function estimates the field, its correlation range, the regression coefficients, and optionally the scales of effect from the analysis rows. It then scores the joint distribution of each held-out block, so that correlation among nearby held-out observations counts. Gaussian responses use exact Gaussian conditioning at the fitted parameters. Count, binary, and positive responses use Laplace integration.
Usage
cross_validate_field(
formula,
data,
coords,
folds,
audit_dir,
crs = NULL,
covariance = c("exponential", "gaussian"),
kernel_inputs = NULL,
optim_args = list(),
control = list(iter.max = 1000L, eval.max = 1500L, rel.tol = 1e-10, x.tol = 1e-08),
metrics = c("rmse", "mae", "neg_log_score"),
max_refits = 200L,
max_memory_mb = 512,
keep_fits = FALSE,
family = c("gaussian", "poisson", "binomial", "nbinom2", "Gamma")
)
Arguments
formula |
Two-sided fixed-effects formula whose response is a numeric
column of |
data |
Data frame of raw responses and predictors, with unique row
names that match the fold IDs, in the same row order as |
coords |
Locations of the observations, one per row of |
folds |
Named list of explicit splits, usually from
|
audit_dir |
Directory where compact, write-once records of each native fit and its starting values are saved, one subfolder per fold. Records of failed fits are kept too. No models, tapes, or dense covariance matrices are saved. Give each candidate model its own directory to keep the records apart. |
crs |
Projected coordinate reference system, in any form accepted by
|
covariance |
Correlation function of the field, either
|
kernel_inputs |
Optional |
optim_args |
Named list of extra |
control |
Named list of native |
metrics |
Scores to record, any of |
max_refits |
Positive whole number, the most native refits allowed in one fold during the scale search (default 200). Each refit checks two starting values. A fold that exceeds the budget fails. |
max_memory_mb |
Positive number, a conservative budget in MiB for the covariance calculations of one fold (default 512), checked before any fitting. Repeated surveys at one location share one field value, so they do not enlarge the training covariance matrix. This is a planning check, not an operating-system memory limit. |
keep_fits |
Logical. |
family |
Response family and link. Use |
Details
The count, binary, and positive response families are experimental. Their arguments and results may change in a later release without a deprecation period.
Value
A list of class multiScaleR_field_cv, which inherits from
multiScaleR_cv. summary holds the pooled scores, predictions the
predicted mean, errors, and variance components of each held-out
observation, joint_scores the joint loss of each held-out block, and
training the field SD, correlation range (in coordinate units),
dispersion, and coefficients of each fold. Compact selection_records
are always kept. The spatial field section of multiScaleR_cv
describes every element and its scale.
What each fold estimates
The native fits use glmmTMB and TMB with maximum likelihood. The model has
one shared latent Gaussian field with exponential or Gaussian correlation,
and a constant observation dispersion where the family has one. From the
analysis rows each fold estimates the regression coefficients, the field
SD, the correlation range, the observation dispersion, and, with
kernel_inputs, the scales of effect. Distance bins, standardization, and
the constants of learned formula terms also come from the analysis rows
only. Custom preprocessing that depends on the data must be learned inside
each training fold too, because formula evaluation cannot detect outside
information passed in through your own functions. No missing rows are
dropped silently.
The correlation range is the distance, in coordinate units, over which the unexplained variation stays correlated. It is separate from the kernel scale of effect, which describes how far the landscape around a point affects it.
Every fit tries two deterministic starting values chosen from the training
data and records the package versions, convergence, marginal score, and
curvature checks of each. For Gaussian responses both starts must pass and
agree, or the fold fails. For the other families the passing start with
the highest likelihood is used, and the outcome of each start is kept.
With few locations in a training fold, the field's standard deviation and
range are often weakly identified, and the two Gaussian starts can stop at
different points of a nearly flat likelihood. Those folds fail by design
("starts disagree") rather than report one arbitrary solution. Use more
locations per fold, or fewer folds, and inspect audit_dir to see how far
apart the starts ended.
Build folds for a field model
Hold out complete locations, so that no location has observations in both
parts of a split. Spatial blocks with a buffer test prediction at new
places. The field locations in coords can differ from the focal points
used for the landscape covariates, but each location must be given by its
actual, consistent coordinates, and coords is required even when
kernel_inputs is supplied. A template that compares two correlation
functions on the same folds:
folds <- spatial_cv_folds(field_xy, block_size = 10000, k = 5,
buffer = 1000, crs = 32617, ids = rownames(raw_data))
covariances <- c(exponential = "exponential", gaussian = "gaussian")
candidates <- lapply(covariances, function(covariance) {
cross_validate_field(y ~ habitat * cover + offset(log(exposure)),
raw_data, field_xy, folds, crs = 32617, covariance = covariance,
kernel_inputs = inputs,
audit_dir = file.path("field-cv-audits", covariance))
})
cv_tab(candidates, metric = "neg_log_score")
selected <- select_cv(candidates, criterion = "AICc")
selected$selection$chosen # chosen by the training criterion in each fold
How the joint score works
The negative log score treats the held-out observations of each fold as one block. For Gaussian responses it is the negative log of one multivariate normal density. Its covariance holds the field variation that remains after conditioning on the analysis responses, plus the observation noise. For the other families the score is the Laplace log marginal likelihood of the analysis responses alone minus that of the analysis and assessment responses together. Both calculations use parameters estimated from the analysis rows only, including the field covariance, coefficients, dispersion, and scales, so the score keeps the dependence among held-out locations and repeated observations. For counts and 0/1 data, a block probability above one beyond numerical roundoff is recorded as a failed score.
The pooled score is the total block loss divided by the number of
assessment observations, and smaller is better. RMSE and MAE summarize the
errors of the predicted response means. Multiplying separate marginal
densities would ignore the field dependence and define a different score,
so cv_tab() keeps these scores apart from the per-observation scores of
ordinary GLMs.
Predicted means and spreads
For 0/1 responses, predicted means and observation SDs integrate over a Gaussian approximation to the field given the analysis responses. For log-link families, the first two response moments come from Laplace ratios of exponentially tilted analysis likelihoods, with two additional latent solves per distinct assessment location and the training covariance factor held fixed. This improves the accuracy of the moments in low-dimensional numerical comparisons, particularly for sparse observations with strong fields. The joint block score uses its own integration.
observation_predictive_SE combines the conditional observation noise
with the variation of the response mean. For a nonlinear link, square it
to get the total response variance. The two field variance columns
describe the field on the linear-predictor scale. All of these condition
on the estimated parameters. Use them as predictive spreads for new
observations, not as standard errors of the predicted mean.
Check calibration separately
A scored fold has an eligible native fit and a valid score. It does not show that the predictive spreads are reliable. Assess that on the held-out locations, and count failed folds in the denominator when you report how often the method succeeds. In simulations with buffered held-out locations, squared prediction errors averaged 1.5 (Gaussian), 2.7 (Poisson), and 1.9 (NB2) times the predicted observation variance, against 1 for a calibrated prediction. Treat the returned spreads as optimistic when parameters are estimated.
Compare and select field models
Use cv_tab() to rank field results fitted to the same responses, folds,
and coordinates. Poisson and NB2 results share a count target. Use
select_cv() to score a training AIC, AICc, or BIC rule from the compact
records. The coefficients, field SD, estimated range, and any observation
dispersion count toward K, while the integrated field values add nothing.
Field scores do not integrate parameter or scale uncertainty and do not
establish calibration. vignette("v08-cross-validation", package = "multiScaleR") explains fold design and how to read the scores, and
vignette("v11-spatial-fields", package = "multiScaleR") covers spatial
field models.
See Also
cross_validate(), cross_validate_glm(),
response_field_geometry(), multiScaleR_cv, cv_tab(), and
select_cv().
Examples
if (requireNamespace("glmmTMB", quietly = TRUE)) {
data("landscape_counts")
data("surv_pts")
xy <- crds(vect(surv_pts)) # simulated coordinates in meters
folds <- spatial_cv_folds(xy, block_size = 1000, k = 3, crs = 32617)
# Poisson counts with a site covariate and an exponential field. The
# Poisson family is experimental.
field_cv <- cross_validate_field(counts ~ site, landscape_counts, xy,
folds, audit_dir = file.path(tempdir(), "field-cv"), crs = 32617,
family = "poisson")
print(field_cv) # the log score is a joint score per held-out survey
# Field SD (log-link scale) and correlation range (m) in each fold
print(sapply(field_cv$training, function(fold)
unlist(fold$parameters[c("field_SD", "range")])))
}
Cross-Validate an Ordinary GLM Reference Model
Description
Fit a GLM to the analysis rows of each fold and score its predictions for
the held-out rows. No scales of effect are estimated. Use this function to
build null and nonspatial reference models on the same folds you give
cross_validate(), so that a scale-of-effect model has a baseline to beat.
Usage
cross_validate_glm(
formula,
data,
folds,
family = c("gaussian", "poisson", "binomial", "nbinom2", "Gamma"),
weights = NULL,
glm_control = stats::glm.control(),
metrics = NULL,
keep_fits = FALSE,
keep_selection = FALSE,
theta = NULL,
dispersion = NULL
)
Arguments
formula |
Two-sided model formula, written as for |
data |
Data frame with one row per observation, holding the raw responses and every predictor. Its row names are the row IDs that the folds refer to, and they must be unique. Do not supply predictors standardized or transformed with all rows (see "What each fold fits"). |
folds |
Named list of explicit splits, for example from
|
family |
Character response family. Choose |
weights |
Optional case frequencies, one nonnegative whole number per
row of |
glm_control |
Named list of |
metrics |
Optional character vector of scores to record. The defaults
depend on |
keep_fits |
Logical. The default |
keep_selection |
Logical. |
theta |
Optional NB2 size parameter fixed in advance, one positive
number. The default |
dispersion |
Optional Gamma dispersion fixed in advance, one positive
number. The default |
Value
A list of class multiScaleR_cv, with class
multiScaleR_distribution_cv added for "nbinom2" and "Gamma". It has
the elements of a cross_validate() result, with these differences.
settings$backend is "glm". training holds only the coefficients of
each fold, plus the frozen nuisance parameter for NB2 and Gamma.
diagnostics holds the convergence record of each fold's GLM, and fits
holds ordinary glm objects when keep_fits = TRUE. See
multiScaleR_cv for every element and how to read each score.
What each fold fits
Each fold fits glm() to its analysis rows with the declared family and
frequency weights, then predicts the expected response of the assessment
rows. The families, response forms, weights, and scores are those of
cross_validate(). Factors, interactions, and offsets use the native GLM
machinery. The constants of scale(), poly(), splines::ns(), and
splines::bs() come from the analysis rows, even inside expressions and
offsets. Any other preprocessing that learns from the data must also
happen within the analysis rows of each fold, so do not supply predictors
standardized with all rows. The section "Formula terms that learn from the
data" in cross_validate() lists the supported terms and their limits.
Missing values are never dropped silently, and native warnings and failed
folds are kept.
Binomial responses
A binomial response can be numeric or logical 0/1 values, a two-level
factor (the second level counts as a success), or
cbind(successes, failures) for several trials per row. Keep trial counts
in the response and case frequencies in weights, because the two are
scored differently.
The negative log score of a row is the negative log binomial probability of its observed number of successes, given its trials. Rows are averaged with their frequency weights.
The Brier score of a row is the squared error of the predicted success probability, averaged over the row's trials. Rows are averaged with weights equal to frequency weight x trials, so the pooled Brier score is a mean per trial. A row with many trials counts more in the Brier score than in the log score.
A row with zero trials or zero weight stays in
predictionsbut contributes to neither score.An observed outcome given zero probability produces an infinite log score. It is kept as is, not clipped.
Negative binomial and Gamma responses
"nbinom2" fits MASS::glm.nb() when theta is estimated and
glm(family = MASS::negative.binomial(theta)) when it is fixed, so it
needs the MASS package. "Gamma" uses a log link. In each fold the
nuisance parameter (theta, or the Gamma dispersion) is estimated from the
analysis rows, frozen, and used to score the assessment rows. Coefficients
and their native standard errors are those of the native fit. A fixed
Gamma dispersion is built into a normalized Gamma family before fitting.
The section "Negative binomial and Gamma responses" in cross_validate()
describes how these parameters enter K and the rules they follow.
How to read the Gamma dispersion
distribution[[fold]]$dispersion is the training deviance divided by the
training sum of case frequencies, the value native Gamma AIC uses. It is
held fixed when the held-out Gamma densities are scored. Native
coefficient standard errors use the Pearson dispersion instead, so they
can rest on a different number. The density dispersion does not replace
that coefficient uncertainty. convention records the rule that produced
the value, and estimated is FALSE when you fixed it with dispersion.
Supply theta or dispersion only when the value is known or was fixed
independently of the assessment outcomes.
What the scores do and do not include
Predictions use each fold's fitted parameters as if they were known. They
do not integrate parameter uncertainty, provide prediction intervals, or
establish calibration. Use cross_validate() to estimate scales of effect
within the same folds.
See Also
cross_validate(), cv_tab(), select_cv(),
multiScaleR_cv, and
vignette("v08-cross-validation", package = "multiScaleR").
Examples
data("landscape_counts") # counts and a site-level covariate
data("surv_pts") # survey locations
# Three spatial folds. The simulated coordinates are in meters.
folds <- spatial_cv_folds(crds(vect(surv_pts)), block_size = 1000, k = 3,
crs = 32617)
# Null and site-only reference models on the same folds
null_cv <- cross_validate_glm(counts ~ 1, landscape_counts, folds,
family = "poisson")
site_cv <- cross_validate_glm(counts ~ site, landscape_counts, folds,
family = "poisson")
site_cv # pooled held-out scores, lower is better
cv_tab(list(null = null_cv, site = site_cv), metric = "neg_log_score")
# Negative binomial: theta is estimated in each fold and frozen for scoring
if (requireNamespace("MASS", quietly = TRUE)) {
nb_cv <- cross_validate_glm(counts ~ site, landscape_counts, folds,
family = "nbinom2")
sapply(nb_cv$distribution, function(d) d$theta) # small theta: overdispersed
}
# Gamma model for a strictly positive response
i <- 1:96
positive <- data.frame(
y = exp(0.2 + 0.35 * sin(i * 0.73)) *
rep(c(0.3, 0.6, 1.1, 2.4, 0.8, 1.8, 0.4, 1.6), 12),
x = sin(i * 0.73))
gamma_folds <- grouped_cv_folds(rep(letters[1:12], each = 8), k = 3)
gamma_cv <- cross_validate_glm(y ~ x, positive, gamma_folds, family = "Gamma")
gamma_cv$summary
# Training deviance / sum of case frequencies, frozen for scoring each fold
sapply(gamma_cv$distribution, function(d) d$dispersion)
Cross-Validate Mixed-Effects Models
Description
Refit a mixed model in every analysis split and score the observations held out from it. A random intercept gives each group, such as a site, its own baseline drawn from a common distribution, which accounts for the similarity among repeated surveys of that group. Choose whether prediction is for groups represented in training or for wholly new groups. Response means and joint group log scores integrate over the shared group effect.
Usage
cross_validate_mixed(
formula,
data,
folds,
family = c("gaussian", "poisson", "binomial", "nbinom2", "Gamma"),
prediction = c("new_group", "existing_group"),
kernel_inputs = NULL,
optim_args = list(),
metrics = NULL,
control = NULL,
integration_tol = 1e-08,
keep_fits = FALSE
)
Arguments
formula |
Two-sided native mixed-model formula with one grouping
column, for example |
data |
Raw data frame with unique row names. The names identify rows in the split plan and, if supplied, in the prepared raw-cell buffers. |
folds |
Named list of explicit analysis and assessment row-ID splits.
Use |
family |
Character response family. Choose |
prediction |
Character prediction target. |
kernel_inputs |
Optional raw-cell |
optim_args |
Named list of extra serial |
metrics |
Character vector of |
control |
A |
integration_tol |
Relative tolerance for the one-dimensional adaptive
integration over the group effect in non-Gaussian models. The default is
|
keep_fits |
Logical. Retain the fitted model of each successfully
scored fold. Defaults to |
Details
This function is experimental. Its arguments and results may change in a later release without a deprecation period.
Value
A list of class multiScaleR_mixed_cv, which inherits from
multiScaleR_cv. summary and metrics hold the pooled and per-fold
scores, predictions the integrated response mean of each held-out row,
joint_scores the joint log score of each held-out group, and
training the coefficients, random-effect covariance, dispersion, and
any fitted scales of each fold. Compact selection_records are always
kept. A failed fold makes the pooled scores NA. The mixed model
section of multiScaleR_cv describes every element.
How predictions and scores are made
Mixed CV uses maximum-likelihood fits with constant dispersion and a Gaussian distribution for the group effects. Given the fitted parameters, new groups use the estimated population distribution of effects. Existing groups condition that distribution on their analysis responses. Gaussian response models use exact multivariate normal conditioning. For other families the function integrates over one group intercept with adaptive quadrature. Each assessment group contributes one joint predictive density, because all of its rows share one unknown group effect. Parameter, ecological-scale, and model-selection uncertainty are outside these plug-in predictions. Native fitting, preprocessing, and selection use the analysis observations only.
Compare and select models
Use cv_tab() to compare complete results with the same observation
support, group assignments, prediction target, and splits. A joint group
score is not on the same footing as the per-observation scores of
cross_validate_glm(), so the two cannot be mixed. Use select_cv() to
evaluate a training information-criterion selection rule. Its sample size
is the native number of analysis observations. Estimated covariance
parameters count toward the penalty, and integrated group effects do not
count individually. vignette("v08-cross-validation", package = "multiScaleR") shows new-site and later-visit designs.
See Also
cross_validate(), cross_validate_field(), cv_tab(),
select_cv(), and multiScaleR_cv.
Examples
if (requireNamespace("glmmTMB", quietly = TRUE)) {
surveys <- glmmTMB::Salamanders
# Hold out whole sites, so every prediction is for a new site
folds <- grouped_cv_folds(surveys$site, k = 3, ids = rownames(surveys))
# One fold keeps the example fast
cv <- cross_validate_mixed(count ~ spp + (1 | site), surveys,
folds[1], family = "poisson")
cv$summary # joint log score per held-out row, and RMSE in counts
}
Compare Cross-Validated Prediction Scores
Description
Rank candidate models by one held-out score, after checking that every candidate was scored on the same folds and the same observations. Lower scores are better.
Usage
cv_tab(mod_list, metric, by_fold = FALSE)
Arguments
mod_list |
Named list of complete cross-validation results to compare,
for example |
metric |
One score name, chosen explicitly: |
by_fold |
Logical. The default |
Value
A data frame with one row per candidate (per candidate and fold
when by_fold = TRUE), sorted from best to worst. Its columns are:
-
Modnames: the candidate's name inmod_list. -
Rank: 1 for the best score. Tied scores share the lowest rank. -
Score: the pooled score, or the fold score whenby_fold = TRUE. -
Delta:Scoreminus the best score, in the units of the score. It isNAwhen every score is infinite. -
Metric,Unit: the score and what one score refers to, for example"observation","trial", or"choice_set". See multiScaleR_cv. -
N_assessment,N_scored,Weight_sum: the planned assessment occurrences, the number that entered the score, and their total weight. -
Warnings: the number of warnings recorded while fitting the candidate (in that fold whenby_fold = TRUE). Read them in the candidate'swarningselement. -
Fold: the fold, whenby_fold = TRUE.
The candidate results themselves are not modified.
How to read the table
The best candidate is listed first. Delta is each candidate's distance
from it, in the units of the score. For RMSE and MAE that is a difference
in response units, such as animals per survey. For the negative log score,
a Delta of D means the best model gave the observed outcomes exp(D)
times the probability, as a geometric mean per observation (per choice set
for conditional choice). The per-fold table from by_fold = TRUE is
descriptive. Use it to see whether one fold drives a ranking, never to pick
a model for that fold from its own assessment score.
What can be compared
Every candidate must be complete, with no failed fold. An incomplete candidate stops the comparison, because a model scored only on its easier folds would look better than it is. No failed model or fold is removed silently. Results of different kinds cannot be mixed.
| Results | Comparisons allowed |
Gaussian, Poisson, and binomial from cross_validate() and cross_validate_glm() | RMSE and MAE across families on identical observations. The log score, deviance, and Brier score need the same family and link. |
| NB2 or Gamma, alone or with Gaussian or Poisson | RMSE and MAE across these families on identical observations. Log scores between Poisson and NB2 on the same counts. A Gamma log score compares only with another Gamma. |
cross_validate_clogit() | Other conditional-choice results with the same complete sets and partial-likelihood method, using neg_log_score only. |
cross_validate_field() | Other field results with the same responses, folds, and projected coordinates. Poisson and NB2 share a count target. |
cross_validate_mixed() | Other mixed-model results with the same groups, prediction target, and folds. |
cross_validate_bayes() | Other Bayesian results with the same targets, folds, and blocks, using neg_log_score only.
|
A binomial log score refers to the probability of the observed count of successes, while a Brier score is a mean over individual trials. Field, mixed-model, and Bayesian log scores are joint scores for blocks of held-out observations, so they are kept apart from the per-observation scores of ordinary GLMs.
What the table does not do
The scores carry no penalty for model complexity, and Delta is not an
AIC difference, an Akaike weight, or a model probability. The spread of
fold scores is not a standard error, because folds share training data
and are few. If you use the table to choose a model or a tuning rule, the
winning score is optimistic. Evaluate that choice with an independent test
set or an outer validation layer. To score a predeclared rule that picks a
model by training AIC, AICc, or BIC, use select_cv().
See Also
cross_validate(), cross_validate_glm(), select_cv(),
multiScaleR_cv, aic_tab(), and
vignette("v08-cross-validation", package = "multiScaleR").
Examples
data("landscape_counts")
data("surv_pts")
# Three spatial folds. The simulated coordinates are in meters.
folds <- spatial_cv_folds(crds(vect(surv_pts)), block_size = 1000, k = 3,
crs = 32617)
candidates <- list(
null = cross_validate_glm(counts ~ 1, landscape_counts, folds,
family = "poisson"),
site = cross_validate_glm(counts ~ site, landscape_counts, folds,
family = "poisson"))
# Pooled ranking. Delta is the gap from the best model in animals per survey.
cv_tab(candidates, metric = "rmse")
# exp(Delta) is how many times more probability the best model gave the
# observed counts, as a geometric mean per survey
cv_tab(candidates, metric = "neg_log_score")
# Is the ranking the same in every fold?
cv_tab(candidates, metric = "rmse", by_fold = TRUE)
Assess Fitted Scale Probabilities from an Uncorrected Laplace Fit
Description
Check the probability that each fitted scale lies at or below a distance you name, as reported by a joint Laplace or uncorrected marginal Laplace fit, against a fresh importance-weighted estimate of the same posterior. Read this check alongside the fit's own optimizer and integration diagnostics.
Usage
diagnose_bayes_laplace(
object,
thresholds,
scale = c("distance", "log"),
tolerance = 0.05,
candidates = 16384L,
seed = NULL
)
Arguments
object |
A fitted |
thresholds |
Named list of scale thresholds, as in
|
scale |
Units of |
tolerance |
Absolute difference in probability that matters for your inference, strictly between 0 and 1; default 0.05. Choose it, and the thresholds, before looking at the results. |
candidates |
Number of fresh importance candidates, at least 2000; default 16384. The validation study used 65536. More candidates can reduce simulation error when the proposal overlaps the posterior well. Every candidate is kept for the weight and event diagnostics, so memory use grows with this number and with the number of parameters. |
seed |
Optional positive integer seed for the assessment. Your own random-number state is restored afterward. |
Details
This function is experimental. Its arguments and results may change in a later release without a deprecation period.
Value
A list with these elements.
-
available:TRUEwhen importance ratios and reference summaries could be calculated. A reference that fails its overlap checks is still available, but its statuses stay"unresolved". -
reason: why the reference is unavailable, why it failed its overlap checks, or that the original fit failed its own diagnostics. An empty string otherwise. -
raw_diagnostics: the fit's originaldiagnostics, unchanged. -
overlap: the importance checks of the reference (passed,pareto_k,ess,min_tail_ess,max_weight,split_cdf_error), orNULLwhen the reference is unavailable. -
target_evaluation: counts of posterior density evaluations and of rechecks of invalid values. -
probabilities: a data frame with one row per fitted scale combination and threshold.covariate,group,row,threshold, andthreshold_scaleidentify the event.approximationis the probability from the fit's draws andreferencethe importance-weighted probability, with its Monte Carlo standard errorreference_mcse.differenceis the approximation minus the reference, anddifference_loweranddifference_upperbound it numerically.indicator_essis the effective sample size of the reference event indicator,split_reference_differencethe absolute difference between the two halves of the reference, andstatusthe verdict described in "Read the status". -
candidates,seed,tolerance: the settings used. -
coefficient_proposal: the number of fallback coefficient proposals (fallbacks) and the largest remaining Newton step (max_step). -
defensive_draws: the number of candidates drawn from the defensive prior component. -
metadata_establishes_eligibility: alwaysFALSE.
Read the status
status | Meaning | What to do |
"discrepancy" | The numerical bounds on the difference lie wholly beyond tolerance on one side | Do not report the approximate probability. Sample the model |
"within_tolerance" | Both bounds lie inside tolerance | You can report the approximate probability, for this threshold only |
"unresolved" | Every other case, including a reference too imprecise or overlapping the posterior too poorly to decide | Treat the probability as unchecked. Raise candidates, or sample
|
An event can be resolved only when the reference passes the package's
importance overlap checks, the original fit passed its own diagnostics, the
event has an indicator ESS of at least 400, and the two independent halves
of the reference differ by no more than the smaller of 0.05 and
tolerance. The bounds combine three standard errors of the weighted
reference with Wilson bounds for the original approximate draws. A constant
reference indicator also leaves the event unresolved. Expect
"unresolved" often, and read it as "not checked", not as "close enough".
vignette("v15-bayesian-computation", package = "multiScaleR") reports how
often each status occurred in simulations.
How the reference is built
Candidates come 80% from heavy-tailed local proposals around the approximation and 20% from a defensive component based on the latent-effect and scale priors. Response coefficients are drawn from their exact Gaussian conditional, or from a normalized heavy-tailed conditional proposal for other families. The full posterior density and the actual mixture density determine every weight. Neither the approximation nor its draws are replaced.
This exploratory check targets only the requested scale probabilities. A heavy-tailed proposal can still miss posterior regions. The report does not certify approximation accuracy, general calibration, held-out predictions, or the fit's original diagnostics. Compare with a full posterior fit whenever your conclusions depend on these probabilities.
See Also
multiScale_bayes(), diagnose_bayes_probabilities(),
posterior_scales(), multiScaleR_bayes;
vignette("v15-bayesian-computation", package = "multiScaleR").
Examples
if (requireNamespace("RTMB", quietly = TRUE) &&
requireNamespace("posterior", quietly = TRUE)) {
example <- readRDS(system.file("extdata", "bayesian-annual-example.rds",
package = "multiScaleR"))
# A joint Laplace fit of the annual model, which takes about a second
fast_fit <- multiScale_bayes(count ~ habitat + factor(year) + (1 | site),
example$inputs, example$data, scales = list(habitat = ~1 + (1 | year)),
row_id = "site_year", family = "nbinom2",
priors = list(scale_median = 250, scale_group_sd = 0.5),
method = "laplace", seed = 527001)
# Probability that each year's sigma is 150 m or less. The smallest
# candidate budget keeps this example short. The validation study used
# 65536 candidates.
check <- diagnose_bayes_laplace(fast_fit,
thresholds = list(habitat = 150), candidates = 2000, seed = 127)
print(check$reason) # empty when the reference and the fit passed
print(check$probabilities[c("group", "approximation", "reference",
"status")])
# "unresolved" means the probability was not checked, not that it is
# close enough.
}
Check Monte Carlo Precision of Scale Probabilities
Description
Estimate the posterior probability that each fitted kernel scale lies at or below thresholds you name, and report how precisely the original sampling chains pin down each probability.
Usage
diagnose_bayes_probabilities(
object,
thresholds,
scale = c("distance", "log"),
mcse_target = NULL
)
Arguments
object |
A fitted |
thresholds |
A nonempty named list of numeric vectors. Each name
selects a fitted landscape predictor, and each vector holds distinct
finite scale thresholds. Every threshold is applied to every distinct
fitted combination of scale covariates and groups for that predictor. For
example, |
scale |
|
mcse_target |
Optional target for the Monte Carlo standard error
(MCSE) on the probability axis, strictly between 0 and 1. For example,
|
Value
A list with these elements.
-
available,reason: whether the original chains could be read, and an explanation when they could not. A single event can lack precision estimates even when the report is available. -
raw_diagnostics: the fit's original diagnostics, unchanged. -
probabilities: a data frame with one row per fitted scale combination and threshold.covariate,group,row,threshold, andthreshold_scaleidentify the event.estimateis the posterior probability that the scale is at or below the threshold.mcse,ess_mean, andrhatare the Monte Carlo standard error, mean effective sample size, and rank-normalized Rhat of the event indicator.constantflags an indicator that never changed.precision_availableisTRUEwhen the MCSE and mean ESS are finite and positive.precision_target_metcomparesmcsewithmcse_target, and isNAwhen no target was given.reasonexplains missing precision.rhat_availableandrhat_reasonreport separately whether Rhat could be computed. Undefined values areNA. -
chain_probabilities: the same event identifiers withchain, that chain'sestimate, and whether its indicator isconstant. Large differences among chains signal poor mixing. -
chains,iterations: the number of chains and of post-warmup iterations per chain, orNAwhen unavailable. -
mcse_target,event,notes: the requested target, the event definition ("kernel_scale <= threshold"), and the limits of interpretation. -
metadata_establishes_eligibility: alwaysFALSE. The report does not change the fit's sampling or derived-scale diagnostic gates.
Read the precision
The MCSE is computational uncertainty in the probability estimate, not
posterior uncertainty about the scale and not observation variation.
precision_target_met only compares that MCSE with your target. It
does not override Rhat, ESS, the raw sampler checks, or model checks, and a
small MCSE cannot rule out an unvisited tail or mode. Read
diagnose_bayes_scales() alongside this report, and compare independent
runs when a consequential probability remains uncertain. Longer chains
reduce the MCSE.
How the events are computed
Each event is evaluated on fitted log scales in map units, which avoids
overflow from exponentiating distances. The posterior package computes the
mean ESS, MCSE, and rank-normalized Rhat of each binary indicator. At least
two chains with four retained iterations each are needed for precision
diagnostics. A constant indicator has no estimable precision, even when its
probability is exactly zero or one. Indicator Rhat can be undefined for a
balanced binary event even when the MCSE is finite. It is then reported as
NA with its own flag and reason, which alone does not make the precision
unavailable. A nonfinite derived log scale is an error, and iterations are
never dropped.
The function does not fit a model, change priors, simulate new groups, or
treat importance candidates as MCMC chains. Reading a full NUTS sampler can
take substantial memory, but the report keeps only summaries.
vignette("v15-bayesian-computation", package = "multiScaleR") shows how to
report a probability with its MCSE.
See Also
diagnose_bayes_scales(), posterior_scales(),
predict_scales(), diagnose_bayes_laplace(),
multiScaleR_bayes
Examples
# A stored slice fit that keeps its four original chains
shared <- readRDS(system.file("extdata", "cache-bayesian-scales.rds",
package = "multiScaleR"))$fit
if (requireNamespace("posterior", quietly = TRUE)) {
report <- diagnose_bayes_probabilities(shared,
thresholds = list(land1 = c(200, 300)), mcse_target = 0.01)
# Probability that sigma for land1 is at most 200 m and at most 300 m
print(report$probabilities[c("threshold", "estimate", "mcse",
"precision_target_met")])
print(report$chain_probabilities[c("threshold", "chain", "estimate")])
}
# A compact fit keeps thinned, permuted draws and cannot be checked
example <- readRDS(system.file("extdata", "bayesian-annual-example.rds",
package = "multiScaleR"))
compact <- diagnose_bayes_probabilities(example$fits$pooled,
thresholds = list(habitat = c(100, 250)))
compact$available # FALSE
compact$reason
Check Sampling Precision of Fitted Bayesian Scales
Description
Check chain mixing and simulation precision for the quantities you report from a sampled fit, the log scale of each landscape predictor and the between-group SDs. These derived quantities can mix differently from the individual parameters checked by the sampler's own diagnostics.
Usage
diagnose_bayes_scales(object, probs = c(0.025, 0.5, 0.975))
Arguments
object |
A fitted |
probs |
Numeric vector of distinct probabilities strictly between 0
and 1. The default |
Value
A list with these elements.
-
available,reason: whether full chain diagnostics could be computed, and an explanation when they could not. -
raw_diagnostics: the sampler or approximation diagnostics stored in the fit, unchanged. -
parameters: a data frame with one row per derived quantity.variableis an internal label.quantityis"log_distance","scale_group_sd", or"response_group_sd".covariate,group, and a representative observationrowidentify it, andunitsstates its units.rhat,ess_bulk, andess_tailgive the rank-normalized Rhat and the bulk and tail effective sample sizes. -
quantiles: a data frame with the same identifying columns plusprobability, the quantileestimate, and its Monte Carlo standard errormcse, both in the stated units. Undefined values areNA. -
chains,iterations: the number of retained chains and of post-warmup iterations per chain, orNAwhen unavailable. -
derived_passed:TRUEwhen there are at least two chains and every derived quantity has Rhat at most 1.01 and bulk and tail ESS of at least 100 per chain.NAwhen unavailable. -
passed:TRUEwhen both the original sampler checks and the derived checks pass.NAwhen unavailable. For a slice fit sampled without the posterior package, the original parameter checks are computed here from the stored chains, while the fit's stored diagnostics stay as recorded. -
criteria,notes: the fixed derived checks and their limits.
Read the report
| Column | Acceptable | If it fails |
rhat | 1.01 or less | Refit with another seed and compare. A weak landscape effect leaves its scale poorly identified, and longer chains do not cure that |
ess_bulk, ess_tail | At least 100 per chain (400 for four chains) | Increase iter, or switch from slice sampling to NUTS |
mcse | No fixed cutoff. Small next to the precision your question needs | Increase iter, and compare independent runs when an interval limit matters
|
Landscape scales are diagnosed on the natural log axis in map units, which
avoids overflow and the infinite arithmetic distance moments that the
hierarchical priors allow (see posterior_scales()). Exponentiate a
log-distance quantile to express it in map units. Its MCSE is on the log
axis, so an MCSE of 0.01 is about 1% of the distance. The MCSE is
computational uncertainty, not a posterior interval or a biological SD.
Scale-group SDs measure population variation in log distance.
Response-group SDs use the response linear-predictor axis.
The posterior package computes rank-normalized Rhat, effective sample sizes, and quantile MCSE. A passed screen guarantees neither a precise tail endpoint nor discovery of every mode. Compare the MCSE with the precision your scientific decision needs, inspect independent runs when tails matter, and assess the likelihood and priors separately.
Why compact fits cannot be checked
Permuted or thinned stored draws cannot rebuild the original chain order or full-chain precision. Compact examples therefore keep their original diagnostic evidence but cannot provide new chain diagnostics. Laplace draws and weighted importance candidates are not MCMC chains, so use the stored numerical checks for those fits.
Draw chain plots
For chain plots in bayesplot, pass fit$chains for a slice fit, or
rstan::extract(fit$sampler, permuted = FALSE, inc_warmup = FALSE) for a
NUTS fit. vignette("v13-bayesian-scales", package = "multiScaleR") shows
trace plots alongside these diagnostics, and
vignette("v15-bayesian-computation", package = "multiScaleR") works
through a fit that fails them.
See Also
multiScale_bayes(), posterior_scales(),
plot.multiScaleR_bayes(), diagnose_bayes_probabilities(),
multiScaleR_bayes
Examples
# A stored slice fit that keeps its four original chains
shared <- readRDS(system.file("extdata", "cache-bayesian-scales.rds",
package = "multiScaleR"))$fit
if (requireNamespace("posterior", quietly = TRUE)) {
report <- diagnose_bayes_scales(shared)
print(report$passed) # sampler and derived checks together
# Agreement among chains and effective sample size for each log sigma
print(report$parameters[c("covariate", "rhat", "ess_bulk", "ess_tail")])
# Interval limits of log sigma, with their Monte Carlo standard errors
q <- report$quantiles
print(data.frame(q[c("covariate", "probability")],
sigma_m = exp(q$estimate), mcse_log = q$mcse))
}
# A compact fit keeps thinned, permuted draws and cannot be checked
example <- readRDS(system.file("extdata", "bayesian-annual-example.rds",
package = "multiScaleR"))
compact <- diagnose_bayes_scales(example$fits$pooled)
compact$available # FALSE: the compact example contains no full sampler
compact$reason
Retrieve diagnostics from multiScaleR objects
Description
Returns structured warning/diagnostic information stored on fitted
multiScaleR objects. Diagnostics are populated automatically during
multiScale_optim and flag potential issues with the
optimization result.
Usage
diagnostics(object, ...)
## S3 method for class 'multiScaleR'
diagnostics(object, ...)
Arguments
object |
An object to inspect. Must be of class |
... |
Additional arguments passed to methods. |
Details
These diagnostics are evaluated automatically at the end of
multiScale_optim. Console warnings are printed when any
diagnostic is triggered and verbose = TRUE. diagnostics() provides programmatic access
to the same information without re-running the model.
These stored diagnostics retain the historical 1D 90% distance and
threshold, independently of the new 2D reporting default in plots and
summaries. Changing dimension when reporting a fit does not
recompute its stored diagnostics. Use kernel_dist(object) to inspect
the ideal planar radius separately.
When max_distance is triggered, consider re-running
kernel_prep with a larger max_D value. The suggested
minimum is stored in suggested_max_D.
When sigma_precision is triggered, the variable may not have a
meaningful scale of effect, or the data may be insufficient to estimate it
precisely. Interpret affected covariates with caution.
Value
A named list with the following elements:
max_distanceA list describing whether the estimated scale of effect approaches or exceeds
max_D. Fields include:triggered(logical),variables(names of affected covariates),effective_distance(estimated 90% one-dimensional kernel distance per covariate; seekernel_dist),max_D(the limit used),ratio(max_D / effective_distance), andsuggested_max_D(a recommended minimummax_Dvalue). Triggered whenmax_D / effective_distance < 2.sigma_precisionA list describing whether sigma estimates are imprecise. Fields include:
triggered(logical),variables(names of affected covariates),estimate(sigma means),se(standard errors), andse_to_mean(ratio of SE to mean). Triggered whenSE / Mean >= 0.5for any covariate.NULLwhen no precision concern was flagged.shape_precisionIdentical structure to
sigma_precisionbut for the shape parameter of the exponential power kernel.NULLunlesskernel = "expow"was used and a precision concern arose.sample_sizeA list with
fitted_n, the number of observations in the final model, andprepared_n, the number of observations in the preparation object, or model rows for repeated-siteunmarkeddata. Forunmarkedfits,prepared_sitesis the number of distinct spatial sites in the preparation object.triggeredisTRUEwhen the fitted model uses fewer observations. Candidate scales that change the initial model's sample are rejected during optimization.start_stallFor the default refit backend, present only when the optimizer returned its starting values, so the reported scales are those starts. A search from the default start is flagged whenever it returns that start. A user-supplied or screened start is flagged only when the search stopped after one evaluation, because such a start may already be an optimum. Fields include
reason,screened(whether the start came fromstart_strategy = "screen"),start(starting sigma values in map units),function_evaluations, andmessage, which names the remedy.reasonis"hard_radius"when every optimized scale is a hard radius, as underkernel = "fixed". Its likelihood changes in steps, so the gradient is zero almost everywhere.reasonis"refit_failed"when no refitted model gave a finite log-likelihood at the start. A glmmTMB model with a non-positive-definite Hessian reports none.reasonis"no_progress"otherwise. A warning gives the same message when the fit is made, andprint()andsummary()repeat it.refit_hessianFor the default refit backend, retains the outer curvature status and active smooth-parameter mask. A bound table records estimates, lower/upper bounds in reporting units, and bound flags. If any active parameter is within
1e-5log units of a positive bound, joint outer Wald SEs are withheld. A zero lower bound is flagged only when reached. The original curvature status is retained separately. A status of"hessian_includes_failed_refit"means a refit failed at one of the finite-difference points used for the Hessian, so its curvature reflects the failure penalty; Wald SEs are withheld and a warning is given. This is a numerical support flag, not a test of identification or a calibrated confidence limit. Native coefficient covariance and parameter counts are unchanged.radius_profileFor a declared radius grid, one row per combination.
radius, or oneradius:<predictor>column per hard radius, uses map units. Anysigma:<predictor>andshape:<predictor>columns hold the reoptimized smooth bandwidths in map units and unitless shapes, respectively. The table also reports nativelog_likelihood,status(scored or failed), any failuremessage, and a logicalselectedflag. With smooth predictors,smooth_startsholds a table of optimizer and convergence diagnostics for each combination that reached the smooth search. An all-failed search carries the profile table on the error condition.profile_glmPresent for both opt-in analytic GLM backends. Includes
uncertainty_available, explanatoryreasons,weak_identifiability,boundary,condition_number, log-kernel standard errors, competing-mode flags, and attempted/eligible start counts.poisson_limitmarks negligible fitted NB2 extra variance;poisson_compatibleandpoisson_deviancecompare the NB2 fit with a Poisson fit at the selected kernel scales. SeemultiScale_optimfor thresholds and limitations.
See Also
Examples
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,
kernel = 'gaussian')
mod <- glm(y ~ hab, family = poisson, data = count_data)
opt <- multiScale_optim(fitted_mod = mod, kernel_inputs = kernel_inputs)
## Access diagnostics
diag <- diagnostics(opt)
diag$max_distance$triggered
diag$sigma_precision
Estimate Memory Requirements for Multiscale Optimization
Description
Estimates how much memory a kernel_prep() object (and optionally a fitted
starting model) needs during multiScale_optim(), and recommends a
conservative maximum number of parallel workers (n_cores). Use it before
running a large or slow model in parallel, because each worker holds its
own copy of the inputs.
Usage
estimate_multiscale_ram(
kernel_inputs,
fitted_mod = NULL,
join_by = NULL,
refit_fn = NULL,
n_cores = NULL,
PSOCK = (.Platform$OS.type != "unix"),
safety_factor = 1.5,
ram_fraction = 0.75,
leave_free = 2L
)
## S3 method for class 'multiScaleR_ram'
print(x, ...)
Arguments
kernel_inputs |
A |
fitted_mod |
Optional fitted starting model, as you would pass to
|
join_by |
Optional data frame passed through to |
refit_fn |
Optional custom refit function passed through to
|
n_cores |
Optional positive integer. Worker count at which to report the peak memory estimate. When omitted, the recommended maximum is used. |
PSOCK |
Logical. Budget workers as PSOCK (socket) workers. Default:
|
safety_factor |
Numeric scalar, at least 1. Multiplier on each
worker's payload to allow for temporary allocations during optimization.
Larger values give fewer recommended workers. Default: |
ram_fraction |
Numeric scalar between 0 and 1. Share of total system
RAM treated as usable. The rest is left for the operating system and
other R objects. Default: |
leave_free |
Non-negative integer. Number of physical CPU cores to
leave unused when computing the CPU limit. Default: |
x |
A |
... |
Not used. |
Value
estimate_multiscale_ram() returns a list of class
multiScaleR_ram with these elements:
-
requested_n_cores: the worker count used for the peak estimate (n_cores, or the recommendation whenn_coresis omitted). -
recommended_n_cores: the smaller of the CPU and RAM limits, or the CPU limit when RAM could not be detected. Never less than 1. -
max_cores_by_cpu: physical cores minusleave_free, at least 1. -
max_cores_by_ram: the number of workers that fit in the usable RAM, at least 1, orNAwhen total RAM could not be detected. -
backend:"PSOCK"or"fork", the assumed parallel backend. -
system: list with the detectedphysical_coresandlogical_cores,leave_free,total_ram_bytes,usable_ram_fraction,usable_ram_bytes,safety_factor, and readable versions of the RAM values (total_ram_pretty,usable_ram_pretty). -
point_summary: one-row data frame with the number of points, the mean, median, and maximum number of extracted cells per point (NAin lean mode), the number of source layers, whether cell-level data are stored (cell_data_stored), and the number of distance bins (nbins). -
component_bytes: data frame with columnscomponent,bytes, andpretty(a readable size) for each stored object (kernel_inputs_total,kernel_dat,d_list,raw_cov,binned,join_by,fitted_mod,opt_context), the two bundles described in Details (worker_bundleandmain_bundle), andpeak_parallel_estimate. -
notes: character vector of interpretation notes and detection warnings.
print() displays the main limits, the detected hardware, the peak
estimate, and the notes, and returns x invisibly.
How the estimate is built
Sizes come from utils::object.size(), so they describe stored R objects,
not the transient memory used by exactextractr, model refits, or linear
algebra libraries. The main bundle is what the main R session holds (the
kernel inputs, join_by, the optimization context, and the model). The
worker bundle is what each parallel worker receives (the per-cell
distances and values, join_by, the optimization context, and the model).
The limits and the peak estimate follow from these sizes.
Usable RAM = total RAM x
ram_fraction.RAM limit = (usable RAM - main bundle) / (worker bundle x
safety_factor), rounded down.Peak estimate = main bundle +
n_coresx worker bundle xsafety_factor.
Even where forking lets workers share memory, each worker is budgeted as if it held its own copy. Hardware measurements that succeed are kept for the rest of the R session. A failed RAM lookup is retried on the next call.
Read the report
Compare the worker count you plan to use with max_cores_by_ram, and read
the peak estimate at that count. These are conservative estimates, not
measured memory use. The recommendation is never below one worker, but
that does not guarantee a serial run fits in memory. A run at or below the
limit can still run out of memory during a model refit. If RAM detection
or the estimate fails, no limit can be enforced.
Reduce the memory needed
When every covariate is a kernel mean, rebuild the original
kernel_prep() call with bin = TRUE, store_cell_data = FALSE, keeping
its other settings, and check the estimate again. This lean mode keeps only
the distance-binned summaries that optimization uses. It is not available
for landscape or surface metrics, which need the cell-level data.
Otherwise, use fewer workers or n_cores = 1. Do not delete components of
the object by hand, and do not shrink a scientifically chosen max_D only
to pass the check.
How multiScale_optim() uses the estimate
With n_cores > 1, multiScale_optim() calls this function with its
default settings before starting workers. It stops with an error when
n_cores exceeds max_cores_by_ram. It does not lower n_cores for you.
When RAM cannot be detected or the estimate fails, the check does not
block the run.
See Also
multiScale_optim(), kernel_prep(). The section "Estimate the
scales of effect" in
vignette("v02-user-guide", package = "multiScaleR") shows the check on
a worked example.
Examples
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,
kernel = "gaussian", verbose = FALSE)
mod <- glm(y ~ hab, family = poisson,
data = data.frame(count_data["y"], kernel_inputs$kernel_dat))
# Recommended worker limits and the peak memory estimate for two workers
ram <- estimate_multiscale_ram(kernel_inputs, fitted_mod = mod, n_cores = 2)
ram
# Estimated size of each component, largest first
ram$component_bytes[order(-ram$component_bytes$bytes), ]
Expand Site and Survey Covariates into GDR Intervals
Description
Copy chosen site covariates, or covariates recorded once per visit, into
the observation table of an unmarkedFrameGDR, which has one row per
survey and removal interval. A removal formula reads its covariates from
that table, so a covariate constant within a survey, such as the observer,
must be repeated there before you can use it in the removal formula. The
function also adds the interval number and returns a copy of the frame
with a record of how every row was aligned.
Usage
expand_gdr_intervals(
object,
event_keys,
event_id,
interval_units,
site_covariates = character(),
yearly_covariates = character(),
interval = "interval",
site_id = NULL,
effort = NULL,
expected_event_keys = NULL
)
Arguments
object |
An |
event_keys |
Data frame with one row per survey event, in the frame's order (all primary periods of the first frame row, then the second, and so on). Include completed surveys with zero counts. Use the original survey identifiers. |
event_id |
Character vector naming the column(s) of |
interval_units |
Character string naming the time unit of the removal
intervals, such as |
site_covariates |
Character vector naming the site covariates
( |
yearly_covariates |
Character vector naming covariates in the frame's
yearly table ( |
interval |
Character string, default |
site_id |
Optional column(s) of |
effort |
Optional numeric vector of survey effort, one value per
event, passed to |
expected_event_keys |
Optional independent event list in frame
order, passed to |
Value
A list of class msr_gdr_intervals, as from
prepare_gdr_intervals(): data is the copied frame with the new
observation columns, survey_audit is the survey audit, alignment
records which input row fills each observation row, and protocol
records units, interval lengths and the added columns. In addition,
protocol$expanded_covariates is a data frame with one row per copied
covariate: source_table ("site" or "yearly"), the source column
and its target name in the observation table. With no covariates
selected, only the interval column is added. fit_eligibility_established
is always FALSE.
Why repeat covariates
When the removal formula contains a random effect, unmarked evaluates
the random-effect part on the observation table, and that step also needs
the formula's fixed covariates there. Repeating only an observer label can
therefore leave a
formula such as ~ rem_forest + I(interval == 1) + (1 | rem_observer)
without rem_forest. Select every survey-constant covariate the
observation formula needs.
How values are repeated
A site covariate is repeated for every primary period and interval at that
site. A yearly covariate is repeated only for the intervals of its own
primary period. Column classes, matrix columns, factor levels, contrasts
and missing values are kept. Nothing is standardized, imputed or dropped,
and the original covariate tables, counts, distance bands and interval
lengths are unchanged. Existing observation columns cannot be overwritten.
For covariates that change from one interval to the next, use
prepare_gdr_intervals() directly.
Name copies by role
Give a copy a new name when the same field plays different roles, for
example forest in the abundance formula and rem_forest in the removal
formula. A copy holds the values present when it was made. If you later
change the site covariate, for example while estimating its scale of
effect, the copy does not change with it. multiScale_optim() also stops
if a covariate whose scale it estimates shares its name with a column in
the observation or yearly tables, so new names avoid that conflict.
Aligning the data does not show that a model fitted to it converges or
that its parameters are identifiable. See the "Add covariates for the time
intervals" section of
vignette("v12-distance-removal", package = "multiScaleR") for a worked
example.
See Also
prepare_gdr_intervals(), prepare_gdr_histories(),
validate_unmarked_data()
Examples
# Two surveys, two distance bands and three removal intervals
frame <- unmarked::unmarkedFrameGDR(matrix(0, 2, 2), matrix(0, 2, 3),
siteCovs = data.frame(forest = c(.2, .8), Observer = factor(c("A", "B"))),
dist.breaks = c(0, 25, 75), unitsIn = "m", period.lengths = c(1, 2, 1))
keys <- data.frame(survey = c("s1", "s2"))
# Copy forest and observer into the interval table under new names
prepared <- expand_gdr_intervals(frame, keys, "survey", "minutes",
site_covariates = c(rem_forest = "forest", rem_observer = "Observer"))
# One row per survey and interval, ready for a removal formula such as
# ~ rem_forest + I(interval == 1) + (1 | rem_observer)
unmarked::obsCovs(prepared$data)
prepared$protocol$expanded_covariates
Fit a Fixed-Range Spatial Abundance Field to a Distance-Removal Model
Description
Replace the independent random intercepts on abundance in a native TMB
distance-removal (GDR) model with a spatially correlated Gaussian field.
Nearby survey blocks then tend to have similar density deviations. The
correlation between two blocks falls with the distance d between them as
exp(-d / range). You supply range; it is not estimated. Ecological
scales of effect remain separate parameters, estimated later with
make_gdr_refitter() and multiScale_optim().
Usage
fit_gdr_response_field(
model,
coords,
crs,
range,
cold_starts,
audit_dir,
tmb_settings,
max_memory_mb = 512
)
Arguments
model |
An |
coords |
Numeric matrix or data frame with two projected coordinate
columns (x, y) and one row per survey, in the row order of the model's
frame. Row names must equal the frame's site row names, which are
|
crs |
The projected coordinate reference system of |
range |
Positive number. The fixed correlation range of the
exponential field, in the linear units of |
cold_starts |
Named list of one or more extra starting vectors (for
example |
audit_dir |
Character string naming a directory for audit records. It
is created if needed. Every fit writes small |
tmb_settings |
Named list of optimizer settings with elements |
max_memory_mb |
Positive number, default 512. A conservative planning
budget, in MiB, for the dense field covariance and the TMB tape. The fit
stops before optimizing when its estimate exceeds the budget. The same
budget limits later |
Details
A random intercept for each survey block lets density differ among blocks
beyond what the covariates explain. In the template model those block
deviations are independent. This function keeps the same distance and
removal observation model, the same cutoff K and the same SD of the
deviations, but makes the deviations of nearby blocks correlated. See the
"Model spatial correlation among survey blocks" section of
vignette("v12-distance-removal", package = "multiScaleR") for a worked
example.
Value
An object of class unmarkedFitGDRField.
It extends the unmarkedFitGDR class of unmarked, so coef(), logLik(),
unmarked::sigma() and summary() work as usual, while predict(),
vcov() and confint() use the retained field covariance. The table
under "Read the fitted model" says where each parameter lives and on what
scale. The log-likelihood is the native Laplace approximation of the
marginal likelihood, with the field integrated out. The AIC counts the
same parameters as the template model, because the range is fixed.
The attribute msr_gdr_refit_audit summarizes the fit: status, the
attempts from every start with their diagnostics, the index of the
selected start, maximum_start_value_difference (the spread of the
negative log-likelihoods among starts) and the audit path.
Check that your model qualifies
The template must have all of the following:
Poisson abundance (
mixture = "P") and a half-normal distance function (keyfun = "halfnorm").Density output in birds per square kilometer (
output = "density",unitsOut = "kmsq").One visit per point (one primary period) and complete counts for every survey, with no sites dropped by
unmarked.Distance bands in meters with boundaries
c(0, 25, 75)orc(0, 25, 50, 75), so the survey circle has a 75 m radius.Exactly one random intercept in the abundance formula, such as
~ land1 + (1 | block). Every level of the grouping factor must have at least one survey.Optionally, one independent random intercept in the distance formula, such as an observer effect. It stays independent. The removal formula takes no random effects.
No
offset()terms.-
unmarked1.5.2 andTMB1.9.25.
The field correlation matrix must also be numerically positive definite.
Blocks at nearly identical locations relative to range can fail this
check. No numerical jitter is added.
How the fit is checked
The field model is fitted from the template's own estimates (the start
named "original") and from every vector in cold_starts. Each fit starts
its block deviations at zero. Every start must return a converged,
warning-free fit with usable covariance and a largest absolute gradient
below 0.001. All starts must also agree, with negative log-likelihoods
within 1e-5 and coefficients and log SDs within 0.001 of one another. If
any start fails or the starts disagree, the function stops with an error
and leaves the records in audit_dir. When every check passes, it returns
the fit with the highest likelihood. Agreement among a few starts does not
prove that no better optimum exists. If the starts disagree, compare the
attempts recorded in audit_dir before trying other starting values.
Read the fitted model
| Quantity | Where to find it | Scale | How to read it |
| Density intercept | coef(fit)["lambda(Int)"] | log | exp() gives density per square km when covariates and the field are zero |
| Abundance covariate effect | coef(fit)["lambda(x)"] | log | exp() is the factor by which density changes per unit of x |
| Distance scale | coef(fit)["dist(Int)"] | log | exp() gives the half-normal scale in meters |
| Removal probability | coef(fit)["rem(Int)"] | logit | plogis() gives the probability, per unit of interval time, that a bird present is first detected |
| Field SD | unmarked::sigma(fit) | log density | Typical size of a block deviation. A block one SD above zero has exp(SD) times the density of a block with no deviation |
| Block deviations | coef(fit, type = "lambda", fixedOnly = FALSE) | log density | The entries labeled lambda(b_lambda), one fitted field value per block, follow the fixed coefficients |
| Correlation range | fit@response_field$definition$range | CRS units | Supplied by you, not estimated |
Internally, TMB works with uncorrelated (whitened) versions of the block
deviations. Every value reported by coef(), vcov() and predict() is
converted back to the physical field, the deviation at each block's
location.
How uncertainty is reported
vcov() returns the covariance retained
from the fit. It includes the covariance between components (abundance,
distance, removal) and between the fixed coefficients and the field values.
It is computed once during fitting, so vcov() does not rerun TMB.
predict() uses that covariance for
its standard errors. At a block used in fitting, the SE comes from the
fitted coefficients and field values alone. At a new location, the SE adds
the field variance that remains after conditioning on the fitted blocks.
That extra variance describes how uncertain the field is between blocks.
It is not observation noise. Density predictions are exp() of the linear
predictor at the fitted field values. They are not averages over possible
field values, which would be larger. With re.form = NA, predictions set
the field to zero, which describes a block with no deviation rather than an
average over blocks.
All of these intervals treat the ecological scales of effect and the correlation range as known. They add no uncertainty for either.
Estimate scales of effect with the field in place
Build a refit function from the field fit, using the same starts and the
identical tmb_settings, and pass it to multiScale_optim():
refit <- make_gdr_refitter(field_fit, list(cold = cold),
audit_dir = tempfile("gdr-field-refits-"), tmb_settings = settings)
opt <- multiScale_optim(field_fit, kernel_inputs, refit_fn = refit,
n_cores = 1)
Each candidate scale refits the field from every start, with the range held
fixed. Expect minutes even for 100 surveys. The search must run on one core
with the default backend = "refit" and PSOCK = FALSE. The ordinary
update() method stops for this class. Use the refit function instead.
Map density with the field
A density map needs the field value at every raster cell. Bind the fitting
coordinates to the scale-of-effect result with response_field_geometry(),
then pass the descriptor to predict.multiScaleR():
geometry <- response_field_geometry(opt, coords = block_xy, crs = 32617) layers <- kernel_scale.raster(land, multiScaleR = opt, scale_center = TRUE, match_buffer = TRUE) dens <- predict(opt, layers, type = "lambda", se.fit = TRUE, uncertainty = "conditional", raster_args = list(field_geometry = geometry))
The raster CRS must match crs, and prediction runs on one core. Each cell
gets the field value predicted at its center from the fitted block values.
The grouping factor of the field (block above) is not needed as a
raster. A factor that also enters a fixed part of the model still needs an
explicit value through site_values in kernel_scale.raster() or a raster
coded with the fitted levels. To map the zero-field reference instead, omit
field_geometry and set re.form = NA.
Not supported
Estimating the range, other abundance mixtures or distance functions,
repeat visits with availability, a removal field, simulate(),
profile(), ranef() and spatial cross-validation are not available for
this model.
See Also
unmarkedFitGDRField, make_gdr_refitter(),
gdr_start_values(), response_field_geometry(),
vignette("v12-distance-removal", package = "multiScaleR")
Examples
# The field needs unmarked 1.5.2 and TMB 1.9.25.
if (requireNamespace("TMB", quietly = TRUE) &&
utils::packageVersion("unmarked") == "1.5.2" &&
utils::packageVersion("TMB") == "1.9.25") {
# Eight survey blocks 1 km apart along a line, six point counts in each
block <- factor(rep(paste0("b", 1:8), each = 6))
hab <- rep(seq(-1, 1, length.out = 6), 8)
shift <- c(-0.4, -0.3, -0.1, 0, 0.1, 0.2, 0.35, 0.4)[block]
sim <- sim_dat_gdr(density = exp(log(400) + 0.5 * hab + shift),
distance_scale = 40, removal = 0.2, dist_breaks = c(0, 25, 50, 75),
interval_lengths = c(2, 3, 5), interval_units = "minutes",
site_covs = data.frame(hab = hab, block = block), seed = 1)
umf <- sim$observed
# Template: an independent random intercept for each block (TMB engine)
template <- unmarked::gdistremoval(lambdaformula = ~ hab + (1 | block),
removalformula = ~ 1, distanceformula = ~ 1, data = umf,
keyfun = "halfnorm", mixture = "P", output = "density",
unitsOut = "kmsq", K = 60, engine = "TMB",
starts = c(log(400), 0, log(40), qlogis(0.2), log(0.3)))
# Every survey carries the projected coordinates (m) of its block center
block_xy <- cbind(x = 500000 + 1000 * (as.integer(block) - 1),
y = 4400000)
rownames(block_xy) <- rownames(unmarked::siteCovs(umf))
# A second set of starting values, named by parameter block and position
cold <- c("beta_lambda[1]" = log(300), "beta_lambda[2]" = 0,
"beta_dist[1]" = log(30), "beta_rem[1]" = qlogis(0.4),
"lsigma_lambda[1]" = log(0.5))
settings <- list(method = "BFGS", se = TRUE, threads = 1L,
control = list(maxit = 2500L, reltol = 1e-10))
field_fit <- fit_gdr_response_field(template, coords = block_xy,
crs = 32617, range = 2000, cold_starts = list(cold = cold),
audit_dir = tempfile("gdr-field-"), tmb_settings = settings)
# Log density, log distance scale (m) and logit removal probability
print(unmarked::coef(field_fit))
# SD of the block deviations, on the log density scale
print(unmarked::sigma(field_fit))
# The range adds no parameter, so the AIC penalty matches the template
print(c(template = template@AIC, field = field_fit@AIC))
}
List the Starting-Value Order of a Distance-Removal Model
Description
Read the fitted coefficient and log SD values of an unmarked
distance-removal (GDR) model in the order that unmarked::gdistremoval()
expects for its starts argument, with a map that names the model
component and position of each value. Use it to build extra starting
values for make_gdr_refitter() and fit_gdr_response_field().
Usage
gdr_start_values(model)
Arguments
model |
An |
Value
A plain list:
-
starts: an unnamed numeric vector of the fitted values in starting order, on the link scales (log, logit, and log for SDs). Random-effect values are not included. -
map: a data frame with one row per element ofstarts:constructor_position, the TMB parameterblock(such as"beta_lambda"or"lsigma_lambda"),within_block(position in the block),fitted_position(position in the fitted optimizer vector),component("lambda","dist","rem"and so on),kind("regression"or"log_sd") andlabel, the coefficient or variance name stored byunmarked. For a TMB-engine model, pasteblockandwithin_blockas"beta_lambda[1]"to name a start formake_gdr_refitter(). -
fitted_values: the fitted optimizer vector with its own names and order.coordinate_countis its length, not a count for AIC.random_modes_omittedgives the number of random-effect values left out in each component. -
optimizer: the stored objectivevalueandconvergencecode, as reported by the fit. -
provider: theunmarkedversion, the engine and, for TMB, the TMB version.format_versionidentifies the layout of this list. -
fingerprint: a SHA-256 of this list. It does not identify the data, settings or likelihood. -
fit_eligibility_established,likelihood_evaluatedanduncertainty_evaluated: alwaysFALSE. The function only reads stored values.
Why the order matters
With the TMB engine, the order of the starts argument can differ from
the order of the fitted optimizer vector. For example, unmarked may
place the negative binomial dispersion after the regression and variance
blocks in the starts, but next to abundance in the fitted vector. Repeated
coefficient labels cannot resolve this, so the map identifies each value
by its block and position and checks every value against the stored
estimates.
What the function does not do
It reads stored values only. It does not evaluate the likelihood, its gradient or Hessian, and it leaves the model unchanged. A failed or nonconverged fit can still have finite values, and its stored diagnostics keep their meaning. Nonfinite or inconsistent values stop with an error rather than being dropped or repaired.
The list can be saved with saveRDS() without saving a fitted model. It
cannot restore a fit. Refitting still needs the original data,
transformations, formulas and optimizer settings.
See Also
make_gdr_refitter(), fit_gdr_response_field(),
expand_gdr_intervals()
Examples
frame <- unmarked::unmarkedFrameGDR(matrix(c(0, 0, 1, 0), 2, byrow = TRUE),
matrix(c(0, 0, 0, 1, 0, 0), 2, byrow = TRUE),
dist.breaks = c(0, 25, 75), unitsIn = "m", period.lengths = c(1, 2, 1))
# A fixed point for inspecting coordinates, not a converged fit.
point <- unmarked::gdistremoval(data = frame, engine = "C", K = 30,
starts = c(log(8), log(40), qlogis(.3)), se = FALSE,
control = list(maxit = 0))
snapshot <- gdr_start_values(point)
# Log density, log distance scale and logit removal, in starting order
snapshot$starts
# Component, block position and stored label of each value
snapshot$map[, c("block", "within_block", "component", "kind", "label")]
Create Grouped Cross-Validation Folds
Description
Keep all rows from a sampling group in the same assessment fold, so that a held-out row is never predicted with help from its own group. Whole groups are assigned to folds to balance the row counts, largest groups first.
Usage
grouped_cv_folds(group, k = 5, ids = NULL)
## S3 method for class 'multiScaleR_folds'
print(x, ...)
Arguments
group |
Vector of sampling-group labels, one per row, such as site, animal, year, or choice-set IDs. Missing or empty labels are rejected. |
k |
Number of folds, at least two and no greater than the number of groups. The default is five. |
ids |
Unique character row IDs, in the order of |
x |
A |
... |
Not used. Reserved for future print controls. |
Details
Assignment is deterministic and does not use the random-number
generator, so the same call always gives the same folds. Groups of equal
size are ordered by their labels. Balancing row counts does not stratify
the responses. Choose the sampling groups and the prediction question
before you look at any scores. To keep groups together within spatial
blocks, pass them as group to spatial_cv_folds(). Building folds does
not decide which models can be scored. For matched choice sets, score
the folds with cross_validate_clogit().
vignette("v08-cross-validation", package = "multiScaleR") compares
grouped, spatial, and random fold designs.
Value
A named list of class multiScaleR_folds with one element per fold
(fold1, fold2, and so on), ready for cross_validate() and the other
cross-validation functions. Each element holds two character vectors of
row IDs, analysis (rows used to fit) and assessment (rows held out).
Every row is assessed exactly once. The attribute fold_info holds the
method ("grouped"), k, an assignment data frame with the row_id,
group, unit, and assessment fold of every row, and excluded, the
IDs left out of each fold's training rows (none for grouped folds).
print() shows the number of analysis, assessment, and excluded rows in
each fold, and returns x invisibly.
See Also
spatial_cv_folds(), cross_validate(), cv_tab()
Examples
# Twelve records from six sites, two visits each
ids <- paste0("row", 1:12)
folds <- grouped_cv_folds(rep(letters[1:6], each = 2), k = 3, ids = ids)
folds # rows fitted and held out in each fold
folds$fold1$assessment # both visits to a site are held out together
Example habitat raster
Description
A binary habitat raster stored as hab.tif in the package's extdata
folder, used with pts and count_data.
Format
A SpatRaster with one layer, hab, of 400 by 400 cells of 10
map units (an extent of 0 to 4000 in each direction) and no coordinate
reference system. Cells are 1 for habitat and 0 otherwise.
Source
Simulated for this package.
See Also
Examples
hab <- terra::rast(system.file("extdata", "hab.tif",
package = "multiScaleR"))
hab
terra::plot(hab)
Convert Sigma into an Effective Distance
Description
Converts a kernel scale parameter (sigma) into an effective
distance in map units, the distance that holds a stated proportion of the
kernel weight. Use it with a fitted multiScaleR object to report the
estimated scales of effect as distances, or with kernel parameters you
supply to explore how far a kernel reaches before fitting. The kernels, the
two distance definitions, and their formulas are described in
multiScaleR-kernels.
Usage
kernel_dist(model, prob = 0.9, dimension = c("2d", "1d"), ...)
Arguments
model |
A fitted |
prob |
Numeric between 0 and 1 (exclusive). Proportion of the kernel
weight that the reported distance must hold. Default: |
dimension |
Character. How the distance is measured. |
... |
Kernel parameters used when
|
Value
When model is supplied, a data frame with one row per optimized covariate
(row names are the covariate names) and three columns, all in map units and
rounded to two decimal places:
-
Mean: the effective distance at the estimated sigma. -
2.5%: the distance at the lower 95% limit of sigma. -
97.5%: the distance at the upper 95% limit of sigma.
For a hard-radius covariate (a landscape metric, an unweighted surface
metric, or any covariate fitted with kernel = "fixed"), the row reports
the radius itself under either dimension. Limits are NA when no
interval is available (see Details). A covariate whose sigma estimate is
not finite returns NaN.
When kernel parameters are supplied through ..., a single numeric value,
the distance in map units that holds prob of the kernel weight under
the chosen dimension, rounded to two decimal places.
Read the distances
Sigma is a kernel parameter, not a radius. An effective distance puts the
estimate in map units you can compare across kernels and studies. With
sigma = 300 m, a Gaussian kernel holds 90% of its planar weight within
about 644 m (dimension = "2d"), while the line-based 90% distance is about
493 m (dimension = "1d"). Use "2d" when you describe the area a kernel
draws on, and always state the definition and the value of prob you
report. The formulas for each kernel are tabulated in
multiScaleR-kernels.
Both definitions describe the ideal continuous kernel. They do not account
for truncation at max_D, raster edges, missing cells, or cell geometry,
so the share of weight among the cells actually extracted around a point
can differ. If the "2d" radius approaches or exceeds max_D, increase
max_D in kernel_prep() and refit the model.
Reproduce distances from earlier versions
Versions 0.7.4 and later report dimension = "2d" distances by default in
kernel_dist(), summary(), print(), and kernel plots. Earlier versions
reported the line-based distance. The switch changes reporting only. It
does not change fitted sigma values, kernel weights, or likelihoods. To
reproduce distances reported by earlier versions, set the dimension
explicitly:
kernel_dist(fit, dimension = "1d") summary(fit, dimension = "1d") print(fit, dimension = "1d") plot(fit, dimension = "1d") plot_kernel(sigma = 300, kernel = "gaussian", dimension = "1d")
Simulation extents in sim_dat(), the pct_wt window in
kernel_scale.raster(), and the max_D warning of multiScale_optim()
keep their line-based definitions.
Confidence limits from a fitted model
Each limit of sigma is converted to a distance with the same formula as the
estimate. By default the sigma limits are Wald limits from the
Hessian-based standard errors. When the fitted object stores its own
interval table in profile_scale_est (see the
fitted-object help page), those
limits are used instead. summary(fit, profile = TRUE) converts
profile-likelihood limits to distances in its own output, as described in
summary.multiScaleR(). For exponential-power kernels, the shape is held
at its estimate during this conversion, so the limits do not include
uncertainty in the shape. These rules depend on the fitting route:
With
backend = "profile_glm"or"joint_nb2"and an estimated exponential-power shape, distance limits use joint log-scale delta-method uncertainty for both sigma and shape. They remain Wald limits even when sigma limits are profiled insummary(), and they are missing when the fit fails the joint identifiability checks. Point distances remain available.With
backend = "conditional_logit", point distances are available but scale uncertainty has not been calibrated, so distance limits are missing.With the default refit backend, point distances remain available when a sigma standard error is not finite, but its Wald limits are missing. When a smooth parameter sits at a search bound, the whole Wald block is withheld, while explicitly marked profile limits remain available.
A hard-radius covariate reports its radius directly and has no kernel shape, including in an exponential-power fit. It has no Hessian-based interval, but stored profile limits are kept. See the section on smooth kernels and hard radii in multiScaleR-kernels.
Native coefficient standard errors remain conditional on the selected
scales. Manually supplied fixed-kernel parameters still return the
requested weight quantile under the chosen dimension.
See Also
multiScaleR-kernels for the kernel formulas and both distance
definitions. summary.multiScaleR(), plot.multiScaleR(), and
plot_kernel() report and draw the same distances. vignette("v02-user-guide", package = "multiScaleR")
converts sigma to effective distances on a worked example.
Examples
## Distances from kernel parameters, without a fitted model
# A Gaussian kernel with sigma = 300 m: planar radius holding 90% of the weight
kernel_dist(sigma = 300, kernel = "gaussian") # about 644
# The original line-based definition gives a shorter distance
kernel_dist(sigma = 300, kernel = "gaussian", dimension = "1d") # about 493
# Other kernels and proportions
kernel_dist(sigma = 500, kernel = "gaussian", prob = 0.95)
kernel_dist(sigma = 100, kernel = "exp", prob = 0.975)
kernel_dist(sigma = 100, kernel = "expow", shape = 1.5, prob = 0.95)
kernel_dist(sigma = 100, kernel = "fixed") # radius holding 90% of the buffer area
## Distances from a fitted model
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,
kernel = "gaussian",
verbose = FALSE)
mod <- glm(y ~ hab, family = poisson, data = count_data)
opt <- multiScale_optim(fitted_mod = mod,
kernel_inputs = kernel_inputs,
verbose = FALSE)
# Planar radius (m) holding 90% of the weight, with limits from the
# 95% interval of sigma
kernel_dist(model = opt)
# Line-based distances, as reported before version 0.7.4
kernel_dist(model = opt, dimension = "1d")
# Radius holding 95% of the weight
kernel_dist(model = opt, prob = 0.95)
Prepare Kernel Inputs for Scale Optimization
Description
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 |
raster_stack |
A |
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 |
kernel |
Character. Distance-weighting function used for every
covariate: |
scale_vars |
Optional covariate specifications created with
|
sigma |
Optional numeric vector of starting sigma values, in map
units, one per covariate whose scale is estimated (one per raster layer
when |
shape |
Optional numeric vector of starting shape values for
|
projected |
Logical. Whether |
progress |
Logical. Show progress bars during extraction and weighting.
Default: |
verbose |
Logical. Print status messages. Default: |
bin |
Logical. If |
nbins |
Integer, at least 2. Number of equal-width distance bins when
|
store_cell_data |
Logical. If |
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
# Standardized kernel-weighted habitat at the starting sigma (125 m)
head(kernel_inputs$kernel_dat)
# 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
Prepare Kernel Inputs from Group-Specific Rasters
Description
Assign each observation to one raster map, then prepare one pooled data
object for multiScale_optim. Use this when land cover changes
across years but the model estimates shared landscape effects and scales.
Usage
kernel_prep_by_group(
pts,
raster_stacks,
group,
max_D,
kernel = c("gaussian", "exp", "expow", "fixed"),
scale_vars = NULL,
sigma = NULL,
shape = NULL,
bin = TRUE,
nbins = 256L,
store_cell_data = TRUE,
progress = FALSE,
verbose = TRUE
)
Arguments
pts |
Projected point locations as an |
raster_stacks |
Named list of |
group |
Character or factor vector, one value per point, identifying
the corresponding name in |
max_D |
Positive numeric scalar. Maximum extraction radius, in the
projected map units, and the upper bound of the sigma search. See the
section on choosing |
kernel |
Kernel weighting function: |
scale_vars |
Optional |
sigma |
Optional starting scales in map units. Defaults to
|
shape |
Optional starting shapes for the exponential power kernel. Defaults to 2 for each optimized covariate. |
bin |
Logical. Build pooled distance bins for kernel covariates.
Default: |
nbins |
Number of distance bins when |
store_cell_data |
Logical. Retain per-cell values and distances. Default:
|
progress |
Logical. Display extraction progress. Default |
verbose |
Logical. Print preparation messages. Default |
Details
Raster maps must be aligned because landscape configuration metrics use cell adjacency and the resulting model assumes common map units. Group-specific maps may contain different missing cells. For kernel covariates, pooled bins track both finite-cell value sums and counts. The fitted model has common slopes and scales unless its formula explicitly includes group interactions. Choose the response likelihood and any group effect according to the sampling design. A pooled model does not establish that effects are stable across years.
Value
A multiScaleR_data list with the same structure as the
output of kernel_prep() (see multiScaleR_data), plus
raster_group. It contains:
kernel_datInitial covariate data frame, with one row per point. Columns are centered and divided by their pooled standard deviations. Use this in the starting model.
d_list,raw_covNamed per-point distance vectors (divided by
unit_conv) and raster-value matrices. Both areNULLin lean mode.binnedPooled distance-bin summaries for kernel covariates, or
NULLwhenbin = FALSE. Each covariate has finite-value sums and counts by point and distance bin.cell_sizeFixed x/y cell dimensions in map units, shared by every map. CV derives its intersecting-cell center envelope from this declared geometry, independently of assessment data.
raster_groupNamed character vector recording the map assigned to each point, in input order.
scl_paramsPooled means and standard deviations used to create
kernel_dat; the fitted model replaces these with scaling parameters at the optimized scales.kernel,sigma,shapeKernel name, initial scales divided by
unit_conv, and optional initial shape values.min_D,max_D,unit_convLower scale bound, maximum extraction radius, and internal distance scaling factor. These are in map units except the internally scaled
sigma.n_covs,scale_varsNumber of optimized covariates and the validated covariate definitions.
resolution,n_colsRaster cell size and column count, used to calculate landscape configuration metrics.
cell_data_storedWhether per-cell values and distances are retained.
Pass the full object to multiScale_optim.
See Also
kernel_prep, multiScale_optim,
multiScaleR_data.
vignette("v06-year-specific-rasters", package = "multiScaleR") fits
one pooled model to observations from two annual maps.
Examples
library(terra)
r1 <- rast(nrows = 20, ncols = 20, xmin = 0, xmax = 200,
ymin = 0, ymax = 200, crs = "EPSG:26915")
values(r1) <- seq_len(ncell(r1)) / ncell(r1)
names(r1) <- "habitat"
r2 <- r1
r2[seq_len(30)] <- 0
pts <- vect(cbind(c(50, 70, 90, 110, 130, 150),
c(60, 90, 120, 140, 100, 70)),
type = "points", crs = crs(r1))
prep <- kernel_prep_by_group(pts, list(y1 = r1, y2 = r2),
group = rep(c("y1", "y2"), 3),
max_D = 25, verbose = FALSE)
# Standardized habitat covariate, pooled across both maps
head(prep$kernel_dat)
# The map assigned to each point
prep$raster_group
Apply Kernels to Raster Layers for Mapping
Description
Computes the model covariates (kernel-weighted means, or
declared landscape or surface metrics) for every cell of one or more raster
layers, at the scales estimated by multiScale_optim() or at scales you
supply. The result is a stack of covariate layers that a fitted model can
predict from, so this is the usual first step in mapping a fitted model.
vignette("v03-map-predictions", package = "multiScaleR") works through
projection, extrapolation checks, and clamping.
Usage
kernel_scale.raster(
raster_stack,
sigma = NULL,
multiScaleR = NULL,
shape = NULL,
kernel = c("gaussian", "exp", "expow", "fixed"),
scale_vars = NULL,
pct_wt = 0.975,
fft = TRUE,
scale_center = FALSE,
clamp = FALSE,
pct_mx = 0,
na.rm = TRUE,
verbose = TRUE,
offset_values = NULL,
include_fixed = FALSE,
match_buffer = FALSE,
site_values = NULL,
...
)
Arguments
raster_stack |
A |
sigma |
Numeric vector of kernel scale parameters (or hard radii), in
map units. Supply one value per optimized covariate in declaration order
when |
multiScaleR |
A fitted |
shape |
Numeric vector of shape parameters for the exponential power
kernel ( |
kernel |
Character. Kernel used for smoothing: |
scale_vars |
Optional covariate specifications from |
pct_wt |
Numeric between 0 and 1 (exclusive). Sets the size of the
default smoothing window for kernel means and kernel-weighted surface
metrics. The window extends to the line-based (1D) distance that holds
|
fft |
Logical. If |
scale_center |
Logical. If |
clamp |
Logical. If |
pct_mx |
Numeric greater than -0.5 and no larger than 0.99. When
|
na.rm |
Logical. If |
verbose |
Logical. Print a progress message for each layer. Default:
|
offset_values |
Named numeric vector of raw input values for variables
inside model offsets, such as |
include_fixed |
Logical. Set |
match_buffer |
Logical. With the default |
site_values |
Optional named list of scalar values for nonspatial
predictors, in their native units, for example
|
... |
Reserved for deprecated arguments. Only |
Value
A SpatRaster on the grid of raster_stack, with one layer per
covariate (as declared in scale_vars or stored in multiScaleR), or one
per raster layer when you supply sigma without scale_vars. Layers are
named as in the model. Read the values as follows:
-
Covariate layers. With
scale_center = FALSE, values are in the covariate's own units. A kernel-weighted mean is in the units of the source layer, and a metric in the units given inmsr_vars(). Withscale_center = TRUE, values are in standard deviations of the fitting data, so 0 is the average survey point. -
Site-level layers. With a fitted object, predictors not derived from rasters (for example survey effort) are added as constant layers, at 0 unless set by
site_values, so that the stack works withterra::predict(). These do not represent spatial variation. -
Offset layers. Variables inside offsets are added under their input names, at the values described for
offset_values.
With a fitted object, the returned R object also carries a
"multiScaleR_projection" attribute that records how the layers were
made. predict.multiScaleR() checks it before raster prediction. Raster
files written to disk do not store this attribute.
Choose where the scales come from
-
A fitted model (
multiScaleR = fit) is the usual choice for mapping. Each covariate is smoothed at its estimated sigma or radius with the fitted kernel. -
A prepared object (
multiScaleR = kernel_inputs) uses the starting scales ofkernel_prep(). Use it to check how a preparation maps before fitting. -
Your own values (
sigma,kernel, andshape, with optionalscale_vars) let you explore smoothing at any scale without a model.
Set the smoothing window
By default (match_buffer = FALSE), each kernel mean and kernel-weighted
surface metric uses a square window that extends to the line-based
distance holding pct_wt of the kernel weight. For a Gaussian kernel and
the default pct_wt = 0.975, that is about 2.24 sigma. Hard-radius metrics
use the cells whose centers lie within their radius. This window need not
include the same cells that kernel_prep() used at the survey points,
which were every cell intersecting a circle of radius max_D, including
partly covered boundary cells.
With match_buffer = TRUE, kernel means and kernel-weighted surface
metrics use that preparation footprint instead. The same projected
sf::st_buffer() circle and polygon-intersection cell selection are
applied around each raster cell center. Partly covered boundary cells get
their usual full-cell kernel weights, as in fitting, rather than
coverage-fraction weights. Weighted SQ remains a weighted population spread
(zero for constant values), and a hard-radius SQ remains a sample standard
deviation. Requirements and limits:
Supply a fitted or prepared object, a raster with a projected (not longitude and latitude) CRS, square cells at the prepared resolution, and
na.rm = TRUE. Use the intended source layers in matching map units.Both smoothing engines support matching. Direct focal calculation (
fft = FALSE) can be much slower with a largemax_D, so check the cost on a small area first.A metric radius larger than the prepared
max_Draises an error, because its truncated footprint cannot be reproduced by capping the radius. Prepare again with an adequatemax_Dbefore fitting such a model.Matching aligns the footprint at raster cell centers. It does not undo distance binning, reconstruct missing CRS metadata, replace missing source coverage, or remove the difference between a sampled point and a cell center.
Choose a smoothing engine
FFT and direct focal calculations evaluate the same neighborhood with the
same finite-cell normalization, so they agree up to small floating-point
differences. Weighted means renormalize over the available mapped cells,
including at raster edges. Cells that are missing in the source layer stay
missing in the output, so smoothing never fills unmapped locations. With
na.rm = FALSE, incomplete windows, including those that extend beyond the
map, return NA. Weighted SQ over constant values returns zero, while the
standardized higher moments stay undefined when the spread is zero. Use
fft = FALSE mainly to confirm a result, because it can be much slower.
Standardize and clamp for prediction
By default, multiScale_optim() fits the model to centered and scaled
covariates, so set scale_center = TRUE before predicting from the fitted
model. The scaling uses the means and standard deviations stored in the
supplied object (for a fitted model, those at the estimated scales). Map
cells can take covariate values outside the range seen at the survey
points. clamp = TRUE holds such values at the surveyed limits, and
pct_mx moves those limits in or out.
vignette("v03-map-predictions", package = "multiScaleR") shows how to
find extrapolated cells and choose a setting.
Fill site-level predictors and offsets
With a fitted object, the function finds predictors that no raster layer
supplies, such as survey effort or a habitat type recorded in the field.
They cannot be mapped, so they are added as constant layers. A numeric
predictor defaults to zero, which is its mean when it was centered and
scaled. Set site_values for any other scenario. Categorical predictors
are skipped with a warning unless you supply a fitted level, and their
raster category labels keep the fitted levels. Checked prediction also
restores logical types. Native unmarked models require explicit
nonspatial prediction scenarios. When every predictor comes from a raster,
no constant layers are added. You can also supply remaining variables
through native prediction data or terra::predict(..., const = scenario).
Offset terms use their underlying input variables as layer names. For
offset(log(n_weeks)), the default layer is n_weeks = 1, one week of
effort. Set offset_values = c(n_weeks = 4) to predict for four weeks.
Direct offsets default to zero. Compound offsets, such as
offset(log(effort * duration)), need explicit raw values for each input.
Literal constant offsets need no layer. Ambiguous or conflicting default
scenarios raise an error.
Include verified fixed-radius metrics
A fitted model can contain fixed-radius metrics whose scaling parameters
are kept only in its original preparation. Set include_fixed = TRUE with
scale_center = TRUE to standardize them with that preparation. The
function first checks that the original fixed transforms and training
normalization reproduce the native model covariates exactly. Changed
definitions or training inputs raise an error. The check needs:
The retained training buffers, matching fixed metric definitions, and a raster at the fitted resolution.
A recoverable training frame (for
glm()andcoxph(), fit withmodel = TRUE), with the fixed predictors retained under their original names and row IDs matching the prepared sites.A fixed radius no larger than the fitted
max_D.
Transformations that do not retain a fixed predictor under its original
name are not reconstructed. This option does not alter your fitted
object, the metric definitions, or the interpretation of native
uncertainty. prepare_unmarked_data() describes the same verification for
unmarked models.
Predict from the result
Pass the returned stack to predict.multiScaleR(), which checks the
projection settings, or to terra::predict() with the fitted model
(fit$opt_mod). For a conditional-logistic step-selection model, native
type = "risk" with reference = "zero" gives a relative selection
score, not a choice or occurrence probability. Supply required stratum
variables through const. See multiScaleR-prediction.
See Also
multiScaleR-kernels, msr_vars(), predict.multiScaleR(),
multiScaleR-prediction.
vignette("v03-map-predictions", package = "multiScaleR") maps a fitted
model, and vignette("v04-landscape-metrics", package = "multiScaleR")
and vignette("v05-surface-metrics", package = "multiScaleR") map
metrics.
Examples
## Smooth a raster at a chosen sigma, without a fitted model
hab <- terra::rast(system.file("extdata", "hab.tif",
package = "multiScaleR"))
hab_100 <- kernel_scale.raster(hab, sigma = 100, kernel = "gaussian",
verbose = FALSE)
# Each cell now holds the kernel-weighted proportion of habitat around it
plot(c(hab, hab_100))
## Map a fitted model
# A fit stored with the package (the Quick Start model of counts on
# land1 and land2, with a site-level covariate)
fit <- readRDS(system.file("extdata", "cache-quickstart.rds",
package = "multiScaleR"))$opt
land <- terra::rast(system.file("extdata", "landscape.tif",
package = "multiScaleR"))
# Smooth each layer at its estimated sigma, standardize it as in fitting,
# and clamp it to the range seen at the survey points
r_scaled <- kernel_scale.raster(land, multiScaleR = fit,
scale_center = TRUE, clamp = TRUE,
verbose = FALSE)
# land1 and land2 in standard deviation units, plus a constant layer
# (0, the mean) for the site-level covariate
names(r_scaled)
# Expected count in every cell
pred <- terra::predict(r_scaled, fit$opt_mod, type = "response")
plot(pred)
## Use the preparation footprint of kernel_prep()
# match_buffer needs a projected CRS in meters. The bundled raster has
# none, so assign one for this example.
terra::crs(land) <- "EPSG:32617"
r_matched <- kernel_scale.raster(land, multiScaleR = fit,
scale_center = TRUE, clamp = TRUE,
match_buffer = TRUE, verbose = FALSE)
# Change in standardized land1 (standard deviation units) from using the
# wider preparation footprint instead of the pct_wt window
summary(abs(terra::values(r_matched$land1) -
terra::values(r_scaled$land1))[, 1])
Example landscape raster
Description
Three simulated landscape layers stored as landscape.tif in the
package's extdata folder, used with surv_pts and landscape_counts in
the vignettes.
Format
A SpatRaster with three layers of 200 by 200 cells of 20 map
units (an extent of 0 to 4000 in each direction) and no coordinate
reference system. Values range from 0 to 1:
-
land1: binary surface with low spatial autocorrelation. -
land2: continuous surface with low spatial autocorrelation. -
land3: continuous surface with high spatial autocorrelation.
Source
Simulated for this package.
See Also
Examples
land <- terra::rast(system.file("extdata", "landscape.tif",
package = "multiScaleR"))
land
terra::plot(land)
Simulated counts for the vignette example
Description
Simulated counts at the 100 points in surv_pts, used as the running
example in the vignettes with the landscape.tif raster.
Usage
data(landscape_counts)
Format
A data frame with 100 rows, one per point in surv_pts, and 2 columns:
-
counts: integer count at each point. -
site: a habitat variable measured at the point itself, which has no scale of effect.
Details
Counts were simulated from a Poisson distribution with an
intercept of 0.25 and log-scale coefficients of -0.5 for land1, 0.3 for
site, and 0.7 for land2. The true Gaussian scales of effect (sigma) are
250 map units for land1 and 500 for land2. The land1 and land2
covariates are not stored here; build them from landscape with
kernel_prep().
Source
Simulated for this package.
See Also
surv_pts, landscape,
vignette("v01-quickstart", package = "multiScaleR").
Examples
data(landscape_counts)
summary(landscape_counts)
Create an Audited Refit Function for Distance-Removal Models
Description
Build a refit function for multiScale_optim(refit_fn = ...) that refits
an unmarked distance-removal (GDR) model at each candidate scale of effect
from its original estimates and from extra starting values you declare. It
keeps the best clean fit and writes a record of every attempt to an audit
directory. A distance-removal likelihood can have more than one local
optimum, and several starts make it less likely that a poor optimum is
accepted unnoticed.
Usage
make_gdr_refitter(
model,
cold_starts,
audit_dir,
provenance = list(),
tmb_settings = NULL
)
Arguments
model |
The starting model. One of:
The refit function is tied to this model. It reuses the model's data,
formulas, cutoff |
cold_starts |
Named list of one or more extra starting vectors on the
link scales of the model, for example |
audit_dir |
Character string naming the directory for audit records. It must be new or empty, and it is created if needed. (For a field model, an existing directory with records is also accepted.) Keep it, because the records are the only trace of failed attempts. See "Read the audit directory". |
provenance |
Optional named list of your own identifiers, such as a data source, a script version or an archive DOI. Use simple values: atomic vectors of at most 64 elements, or nested lists of them, with at most 64 KiB in total. It is copied into every record as supplied and is not checked. |
tmb_settings |
For a TMB-engine or field model, a named list of the
optimizer settings to use for every refit. Leave it
Optional elements:
For a field model, pass the identical list used in
|
Value
A function with arguments model, data and context, for the
refit_fn argument of multiScale_optim(). The optimizer calls it with
the starting model, a copy of its frame in which the kernel-weighted
covariates have new values, and a context whose covs element names
those columns. Each call returns one fitted model of the same class as
model, with an attribute msr_gdr_refit_audit that summarizes the call:
-
status:"returned"for a successful call. -
attempts: one record per start ("original", each cold start, and"final"), each with thestart,converged, thelogLik,coefficientson the link scale,warnings, anyerror, thecovariancestatus, whether it waseligible, and the optimizer output (par,value,counts,convergence,message). TMB attempts addmarginal_score(largest absolute gradient, its 0.001 threshold and whether it passed) andoptimizer_point_file. -
selected: the index of the start with the highest log-likelihood. -
objective_only:TRUEwhen the call skipped the final refit. -
contract_sha256andinput_context_sha256: fingerprints that tie the call tocontract.rdsand to the inputs it received.pathis the summary record.
A field model returns the record described in fit_gdr_response_field()
instead. A failed call stops with an error of class
msr_gdr_refit_error, whose audit and audit_file elements hold the
record and its path.
How each refit works
At every call the function fits the model from its original estimates
(the start named "original") and from each cold start, then keeps the
start with the highest finite log-likelihood. That start must be eligible:
converged (code 0) with no warnings and, for TMB models, usable covariance
and a largest absolute gradient below 0.001. If it is not eligible, the
call fails rather than returning a lower-likelihood fit in its place.
When multiScale_optim() needs the fitted model rather than only its
likelihood, a final fit starts from the selected coefficients with the
original standard-error request. It must also be eligible and may lose no
more than 1e-5 log-likelihood units. C-engine intermediate fits skip
coefficient Hessians, which saves time.
Only the columns named in context$covs may change between calls, and
only static site covariates qualify. A covariate whose name also appears in
the yearly or observation covariates is rejected, so give it a distinct
name.
Changes to the counts, the other covariates, the survey protocol or the
row order stop the call.
Each TMB attempt builds a new TMB objective and starts its random effects
at zero. It always runs TMB::sdreport(), even with se = FALSE, so TMB
refits are not faster without standard errors. Usable covariance requires
a positive-definite Hessian, fixed covariance and joint precision. The
random effects must sit at a mode with positive-definite curvature and a
largest gradient and Newton decrement below 0.001. The objective,
recomputed at the optimizer's coordinates, must also agree with the
reported value within 1e-7. These are local checks. They
do not show that the mode is unique or that TMB's Laplace approximation is
accurate.
Declare TMB settings
A C-engine fit keeps the optimizer settings it used, so they are read
automatically. A TMB fit in unmarked 1.5.2 does not keep them, and its
constructor does not pass optimizer controls through. Declare them in
tmb_settings instead. The refit function passes them to optim()
directly, without changing unmarked. A typical list is:
list(method = "BFGS", se = TRUE, threads = 1L,
control = list(maxit = 2500L, reltol = 1e-10))
random.start and inner.control change how TMB searches for the random
effects. A different setting can reach a different numerical solution, so
treat a change as a new analysis and check its results. No setting is
changed automatically after a failure. With record_memory = TRUE, each
phase record stores the resident memory of the whole R process and its
lifetime peak, in bytes. These numbers include everything else loaded in
the session, so they are not the memory used by one phase.
Read the audit directory
| File | Written | Contents |
contract.rds | When the refit function is created | Fingerprints of the original data and design, the settings, the starts, the original coefficients and optimizer summary, and the identity of unmarked, TMB and multiScaleR, with a SHA-256 of the whole contract |
refit-*-request.rds | At the start of each call | The call's opening record |
refit-*-input.rds | After the inputs pass their checks | Fingerprints of the new data and the changed columns |
refit-*-attempt-*-request.rds | Before each start enters unmarked | The start and its name |
refit-*-attempt-*-point.rds | TMB only, after optimization and before covariance | The optimizer result |
refit-*-attempt-*.rds | After each start | The completed attempt record |
refit-*.rds | At the end of each call | The summary, also attached to the returned model |
A request without a matching completed record documents an attempt that never finished, for example after an interruption. Keep it. Records contain numbers, settings and SHA-256 fingerprints. They contain no raw data, design matrices, Hessians or fitted models, so they stay small.
The optimizer point file (class msr_gdr_optimizer_point) is written
before the covariance step, so a later covariance failure still leaves
evidence that the optimization finished. It holds the optimizer's par,
value, counts, convergence and message, the coordinate labels, data
and layout fingerprints, the cutoff K, the declared settings and the
elapsed time of each phase. It is always marked
inference_eligible = FALSE. It is not a fitted model, it gives no
standard errors, and a fit cannot be resumed from it.
At each call the refit function also confirms that unmarked, TMB and
this function's own code have not changed since it was created. A change,
including a different installation in a new worker process, stops the call
before fitting.
Refit a response field
For a model from fit_gdr_response_field(), each call refits the field
with all of that function's checks, with the range held fixed. Use the
same cold_starts and the identical tmb_settings, and run
multiScale_optim() with n_cores = 1. The ordinary update() method
stops for field models, so this refit function is the way to refit one.
What the checks do not establish
Coefficient standard errors from the returned model treat the selected scales of effect as known. The function adds no priors, bootstrap intervals or kernel-scale uncertainty. Agreement among the declared starts does not guarantee that a better optimum does not exist elsewhere.
The cutoff K (the largest abundance the likelihood considers at a point)
is unrelated to the K column of aic_tab(), which counts parameters.
Reusing one cutoff does not replace a check that results are insensitive to
it.
See the "Refit from several starting values" section of
vignette("v12-distance-removal", package = "multiScaleR") for a worked
example.
See Also
multiScale_optim(), gdr_start_values(),
fit_gdr_response_field(), validate_unmarked_data(), aic_tab()
Examples
if (as.character(utils::packageVersion("unmarked")) == "1.5.2") {
# Five point counts: birds by distance band and by time interval
yd <- rbind(c(0, 0), c(1, 0), c(0, 2), c(2, 1), c(0, 0))
yr <- rbind(c(0, 0, 0), c(0, 1, 0), c(1, 0, 1), c(1, 1, 1), c(0, 0, 0))
frame <- unmarked::unmarkedFrameGDR(yd, yr, dist.breaks = c(0, 25, 75),
unitsIn = "m", period.lengths = c(1, 2, 1),
siteCovs = data.frame(hab = seq(-1, 1, length.out = 5)))
# Fit the starting model (C engine) before declaring extra starts
model <- unmarked::gdistremoval(lambdaformula = ~hab, data = frame,
output = "abund", K = 40, se = FALSE, engine = "C",
starts = c(log(8), 0, log(40), qlogis(0.3)), control = list(maxit = 2000))
# One extra start, named like the model coefficients (link scales)
cold <- unmarked::coef(model)
cold[] <- 0
cold["dist(Int)"] <- log(30)
audit_dir <- tempfile("msr-gdr-audit-")
refit <- make_gdr_refitter(model, list(cold = cold), audit_dir = audit_dir)
# multiScale_optim() calls refit() at each candidate scale. Calling it
# once here, on the original data, shows what each call records.
fit <- refit(model, frame, context = list(covs = "hab"))
audit <- attr(fit, "msr_gdr_refit_audit")
# Log-likelihood and eligibility of each start, then the selected start
print(sapply(audit$attempts, function(a)
c(logLik = a$logLik, eligible = a$eligible)))
print(audit$attempts[[audit$selected]]$name)
# contract.rds, plus request, input, attempt and summary records
print(list.files(audit_dir))
}
Define Model Covariates from Raster Layers
Description
These helpers declare how each model covariate is computed from a source
raster layer, and whether its scale is estimated or fixed. Use
kernel_var() for a kernel-weighted mean, landscape_var() for a landscape
metric of a categorical raster, and surface_var() for a texture metric of
a continuous raster. Collect the specifications with msr_vars() and pass
the result to the scale_vars argument of kernel_prep() and
kernel_scale.raster().
The helpers are optional. Without scale_vars, kernel_prep() turns each
raster layer into one kernel-weighted mean covariate with the layer's name.
Usage
msr_vars(...)
kernel_var(source)
landscape_var(
source,
metric,
radius = NULL,
base = exp(1),
classes_max = NULL,
class = NULL
)
surface_var(source, metric, radius = NULL, weighted = FALSE)
## S3 method for class 'multiScaleR_vars'
print(x, ...)
Arguments
... |
For |
source |
Character scalar. Name of the source layer in the
|
metric |
Character scalar. Code of the metric to compute within the
buffer, matched case-insensitively. |
radius |
Optional positive numeric scalar. Buffer radius in map units.
With the default |
base |
Positive numeric scalar, not equal to 1. Base of the logarithm
used by Shannon diversity ( |
classes_max |
Positive numeric scalar. Number of classes that could
occur in the landscape. Required for relative patch richness ( |
class |
Optional integer-like scalar. The focal class code for the
class-level metrics ( |
weighted |
Logical, for |
x |
A |
Value
msr_vars() returns a data frame of class
c("multiScaleR_vars", "data.frame") with one row per covariate and these
columns:
-
covariate: the name given in.... -
source: the source raster layer. -
type:"kernel","landscape", or"surface". -
metric: the metric code, orNAfor a kernel mean. -
radius: the fixed radius in map units, orNAwhen the scale is estimated. -
optimize:TRUEwhen the scale is estimated with the model. -
weighted:TRUEfor a kernel-weighted surface metric. -
base: the logarithm base actually used. -
classes_max: the denominator of"rpr", orNA. -
class: the focal class of a class-level metric, orNA.
kernel_var(), landscape_var(), and surface_var() each return a list of
class "multiScaleR_var" holding one specification. Pass it to
msr_vars(). It has no use on its own.
print() displays the specification table and returns x invisibly.
Choose a covariate type
| Helper | Source raster | What it summarizes | Scale |
kernel_var() | Any numeric layer | Kernel-weighted mean of the cell values | Sigma, estimated, with a standard error |
landscape_var() | Categorical, with integer class codes | Composition, edges, aggregation, information theory, or one focal class | Hard radius, estimated without a standard error, or fixed |
surface_var() | Continuous, such as elevation or canopy height | Variation, distribution shape, slope, or relief | Hard radius (estimated or fixed), or sigma with weighted = TRUE
|
A kernel mean describes how much of something surrounds a point. Landscape and surface metrics describe how it is arranged or how much it varies, so they complement the mean rather than replace it. Note that for a metric, changing the radius changes both the spatial scale and the statistical quantity summarized. Landscape metrics require finite, integer-like class codes, and both metric types require square raster cells.
Whether a scale is a smooth kernel width or a hard radius decides how it can be estimated and reported. multiScaleR-kernels explains the difference, and why a hard radius has a stepped likelihood and no Hessian standard error.
Combine covariate types
One msr_vars() call can mix all three types, including several covariates
from the same source layer. For example, a kernel-weighted mean of forest
cover and a fixed-radius edge density of the same layer:
vars <- msr_vars(
forest_mean = kernel_var("forest"),
forest_ed500 = landscape_var("forest", metric = "ed", radius = 500)
)
kernel_inputs <- kernel_prep(pts, rasters, max_D = 1000,
scale_vars = vars)
A covariate with a fixed radius is computed once and is not re-evaluated
during optimization, which can save considerable time. Under
kernel = "expow", a hard-radius covariate does not use the kernel shape.
Its reported shape and shape standard error are NA, and its unused shape
position is left out of model-selection parameter counts.
Not every fitting route accepts every covariate type. Kernel means,
weighted "sq", and fixed-radius metrics work with every route, including
the analytic backends of multiScale_optim() and multiScale_bayes(),
within each route's kernel restrictions. Those routes need a Gaussian or
negative exponential kernel for weighted "sq". An estimated hard radius,
and any weighted metric other than "sq", needs the default refit
backend. See multiScaleR-fitting-methods and
vignette("v07-fitting-methods", package = "multiScaleR") for the full
feature table.
Landscape metric definitions
Each landscape metric summarizes the cells whose centers lie within the
radius. In the formulas, n is the number of valid (non-missing) cells,
n_i the number in class i, p_i = n_i / n, m the number of classes
present, res the cell size in map units, and A = n * res^2 / 10000 the
buffer area (hectares when map units are meters). g_ij counts pairs of
cells that share a side, have classes i and j, and both lie in the
buffer. Each pair is counted in both directions, and q_ij = g_ij / sum(g).
Logarithms use base where marked, and the natural log otherwise.
Composition (how many classes, and how evenly they share the buffer):
| Code | Name | Definition | Units or range |
shdi | Shannon diversity | -sum(p_i * log(p_i)), with base | Log units, 0 or more |
shei | Shannon evenness | shdi / log(m), with base. 0 when m = 1 | 0 to 1 |
sidi | Simpson diversity | 1 - sum(p_i^2) | 0 to 1 |
siei | Simpson evenness | sidi / (1 - 1 / m). NA when m = 1 | 0 to 1 |
msidi | Modified Simpson diversity | -log(sum(p_i^2)) | Natural log units, 0 or more |
msiei | Modified Simpson evenness | msidi / log(m). Undefined when m = 1 | 0 to 1 |
pr | Patch richness | m | Number of classes |
prd | Patch richness density | m / A * 100 | Classes per 100 ha |
rpr | Relative patch richness | m / classes_max * 100 | Percent |
ta | Total area | A | Hectares |
Edge (how much boundary separates different classes). Here E is the
number of cell sides shared by two buffer cells of different classes, and
B the number of cell sides on the buffer's outer boundary or next to a
missing cell:
| Code | Name | Definition | Units or range |
te | Total edge | E * res | Map units (meters) |
ed | Edge density | E * res / A | Meters per hectare |
lsi | Landscape shape index | (E + B) / Pmin(n), where Pmin(n) is the smallest possible perimeter, in cell sides, of n cells | Ratio, 1 or more |
Aggregation (whether cells of a class sit together or are mixed with other classes):
| Code | Name | Definition | Units or range |
pladj | Proportion of like adjacencies | sum(g_ii) / sum(g) * 100 | Percent |
ai | Aggregation index | sum(p_i * (g_ii / 2) / gmax_i) * 100, where gmax_i is the most like adjacencies n_i cells can have | Percent |
contag | Contagion | (1 + sum(q_ij * log(q_ij)) / (2 * log(m))) * 100. NA when m < 2 | 0 (interspersed) to 100 (one class) |
iji | Interspersion and juxtaposition | -sum(e * log(e)) / log(m * (m - 1) / 2) * 100, where e is each class pair's share of the adjacencies between different classes. NA when m < 3 or no such adjacencies exist | Near 0 (one pair dominates) to 100 (all pairs equally adjacent) |
Information theory (pattern complexity, split into composition and
configuration, following Nowosad and Stepinski 2019). With
q_i = sum_j(q_ij):
| Code | Name | Definition | Units or range |
ent | Marginal entropy, H(x) | -sum(q_i * log(q_i)), with base | Log units. Rises with the number and evenness of classes |
joinent | Joint entropy, H(x, y) | -sum(q_ij * log(q_ij)), with base | Log units. Total complexity of the pattern |
condent | Conditional entropy, H(y given x) | joinent - ent | Log units. Uncertainty about a neighbor's class given a cell's class |
mutinf | Mutual information, I(y, x) | ent - condent | Log units. How much a cell's class tells you about its neighbor's |
relmutinf | Relative mutual information | mutinf / ent, and 1 when mutinf = 0 | 0 to 1, unaffected by base
|
Both clumping and regular alternation make neighbors predictable and raise
mutinf. Its size also depends on ent, so it is not a
composition-free aggregation index. relmutinf rescales it so that
configuration can be compared across buffers with different composition.
Class level (one focal class k, set with class):
| Code | Name | Definition | Units or range |
pland | Percentage of landscape | n_k / n * 100. 0 when the class is absent | Percent |
ca | Class area | n_k * res^2 / 10000. 0 when the class is absent | Hectares |
clumpy | Clumpiness index | With G = g_kk / (4 * n_k - Pmin(n_k)) and P = n_k / n: (G - P) / (1 - P) when G >= P or P >= 0.5, otherwise (G - P) / P, the FRAGSTATS definition. NA when the class is absent or fills the buffer | Unitless, from -1 (maximally dispersed) through 0 (random) to 1 (maximally clumped). landscapemetrics 2.2.1 divides by -P in the second case, which reverses the sign of dispersed classes
|
Surface metric definitions
Each surface metric summarizes the values z of the n valid cells whose
centers lie within the radius. s is the sample standard deviation
("sq") and res the cell size in map units.
| Code | Name | Definition | Units |
sa | Average roughness | sum(abs(z - mean(z))) / n | Raster units |
sq | Root mean square roughness | sqrt(sum((z - mean(z))^2) / (n - 1)). NA when n < 2 | Raster units |
ssk | Skewness | sqrt(n * (n - 1)) / (n - 2) * (sum((z - mean(z))^3) / n) / s^3. NA when n < 3 or s = 0 | Unitless. Positive when a few high values stand out |
sku | Excess kurtosis | (sum((z - mean(z))^4) / n) / s^4 - 3. NA when s = 0 | Unitless. 0 for normally distributed values |
sdq | Root mean square slope | Square root of the mean of ((z - z_right)^2 + (z - z_below)^2) / res^2 over cells whose right and lower neighbors are both in the buffer | Raster units per map unit |
sdr | Surface area ratio | (sum(a) / (k * res^2) - 1) * 100, where a is the three-dimensional area of each of the k blocks of 2 x 2 cell centers in the buffer | Percent |
"sa", "sq", "ssk", and "sku" match the geodiv package. "sdq" is
a true slope (rise over run). geodiv::sdq() assumes a cell spacing of 1,
so it equals "sdq" multiplied by res. "sdr" uses the real values and
cell size, so a plane tilted at slope t returns
(sqrt(1 + t^2) - 1) * 100. geodiv::sdr() rescales the surface to a
unit range first, so its values differ. Read "sdq" and "sdr" as a slope
and an area ratio only when the raster values and the map share units, as
elevation in meters does.
Kernel-weighted surface metrics
With weighted = TRUE, each cell gets the kernel weight w = w(d) of its
distance d from the point (see multiScaleR-kernels), using the cells
extracted within max_D. With the weighted mean
mu = sum(w * z) / sum(w):
| Code | Weighted definition |
sa | sum(w * abs(z - mu)) / sum(w) |
sq | sqrt(sum(w * (z - mu)^2) / sum(w)), and 0 for constant values |
ssk | (sum(w * (z - mu)^3) / sum(w)) / sq^3. NA when sq = 0 |
sku | (sum(w * (z - mu)^4) / sum(w)) / sq^4 - 3. NA when sq = 0
|
Weighted "sq" divides by the sum of weights, so it is a population-style
spread and differs from the n - 1 form of the unweighted metric. The
weighted skewness and kurtosis use plain standardized moments, without the
small-sample adjustment of the unweighted "ssk". Weighted "sq" is
smooth in sigma except where the weighted spread is zero. Absolute
deviations ("sa") and the standardized higher moments have additional
points where they are not smooth or not defined. Within one evaluation,
weighted metrics reuse weights and centered moments only when their
source, scale, shape, and valid cells match exactly. Their scales are
still estimated separately. Under kernel = "fixed", the fitted scale is
a hard cutoff radius. It has no standard error or Wald limits, although
the weighted definitions above still apply.
Check a metric before you optimize it
Before estimating the radius of "iji", "siei", or "msiei", inspect a
pilot kernel_prep() result or a few fixed radii. These metrics can be
undefined or nearly constant when buffers hold too few classes, too few
adjacencies between different classes, or nearly identical evenness at
every point. "iji" in particular returns NA with fewer than three
classes, and small buffers can make it NA everywhere. If so, use a larger
radius, increase max_D, or choose a more stable diversity, entropy, or
edge metric. A candidate scale that leaves a covariate undefined at a
modeled observation is rejected during optimization, so every candidate is
compared on the same observations.
The adjacency and information-theory metrics accept a limited number of
classes, which guards against passing a continuous raster by mistake and
keeps raster projection times bounded. The limits are 200 classes for the
like-adjacency metrics ("ai", "pladj", "clumpy") and 50 for the
metrics built from the full class-pair table ("contag", "iji", and the
information-theory metrics), whose cost grows with the square of the class
count.
During optimization, the adjacency metrics reuse sorted cell and
neighbor-pair distances instead of rescanning every buffered cell at each
radius, and metrics on the same source and radius share their counts. This
saves time at the cost of retained memory, which
estimate_multiscale_ram() includes. It does not change radius boundaries
or metric definitions, and it does not make a hard radius smooth or remove
concerns about local optima.
Map a metric
kernel_scale.raster() computes the same covariates for every raster cell.
Projection of "sq", "ssk", "sku", "sdq", "sdr", and the landscape
metrics uses fast Fourier transform (FFT) convolution by default.
Unweighted "sa" uses an exact compiled moving-window pass instead,
because average roughness cannot be written as a convolution. "sdq" and
"sdr" use each cell's neighbors, so their projected values agree with
point extraction to within a small tolerance at the buffer boundary rather
than exactly. Set fft = FALSE in kernel_scale.raster() to use direct
moving-window calculations instead.
References
Nowosad, J., & Stepinski, T. F. (2019). Information theory as a consistent framework for quantification and classification of landscape patterns. Landscape Ecology, 34(9), 2091-2101. doi:10.1007/s10980-019-00830-x
See Also
kernel_prep(), multiScale_optim(), kernel_scale.raster(),
and multiScaleR-kernels. For worked examples, see
vignette("v04-landscape-metrics", package = "multiScaleR") for the
landscape metrics and
vignette("v05-surface-metrics", package = "multiScaleR") for the
surface metrics.
Examples
## Kernel-weighted mean only (the same as omitting scale_vars)
vars <- msr_vars(forest_prop = kernel_var("forest"))
vars
## Combine kernel, landscape, and surface covariates. The printed table
## shows which scales are estimated (optimize = TRUE) and which are fixed.
vars <- msr_vars(
forest_prop = kernel_var("forest"),
forest_ed = landscape_var("forest", metric = "ed"),
cover_shdi_500 = landscape_var("landcover", metric = "shdi", radius = 500),
elev_sd = surface_var("elevation", metric = "sq")
)
print(vars)
## Shannon diversity in bits within a fixed 250 m radius
landscape_var("landcover", metric = "shdi", radius = 250, base = 2)
## Interspersion of the whole buffer needs no focal class
landscape_var("landcover", metric = "iji", radius = 500)
## Class-level metrics need `class`, here clumpiness and cover of class 3
landscape_var("landcover", metric = "clumpy", radius = 500, class = 3)
landscape_var("landcover", metric = "pland", radius = 500, class = 3)
## Surface metrics with an estimated hard radius, a fixed radius, and
## kernel weights (sigma estimated)
surface_var("elevation", metric = "sq")
surface_var("ndvi", metric = "sa", radius = 300)
surface_var("elevation", metric = "sq", weighted = TRUE)
## Compute covariates at survey points from the bundled landscape
land <- terra::rast(system.file("extdata", "landscape.tif",
package = "multiScaleR"))
# land3 is continuous. Build a three-class layer from it
land$cover <- terra::classify(land$land3,
rbind(c(-Inf, 0.45, 1),
c(0.45, 0.55, 2),
c(0.55, Inf, 3)))
data("surv_pts")
vars <- msr_vars(
land1_prop = kernel_var("land1"),
cover_shdi = landscape_var("cover", metric = "shdi", radius = 400),
land3_rough = surface_var("land3", metric = "sq", radius = 300)
)
inputs <- kernel_prep(pts = terra::vect(surv_pts)[1:20, ],
raster_stack = land, max_D = 500,
scale_vars = vars, verbose = FALSE)
# Standardized covariates, one column per declared covariate
head(inputs$kernel_dat)
Fitted multiScaleR objects
Description
multiScale_optim() returns an object of class "multiScaleR", a list
that holds the estimated scales of effect, your model refit at those
scales, and the record of the search. This page describes every element
and the functions that read the object.
Elements
Every fit has these elements:
-
scale_est: data frame with one row per optimized covariate (row names are covariate names) and two columns.Meanis the estimated sigma in map units, andSEis its Hessian-based standard error.SEisNAfor hard-radius landscape and unweighted surface metrics and for every radius estimated underkernel = "fixed", because their likelihood changes in steps. -
shape_est: data frame with the same layout for the shape parameter whenkernel = "expow", otherwiseNULL. Hard-radius covariates haveNAshape and shape SE because a shape does not apply to them; their unused shape positions are left out of the likelihood parameter count. -
optim_results: the raw list returned bystats::optim()oroptimParallel::optimParallel(), includingpar,value(the negative log-likelihood),hessian, and convergence codes. It also holdspar_unscale(sigma values in map units) andhessian_unscale. For a radius grid, this list describes the selected combination: its Hessian covers only the smooth parameters at those fixed radii, withNAfor hard-radius rows and columns and any inactive shape. Seediagnostics(fit)$radius_profilefor every candidate. -
opt_mod: your model refit at the estimated scales. Use it for coefficients, inference, prediction, andplot_marginal_effects(). Its coefficients are on the model's link scale (for example log for a Poisson model), and by default each optimized covariate is standardized, so a coefficient describes the change in the linear predictor for one standard deviation of the covariate. -
fitted_mod_original: thefitted_modyou supplied, kept for reference. -
min_D,max_D: the lower and upper bounds for sigma during the search, in map units. -
kernel_inputs: thekernel_inputslist (see multiScaleR_data), withoutmin_Dandmax_D, which are stored separately. -
scl_params: named list withmeanandsdvectors, the centering and scaling values of each optimized covariate at the estimated scales.kernel_scale.raster()uses them whenscale_center = TRUEso that maps match the model's covariates. Withcovariate_transform = "raw", the centers are zero and the scales one; prediction never relearns these values from new data. -
join_by: thejoin_bydata frame, orNULL. -
opt_context: internal record of the model-class-specific refit logic, kept forprofile_sigma(). Withcovariate_transform = "raw"it also records that setting.NULLfor the analytic backends. -
profile_scale_est: data frame of profile-likelihood intervals, orNULLuntilprofile_sigma()has been run. -
diagnostics: list of diagnostic records; read it withdiagnostics(). -
next_run: list of suggested settings for a follow-up fit:max_Dfor the nextkernel_prep()call (raised when an estimate approaches the currentmax_D), the estimatedstart_sigmavalues in map units,start_shapeforkernel = "expow", andstart_par, the starts on the internal scale thatmultiScale_optim()expects, scaled to thatmax_D.n_coresisNULL; askestimate_multiscale_ram()for a parallel worker count.NULLfor some analytic backends. -
warn_message: integer vector of warning codes. It starts with0and adds1when an estimate approachesmax_D,2when a sigma standard error is at least half its estimate, and3when a shape standard error is at least half its estimate. See "Read the warnings" inmultiScale_optim(). -
call: the matched call.
Elements added by the analytic backends
-
profile_fit,uncertainty,dispersion_est: present for"profile_glm"and"joint_nb2". They keep the transformed parameter estimates, the starts and their convergence scores, the profile and joint information matrices, identifiability diagnostics, and NB2 theta.uncertainty$availablesays whether joint uncertainty passed its checks, anduncertainty$reasonssays why not.opt_modand its coefficient summary condition on the estimated kernel parameters. Usevcov.multiScaleR()andpredict.multiScaleR()for joint uncertainty. -
profile_fitanduncertaintyfor"conditional_logit", which keep the starts, every start outcome, and the selected start. Scale uncertainty is not available. -
mixed_fitfor"joint_mixed": the kernel engine, log-scale estimates and bounds in internal distance units, the independent starts, every start outcome and warning, the selected start, and the variables prediction needs.uncertainty$availableisFALSE, andnext_runandopt_contextareNULL.
multiScaleR-fitting-methods explains what each backend records and why uncertainty may be withheld.
Where each quantity lives
| Quantity | Where to find it | Scale |
| Scale of effect (sigma) | fit$scale_est$Mean, summary(fit) | Map units |
| Kernel shape | fit$shape_est$Mean | Shape units of the exponential power kernel |
| Effective distance | summary(fit), kernel_dist() | Map units |
| Regression coefficients | coef(fit$opt_mod), summary(fit) | Link scale, per standard deviation of each covariate by default |
| NB2 dispersion | fit$dispersion_est$theta (analytic backends) | Natural scale |
| Profile-likelihood intervals | fit$profile_scale_est, summary(fit, profile = TRUE) | Map units |
The effective distance converts sigma into the distance that contains a set proportion (by default 90 percent) of the kernel's total weight, which is usually the easiest number to report. See multiScaleR-kernels.
Functions that read the object
| Function | What it gives you |
print(), summary.multiScaleR() | Scales, effective distances, intervals, and coefficients |
plot.multiScaleR() | The fitted kernel weight curve for each covariate |
diagnostics() | Search, sample-size, and uncertainty diagnostics |
profile_sigma() | Profile-likelihood intervals for sigma |
predict.multiScaleR(), vcov.multiScaleR() | Predictions and covariance, with joint uncertainty where available |
kernel_scale.raster() | Maps of the covariates at the estimated scales |
plot_marginal_effects() | Effect curves for each covariate |
aic_tab(), bic_tab() | Model comparison by AIC or BIC |
cross_validate() | Out-of-sample prediction scores |
scale_inference() | Likelihood-range and bootstrap assessment of single-kernel NB2 scales |
See Also
multiScale_optim(), multiScaleR-fitting-methods,
multiScaleR-prediction, and
vignette("v01-quickstart", package = "multiScaleR").
Examples
data(pts)
data(count_data)
hab <- terra::rast(system.file("extdata", "hab.tif",
package = "multiScaleR"))
inputs <- kernel_prep(pts = pts, raster_stack = hab, max_D = 250,
kernel = "gaussian", verbose = FALSE)
mod <- glm(y ~ hab, family = poisson, data = count_data)
fit <- multiScale_optim(mod, inputs, verbose = FALSE)
names(fit)
fit$scale_est # sigma (Mean) and its SE, in map units
coef(fit$opt_mod) # coefficients on the log (link) scale
fit$warn_message # 0 plus a code for each warning raised
fit$next_run$max_D # max_D suggested for a follow-up fit
Fitting methods for estimating scales of effect
Description
multiScale_optim() estimates scales of effect through one of several
backends, chosen with its backend argument. A backend is the
computational route that searches over kernel scales and fits the model at
each candidate. Backends differ in the models they accept, the parameters
they estimate together, and the uncertainty they can report. This page
states the requirements and reporting rules of each backend. To choose a
backend for your model, start with
vignette("v07-fitting-methods", package = "multiScaleR"), which compares
them on one data set.
Compare the backends
backend | Models it fits | Estimated in one search | Uncertainty for the scales |
"refit" (default) | Any model that stats::update(), the unmarked equivalent, or a refit_fn can refit | Kernel scales and shapes. The model's own parameters are refit at every candidate | Hessian (Wald) standard errors for smooth kernels. Profile likelihood with summary(fit, profile = TRUE) |
"profile_glm" | Gaussian identity, Poisson log, and binomial logit glm() fits, and NB2 log-link fits | Kernel scales and NB2 theta. Coefficients are solved at every candidate | Joint Wald limits when the checks below pass |
"joint_nb2" | NB2 log-link fits, including the exact Poisson boundary | Kernel scales, coefficients, and dispersion | Joint Wald limits when the checks pass. None at the Poisson boundary |
"joint_mixed" | Poisson and NB2 glmmTMB fits with one random intercept | Kernel scales and all model parameters, with the random intercept integrated out | None. Coefficient uncertainty is conditional on the scales |
"conditional_logit" | Step-selection models from survival::clogit() or amt::fit_clogit() | Smooth kernel scales and conditional-logistic coefficients | None. Coefficient uncertainty is conditional on the scales |
A conditional standard error treats the estimated scales as known. A
joint standard error lets the scales and the coefficients vary together,
so it also carries uncertainty about the scales.
multiScale_bayes() is a separate route that samples or approximates a
posterior instead. See multiScaleR_bayes and the Bayesian vignettes.
The default refit backend
How the search works
The default backend uses the L-BFGS-B algorithm (a bounded quasi-Newton
search) to maximize the log-likelihood over sigma, and over shape for the
"expow" kernel. At each candidate scale it refits the model, so the
regression coefficients take their fitted values for that scale. Candidate
scales that leave a covariate undefined at a modeled observation are
rejected, so every candidate is compared on the same sample. The final
sample_size entry of diagnostics() reports the prepared and fitted row
counts. For unmarked data with repeated sites, it also reports the number
of distinct prepared spatial sites.
Standard errors and intervals
Standard errors are Hessian-based approximations from this outer search. A nonfinite, singular, or non-positive-definite Hessian gives missing standard errors and a retained diagnostic, and the raw Hessian is kept. So does a Hessian built partly from a failed refit: a refit that fails returns a large penalty, and a finite-difference point that lands on one gives an absurdly large curvature. This case also gives a warning, because it means the model is hard to refit near the estimate.
A smooth kernel or shape parameter within 1e-5 of a search bound, on the
log scale, invalidates the Wald approximation. Its standard errors and Wald
limits are withheld. The raw Hessian, the original curvature status, and a
table of parameter bounds stay in diagnostics(fit)$refit_hessian. A lower
bound of zero is flagged only when it is reached. This flag is numerical. It
does not establish that a scale is identified or give a calibrated interval.
Native coefficient covariance still conditions on the selected kernels, and
likelihoods and parameter counts are unchanged.
Hard-radius covariates (landscape metrics, unweighted surface metrics, and
every scale under kernel = "fixed") have a likelihood that changes in
steps as the radius grows. They receive no Hessian standard error or Wald
limit. Their raw Hessian rows remain for compatibility and diagnostics but
are not inverted. See multiScaleR-kernels.
Summary methods report profile-likelihood intervals for sigma once
profile_sigma() has been run on the fit, and Hessian-based intervals
otherwise. summary(fit, profile = TRUE) computes profile-likelihood
intervals directly.
Profile hard radii over a grid
The radius_grid argument is experimental, so its behavior may change in a
later release without a deprecation period. Supply it to the refit backend
for a likelihood profile over hard radii. At each combination of radii, the
model refits its coefficients and any native nuisance parameters on the same
observations. When Gaussian, exponential, or exponential-power kernels supply
smooth predictors, a bounded search starts afresh at each combination and
refits every smooth bandwidth and applicable shape. Use par to give the
first smooth start in the usual parameter layout.
The largest eligible native log-likelihood selects the combination. Exact
ties favor the smallest radii, in model predictor order. Inspect failed
combinations and likelihood plateaus in diagnostics(fit)$radius_profile.
Hard radii have no standard error or confidence interval. Smooth standard
errors and Wald limits, when available, condition on the selected radii.
The grid refits serially. It accepts ordinary lm(), glm(), and
MASS::glm.nb() fits, and complete one-case conditional-logistic models,
each with a retained model frame. Fixed predictors, including fixed-radius
metrics, can accompany the optimized predictors. Retain raw cells and
matching model row IDs, and omit join_by, custom refit functions, and start
screening. For step selection, supply one case and at least one available
alternative per stratum, with an unweighted, unpenalized native likelihood.
Analytic GLM backends
"profile_glm" and "joint_nb2" evaluate the likelihood and its derivatives
directly rather than refitting the model through update(). This makes
joint uncertainty possible.
Models and data they accept
Both need a smooth kernel (Gaussian, exponential, or exponential power) and
a glm or MASS::glm.nb object that retains its model frame. Fit a Gaussian
model with glm(family = gaussian()), because an lm() fit is rejected.
"profile_glm" supports the Gaussian identity, Poisson log, binomial logit,
and NB2 log links. NB2 has variance \mu + \mu^2/\theta, and theta is
estimated alongside the kernel parameters even when the starting GLM used a
fixed theta. "joint_nb2" requires an NB2 log-link model.
The retained model-frame rows define the fitting sample. Their row names must match unique prepared point IDs, so preserve them through any subsetting. Kernel means and standard deviations use only these rows, and no observations are dropped during the search.
A binomial response may be:
numeric
0/1or logicalFALSE/TRUE(Bernoulli observations);a two-level factor, with success in its second level;
-
cbind(successes, failures)with positive trial totals. Logical count columns stand for zero and one counts without changing the trial totals.
Response-scale predictions are success probabilities. Positive whole-number frequency weights are allowed for count and binomial models. Gaussian weights must all equal one. Proportion responses and precision weights are not supported.
Formula terms
Numeric kernel predictors may enter native R product, crossing, and nesting terms, including factor interactions and products of optimized predictors. The native terms and fitted contrast coding define the coefficient layout, and every kernel, coefficient, and cross derivative enters the joint uncertainty.
Scalar arithmetic on kernel values inside I(), and the base functions
exp, log, sqrt, sin, cos, and tan, keep their native coefficient
basis and analytic derivatives. Their inputs must be optimized kernel values
or literal constants, and a nonfinite result is an error.
Cubic splines::ns() and splines::bs() terms also work when you write out
literal fixed knots and two increasing Boundary.knots. All basis columns
share the ecological scale of their source, including in factor
interactions. Knots are in the units of the modeled predictor. The analytic
GLM, conditional-logistic, and joint mixed searches keep their
candidate-specific standardization and its derivatives, so fixed
standardized knots are not fixed thresholds of raw cover. Bayesian targets
keep their frozen reference transformation instead: with a fixed reference,
convert raw knots and boundaries with its center and SD before writing them
into the formula. Basis values and their derivatives update at each
candidate scale, while the knots, the coefficient basis, and any priors stay
fixed. Only cubic bases with distinct, strictly interior knots are
supported. Adaptive df recipes, repeated or boundary knots, and other
degrees need the refit backend. Natural-spline tails are linear on the link
scale. These are unpenalized bases of fixed complexity, with no
smoothing-variance uncertainty and no monotonicity constraint.
GAMs keep their smooth terms and penalties only through the refit backend. They are not treated as ordinary unpenalized GLMs here.
Not supported: fixed inputs inside a dynamic expression, adaptive dynamic
bases, nondifferentiable or arbitrary functions, kernel-dependent offsets,
hard-radius metrics, random effects, and zero inflation. Put offsets in the
formula with offset() rather than in the separate offset argument.
How the search works
Both backends run full multi-start searches in serial by default. Use
n_cores = 1, start_strategy = "single", and profile_control. They do
not accept refit_fn or join_by. Every winning start must pass both the
optimizer's convergence check and a projected-gradient check.
For "profile_glm", regression coefficients are solved by iteratively
reweighted least squares (IRLS) at each candidate. A full-rank NB2 fit whose
iterations fail receives a coefficient refinement that uses the analytic
score and observed information. The Gaussian residual standard deviation is
profiled at its maximum likelihood estimate. Independent native likelihoods
have verified the fitted objective in simulations of the supported families.
This backend is experimental, and the calibration of its scale intervals is
not established. Simulations found Wald undercoverage even among fits that
passed the curvature checks. For single-kernel NB2 models,
scale_inference() examines the full likelihood range and can assess
individual scale values with a parametric bootstrap.
"joint_nb2" uses L-BFGS-B to estimate the kernel parameters, the
coefficients, and \rho = \log(1 + \alpha) together, where
\alpha = 1/\theta. At rho = 0 the likelihood is exactly Poisson.
Each candidate must also agree, within 1e-5 negative log-likelihood units,
with an independently optimized conditional coefficient fit. Start records
keep failures, projected gradients, conditional likelihood gaps, and
warnings. dispersion_est adds alpha and exact_poisson, and a boundary
estimate has theta = Inf. The model is still NB2, so its parameter count
includes dispersion at the boundary. Its conditional coefficient summary
uses the Poisson GLM summary at that boundary; see dispersion_est for the
NB2 boundary details. The profile_fit parameter vector holds the log kernel
parameters followed by rho, and joint_par adds the regression
coefficients. Interior joint covariance from vcov() uses log(theta)
coordinates, as for "profile_glm".
For NB2 models in either backend, profile_control$coefficient_start = "warm" reuses conditional regression coefficients within each search. The
default is "cold". Warm continuation resets at every independent start
and falls back to cold initialization if its score or rank checks fail.
Final likelihood checks always use independently initialized coefficients.
Counts and fallback reasons are stored in profile_fit$coefficient_audit.
Run joint_nb2 starts in parallel
For "joint_nb2" only, profile_control$worker_pool spreads the
independent starts over a PSOCK cluster you create with
parallel::makePSOCKcluster(). It does not reduce the number of starts or
change any uncertainty rule. Keep n_cores = 1, because the pool size sets
the number of workers. Workers must load the same installed package code as
the main session. Each start keeps its cold terminal audit, and results keep
their original start order. Worker coefficient audits are stored in
profile_fit$worker_coefficient_audits, and coefficient_audit then covers
the final evaluation in the main session. Later profile and bootstrap
inference stays serial.
You own the pool. Create it once, pass
profile_control = list(worker_pool = pool) to each call, and close it with
parallel::stopCluster() when finished, including after errors (use
on.exit() inside your own function). Pool connections are not stored in
the fitted object. Separate processes duplicate the data and package memory,
so check estimate_multiscale_ram() first. Pool startup also checks the
binned data against 75 percent of physical RAM, allowing four copies of the
data and 1 GiB per process for the main session and the workers. This is a
planning estimate, not a guarantee of peak memory. Startup can outweigh the
gain for short jobs. Set math-library thread limits before creating workers
to avoid nested parallel computation.
Uncertainty rules
Joint observed information includes kernel, coefficient, and dispersion cross derivatives. Default scale limits are normal approximations on the log scale. Wald uncertainty is withheld when any of these holds:
a parameter sits at a search bound;
the information is not positive, or its scaled condition number is at least 1e8;
a log-kernel standard error exceeds one;
competing starts lie more than 0.5 log units apart within a 95 percent likelihood threshold;
a Poisson fit at the selected scales comes within that same likelihood threshold of the NB2 fit;
the fit sits on the exact Poisson boundary.
These are screening rules, not a proof that the scales are identified. The
Poisson comparison is conservative and is not a formal model test;
reoptimizing the Poisson scales could reveal more compatibility. A separate
near-Poisson diagnostic flags max(mu/theta) < 0.01. A finite upper theta
bound does not establish a finite dispersion maximum. The marginal
covariance and Hessian are missing whenever joint uncertainty is
unavailable.
Predictions with uncertainty = "conditional" at the Poisson boundary
condition on both the kernel parameters and the boundary dispersion. They
say nothing about uncertainty in either. See multiScaleR-prediction.
The conditional opt_mod keeps the standard GLM methods, but
update(opt_mod) is disabled because its original call refers to the
kernel values from before the search. Refit through multiScale_optim().
summary(fit, profile = TRUE) reoptimizes the other kernel parameters and
the NB2 dispersion while it profiles each sigma. It reports the connected
likelihood region around the selected solution. Limits that reach a search
bound are labeled "profile-bound-limited" and are not fully resolved
confidence limits. profile_sigma() instead holds the other kernel
parameters fixed while it reestimates the coefficients and NB2 dispersion.
Neither is guaranteed to find likelihood modes the search never visited.
Compare with an ordinary GLM
At the same fixed scales, with the same rows, design, offset, and response
coding, the analytic binomial likelihood is the ordinary binomial GLM
likelihood. You can check the retained conditional GLM against a separate
glm() fit on the selected predictors. Do not compare the joint intervals
with conditional GLM intervals, because the joint intervals also carry
scale uncertainty. For a covariance comparison, use the same response form
and weights. A vector response and a two-column response can give slightly
different working covariance even when the coefficients and likelihood
agree. aic_tab() and bic_tab() treat logical and numeric binomial
responses as the same zero and one observations when the retained rows,
trial totals, and likelihood weights agree.
Joint mixed backend
backend = "joint_mixed" needs the optional packages RTMB, TMB, and
glmmTMB. It estimates the kernel scales and the model parameters together,
integrating the random intercept out with the Laplace approximation. It fits
log-link Poisson and NB2 glmmTMB models with one conditional random
intercept, constant dispersion, and optional fixed-effects zero inflation.
Use Gaussian or exponential kernels, retained model row names that match the
prepared point IDs, and n_cores = 1. Numeric spatial predictors may enter
native R crossing, nesting, and factor interaction terms.
Not supported: random slopes, more than one grouping term, spatial terms in
the zero-inflation or dispersion formulas, non-unit weights, priors,
parameter maps, and REML. Raw formula variables must be recoverable from the
fitted model, so put offsets in the formula with offset().
Each start uses a fresh native fit, a joint Hessian check, and an
independent native refit at its end point whose likelihood must agree within
1e-5. Failed starts stay in mixed_fit$start_results. If every start
fails, the error condition carries start_results. No Hessian check is
bypassed.
The result's opt_mod is the final native glmmTMB fit, and mixed_fit
records the log scales, bounds, starts, every outcome, and the selected
start. Narrow raw prediction data keep fixed-transform inputs for effect
curves once the temporary refit data are gone. diagnostics(fit)$joint_mixed
reports eligibility and scale-boundary flags. Scale uncertainty has not been
calibrated: scale standard errors and legacy scale Hessians are NA, and
joint intervals are unavailable. Coefficient and prediction covariance
condition on the selected scales. Use
predict(fit, se.fit = TRUE, uncertainty = "conditional") or
predict(fit$opt_mod, ...). This backend does not extend the
single-predictor NB2 contract of scale_inference().
Conditional-logistic backend
backend = "conditional_logit" fits step-selection models with the exact
likelihood of a finite choice set: one used step and at least one available
step per set. See vignette("v10-step-selection", package = "multiScaleR").
Models and data it accepts
Use a survival::clogit() model fitted with model = TRUE, or an
amt::fit_clogit() wrapper, with Gaussian or exponential kernels and one
bare strata(choice_id) term. A quoted choice-set ID is still one bare
variable, and special-call text inside a quoted predictor name is not read
as a Cox special term. IDs must identify sets uniquely across animals and
bursts, and row names must match the prepared point IDs. Prepare complete
sets before fitting. Omitted missing rows, subsets, weights, robust
clustering, and special Cox terms are rejected. Keep the available steps
fixed throughout the search.
Numeric kernel predictors may enter native R interaction, crossing, and nesting terms, including crosses with factors or other optimized predictors. Fixed transformations and offsets keep their native meaning and saved training values. Kernel-only scalar arithmetic and the supported smooth base functions follow the same rules as the analytic GLM backends.
Optimized kernel-weighted surface SQ predictors are supported when the
matching raw buffers are retained. They use the weighted root-mean-square
deviation, not the sample SD within a hard radius. Their scales are
estimated separately, and prediction needs the same source and metric
specifications and the training normalization. Fixed-radius metrics can
enter as fixed predictors. Their original prepared numeric columns must be
retained in the native model frame, and new predictions need those columns
unless include_fixed = TRUE verifies and reuses their original
normalization (see prepare_prediction()).
Not supported: hard-radius landscape and surface metrics with estimated radii, adaptive dynamic bases, arbitrary or nondifferentiable functions, fixed context inside a dynamic expression, and kernel-dependent offsets.
How the search works
The backend runs independent L-BFGS-B starts in serial, with cold
coefficient initialization and a cold native survival refit at every end
point. A start is eligible when it converges, has a small projected score,
agrees in likelihood and coefficients, has well-conditioned coefficient
information, and agrees with the native covariance. Failed attempts and
warnings stay explicit in profile_fit$start_results. If every start fails,
the error condition carries start_results. profile_fit$starts stores the
log-scale starting values, and winner identifies the selected record.
After the original joint point passes the native agreement checks, cold
native coefficients may refine its terminal score if the objective does not
increase and the score improves. Both scores and the refinement flag are
kept, and the eligibility threshold is unchanged.
What the fit keeps
The final opt_mod is the native conditional fit, with amt metadata when
supplied. If the original fitting call no longer exposes its raw data,
retained model-frame values support fixed transformations, factors, and
compound offsets without inverting them. Cold native refits keep the
original prediction transformations, including learned polynomial bases.
Prediction for new data still needs the raw inputs named in the formula.
The internal prediction record omits duplicate fitting data to save space;
the original model stays in fitted_mod_original. Updating the conditional
fit needs explicit data with kernel covariates that are already
standardized; otherwise rerun the original multiscale fit.
Scale standard errors and joint prediction uncertainty are withheld. Coefficient covariance conditions on the selected scales and does not correct for temporal dependence among steps.
Movement terms
The original amt proposal distributions are unchanged. Apply amt's
movement-distribution updates to opt_mod when they suit the movement
terms in your model. Movement terms must match the available-step proposal.
The backend does not add them, check a sampling interval, or calibrate
population inference.
Covariate types and transformations
The analytic backends support optimized kernel means and kernel-weighted
surface SQ (the weighted root-mean-square deviation), alone or together.
Weighted SQ uses retained raw cell buffers with Gaussian or exponential
kernels. Estimating the radius of any other surface metric needs the refit
backend. Kernel means need bin = TRUE in kernel_prep(). Models with only
surface metrics need explicit preparation row IDs and raw buffers, without
binned summaries. See msr_vars() for how each covariate type is defined.
A fixed-radius metric enters the native numeric design as an ordinary
predictor, with no scale parameter, in every backend and in
multiScale_bayes(). Its original prepared values and normalization must
stay recoverable from the native model frame. If every covariate is fixed,
there is no scale to estimate, so fit the model directly to the prepared
columns.
Under the "expow" kernel, a hard-radius predictor has no shape parameter.
Its reported shape and shape standard error are NA, and model selection
leaves the unused shape position out of the parameter count. The starting
parameter vector keeps its full layout, so give a finite positive
placeholder for that position when you supply par.
By default (covariate_transform = "candidate"), each optimized covariate
is centered and scaled again at every candidate scale, so a coefficient
describes a change of one standard deviation. The refit backend also accepts
covariate_transform = "raw", which keeps optimized kernel and metric
values in their own units. The fit records centers of zero and scales of one
and reuses them for prediction, effect curves, and spatial
cross-validation; they are never re-estimated from a prediction batch. Fit
the starting model in those raw units, including any fixed spline knots.
Raw mode does not change upstream surface reference normalization or the
transforms of fixed metrics, and Bayesian targets are unaffected.
The Bayesian route also accepts weighted SQ, with a fixed pooled reference
normalization and proper priors. Neither the candidate standardization nor
the raw transform of multiScale_optim() is substituted into a Bayesian
target.
Distance-removal models
Native distance-removal (GDR) models from unmarked use the refit backend.
make_gdr_refitter() provides an opt-in native C or TMB refit function
when you need independent starts and retained audits. It freezes the
evaluated settings and keeps the final native covariance. TMB needs explicit
tmb_settings, starts in constructor order including log-SDs, and native
joint covariance checks. Its intermediate fits still compute sdreport.
Identified native GDR response fields (fit_gdr_response_field()) need a
serial scale search: n_cores = 1 and PSOCK = FALSE. A NULL core count
selects one for this route. Sending native fits to parallel workers has not
been qualified.
Only active GDR component formulas identify spatial predictors. Availability is inactive for a single primary period, and the distance formula is inactive for a uniform key. Optimized static site covariates must not share names with columns in the native yearly or observation covariate tables. Dot formulas use the original component's available training columns.
Native GDR models with active formula offsets or TMB zero inflation are
rejected before fitting, model selection, or prediction. In the audited
unmarked 1.5.2 provider, offsets did not enter the fitted likelihood and
the TMB zero-inflated Poisson likelihood ignored its zero-inflation
parameter. multiScaleR does not remove offsets, switch engines, change
parameter counts, or substitute uncertainty estimates for these cases.
Offset-free C zero-inflated Poisson models keep their native likelihood and
parameter count. See vignette("v12-distance-removal", package = "multiScaleR").
Control settings
profile_control is a named list. Entries a backend does not accept are an
error.
| Entry | Backends | Default | What it controls |
n_starts | analytic GLM, joint_mixed, conditional_logit | 6 | Number of deterministic kernel starts |
starts | analytic GLM, joint_mixed, conditional_logit | NULL | Matrix of explicit starts, one row per start (see below) |
iter.max | analytic GLM, conditional_logit | 500 | Iteration limit for each L-BFGS-B search |
eval.max | analytic GLM | 1000 | Evaluation limit for later profile and inference refits, which use conditional fitting |
gradient_tolerance | analytic GLM, conditional_logit | 0.001 | Largest projected gradient a winning start may have |
kernel_engine | analytic GLM, conditional_logit | "reference" | "stream" computes kernel values and derivatives with less copying |
theta_bounds | analytic GLM | c(1e-4, 1e5); c(1e-4, Inf) for joint_nb2 | Search bounds for NB2 theta |
theta_start | analytic GLM | NULL | Starting NB2 theta |
coefficient_start | analytic GLM, NB2 only | "cold" | "warm" reuses coefficients within a search |
worker_pool | joint_nb2 only | NULL | PSOCK cluster for running starts in parallel |
Each row of starts holds positive kernel scales in internal distance units
(map distance divided by unit_conv), followed by shapes for "expow", in
model predictor order. Explicit starts replace the deterministic scale
starts, and par, if supplied, is added first. All independent starts are
kept. NB2 dispersion starts cycle through the initial theta, 0.3, 2, and 20
within the bounds. For "profile_glm", theta bounds must be positive,
increasing, and at most 1e6. For "joint_nb2", the upper bound must stay
infinite and the lower bound must be at least 1e-8. Each "joint_nb2"
kernel start is tried at the exact Poisson boundary and at an interior
dispersion, giving 12 fits with the default six kernel starts.
The "stream" kernel engine traverses the prepared matrices contiguously,
copies them less, and caches response-only NB2 terms. It keeps the same
starts, likelihood, and uncertainty checks. It uses extra temporary vectors
proportional to the number of observations and can speed up larger binned
inputs. For smooth weighted SQ predictors under "conditional_logit", it
also computes values and scale derivatives in compiled code, reusing work
buffers across sites, with temporary storage proportional to the largest
retained site buffer.
See Also
multiScale_optim() for the arguments, multiScaleR for the
fitted object, multiScaleR-kernels for kernels and hard radii,
multiScaleR-prediction for prediction uncertainty, and
vignette("v07-fitting-methods", package = "multiScaleR") and
vignette("v09-estimates-and-intervals", package = "multiScaleR").
Glossary of terms used in multiScaleR
Description
Plain-language definitions of the terms used across the multiScaleR help pages and vignettes, in alphabetical order. Each entry names the page that explains the idea in more depth.
Details
-
1D and 2D distance: two ways to turn sigma into a distance. The 2D distance (the default) is the radius of the circle around a point that holds a set proportion of an ideal kernel's weight on a plane. The 1D distance is measured along a line through the point and is shorter. See
kernel_dist(). -
Backend: the computational route
multiScale_optim()uses to search over scales, chosen with itsbackendargument. See multiScaleR-fitting-methods. -
Binned inputs: distance-binned summaries that
kernel_prep()stores whenbin = TRUE(the default). They let the search compute kernel-weighted means without visiting every cell, which is much faster. -
Buffer: the set of raster cells within
max_Dof a survey point. Only these cells contribute to the point's kernel-weighted covariates. -
Choice set: in a step-selection model, one used step together with the available steps it is compared against. See
vignette("v10-step-selection", package = "multiScaleR"). -
Conditional uncertainty: uncertainty that treats the estimated scales as known. Most coefficient standard errors and prediction intervals are conditional. See multiScaleR-prediction.
-
Credible interval: a Bayesian interval that contains a stated posterior probability (for example 95 percent) for a quantity, given the model, the data, and the priors. See
multiScale_bayes(). -
Cross-validation: estimating out-of-sample predictive performance by fitting the model to part of the data (the training folds) and scoring its predictions on the rest (the held-out fold). Spatial folds hold out blocks of nearby points, and grouped folds hold out whole groups such as sites or years. See
cross_validate(). -
Distance-removal model: a model for counts recorded in distance classes and removal intervals that separates abundance from detection. multiScaleR uses
unmarked's generalized distance-removal (GDR) models. Seevignette("v12-distance-removal", package = "multiScaleR"). -
Effective distance: the distance that contains a set proportion (by default 90 percent) of a kernel's weight. It converts sigma into a distance in map units that is easy to report and compare across kernels. See
kernel_dist(). -
Expected response: the mean response a model predicts for given covariate values, such as an expected count or an occurrence probability. It differs from an observation replicate, a simulated new observation that also includes observation noise. See multiScaleR-prediction.
-
Exponential power kernel (
"expow"): a kernel with a shape parameter in addition to sigma, which lets the weight curve range from sharply peaked to nearly flat-topped. See multiScaleR-kernels. -
Fixed kernel: a kernel that gives every cell within a radius the same weight and cells beyond it no weight. Its scale is a hard radius.
-
Fixed-radius metric: a landscape or surface metric computed at a radius you set, so it has no scale to estimate and enters the model as an ordinary covariate. See
msr_vars(). -
Gaussian kernel: the default kernel, whose weights decline with distance following a normal (bell-shaped) curve with standard deviation sigma. See multiScaleR-kernels.
-
Hard radius: a scale at which a cell is either fully in or fully out of the calculation. Landscape metrics, unweighted surface metrics, and the fixed kernel use hard radii. Their likelihood changes in steps, so they get no Hessian standard error.
-
Hessian: the matrix of second derivatives of the log-likelihood at its maximum. Its inverse approximates the variance of the estimates and gives Wald standard errors.
-
Joint uncertainty: uncertainty that lets the scales and the coefficients vary together, so that intervals also reflect uncertainty about the scales. Only some backends provide it. See multiScaleR-fitting-methods.
-
Kernel: a function that assigns a weight to each raster cell according to its distance from a survey point. Kernel-weighted covariates summarize the landscape around each point. See multiScaleR-kernels.
-
Kernel-weighted mean: the weighted average of a raster's cell values around a point, using kernel weights. It is the default covariate type, set with
kernel_var(). -
Landscape metric: a summary of the composition or arrangement of land-cover classes within a radius, such as the proportion of a class or an edge density, set with
landscape_var(). -
Laplace approximation: a fast approximation that treats a distribution (a posterior, or the integral over random effects) as Gaussian around its peak. See
vignette("v15-bayesian-computation", package = "multiScaleR"). -
Lean mode: preparing inputs with
store_cell_data = FALSE, which keeps only the binned summaries to save memory. It works only when every covariate is a kernel-weighted mean. -
Link scale and response scale: a generalized linear model works on the link scale (for example log counts or log odds) and reports predictions on the response scale (counts or probabilities) after back-transforming with the inverse link. See multiScaleR-prediction.
-
Marginal likelihood: the likelihood after integrating out random quantities, such as random effects or a between-group standard deviation of scale.
-
max_Dandmin_D: the largest and smallest scales the search may consider, in map units. Setmax_Dinkernel_prep()above the largest plausible scale of effect;min_Dis set from the raster resolution. -
Negative exponential kernel (
"exp"): a kernel whose weights decline exponentially with distance, giving more weight to nearby cells and a longer tail than the Gaussian kernel. See multiScaleR-kernels. -
Posterior: in a Bayesian model, the probability distribution of the parameters given the data and the priors. See
multiScale_bayes(). -
Profile likelihood: the log-likelihood as a function of one parameter, with every other parameter re-estimated at each value. Profile-likelihood intervals follow the shape of the likelihood instead of assuming it is symmetric. See
profile_sigma(). -
Scale of effect: the distance over which a landscape variable influences the response. multiScaleR estimates it as the sigma of a kernel, which
kernel_dist()converts to an effective distance. -
Shape: the second parameter of the exponential power kernel, which controls how sharply the weights fall off.
-
Sigma: the scale parameter of a kernel, in map units. A larger sigma spreads the weight over a wider area. Sigma is not itself the distance to report; see Effective distance.
-
Spatial response field: a spatially correlated random effect that captures residual spatial pattern the covariates leave unexplained. See
vignette("v11-spatial-fields", package = "multiScaleR"). -
SQ: the kernel-weighted root-mean-square deviation of a continuous surface around its local mean, a measure of surface roughness. See
surface_var(). -
Standardization: centering a covariate on its mean and dividing by its standard deviation. multiScaleR standardizes each optimized covariate at every candidate scale by default, so a coefficient describes the effect of a one standard deviation change.
-
Step-selection model: a model of animal movement that compares each used step with available steps through conditional logistic regression. See
vignette("v10-step-selection", package = "multiScaleR"). -
Surface metric: a summary of the texture of a continuous surface around a point, such as its roughness or skewness, set with
surface_var(). -
Wald interval: an interval built from an estimate plus or minus a multiple of its standard error. It assumes a symmetric, nearly quadratic likelihood near the estimate, which may not hold for scales.
See Also
multiScaleR-package for an overview of the package, and
vignette("v01-quickstart", package = "multiScaleR") to get started.
Kernels and scales of effect
Description
multiScaleR summarizes the landscape around each survey point with a
kernel, a function that gives nearby raster cells more weight than distant
ones. The width of the kernel is its scale parameter, sigma, measured in map
units. This page defines the four kernel families, explains which covariates
use smooth kernel weights and which use a hard radius, shows how sigma is
converted into a distance you can report, and explains how to choose
max_D. For worked examples, see the section "Understand the kernel and its
parameters" in vignette("v02-user-guide", package = "multiScaleR").
What a kernel does
The scale of effect is the distance over which a landscape variable
influences a response measured at a survey point. Instead of fitting one
model per buffer radius, multiScaleR weights every raster cell around a
point by its distance and estimates the kernel width from your data, along
with the regression coefficients.
For a survey point and a raster layer, kernel_prep() extracts the cells
within max_D map units of the point and records the distance d from the
point to each cell center. A kernel-weighted covariate is then the weighted
mean of those cell values v:
x = \frac{\sum_i w(d_i) v_i}{\sum_i w(d_i)}
The sums run over cells with a finite value. A missing cell drops out of
both sums, so the remaining weights renormalize. Because the weight
function appears above and below the line, any normalizing constant
cancels and only the shape of w(d) matters. The model then uses this
covariate after centering and scaling, as described in kernel_prep().
Sigma is estimated by multiScale_optim() (or multiScale_bayes()). It is
always in the linear units of the projection, usually meters.
Choose a kernel family
Set the kernel with the kernel argument of kernel_prep(). All covariates
prepared together share one kernel, so comparing kernels means one
kernel_prep() call per kernel. The weight functions below come from the
package code.
| Kernel | kernel = | Weight of a cell at distance d | Estimated parameters |
| Gaussian (default) | "gaussian" | exp(-d^2 / (2 * sigma^2)) | sigma |
| Negative exponential | "exp" | exp(-d / sigma) | sigma |
| Exponential power | "expow" | exp(-(d / sigma)^shape) | sigma and shape |
| Fixed buffer | "fixed" | 1 when d < sigma, 0 otherwise | sigma, which is the buffer radius |
How to read the parameters:
-
Gaussian. Sigma is the standard deviation of a normal curve. A cell at distance sigma gets about 61% of the weight of a cell at the point, and a cell at twice sigma gets about 14%.
-
Negative exponential. Sigma is the decay length. A cell at distance sigma gets about 37% (1/e) of the weight at the point. The weight drops faster near the point than under a Gaussian kernel and has a longer tail.
-
Exponential power. A cell at distance sigma always gets about 37% of the weight at the point, and
shapesets the form of the curve. Withshape = 1the kernel is the negative exponential with the same sigma. Withshape = 2it has the Gaussian form, with a standard deviation of sigma / sqrt(2). Larger values flatten the top and steepen the edge, so the kernel approaches a fixed buffer of radius sigma. Values below 1 give a sharper peak and a heavier tail.kernel_prep()starts the shape at 2, and the default refit search ofmultiScale_optim()keeps it between 0.75 and 50. -
Fixed buffer. Every cell whose center lies within sigma gets equal weight, so the covariate is the plain mean of those cells.
Start with the Gaussian kernel. Fit the other kernels when you have a reason
to test a different decay shape, and compare the fits by AICc with
aic_tab(). Not every fitting route accepts every kernel, as
multiScaleR-fitting-methods explains.
Smooth kernels and hard radii
A covariate's scale is either a smooth kernel width or a hard radius, and the two behave differently during estimation.
Smooth kernel weights. Kernel means from kernel_var() and
kernel-weighted surface metrics from surface_var(..., weighted = TRUE) use
the Gaussian, negative exponential, or exponential power weights above.
Each weight changes continuously with sigma, so the likelihood is a smooth
function of sigma. multiScale_optim() can then report a Hessian-based
(Wald) standard error and confidence interval for sigma.
Hard radius. Some covariates count each cell fully or not at all:
Every landscape metric from
landscape_var().Every surface metric from
surface_var()withweighted = FALSE(the default).Every optimized covariate prepared with
kernel = "fixed", including kernel means and weighted surface metrics.
The estimated scale of such a covariate is a radius in map units. The
covariate changes only when the radius passes the distance of a cell
center, so the likelihood is a step function of the radius. It is flat
between steps and jumps at them, which leaves no useful curvature for a
Hessian standard error. The default summary therefore shows NA for the
standard error and Wald interval of a hard radius. Examine the likelihood
profile instead, with profile_sigma() or summary(fit, profile = TRUE),
and report the estimate as a radius in map units. An interval read from a
profile cutoff does not by itself establish coverage for a stepped
likelihood. Because a flat objective can stall a search at its start,
multiScale_optim() screens several starting values by default when the
kernel is "fixed".
Under kernel = "expow", a hard-radius covariate has no shape parameter.
Its reported shape and shape standard error are NA, and model selection
leaves that unused position out of the parameter count.
A metric given a fixed radius in landscape_var() or surface_var() has
no scale to estimate. It is computed once and enters the model as an
ordinary covariate.
Report an effective distance
Sigma is a parameter, not a radius. The same sigma reaches a different
distance under each kernel, so report an effective distance, the distance
that holds a stated share prob of the kernel weight (90% by default).
kernel_dist() makes the conversion, plot_kernel() draws it, and
summary() of a fitted model reports it next to each sigma.
Two definitions are available through the dimension argument:
-
Planar,
dimension = "2d"(the default since version 0.7.4). Raster cells lie on a plane, and the number of cells at distancedgrows with the circumference 2 pid. The planar distance is the radius of the circle around the point that holdsprobof the total kernel weight. Use it when you describe the area a kernel draws on. -
Line-based,
dimension = "1d". The kernel is treated as a curve along a single transect through the point. The distance enclosesprobof the area under that curve. This was the default before version 0.7.4.
| Kernel | Line-based distance ("1d") | Planar radius ("2d") | At prob = 0.9, 1D and 2D |
| Gaussian | qnorm((1 + prob) / 2) * sigma | sigma * sqrt(-2 * log(1 - prob)) | 1.645 and 2.146 times sigma |
| Negative exponential | -sigma * log(1 - prob) | sigma * qgamma(prob, shape = 2) | 2.303 and 3.890 times sigma |
| Exponential power | sigma * qgamma(prob, shape = 1 / shape)^(1 / shape) | sigma * qgamma(prob, shape = 2 / shape)^(1 / shape) | Depends on shape |
| Fixed buffer | sigma * prob | sigma * sqrt(prob) | 0.900 and 0.949 times sigma |
For example, a Gaussian kernel with sigma = 300 m holds 90% of its planar weight within about 644 m, while the line-based 90% distance is about 493 m. On an unbounded plane, the circle of radius 493 m holds only about 74% of the weight. A hard-radius covariate reports its radius under either definition. Always state the definition and the share of weight you report.
Both definitions describe the ideal, continuous kernel on an unbounded
plane. They ignore truncation at max_D, raster edges, missing cells, and
cell geometry, so the share of weight held by the cells actually extracted
around a point can differ. The pct_wt smoothing window of
kernel_scale.raster(), the default max_D of sim_dat(), and the
max_D warning of multiScale_optim() keep the line-based definition.
Choose max_D
max_D, set in kernel_prep(), does three jobs.
-
It sets the neighborhood. Each point gets every raster cell that intersects a circle of radius
max_Daround it, including partly covered cells at the edge, which keep their full kernel weight. Cells beyondmax_Dare never seen, so each kernel is cut off atmax_Dand its weights renormalize over the extracted cells. -
It bounds the search.
multiScale_optim()estimates sigma, or a hard radius, betweenmin_D(the spacing of adjacent cell centers, about one cell width) andmax_D.multiScale_bayes()places priors on sigma without these hard bounds, but its covariates still use only the cells extracted withinmax_D. -
It sets the cost. A larger
max_Dextracts more cells per point, which costs preparation time and memory. Withbin = TRUE(the default) the cost of optimizing kernel means no longer depends onmax_D. The raster must cover each point's full buffer.
Set max_D above the largest scale you consider plausible. After fitting,
multiScale_optim() flags an estimate whose line-based 90% distance is more
than half of max_D. It prints a warning (when verbose = TRUE), records
the max_distance entry of diagnostics(), and suggests a larger max_D
in its next_run element. For a Gaussian kernel the flag appears once sigma
exceeds about max_D / 3.3, and for a negative exponential kernel once it
exceeds about max_D / 4.6. So for a plausible upper sigma s, choose max_D of at
least 3.3 s (Gaussian) or 4.6 s (negative exponential). Also compare
the planar radius from kernel_dist(sigma = s, kernel = ...) with max_D.
When that radius approaches max_D, the extracted cells hold noticeably
less of the kernel weight than the ideal kernel describes. If an estimate
comes back near max_D, increase max_D, run kernel_prep() again, and
refit. Do not shrink a scientifically chosen max_D only to save memory.
estimate_multiscale_ram() describes leaner preparation options.
Functions that use kernels
| Function | What it does with the kernel |
kernel_prep(), kernel_prep_by_group() | Set the kernel and max_D, and extract cells and distances |
msr_vars() | Declare kernel means, kernel-weighted surface metrics, and hard-radius metrics |
multiScale_optim() | Estimate sigma (and shape) with the model |
kernel_dist() | Convert sigma into an effective distance |
plot_kernel() | Draw a kernel without a fitted model |
profile_sigma() | Trace the likelihood across sigma or a hard radius |
kernel_scale.raster() | Apply fitted kernels to whole rasters for mapping |
sim_dat() | Simulate responses at known scales of effect |
See Also
-
vignette("v02-user-guide", package = "multiScaleR")for kernel plots, effective distances, and kernel comparison on a worked example. -
vignette("v04-landscape-metrics", package = "multiScaleR")andvignette("v05-surface-metrics", package = "multiScaleR")for hard-radius and kernel-weighted metrics. -
kernel_dist(),plot_kernel(),kernel_prep(),multiScale_optim(),profile_sigma(), multiScaleR-fitting-methods, multiScaleR-glossary.
Prediction quantities and their uncertainty
Description
A prediction from a fitted multiscale model is one specific quantity, such
as an expected count, a linear predictor, or a detection probability. Its
standard error or interval carries one specific kind of uncertainty. This
page lists what each prediction route in multiScaleR returns and what its
uncertainty includes, so that you can choose the call that answers your
question and describe the result correctly. It covers fits from
multiScale_optim(). For fits from multiScale_bayes(), see
predict.multiScaleR_bayes().
vignette("v09-estimates-and-intervals", package = "multiScaleR") works
through these distinctions with examples, and
vignette("v03-map-predictions", package = "multiScaleR") shows how to map
predictions and limit extrapolation.
Choose a prediction route
Two terms recur below. Conditional uncertainty treats the estimated kernel scales (sigma) and shapes as known and carries only the uncertainty in the regression coefficients (and an estimated dispersion, where the model has one). Joint uncertainty lets the kernel parameters and the coefficients vary together.
| Route | Call | Quantity returned | Standard errors | Intervals |
Analytic GLM backends ("profile_glm", "joint_nb2") at points | predict(fit, newdata, kernel_inputs) | Expected response (type = "response") or linear predictor ("link") | Joint (the default) or conditional | interval = "confidence" gives Wald limits for the expected response |
| Analytic GLM backends on a raster | predict(fit, raster) | Expected response or linear predictor in each cell | Conditional only | None |
Conditional logistic ("conditional_logit") | predict(fit, newdata, kernel_inputs, type = "link") | Linear predictor ("link"), relative selection score ("risk"), or probability within each complete choice set ("response") | Conditional only | None |
Joint mixed model ("joint_mixed") | predict(fit, newdata, kernel_inputs) | Native glmmTMB response or link prediction | Conditional only | None |
| Default refit backend, most model classes | predict(fit, newdata, kernel_inputs) | The provider's prediction: response scale by default, linear predictor for Cox models | Conditional, when the provider supplies them | None from the wrapper. Native lm intervals through native_args |
Default refit backend, unmarked models | predict(fit, newdata, kernel_inputs, join_by = keys, type = "state") | One named native component, such as abundance, occupancy, or detection | Conditional | Native confidence limits in the returned table |
| Fixed-row snapshot | predict(prepare_prediction(fit, ...)) | Same as the route it was prepared from | Same | Same |
| Effect curves | plot_marginal_effects(fit) | Expected response across one covariate, other inputs held at reference values | Conditional, for every backend | 95% Wald band |
| Native model | predict(fit$opt_mod, newdata) or terra::predict(raster, fit$opt_mod) | The provider's own prediction, from covariates you have already standardized | Conditional | The provider's own |
| Parameter covariance | vcov(fit) | Covariance of the estimated parameters | Joint or conditional (analytic backends) | Not applicable |
| Bayesian fit | predict(bfit, ...), simulate(bfit, ...) | Posterior expected response, or replicated observations | Full posterior | Credible intervals |
Rasters for predict(fit, raster) come from kernel_scale.raster() with
scale_center = TRUE and match_buffer = TRUE. predict.multiScaleR()
documents the arguments for the first six routes.
Read the scale of a prediction
The linear predictor, or link scale, is the intercept plus each
coefficient times its covariate, plus any formula offset. The response
scale applies the model's inverse link function to it. exp() inverts a
log link and turns a linear predictor into an expected count. plogis()
inverts a logit link and turns it into a probability. Choose with
type = "link" or type = "response".
To back-transform a link-scale result yourself, apply the inverse link to
the estimate and to each confidence limit. Do not apply it to a standard
error. A response-scale standard error comes from the delta method,
abs(d mu / d eta) x SE(link), where mu is the expected response and
eta is the linear predictor. For a log link this is mu x SE(link).
The analytic backends return it with type = "response", se.fit = TRUE.
Their confidence limits are computed on the link scale and then
transformed, so on the response scale they are asymmetric and stay inside
the valid range (positive counts, probabilities between 0 and 1).
Some models have their own scales:
-
Cox and step-selection models. The linear predictor is a log relative risk, and
exp()of it is a relative risk or relative selection score. Neither is a probability of occurrence or survival. Native Cox refits usetype = "lp"(whichtype = "link"also selects) ortype = "risk". The conditional logistic backend uses"link"and"risk", and its"response"is a probability normalized within each supplied choice set. -
Linear models. For an
lmrefit the link and response scales are the same, sotype = "link"returns the response. -
unmarkedmodels. Native prediction back-transforms each component by default, so abundance is a count and occupancy and detection are probabilities. Bindnative_args = list(backTransform = FALSE)inprepare_prediction()to keep the component's link scale.
Landscape covariates enter the model standardized by default, so a coefficient describes the change in the linear predictor for one standard deviation of the kernel-weighted covariate. Every prediction route reuses the mean and standard deviation from the fitted data. Never standardize a prediction data set on its own.
Expected response or a new observation
The expected response is the model's mean at a site: the expected count,
or the probability of occurrence. An observation recorded at that site
scatters around this mean. That scatter is observation noise. Every
standard error and interval that predict.multiScaleR(),
prepare_prediction(), and plot_marginal_effects() return describes the
expected response or a model component, and none adds observation noise.
Two native controls are the exceptions:
For an
lmrefit,native_args = list(interval = "prediction")returns limits for a future observation, including the residual variance.For a spaMM refit, the native
residVarandrespVarvariance attributes are on the response scale and include observation noise.
multiScaleR has no simulate() method for multiScale_optim() fits. For
a GLM, the native simulate(fit$opt_mod) draws new responses at the fitted
rows from the fitted means, holding the scales and coefficients at their
estimates. For a Bayesian fit, simulate.multiScaleR_bayes() draws
replicated observations that carry both posterior uncertainty and
observation noise.
Choose conditional or joint uncertainty
| Fitting route | Joint uncertainty | Conditional uncertainty |
backend = "profile_glm" or "joint_nb2" | Yes, from predict() at points and from vcov(), when fit$uncertainty$available is TRUE | Yes, at points and on rasters |
backend = "conditional_logit" | No | Yes |
backend = "joint_mixed" | No | Yes, from native glmmTMB |
Default backend = "refit" | No | Yes, from the native provider |
multiScale_bayes() | The posterior already covers scales and coefficients together | Not applicable |
predict() defaults to uncertainty = "joint". Every route except the
analytic backends at points needs uncertainty = "conditional" before it
returns a standard error, and stops otherwise rather than silently
returning a conditional one. For the analytic backends, joint uncertainty
is refused when the fit sits at a parameter bound or fails its
identifiability checks. fit$uncertainty$reasons says why. Point
predictions remain available in that case. At the exact Poisson boundary
of a "joint_nb2" fit, conditional standard errors and intervals also hold
the dispersion at that boundary.
Effect curves from plot_marginal_effects() and predictions from the
native model in fit$opt_mod are conditional for every backend, including
the analytic ones. A conditional interval answers the narrower question of
how uncertain a prediction is if the scales of effect are exactly their
estimates. Say so when you report one.
Confidence intervals and prediction intervals
A confidence interval describes uncertainty about the expected response. A prediction interval describes where a single new observation may fall. It adds observation noise and is wider.
The analytic backends return Wald confidence limits with
interval = "confidence", at the confidencelevelyou set.Every other route requires
interval = "none"inpredict(). Nativeunmarkedtables carrylowerandupperconfidence limits for the component at the native level, 0.95 unless you bind anotherlevelinnative_args. Anlmrefit returns native mean confidence limits withnative_args = list(interval = "confidence")and prediction limits withinterval = "prediction", both withuncertainty = "conditional".Effect-curve bands from
plot_marginal_effects()are 95% Wald limits for the expected response.Bayesian credible intervals from
predict.multiScaleR_bayes()describe the expected response. Intervals fromsimulate.multiScaleR_bayes()replicates describe new observations.
Wald intervals are approximations, and the package does not establish
their coverage. vignette("v09-estimates-and-intervals", package = "multiScaleR") summarizes how well they performed in simulations.
Random effects and new groups
Native mixed models predict with the fitted random effects of known groups by default (glmmTMB and lme4). Setting the random effects to zero gives a reference prediction for a group whose deviation is exactly zero:
glmmTMB, lme4, and spaMM:
re.form = NA(orre.form = ~0).nlme:
native_args = list(level = 0).-
unmarked: any non-NULLre.formsets every random effect to zero. It does not select a subset of effects.
A zero-effect prediction is not an average over the random-effect
distribution. Under a nonlinear link, the average over groups generally
differs from the prediction at zero. None of the frequentist routes integrates over
groups or samples effects for new groups. A new group level needs the
provider's own control, such as allow.new.levels = TRUE for glmmTMB, and
then follows the provider's rules. plot_marginal_effects() always sets
random effects to zero. Bayesian predictions can sample new-group effects,
as predict.multiScaleR_bayes() describes.
Pass re.form and other native controls through ... in
predict.multiScaleR(), or bind them with native_args in
prepare_prediction(). The effects field of the prediction_contract
records the policy that was applied.
Components of unmarked fits
An unmarked model has several regression components, and a prediction
describes one of them. Name it with type in predict.multiScaleR() and
plot_marginal_effects(), or with component in prepare_prediction().
Point predictions from occu() and pcount() fits default to "state".
Snapshots and raster predictions require an explicit component.
| Model | type | What it predicts | Rows it uses |
unmarked::occu() | "state" | Probability that a site is occupied | Sites |
unmarked::occu() | "det" | Probability of detection on one survey, given that the site is occupied | Site by survey |
unmarked::pcount() | "state" | Expected abundance at a site. With mixture = "ZIP", the overall mean, including structural zeros | Sites |
unmarked::pcount() | "det" | Probability of detecting each individual on one survey | Site by survey |
unmarked::gdistremoval() | "lambda" | Abundance or density parameter | Sites |
unmarked::gdistremoval() | "phi" | Availability, active only with more than one primary period | Site by primary period |
unmarked::gdistremoval() | "dist" | Distance-detection parameter of the fitted key, inactive for a uniform key | Site by primary period |
unmarked::gdistremoval() | "rem" | Removal parameter | Site by primary period by removal interval |
Abundance from pcount() counts the animals present, not the animals you
would expect to count. For plot_marginal_effects(), type = "lambda" is
an alias for "state" in occu() and pcount() fits, and "state" is an
alias for "lambda" in gdistremoval() fits. Other classes keep their
native component names, such as "psi", "col", and "ext" for dynamic
occupancy (initial occupancy, colonization, and extinction). These are
distinct from smoothed or projected occupancy trajectories.
Native standard errors and confidence limits for every component condition
on the selected scales and add no observation noise. A component
prediction does not change the fitted model's parameter count, likelihood,
or diagnostics. vignette("v02-user-guide", package = "multiScaleR")
fits and maps N-mixture and occupancy models, and
vignette("v12-distance-removal", package = "multiScaleR") covers
gdistremoval().
Bayesian fits
A fit from multiScale_bayes() carries posterior draws of the scales and
coefficients together, so its predictions need no conditional or joint
choice. predict.multiScaleR_bayes() returns posterior summaries of the
expected response, simulate.multiScaleR_bayes() returns replicated
observations, and predict_scales() returns posterior scales for observed
or new groups. vignette("v14-bayesian-prediction", package = "multiScaleR") predicts new sites, new years, and totals.
Check what a result describes
Snapshots from prepare_prediction(), native refit predictions, and
Bayesian summaries carry a prediction_contract that names the quantity,
its scale, the random-effect policy, and the uncertainty it includes and
omits. Read it when you are unsure which interval you are holding.
See Also
predict.multiScaleR(), vcov.multiScaleR(),
prepare_prediction(), prepare_unmarked_data(),
plot_marginal_effects(), prediction_contract,
predict.multiScaleR_bayes(), multiScaleR,
multiScaleR-fitting-methods
Bayesian landscape-scale fits
Description
multiScale_bayes() returns an object of class multiScaleR_bayes. It is a
list that holds the frozen model, the parameter layout, and, once a method
has been run, the posterior draws and the record of that computation. This
page lists every element, shows where each model parameter lives and on
which scale, explains how to convert it to a distance or a multiplier, and
names the functions that read the object. The Bayesian interface is
experimental. Printing any of these objects reports "Experimental Bayesian
landscape-scale model".
Elements in every object
-
specification: the frozen model. Rows, landscape bins, formulas, priors, and the reference standardization are fixed here once and reused by every method. See "Read the specification". -
parameters: a named list of seven numeric vectors that defines the parameter layout and holds starting values. It contains no estimates. See "Find each parameter". -
call: the matched call tomultiScale_bayes(). -
inference: a label for the computation, one of"prepared","full Bayesian NUTS","full Bayesian slice sampling","joint Laplace Gaussian approximation","marginal Laplace with scale-SD quadrature", or"importance-corrected marginal Laplace". -
inference_metadata: a description of what the object estimates. See "Read the inference metadata". Fits saved by older versions of the package can lack it, and they remain usable.
Elements added by each method
method | Elements added |
"prepare" | None. There are no draws, so the object cannot be used for posterior summaries or prediction |
"sample" (NUTS) | draws, sampler, sampling, diagnostics |
"slice" | draws, chains, sampling, diagnostics |
"laplace" | draws, laplace, diagnostics |
"marginal" | draws, marginal, diagnostics |
"marginal" with correction = "importance" | draws, marginal, importance, diagnostics
|
-
draws: a named list of seven numeric matrices, one per parameter block in the order ofparameters. Each matrix has one row per retained joint posterior vector and one column per parameter in the block, on the internal scales given in "Find each parameter". Rowiof every block belongs to the same joint vector, so compute derived quantities from whole rows. NUTS rows come in permuted order. Slice rows follow the chains, one chain after another. Laplace and marginal rows are independent draws from the approximation. Importance-corrected rows are resampled, with replacement, from the weighted candidates. -
sampler(NUTS): thestanfitobject returned by tmbstan. -
chains(slice): a numeric array of post-warmup iterations by chains by parameters, with parameter names such as"beta[1]"and"scale_beta[1]". Chain diagnostics and bayesplot chain plots read it. -
sampling(NUTS and slice): thechains,iter,warmup,seed, and effectivecoresused. NUTS also recordscontrolandlaplace = FALSE. -
laplace,marginal,importance: records of the approximations. See "Read the approximation records". -
diagnostics: the numerical checks of the computation. See "Read the stored diagnostics".
Find each parameter
The seven parameter blocks appear in the same order in parameters,
specification$parameters, draws, and every concatenated vector or
matrix (the Laplace mode, covariance, and hessian, the importance
candidates, and the columns of chains).
| Block | One entry per | What it holds | Scale stored | Interpretable form |
beta | name in specification$beta_names | Response coefficients | Link scale | Read directly, or exp() for count and binomial models. Summarized in summary(fit)$coefficients |
scale_beta | column of each scale design | Scale-formula coefficients | Log of distance divided by specification$unit_conv for intercepts and ~0 + year coefficients. Log-distance contrasts for the rest | Add log(unit_conv) to the intercepts to get log map units, then exp() for a distance. exp() of a contrast is a ratio of distances. Summarized in summary(fit)$scale_coefficients |
scale_z | level of each scale grouping term | Standardized group deviations with a standard-normal prior | None | Multiply by the group SD to get the deviation in log scale |
log_scale_sd | scale random-intercept term | Log of the between-group SD of log scale (tau) | Log | exp() gives tau. exp(tau) is a multiplier on the scale. Summarized in summary(fit)$group_sd$log_scale_group_sd |
response_z | level of each response grouping term | Standardized random intercepts with a standard-normal prior | None | Multiply by the response group SD to get the intercept on the link scale |
log_response_sd | response random-intercept term | Log of the random-intercept SD | Log of a link-scale SD | exp(). Summarized in summary(fit)$group_sd$response_group_sd |
log_dispersion | NB2 or Gaussian model (empty otherwise) | Log NB2 size theta, or log Gaussian residual SD | Log | exp(). Summarized in summary(fit)$dispersion
|
The link scale is the log expected count for Poisson and NB2 models, the log odds for binomial models, and response units for Gaussian models.
Each landscape predictor's scale for observation i, in map units, is
\log D_i = x_i^\top b + \sum_k \exp(s_k) z_{k, g_k(i)} + \log(u)
where x_i is row i of the scale design
specification$scales[[name]]$X, b is
scale_beta[specification$scales[[name]]$beta_index], s_k is the
entry of log_scale_sd for random term k, z_{k, g} is the
entry of scale_z for group g, and u is
specification$unit_conv. Within specification$scales[[name]]$random,
each term records z_index (positions in scale_z, one per level in
levels), index (each row's level), and sd_index (position in
log_scale_sd). Response random terms in specification$response$random
use the same fields for response_z and log_response_sd. This
noncentered form, a standard-normal deviation times a group SD, is the
coordinate system the samplers and approximations work in.
For a shared scale, exp(scale_beta + log(unit_conv)) is the scale itself.
For ~1 + (1 | year), the same expression gives the typical scale, the
median of the population distribution of annual scales, and tau is
exp(log_scale_sd).
A year one SD above typical has a scale exp(tau) times the typical one.
posterior_scales() performs these conversions for every distinct
combination of scale covariates and groups. Prefer it to rebuilding them
by hand.
Read the specification
specification is a list. Most users need only a few elements.
-
covariates: names of the landscape predictors whose scales are estimated.kernelis"gaussian"or"exp". -
unit_conv: the distance normalizer of the prepared inputs. Internal log scales are in units of distance divided byunit_conv. -
support:min_Dandmax_Dof the prepared inputs, in map units. They are a reference range forposterior_scales(), not bounds on the prior. -
center,spread: the fixed reference standardization of each landscape predictor, computed once across fitting rows at the prior median scale. A response coefficient refers to onespreadunit of the kernel-weighted predictor at that scale. -
priors: the complete prior settings, with defaults filled in.scale_medianis a named vector, one entry per landscape predictor. -
beta_names: the names of the response coefficients, inbetaorder. -
scales: one list per landscape predictor, holding the scaleformula, its design matrixX,beta_index,distance_location(TRUEfor coefficients that are log distances rather than contrasts), the prior mean and SD of each coefficient (prior_mean,prior_sd, on the internal log scale),randomterms, andlabelswith therepresentativesrows used to report each distinct combination. -
response: the response formula, its model frame, terms,randomterms, and the levels and contrasts retained for prediction. -
family,y,trials,offset: the response family, the response vector (successes for binomial data), the binomial trial totals (1 for other families), and the offset. -
data,rows,observation_ids,row_id: the observation data, the prepared landscape row of each observation, its point ID, and the name of the row-ID column (NULLwhen row names were used). Older saved fits can lackrow_id. -
V,C,delta: binned value sums, finite-cell counts, and shifted distance terms for kernel means. -
X_fixed: the design columns that do not involve a landscape predictor.
Some models add response_design (interactions and expressions that
involve a landscape predictor), surface (weighted SQ buffers, their
specifications, and the memory planning record), or fixed_reference
(the preparation normalization of declared fixed-radius metrics).
Read the inference metadata
inference_metadata describes the target and the treatment of uncertainty.
It does not report whether a fit passed its checks.
-
schema_version: version of this structure. -
target: always"posterior"for these objects. -
method:"prepare","nuts","slice","joint_laplace","marginal_laplace", or"importance_corrected". -
objective:"negative_log_posterior".population_priorsis"proper", because every parameter has a prior.response_normalizersis"retained". -
integration: how scale effects, response effects, and population parameters (group SDs) are treated, such as"joint_sampling","joint_gaussian", or"joint_importance_sampling", or"not_computed"for a prepared object. -
solver:"none","nuts","slice","optimization", or"importance_sampling". -
uncertainty:intervalsis"marginal_credible"once fitted and"not_provided"when prepared.population_parametersandannual_scalesstate that group-SD uncertainty is propagated through the joint posterior.calibrationis always"not_established", because no method has demonstrated interval coverage for general data sets. -
diagnostics_field: the name of the element that holds the checks,"diagnostics".metadata_establishes_eligibilityis alwaysFALSE.
Read the stored diagnostics
Every fit has diagnostics$passed (TRUE, FALSE, or NA) and, in most
cases, criteria, a sentence stating the rule applied. The other fields
depend on the method.
| Method | Fields | passed requires |
| NUTS | parameters (a posterior summary table with rhat, ess_bulk, ess_tail), divergences, max_treedepth_hits, ebfmi (one per chain) | At least 2 chains, Rhat at most 1.01, bulk and tail effective sample size at least 100 per chain, no divergences or tree-depth hits, and E-BFMI at least 0.3 |
| Slice | parameters | The same chain rules, without the NUTS-only checks. Without the posterior package, passed is NA, parameters is NULL, and reason explains why |
| Laplace | type, gradient_max, min_eigenvalue, condition_number, competing_modes, successful_starts, starts | No distinct mode within 2 log-posterior units. A failed optimizer or an invalid Hessian stops the fit instead |
| Marginal | type, grid_converged, grid_nodes, refinement, competing_mass, upper_tail_mass, gradient_max, condition_number | A converged grid, competing_mass at most 0.01, and upper_tail_mass at most 0.001 |
| Importance | pareto_k, ess, min_tail_ess, max_weight, split_cdf_error, type, candidates, min_candidates, proposal_df, production_candidates, proposal_passed | Pareto k at most 0.7, ess at least 1000, min_tail_ess at least 400, max_weight at most 0.01, and split_cdf_error at most 0.05
|
In the importance checks, ess measures how concentrated the weights
are, min_tail_ess the precision of tail indicators, pareto_k the
presence of extreme ratios, max_weight dominance by one candidate, and
split_cdf_error the disagreement between two independent halves of the
production candidates. min_candidates is the requested minimum.
For the samplers, these checks cover the raw parameters. Use
diagnose_bayes_scales() to check the scales and group SDs you report. For
the approximations, a passed check says the arithmetic finished cleanly. It
does not say the approximation is close to the posterior.
vignette("v15-bayesian-computation", package = "multiScaleR") explains
each check and what to do when one fails.
Read the approximation records
Modes, covariances, Hessians, and candidates in these records use the unconstrained, noncentered coordinates of "Find each parameter", with the blocks concatenated in order.
-
laplace:mode, the jointcovarianceandhessianat the mode, every optimizer attempt instarts, theselected_start, and the number ofdraws,seed,cores, and acoordinatesnote. The covariance keeps correlations among coefficients, scales, and group SDs. -
marginal: the integration grid over the one scale-group SD.xholds the nodes in the coordinates of the SD's half-normal prior CDF (0 to 1).weights,density,cumulative, andlog_normalizerdescribe the integrated SD distribution at those nodes.nodesholds the conditional approximation at each node, with itsmode,covariance,hessian,log_density, and optimizerattempts. The record also keepsprior_sd, the gridrefinementhistory,converged,hyper_index(the position of the SD),parameter_indices(positions of node parameters in the full layout), and thedraws,seed,cores,control, andcoordinatesused. With one response grouping term integrated inside an importance-corrected fit, the nodes exclude its latent site effects. The log normalizer describes the numerical integration. It is not a model-selection criterion. -
importance: all retained productioncandidates(one row each) with normalizedweightsandlog_weights(log posterior minus log proposal density), and theresample_idsinto the candidates that builtdraws.historyhas one row per production stage, with its diagnostics, whether itpassed, and whether it met the requested minimum (budget_met). The record also keeps theseed, a text description of theproposal, theadapted_proposalmixture (itscomponentsand theirweights, where each learned component counts inskipped_nodesthe nodes that kept their original geometry),pilot_candidates,proposal_indices, theconditional_responseflag,production_candidates(including discarded stages),response_proposal(fallback count and largest remaining Newton step), andproposal_diagnostics, the original marginal checks.target_evaluationcounts every posterior density evaluation (evaluations), invalid automatic-differentiation values (ad_invalid), ordinary rechecks that recovered a finite or zero density (recovered_finite,recovered_zero), and values leftunresolved, including pilots and discarded stages. Every candidate is kept, and unresolved densities still fail the importance checks. Withconditional_beta = TRUEthe record also holdsconditional_betaandbeta_proposal, which gives the starting coefficients (start), the number offallbacksto the coefficients' normal prior, the largest remaining Newton step (max_step), and thelatent_prior_fractionof the defensive component.
Functions that read a fit
| Function | What it returns |
print() | Family, observations, scale formulas, and the stored diagnostic status |
summary() | Coefficients, scales, scale coefficients, group SDs, dispersion, and diagnostics. See multiScale_bayes() |
posterior_scales() | Each scale in map units or log map units, with mass below min_D and above max_D |
plot.multiScaleR_bayes() | Interval plots of scales or group SDs |
diagnose_bayes_scales() | Chain diagnostics and Monte Carlo error for scales and group SDs (needs chains or sampler) |
diagnose_bayes_probabilities() | Probabilities that scales fall below thresholds, with Monte Carlo error |
diagnose_bayes_laplace() | A reweighted check of scale probabilities from an uncorrected approximation |
predict.multiScaleR_bayes() | Expected responses or linear predictors at fitted or new observations |
predict_scales() | Scales at new scale covariates and groups, including unsurveyed years |
simulate.multiScaleR_bayes() | Posterior predictive replicate responses |
simulate_bayes_prior() | Prior predictive responses and scales (a prepared object is enough) |
plot_marginal_effects() | Coefficient effect curves at the fixed reference standardization |
cross_validate_bayes() | Refits the model in each fold and scores held-out observations |
aic_tab() and bic_tab() do not accept these objects.
See Also
multiScale_bayes(), posterior_scales(),
predict.multiScaleR_bayes(), diagnose_bayes_scales();
vignette("v13-bayesian-scales", package = "multiScaleR") for fitting and
reading a model,
vignette("v14-bayesian-prediction", package = "multiScaleR") for
prediction, and
vignette("v15-bayesian-computation", package = "multiScaleR") for the
computation methods and their diagnostics.
Examples
# A stored slice-sampling fit with one shared scale per landscape layer
cache <- readRDS(system.file("extdata", "cache-bayesian-scales.rds",
package = "multiScaleR"))
fit <- cache$fit
fit$call # the call that produced this fit
lengths(fit$parameters) # 4 coefficients and 2 scale intercepts
fit$specification$beta_names # order of the beta columns
dim(fit$chains) # iterations x chains x parameters
# Rebuild sigma for land1, in meters, from whole rows of the draws
sm <- fit$specification$scales$land1
log_sigma <- fit$draws$scale_beta[, sm$beta_index] +
log(fit$specification$unit_conv)
quantile(exp(log_sigma), c(0.025, 0.5, 0.975))
posterior_scales(fit)[1, c("median", "lower", "upper")] # the same values
# A stored NUTS fit in which the scale varies among years
annual <- readRDS(system.file("extdata", "bayesian-annual-example.rds",
package = "multiScaleR"))$fits$pooled
year_term <- annual$specification$scales$habitat$random$year
tau <- exp(annual$draws$log_scale_sd[, year_term$sd_index])
median(tau) # between-year SD of log sigma
median(exp(tau)) # a year one SD above typical has this multiple of sigma
Cross-validation results
Description
The cross-validation functions return a list of class multiScaleR_cv.
This page describes every element of that list, what each score measures
and on what scale, and which functions read the result. Several functions
add a subclass that changes or adds a few elements, and those differences
are described at the end.
Which functions return it
| Function | Class of the result |
cross_validate(), cross_validate_glm() (Gaussian, Poisson, binomial) | multiScaleR_cv |
cross_validate(), cross_validate_glm() ("nbinom2", "Gamma") | multiScaleR_distribution_cv, multiScaleR_cv |
cross_validate_clogit() | multiScaleR_choice_cv, multiScaleR_cv |
cross_validate_field() | multiScaleR_field_cv, multiScaleR_cv |
cross_validate_mixed() | multiScaleR_mixed_cv, multiScaleR_cv |
cross_validate_bayes() | multiScaleR_bayes_cv, multiScaleR_cv |
select_cv() | the class of its candidates |
A fold is one split of the data into analysis rows, which fit the model, and assessment rows, which are held out and scored. An assessment occurrence is one held-out row in one fold. A row assessed in two folds has two occurrences.
Read these elements first
-
complete:TRUEwhen every planned fold was fitted and scored. When any fold fails it isFALSE, and every pooled score insummaryisNA. Never rank a model on the folds that happened to finish. -
summary: data frame of pooled scores, one row per metric.-
metricnames the score, andestimateis the pooled score (lower is better). -
unitsays what one score refers to,"observation"or, for the Brier score,"trial". -
n_assessmentis the number of planned assessment occurrences, andn_scoredthe number that entered the score. -
weight_sumis the total frequency weight behind the score (frequency weight x trials for the Brier score). -
completerepeats the completion flag.
-
-
metrics: the same columns plusfold, with one row per fold and metric. A fold that finished keeps its scores even when another fold failed. The pooled RMSE is not the mean of the fold RMSEs. -
fold_results: data frame withfold,n_analysisandn_assessment(rows used to fit and to score), andstatus, either"scored"or"failed". -
errors: list with one element per fold. It isNULLfor a scored fold. For a failed fold it holdsstage, where the fold stopped (for example"initial_glm","scale_fit","prediction", or"training_selection"in aselect_cv()result), andmessage, the reason. A failed scale fit can also carrystart_resultsorradius_profile. Failed folds are never retried. -
warnings: list with one character vector per fold, holding the warning messages captured while that fold was fitted and predicted. They are captured rather than printed, so read them here.
Read the scores
Every score is a loss, so lower is better. Each assessment occurrence gets
its own loss, stored in a column of predictions named after the metric.
The pooled estimate is the frequency-weighted mean of those losses over
the eligible occurrences. An occurrence is eligible when its frequency
weight is positive and, for binomial data, it has at least one trial.
Ineligible occurrences stay in predictions with eligible = FALSE and
contribute nothing.
| Metric | Loss for one occurrence | Pooled score and its scale |
rmse | Squared error, (observed - predicted)^2 | Square root of the mean squared error, in response units (for example, animals per survey) |
mae | Absolute error | Mean absolute error, in response units |
neg_log_score | Negative natural log of the probability (counts, binomial successes) or density (Gamma) that the fitted model gives the observed value | Mean per observation, in natural-log units |
deviance | Poisson deviance contribution (Poisson only) | Mean per observation |
brier | Squared error of the success probability, averaged over the row's trials (binomial only) | Mean per trial, between 0 and 1 |
How to read the scores
RMSE and MAE judge only the predicted mean. RMSE weighs large misses heavily, and MAE treats every miss in proportion to its size. Note that the
rmsecolumn ofpredictionsholds squared errors, not their roots.The negative log score judges the whole predicted distribution, so it also penalizes a model that is too confident. It keeps every constant of the probability function, such as the binomial coefficient. A difference of D between two models means the better one gave the observed outcomes exp(D) times the probability, as a geometric mean per observation. A difference of 0.1 is a ratio of about 1.11. For Gamma responses the score is a density, so it depends on the response units and can be negative.
An observed outcome given zero probability produces an infinite log score. The value is kept, not clipped.
For NB2 and Gamma, the log score uses theta or the dispersion estimated from the analysis rows and frozen for scoring.
A score means little alone. Compare candidates fitted to the same folds with
cv_tab().
Other elements
-
predictions: data frame with one row per assessment occurrence, including the occurrences of failed folds, whose predictions and losses areNA.-
foldandrow_ididentify the occurrence. -
observedis the response (the number of successes for binomial data), andtrialsis 1 except forcbind(successes, failures)responses. -
predictionis the expected response on the response scale (the mean count, the mean, or the probability of success per trial). -
weightis the frequency weight, andeligiblemarks the occurrences that enter the scores. One loss column per metric is named after the metric.
NB2 and Gamma results add
distribution_family, the frozen trainingtheta(NB2) ordispersion(Gamma), withNAwhere it does not apply, andpoisson_limit, which isTRUEonly when a joint NB2 fit verified the exact Poisson limit.
-
-
training: list with one element per fold, describing the fits to the analysis rows. An element can be empty or partial when its fold failed early.-
coefficients: final regression coefficients on the link scale (log for Poisson, NB2, and Gamma, logit for binomial, identity for Gaussian). Useexp()on a log-link coefficient for a multiplicative change in the expected response. Spatial covariates are standardized with the training mean and SD, so their coefficients refer to a one training SD change, unlesscovariate_transform = "raw"was used. -
initial_coefficients: coefficients of the initial GLM, fitted at the starting scales. -
scale_est: data frame withMeanandSE, the estimated sigma and its standard error in map units, one row per optimized covariate. Similar values across folds suggest that the data identify the scales well. -
shape_est: estimated kernel shape (unitless) for kernels that have one, otherwiseNULL. -
initial_normalization,fitted_normalization: lists ofmeanandsd, the analysis-row centering and scaling of each spatial covariate at the starting and the fitted scales. Assessment rows reuse them. -
bin_reference: the frozen distance bins (breaks, representative distancesbin_rep, the extraction envelopedomain, andcell_size). Distances are in units ofmax_D, so 1 equalsmax_D. -
optimizer:par(the optimized scale parameters on the internal scale, sigma divided bymax_D),value(the minimized objective),convergence(0 means success), andmessage. -
start_results: the table of optimizer starts frommultiScale_optim(), when available. -
initial_distribution(NB2 and Gamma): the nuisance parameter of the initial fit, in the same form asdistribution.
cross_validate_glm()estimates no scales, so itstrainingholds onlycoefficients(plus the NB2 and Gamma items). -
-
distribution(NB2 and Gamma only): list with one element per fold, holding the frozen training distribution. An element isNULLwhen the training fit failed.-
family, withtheta(the NB2 size,Infonly for a verified Poisson limit) ordispersion(the Gamma dispersion). -
poisson_limit, andestimated, which isFALSEwhen the parameter was fixed in advance. -
convention, how the value was obtained, for example"native_gamma_deviance_scale"(the training deviance divided by the sum of the weights). -
rank,native_K,logLik,nobs,training_deviance, andsum_weightsof the training fit.
-
-
diagnostics: list with one element per fold.initial_glmandfitted_glmholdconverged,boundary, anditerfrom the initial and final GLM (NB2 and Gamma results also recordth.warnandSE.thetawhere the native fit has them).scaleholds the scale-fit diagnostics described indiagnostics(). Check them before ranking models, because a scored fold is not necessarily a trustworthy one. -
prediction_contracts: list of the prediction contracts attached by the prediction method of each fold (see prediction_contract). Each states what the prediction conditions on and which uncertainty it leaves out. It can be empty when the prediction method attaches none. -
folds: the split plan as supplied. -
assessment_counts: named integer vector, one value per input row, giving how many times the row was assessed (0 for rows never held out). -
targets: data frame withrow_id,observed,trials, andweightfor every row used in any split, sorted by row ID.cv_tab()andselect_cv()use it to confirm that candidates were scored on the same data. It never enters a fit. -
selection_records:NULLunlesskeep_selection = TRUE. Otherwise a list with one compact record per fold, read byselect_cv(). Each record holdsversion,controls,diagnostics, metadatawarnings,data, and anerrormessage if the record could not be built. Leave the records unchanged. They cannot rebuild the fitted models. A successfuldataholds these items.-
logLik, the training log-likelihood (natural log). -
native_K, the parameter count of the fitted regression as its log-likelihood reports it, including an estimated dispersion or theta. -
ecological_K, the number of estimated scales and shapes, andK, their total. -
nobsandobservation_ids, the rows that entered the likelihood. -
targets, the analysis-row responses, trials, and weights, andsignature, a summary of the likelihood used to check that candidates are comparable. -
formula(as text),family, andlink. NB2 and Gamma records addnuisance.
-
-
fits:NULLunlesskeep_fits = TRUE. Otherwise the full model of each fold, fitted to that fold's analysis rows only. -
raster_groups: present only for inputs fromkernel_prep_by_group(). For each fold, the map labels of the analysis and assessment rows. These are fixed inputs, not fitted random effects. -
settings: list withfamily,link,backend("glm"forcross_validate_glm()and"training_selection"forselect_cv()),metrics, the control lists used, and labels that state what the scores mean.normalization = "training_only"andparameter_uncertainty = "not_integrated", for example, say that standardization came from the analysis rows and that the predictions treat fitted parameters as known.cv_tab()checks these labels before comparing candidates. -
call: the matched call.
A select_cv() result also holds selection, with the criterion and
ties rule, the candidates, the metrics kept and metrics_dropped,
chosen (the candidate selected in each fold, NA when selection
failed), tables (the training information-criterion table of each
fold), candidate_settings, candidate_warnings, and
candidate_diagnostics. Its settings$controls_from names the candidate
whose controls fill the shared settings. NB2 and Gamma selections add
settings$fold_settings, the settings of the model chosen in each fold.
Functions that read it
-
print()reports how many folds were scored and how many input rows were assessed, warns when the result is incomplete, and printssummary. -
cv_tab()ranks complete results on one score, after checking that every candidate used identical folds, responses, trials, and weights. -
select_cv()scores a rule that picks a model in each fold by its training AIC, AICc, or BIC. It needsselection_recordsorfits. -
aic_tab()andbic_tab()refuse a cross-validation result, because held-out scores are not a maximized likelihood.
Conditional choice results (multiScaleR_choice_cv)
cross_validate_clogit() scores the probability of the used alternative
within each held-out choice set, and the elements change accordingly.
-
predictionshas one row per alternative.observedis 1 for the used alternative and 0 for the available ones,choiceis the set ID, andtrialsandweightare 1.linear_predictoris uncentered, so only differences within a set matter.predictionis the probability of the alternative within its set (the probabilities of a set sum to 1), andlog_probabilityis its natural log. Only the used alternative iseligible, and itsneg_log_scoreis the negative log probability of the choice. Log scores are computed directly on the log scale, so they stay finite when a printed probability rounds to zero. -
summaryandmetricsholdneg_log_scoreonly, averaged over choice sets, withunit = "choice_set".n_assessment,n_scored, andweight_sumcount sets, andn_alternativescounts the alternative rows. A model without covariates or offsets gives each of k alternatives a probability of 1/k and scores log(k), for example 1.099 for three alternatives. -
fold_resultscounts alternative rows, andtargetsaddschoice. -
diagnosticsholdsinitialandnative(iteration countiterand partial-likelihoodmethod) andscale. -
selection_recordsare version 2. Theirnobscounts choice sets (one event each), not alternatives, and they record themethod. -
settingsgivesfamily = "conditional_choice",link = "softmax", themethod, andbackend = "clogit"when no scales were estimated. Its
print()method reports the folds scored and printssummary.
Spatial field results (multiScaleR_field_cv)
cross_validate_field() scores each held-out block jointly, so that
correlation among neighboring held-out observations counts.
-
predictionsholdsfold,row_id,observed,prediction(the predicted response mean),squared_error,absolute_error, andeligible, plus four variance columns.new_location_field_varianceis the field variance that would remain even if the field were known exactly at the training locations, andfitted_training_field_varianceis the extra variance that arises because the field there is itself estimated. Both are on the linear-predictor scale and, for non-Gaussian families, describe a local Gaussian approximation.observation_noise_variance(response scale) is the observation variance, averaged over the field for non-Gaussian families.observation_predictive_SE(response scale) is the standard deviation of a new observation, combining the field and the noise. It is a predictive SD, not the standard error of the mean. -
joint_scoresholds, for each fold, the block sizenand the block'sneg_log_score. Gaussian blocks add thequadraticloss andlog_determinant. Laplace blocks add the analysis and combined log densities, their latent-mode diagnostics, and the gap from the native analysis likelihood. -
summaryhas columnsmetric,estimate,n_assessment,unit, andcomplete. The log score is the sum of the block scores divided by the number of assessment observations, with unit"joint_block_density_per_observation"or"joint_block_mass_per_observation"(counts and 0/1 data). RMSE and MAE have unit"response". There is nometricstable, so usecv_tab(by_fold = TRUE)for fold scores. -
trainingholds the analysisrow_ids,parameters(field_SD, the correlationrangein coordinate units,observation_SDor the NB2 or Gamma dispersion, and parameter counts),coefficients(link scale), and, with kernel inputs,normalization,scale_est,bin_reference, and the number ofrefits. -
selection_recordsare always kept. Each holdslogLik,K,native_K,ecological_K,nobs,training_ids, and hashes of the training responses and coordinates. -
diagnosticsholds the native fit record of each fold, including the covariance starts tried and the path of its audit file. -
targetsholdsrow_idandobserved,coordinatesholdsrow_id,x, andy, andintegrity_sha256is a hash of the recorded results.cv_tab()andselect_cv()refuse a result whose records were changed after the run.
Mixed model results (multiScaleR_mixed_cv)
cross_validate_mixed() scores all held-out rows of a group jointly,
because they share one unknown group effect.
-
predictionsaddsgroup, andpredictionis the response mean integrated over the group effect (the success probability per trial for binomial data). -
joint_scoresholds, for each scored fold, a data frame withgroup, the number of held-out rowsn, and the group's jointneg_log_score. In
summaryandmetrics, the log score is the sum of the group scores divided by the number of assessment rows (unit"joint_group_density_per_row"). RMSE and MAE have unit"response", or"proportion"for binomial data, where they compare the predicted probability with the observed fraction of successes. The Brier score has unit"trial".-
trainingholds the analysisrow_ids,coefficients(link scale), the random-effectcovariance, the nativedispersion(1 for Poisson and binomial), and any fittedscale_est,normalization, andbin_reference. -
selection_recordsare always kept, withlogLik,K,native_K,ecological_K,nobs, and theanalysisrow IDs. -
diagnosticsholdsconvergence,positive_hessian,native_message, andscale_convergence, andintegrity_sha256protects the records as for field results.
Bayesian results (multiScaleR_bayes_cv)
cross_validate_bayes() scores held-out blocks with the posterior
predictive density, the only score in the package that averages over
parameter uncertainty. Its summary reports the joint negative log score
per observation, and its predictions hold posterior mean responses and
marginal row scores. It has no training likelihood, so select_cv() does
not apply. See cross_validate_bayes() for its elements.
See Also
cross_validate(), cv_tab(), select_cv(), and
vignette("v08-cross-validation", package = "multiScaleR").
Examples
data("landscape_counts")
data("surv_pts")
# Three spatial folds. The simulated coordinates are in meters.
folds <- spatial_cv_folds(crds(vect(surv_pts)), block_size = 1000, k = 3,
crs = 32617)
cv <- cross_validate_glm(counts ~ site, landscape_counts, folds,
family = "poisson", keep_selection = TRUE)
class(cv)
cv$complete # TRUE: every fold was fitted and scored
cv$summary # pooled scores, one row per metric, lower is better
cv$metrics[cv$metrics$metric == "rmse", ] # the same score in each fold
head(cv$predictions) # one row per held-out observation, with its losses
cv$fold_results # rows fitted and held out, and the status of each fold
cv$training$fold1$coefficients # log-link coefficients fitted in fold 1
# What select_cv() reads from each fold
cv$selection_records$fold1$data[c("logLik", "K", "nobs")]
# The pooled RMSE is the square root of the mean squared error over all
# held-out rows, not the mean of the three fold RMSEs
sqrt(mean(cv$predictions$rmse))
Prepared inputs for scale estimation
Description
kernel_prep() and kernel_prep_by_group() return an object of class
"multiScaleR_data", a list that holds everything the fitting functions
need about the survey points and the raster cells around them. Pass it as
kernel_inputs to multiScale_optim(), multiScale_bayes(),
cross_validate(), and related functions. This page describes every
element.
Elements
-
kernel_dat: data frame of the initial kernel-weighted covariate values, centered and scaled to unit variance, with one row per point and one column per covariate. Row names match the row names ofptsor are sequential integers. Fit your starting model to these columns. -
d_list: named list, one element per point, of distances from the point to every raster cell within the buffer.NULLin lean mode. -
raw_cov: named list, one element per point, of matrices holding the raw raster cell values within the buffer, aligned withd_list. Each is stored as a dense or sparse matrix, whichever is smaller.NULLin lean mode. -
kernel: the kernel name ("gaussian","exp","expow", or"fixed"). -
sigma: initial sigma values on the internal scale (map units divided byunit_conv). -
shape: initial shape values for"expow", otherwiseNULL. -
min_D: approximate minimum distance between cells, used as the lower bound for sigma during the search, in map units. -
max_D: themax_Dyou supplied, the upper bound for sigma, in map units. -
n_covs: number of covariates whose scale is estimated. -
unit_conv: internal distance scaling factor, equal tomax_D. -
scale_vars: data frame of class"multiScaleR_vars"describing every covariate specification (seemsr_vars()). -
resolution: raster cell resolution in map units. -
cell_size: cell width and height in map units. Cross-validation uses them to keep intersecting cells whose centers lie beyondmax_D. -
n_cols: number of raster columns, used by adjacency-based landscape metrics. -
binned: whenbin = TRUE, a list of distance-binned summaries (representative bin distances and value and count matrices for each covariate) that speed up the search.NULLwhenbin = FALSEor when no covariate is a kernel-weighted mean. -
cell_data_stored:FALSEonly in lean mode (store_cell_data = FALSE), whend_listandraw_covwere dropped. -
scl_params: named list withmeanandsd, the centering and scaling values applied tokernel_dat. -
raster_group: fromkernel_prep_by_group()only, the raster group of each point.
Lean mode keeps only the binned summaries. It works only when every covariate is a kernel-weighted mean, because landscape and surface metrics need the cell-level data. Printing the object reports the number of points and covariates, the kernel, the binning, and the distance bounds.
See Also
kernel_prep(), kernel_prep_by_group(), msr_vars(),
multiScaleR, and
vignette("v02-user-guide", package = "multiScaleR").
Examples
data(pts)
hab <- terra::rast(system.file("extdata", "hab.tif",
package = "multiScaleR"))
inputs <- kernel_prep(pts = pts, raster_stack = hab, max_D = 250,
kernel = "gaussian", verbose = FALSE)
inputs # short summary of the prepared inputs
head(inputs$kernel_dat) # standardized covariate values at the start
inputs$max_D # upper bound for sigma, in map units
Estimate scales of effect by maximum likelihood
Description
Estimates the scale of effect (sigma) of each kernel-weighted
covariate in a fitted model by maximizing the model's log-likelihood. The
scale of effect is the distance over which a landscape variable influences
the response. By default, multiScale_optim() recomputes the kernel-weighted
covariates at each candidate scale, refits your model, and searches with the
L-BFGS-B algorithm through stats::optim() (or
optimParallel::optimParallel() for parallel searches). Other backends
estimate the scales and the model parameters in one likelihood; see
multiScaleR-fitting-methods.
Usage
multiScale_optim(
fitted_mod,
kernel_inputs,
join_by = NULL,
par = NULL,
start_strategy = NULL,
screen_n_sigma = 5,
screen_n_jitter = 6,
screen_maxit = 8,
screen_jitter_sd = 0.5,
n_cores = NULL,
PSOCK = FALSE,
verbose = TRUE,
refit_fn = NULL,
backend = c("refit", "profile_glm", "joint_nb2", "joint_mixed", "conditional_logit"),
profile_control = list(),
covariate_transform = c("candidate", "raw"),
radius_grid = NULL
)
Arguments
fitted_mod |
A fitted model object whose covariates include the
kernel-weighted variables defined in |
kernel_inputs |
A list of class |
join_by |
Default: |
par |
Optional numeric vector of starting values. Default: |
start_strategy |
Character. How to choose starting values when
|
screen_n_sigma |
Positive integer. Number of log-spaced sigma values
evaluated per covariate during the prescreen when
|
screen_n_jitter |
Non-negative integer. Number of jittered candidate
starts tried with short searches after the prescreen. Default: |
screen_maxit |
Positive integer. Maximum iterations for each short
screening search. Default: |
screen_jitter_sd |
Non-negative numeric scalar. Standard deviation of
the multiplicative sigma jitter, on the log scale, used during screening.
Default: |
n_cores |
Positive integer. Number of cores for a parallel search
through |
PSOCK |
Logical. On Windows, a PSOCK cluster is always used. On Unix,
a FORK cluster is used by default because it is faster. Set |
verbose |
Logical. Print the search status and diagnostic messages to
the console. Default: |
refit_fn |
Optional function for refitting |
backend |
Character. The fitting method. |
profile_control |
Named list of settings for the analytic backends,
such as the number of starts ( |
covariate_transform |
Character. How optimized covariates enter the
model. |
radius_grid |
Experimental, so its behavior may change in a later
release without a deprecation period. With |
Value
An object of class "multiScaleR", a list. The elements you will
use most are:
-
scale_est: the estimated sigma of each optimized covariate (Mean) and its standard error (SE), in map units; -
shape_est: the same for the shape parameter underkernel = "expow", otherwiseNULL; -
opt_mod: your model refit at the estimated scales, to use for coefficients, prediction, and effect plots; -
diagnostics: search and uncertainty diagnostics, read withdiagnostics(); -
next_run: suggestedmax_Dand starting values for a follow-up fit.
multiScaleR describes every element, including those added by the analytic backends, and lists the methods that read the object.
How the search works
A kernel is a distance-weighting function that converts a raster layer
into one covariate value per survey point. Its scale, sigma, sets how fast
the weights decline with distance (see multiScaleR-kernels). The default
refit backend proposes sigma values (and shape values for "expow"),
recomputes the kernel-weighted covariates, refits fitted_mod, and keeps
the values that maximize the log-likelihood. Standard errors come from the
Hessian of this outer search. Hard-radius covariates have no Hessian
standard error because their likelihood changes in steps. Profile
likelihood intervals are available with summary(fit, profile = TRUE) or
profile_sigma(). multiScaleR-fitting-methods gives the rules for each
backend.
Read the warnings
multiScale_optim() prints a warning, and records a code in
warn_message, in three situations:
-
The scale approaches
max_D. The estimate is near or beyond the search extent, so the true scale may be larger. Rebuild the inputs withkernel_prep()using at least the suggestedmax_D, which is also stored infit$next_run$max_D, and refit. -
A sigma standard error is at least half its estimate. The scale is poorly determined. Assess whether the covariate is meaningful in your analysis and interpret it with caution.
-
A shape standard error is at least half its estimate. Assess whether the exponential power kernel suits your data.
A search that never leaves its starting values also warns and records
start_stall in diagnostics(). Supply different starts with par, or use
start_strategy = "screen".
Choose starting values
With start_strategy = "screen" and par = NULL, multiScale_optim()
first scouts the sigma range with one-dimensional, log-spaced scans of each
covariate. It then tests a few jittered starts with short searches that skip
the Hessian. The marginal scans are serial, but the short searches use
n_cores when you request a parallel search. Screening only chooses one
starting vector for the single full search. On Windows those parallel
screening searches use PSOCK workers, so the serialization advice under
"Speed up the search" applies to them too. Call set.seed() before
multiScale_optim() for reproducible screened starts.
To continue from an earlier fit, rebuild the inputs with fit$next_run$max_D
and pass fit$next_run$start_par as par. Those starts are scaled to that
max_D.
Speed up the search
When kernel_prep() was run with bin = TRUE (the default),
kernel-weighted covariates are computed from precomputed distance-binned
summaries instead of every buffer cell at each evaluation. The cost of an
evaluation then no longer depends on max_D, which usually speeds the
search by an order of magnitude or more for large buffers, with a
negligible binning approximation. Inputs created with
store_cell_data = FALSE (lean mode) carry only the binned summaries; they
still optimize, profile, and refit normally. Landscape-metric covariates
always use the exact per-cell path and so need the cell-level data.
For a parallel search, fit the starting model with fully
namespace-qualified functions so that its call serializes cleanly to the
workers. For example, fit a negative binomial model as
fitted_mod <- MASS::glm.nb(y ~ x, data = df) rather than relying on an
attached package.
Fit unmarked models with repeated sites
When the rows of an unmarked model repeat spatial sites, for example a
stacked layout with one row per site and year, the preparation object
still has one row per unique site. Add a site ID to the model's siteCovs
and pass one matching ID per prepared site through join_by. For spatial
sites c("A", "B") and model rows c("A", "B", "A", "B") for two years,
use join_by = data.frame(site = c("A", "B")) and include the four-row
site column in siteCovs. Multiple key columns are allowed. Prepared keys
must be unique, every model row must match one, and the IDs in the model
may repeat in any order. The model's response and site-covariate row order
is preserved.
The layout looks like this, where counts_by_year is a list of count
matrices, each with one row per site (in the order of
kernel_inputs$kernel_dat) and one column per visit:
site_id <- seq_len(nrow(kernel_inputs$kernel_dat))
y_stacked <- do.call(rbind, counts_by_year)
site_row <- rep(site_id, times = length(counts_by_year))
site_covs <- kernel_inputs$kernel_dat[site_row, , drop = FALSE]
site_covs$site_id <- site_id[site_row]
site_covs$Year <- factor(rep(seq_along(counts_by_year),
each = length(site_id)))
umf <- unmarked::unmarkedFramePCount(y = y_stacked, siteCovs = site_covs)
mod <- unmarked::pcount(~Year ~ Year + hab, data = umf, K = 100)
fit <- multiScale_optim(mod, kernel_inputs,
join_by = data.frame(site_id = site_id))
Check that the rows of y_stacked and site_covs refer to the same
site-year records before fitting. Without join_by, model rows must match
the prepared sites one for one, in the same order. When both objects keep
the same row IDs their order is checked; otherwise you are responsible for
it. An open-population unmarked::pcountOpen() model instead stores one
row per site with the years across count columns, so it uses the same
static site covariates without join_by. Optimized covariates must be
static siteCovs; obsCovs and yearlySiteCovs cannot be optimized
through this site-level workflow. Sparse counts can leave scales weakly
identified, so examine the scale profile and diagnostics().
Supply a custom refit function
By default, multiScale_optim() refits the model with stats::update()
(standard models) or the unmarked equivalent. When that is not enough,
supply refit_fn. The function must accept the arguments model, data,
and context, and return a fitted model whose log-likelihood
stats::logLik() or insight::get_loglikelihood() can extract. A minimal
refit function:
refit_fn <- function(model, data, context) {
stats::update(model, data = data)
}
For models that need their call rebuilt explicitly:
refit_fn <- function(model, data, context) {
call <- model$call
call$data <- quote(data)
eval(call, envir = list(data = data), enclos = parent.frame())
}
With PSOCK clusters, refit_fn must serialize cleanly. Prefer
namespace-qualified calls such as stats::update() and avoid closures over
large local objects.
The function receives context$return_model = FALSE for scalar objective
evaluations and TRUE when a fitted model is wanted, including the final
refit at the selected scales. For supported unmarked models, you can skip
the intermediate Hessian calculations while keeping the original model's
uncertainty settings whenever a fitted model is returned:
refit_unmarked <- function(model, data, context) {
if (identical(context$return_model, FALSE))
unmarked::update(model, data = data, se = FALSE)
else
unmarked::update(model, data = data)
}
This changes neither the coefficient starts nor the model's likelihood. It
does not add uncertainty for the kernel scales or override an original
se = FALSE setting. Verify this behavior for your model class before you
rely on a custom refit function.
Fit wrapper model objects
Some packages return a wrapper around another fitted model. For example,
amt::fit_clogit() wraps a survival::clogit() fit in its model
component. multiScale_optim() unwraps these automatically when it can.
For amt::fit_clogit(), pass model = TRUE when fitting so the nested
clogit model keeps its model frame. For complete choice sets with learned
predictors such as base::scale(), use na.action = stats::na.fail to keep
the fitted transformation attributes, because some survival versions drop
them when applying omission, even with complete data.
See Also
multiScaleR-fitting-methods for the backends,
multiScaleR for the returned object, kernel_prep() to prepare
the inputs, profile_sigma() for profile-likelihood intervals,
kernel_scale.raster() to map the fitted covariates, kernel_dist() for
effective distances, and
vignette("v01-quickstart", package = "multiScaleR") and
vignette("v02-user-guide", package = "multiScaleR") for worked
examples.
Examples
set.seed(555)
points <- vect(cbind(c(5,7,9,11,13),
c(13,11,9,7,5)))
mat_list <- list(r1 = rast(matrix(rnorm(20^2),
nrow = 20)),
r2 = rast(matrix(rnorm(20^2),
nrow = 20)))
rast_stack <- rast(mat_list)
kernel_inputs <- kernel_prep(pts = points,
raster_stack = rast_stack,
max_D = 5,
kernel = 'gaussian',
sigma = NULL)
## Example response data
y <- rnorm(5)
## Create data frame with raster variables
dat <- data.frame(y = y,
kernel_inputs$kernel_dat)
mod1 <- glm(y ~ r1 + r2,
data = dat)
## NOTE: This code is only for demonstration
## Optimization results will have no meaning
opt_mod <- multiScale_optim(fitted_mod = mod1,
kernel_inputs = kernel_inputs,
par = NULL,
n_cores = NULL)
## Using package data
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,
kernel = 'gaussian')
mod <- glm(y ~ hab,
family = poisson,
data = count_data)
## Optimize scale
opt <- multiScale_optim(fitted_mod = mod,
kernel_inputs = kernel_inputs)
## Summary of fitted model
summary(opt)
## 'True' parameter values data were simulated from:
# hab scale = 75
# Intercept = 0.5,
# hab slope estimate = 0.75
## Plot and visualize kernel density
plot(opt)
## Apply optimized kernel to the environmental raster
opt_hab <- kernel_scale.raster(hab, multiScaleR = opt)
plot(c(hab, opt_hab))
## Project model; scale & center
opt_hab.s_c <- kernel_scale.raster(raster_stack = hab,
multiScaleR = opt,
scale_center = TRUE)
mod_pred <- predict(opt_hab.s_c, opt$opt_mod, type = 'response')
plot(mod_pred)
## Custom refit hook for model classes that need explicit control.
## This example still uses glm(), but the same pattern can be used for
## classes whose default update path is not sufficient.
refit_glm <- function(model, data, context) {
stats::update(model, data = data)
}
opt_custom <- multiScale_optim(fitted_mod = mod,
kernel_inputs = kernel_inputs,
refit_fn = refit_glm)
## Opt-in NB2 fit: theta and kernel scales are estimated together.
if (requireNamespace("MASS", quietly = TRUE)) {
ki_nb <- kernel_prep(pts = pts, raster_stack = hab, max_D = 250,
kernel = "gaussian", bin = TRUE)
nb_data <- data.frame(ki_nb$kernel_dat)
nb_data$y <- rnbinom(nrow(nb_data),
mu = exp(0.5 + 0.8 * nb_data$hab), size = 2)
nb_initial <- glm(y ~ hab, data = nb_data,
family = MASS::negative.binomial(2))
nb_fit <- multiScale_optim(nb_initial, ki_nb, backend = "profile_glm",
n_cores = 1,
profile_control = list(n_starts = 6))
diagnostics(nb_fit)$profile_glm
predict(nb_fit) # Expected counts for the retained fitting rows.
if (nb_fit$uncertainty$available) {
predict(nb_fit, interval = "confidence")
vcov(nb_fit) # Includes kernel/coefficient/dispersion covariance.
}
}
Plot method for multiScaleR objects
Description
Plots the optimized kernel weight distribution for each spatial covariate in
a fitted multiScaleR object, with optional annotations showing the
effective scale of effect and its 95% confidence interval.
Usage
## S3 method for class 'multiScaleR'
plot(x, dimension = c("2d", "1d"), ...)
Arguments
x |
A fitted |
dimension |
Character. |
... |
Optional named arguments to customize the plot:
|
Details
Development versions after 0.7.3 default to 2D reporting, as do
kernel_dist and plot_kernel. Set
dimension = "1d" to reproduce the original line-based distances.
This switch changes distance markers and converted confidence limits, not
the fitted sigma, regression coefficients, or likelihood.
The curve shows cell weight declining with distance, normalized over the
plotted sample distances. It is not a radial weight distribution. A planar
marker accounts for the increasing area of concentric rings, so the area
under the displayed curve to its left is not the stated proportion.
Distances refer to an ideal untruncated kernel. Actual retained weight can
differ with max_D, raster edges, missing cells, and cell geometry.
Hard-radius covariates, including every fitted fixed-kernel scale, show
a uniform buffer and mark its full radius,
regardless of prob or dimension. A shaded interval is drawn
only when finite limits are available.
Value
A list of ggplot2 objects (one per covariate with a finite
scale and effective distance), returned invisibly. Plots are printed as
a side effect.
See Also
Examples
## Using package data
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,
kernel = 'gaussian')
mod <- glm(y ~ hab,
family = poisson,
data = count_data)
## Optimize scale
opt <- multiScale_optim(fitted_mod = mod,
kernel_inputs = kernel_inputs)
plot(opt)
plot(opt, dimension = "1d") # Original line-based distances
plot(opt, prob = 0.95)
plot(opt, scale_dist = FALSE)
plot(opt, scale_dist = TRUE, add_label = FALSE)
Plot Bayesian Landscape Scales and Group Variation
Description
Draw posterior medians and central credible intervals for the fitted scales, or for the standard deviations that describe variation among groups. Plotting does not refit the model or change its draws.
Usage
## S3 method for class 'multiScaleR_bayes'
plot(
x,
type = c("scales", "group_sd"),
covariate = NULL,
level = 0.95,
scale = c("distance", "log"),
estimator = c("auto", "draws", "weighted"),
...
)
Arguments
x |
A fitted |
type |
|
covariate |
Optional character vector of landscape predictors to plot
with |
level |
Probability of the central credible interval; default 0.95. |
scale |
|
estimator |
|
... |
Not used. Supplying any further argument is an error. |
Value
A ggplot object. Its data holds the plotted summaries, including
median, lower, and upper. Scale panels also hold covariate and
group, and SD panels hold component and term. Print the object to
display it inside a function or loop. When the stored diagnostic flag of
the fit failed or is unavailable, the subtitle says so. Plotting computes
no new chain diagnostics.
Read the plots
With type = "scales", each point is the posterior median of one group's
scale and each bar its central credible interval. Annual intervals describe
uncertainty in each fitted year's scale. They are separate intervals, not a
joint band. With type = "group_sd", the scale panel shows the SD of log
scale among groups (tau), and exp(tau) is the multiplier on the scale
for a group one SD above typical. It is not the standard error of any
year's scale. The response panel shows random-intercept SDs on the link
scale. A shared-scale model without group effects has no group SD to plot.
The half-normal prior on an SD has no point mass at zero, so a positive lower limit does not establish that groups differ. Judge whether the variation is meaningful, and compare a shared-scale model. No plot establishes calibration or model adequacy.
For NUTS and slice fits, the stored flag describes checks on the original
parameters, and for NUTS also on sampler behavior. Use
diagnose_bayes_scales() to check the mixing and simulation precision of
the derived log scales and group SDs.
Draw chain plots
For chain plots, pass fit$chains for a slice fit, or
rstan::extract(fit$sampler, permuted = FALSE, inc_warmup = FALSE) for a
NUTS fit, to bayesplot. Use mcmc_trace() for trajectories,
mcmc_rank_overlay() for rank distributions by chain, and
mcmc_dens_overlay() for posterior densities by chain. Select
regex_pars = "^scale_beta" to see the scale-formula coefficients on the
internal log scale. Chain plots need the original post-warmup draws in
iteration and chain order. Approximate fits and compact examples support
only interval plots and posterior predictive checks.
See Also
posterior_scales(), multiScale_bayes(),
diagnose_bayes_scales(), simulate.multiScaleR_bayes(),
multiScaleR_bayes;
vignette("v13-bayesian-scales", package = "multiScaleR").
Examples
example <- readRDS(system.file("extdata", "bayesian-annual-example.rds",
package = "multiScaleR"))
plot(example$fits$pooled) # sigma for each year, meters
plot(example$fits$pooled, type = "group_sd") # tau and the site SD
# The plotted summaries are kept in the ggplot object
p <- plot(example$fits$pooled, scale = "log")
p$data[c("group", "median", "lower", "upper")] # log meters
# Trace plots from a stored slice fit that keeps its chains
shared <- readRDS(system.file("extdata", "cache-bayesian-scales.rds",
package = "multiScaleR"))$fit
if (requireNamespace("bayesplot", quietly = TRUE)) {
print(bayesplot::mcmc_trace(shared$chains, regex_pars = "^scale_beta"))
}
Plot a Sigma Profile
Description
Draws one panel per covariate from a profile_sigma() result. Each panel
plots AICc or the log-likelihood (whichever metric was chosen in
profile_sigma()) against sigma, with points at the evaluated values and a
dashed red vertical line at the estimated sigma.
Usage
## S3 method for class 'sigma_profile'
plot(x, ...)
Arguments
x |
A |
... |
Not used. |
Details
How to read the plot. The x-axis is sigma in map units, and the
y-axis is AICc (lower is better) or the log-likelihood (higher is better).
A clear trough in AICc, or peak in log-likelihood, at the dashed line means
the data identify the scale of effect well. A flat curve means many
scales fit about equally well. Points are joined with straight lines, so
a hard-radius covariate's stepped likelihood is not shown between grid
values. See profile_sigma() for how the values are computed.
Value
A named list of ggplot objects, one per covariate, returned
invisibly. Each plot is printed as a side effect. Modify a stored plot
and print it again to customize it.
See Also
Examples
## A stored profile from the Quick Start fit (two covariates, 15 values each)
prof <- readRDS(system.file("extdata", "cache-quickstart.rds",
package = "multiScaleR"))$prof
# One AICc panel each for land1 and land2. AICc is lowest near the
# estimated sigma (dashed line)
p <- plot(prof)
# The stored ggplot objects can be modified and drawn again
p$land1 + ggplot2::labs(x = "sigma (m)")
Plot a Kernel Weight Curve
Description
Draws the weight a kernel gives to a raster cell as a function
of its distance from a survey point, and marks the effective distance that
holds a chosen share of the kernel weight. No fitted model is needed, so
use it to explore how kernel type, sigma, and shape translate into spatial
reach before you run multiScale_optim(). To plot the kernels of a fitted
model, with their confidence intervals, use plot.multiScaleR(). The
kernels are defined in multiScaleR-kernels.
Usage
plot_kernel(
prob = 0.9,
sigma,
shape = NULL,
kernel,
scale_dist = TRUE,
add_label = TRUE,
dimension = c("2d", "1d"),
...,
beta = NULL
)
Arguments
prob |
Numeric between 0 and 1 (exclusive). Share of the ideal kernel
weight held within the marked distance, under the selected |
sigma |
Positive numeric scalar. The kernel scale parameter, in the
map units of the projection used with |
shape |
Positive numeric scalar. Shape of the exponential power kernel
( |
kernel |
Character. The kernel to draw: |
scale_dist |
Logical. If |
add_label |
Logical. If |
dimension |
Character. |
... |
Not used. |
beta |
Deprecated former name of |
Details
How to read the plot. The curve shows the relative weight given to a
single cell at each distance. Weights are normalized to sum to one over the
200 plotted distances, so only the shape of the curve and its relative
height matter. The curve is not the distribution of total weight in
concentric rings. Under the default "2d" definition the marker accounts
for the area of each ring, which grows with distance, so the area under
the plotted curve to the left of the marker is not prob. Sigma remains a
kernel parameter, not the marked radius. For a Gaussian kernel with
sigma = 300 m, the 90% marker sits at about 644 m under "2d" and 493 m
under "1d".
The x-axis extends to the distance holding at least 99.9% of the weight
under the selected definition (or prob, if larger). For the fixed kernel
it extends to 1.1 times sigma. Marker positions use the unrounded distance,
and the caption rounds it to two decimal places.
Versions 0.7.4 and later mark the "2d" radius by default. Set
dimension = "1d" to reproduce plots from earlier versions. Both are ideal
continuous-kernel distances. They do not reflect truncation at max_D,
raster edges, missing cells, or cell geometry at a particular site.
Value
A ggplot2 object with distance in map units on the x-axis and
relative kernel weight on the y-axis. It prints when returned at the
console. Add layers or themes to customize it.
See Also
multiScaleR-kernels, kernel_dist(), plot.multiScaleR().
vignette("v02-user-guide", package = "multiScaleR") compares the four
kernels side by side.
Examples
## Radius holding 95% of the ideal planar weight, sigma = 100 map units
plot_kernel(prob = 0.95, sigma = 100, kernel = "gaussian")
# The negative exponential reaches farther for the same sigma
plot_kernel(prob = 0.95, sigma = 100, kernel = "exp")
# Equal weight out to sigma, then zero
plot_kernel(prob = 0.95, sigma = 100, kernel = "fixed")
# A flatter top and steeper edge than the Gaussian
plot_kernel(prob = 0.95, sigma = 100, shape = 5, kernel = "expow")
## The original line-based definition marks a shorter distance
plot_kernel(sigma = 100, kernel = "gaussian", dimension = "1d")
Plot marginal effects from a fitted model
Description
Draw one panel per covariate that shows the model's expected response as that covariate sweeps across its observed range, with every other input held at a reference value, and a 95% confidence band. Read each curve as the direction and size of one effect in the covariate's own units, at the selected scales of effect.
vignette("v02-user-guide", package = "multiScaleR") reads these plots for
a count model and an N-mixture model. multiScaleR-prediction explains
what the bands include.
Usage
plot_marginal_effects(
x,
ylab = "Estimated response",
length.out = 100,
type = "state",
link = FALSE,
draws = NULL,
reference_data = NULL,
component = NULL,
add_label = FALSE
)
Arguments
x |
A fitted |
ylab |
Character scalar. Y-axis label for every panel. Default
|
length.out |
Positive integer. Number of equally spaced values at
which each numeric curve is evaluated. Default |
type |
Character. Component to plot for
|
link |
Logical. If
|
draws |
For Bayesian fits, either a positive number of stored draws
to select evenly across the retained sample, or explicit draw indices.
The default |
reference_data |
Optional data frame of raw predictor values for the
rows used to fit the model. Default |
component |
Optional positive integer selecting a native output
column of a GAM with several linear predictors. Required for those fits
and otherwise must be |
add_label |
Logical. If |
Value
Invisibly, a named list of ggplot2 objects, one per plotted
covariate and named after it. Each plot is also printed. A panel shows:
the predicted response as a line for a numeric covariate, or as points for the levels of a factor. The x-axis is in the covariate's original units, with optimized covariates back-transformed by
x$scl_params.a shaded band, or error bars for a factor, for the 95% limits when the model's prediction method supplies standard errors. Bayesian panels show the posterior median and central 95% credible interval.
a subtitle naming any
I()term (such asI(x^2)) or interaction that involves the covariate.
For a frequentist fit, each plot's data element holds the plotted
values: x, fit, lwr, upr, and variable. The list can carry
attributes: a
prediction_contract for unmarked, glmmTMB, lme4, multi-component GAM,
and Bayesian fits, reference_data_contract when you supply
reference_data, and draw_ids for Bayesian fits.
How each panel is built
The focal covariate sweeps from its minimum to its maximum observed value.
A factor uses its observed levels, with one point and interval per level.
Every other numeric input is held at its sample mean. For a standardized
kernel-weighted covariate the mean is 0, the average landscape value at the
survey points. Other non-numeric inputs are held at their first observed
value, which keeps an actual fitted level. Variables that enter only
through an offset are held at their sample mean and get no panel. Numeric
predictors that multiScale_optim() did not optimize keep their own units.
Panels come from the active model terms. For ordinary lm, glm,
MASS::glm.nb, and time-fixed, unpenalized Cox and clogit fits, the
fitted terms expand dot shortcuts, keep active offset covariates, and
annotate interactions. Removed terms add no panel or prediction input.
Quoted predictor names keep their original spelling. Factor contrasts and
fixed transformations are evaluated by the fitted model, and the plotting
grid never relearns a learned transformation. When x$opt_mod wraps
another fitted model, the nested model is used to find the predictors,
recover the data, and predict.
With an interaction, each panel is one slice of the interaction surface, at the mean of the interacting variable. A message says so, and the panel subtitle names the variables held at their mean.
Scale of the curves and their limits
-
GLMs. Predictions and their standard errors are computed on the link scale. The limits are the estimate plus and minus 1.96 standard errors, transformed by the inverse link (for example
exp()for a Poisson log link) and ordered for increasing or decreasing links. Limits with nonfinite standard errors, invalid endpoints for the link or family, or an inverse-link pole inside the interval are not shown, with a warning. Fitted values stay native, and the method does not clip or repair invalid limits. -
Models without a link, such as
lm: the estimate plus and minus 1.96 standard errors. -
glmmTMB and lme4: native response predictions, including zero-inflation and truncated-family means, with native response-scale Wald limits when available.
-
spaMM: the linear predictor and its native fixed-effect variance (
fixefVar), transformed through the inverse link. The response variance is not used as an interval for the mean. -
pscl
zeroinfl: class-specific predictions with their own limits. -
mgcv::ziplss(): response-scale Wald limits that propagate the full native coefficient covariance through both linear predictors. They can extend below zero.
Every frequentist band is a confidence band for the expected response. It holds the selected scales of effect at their estimates, even for the analytic backends, and it adds no observation noise, so it is not an interval for a future count.
Random effects
Mixed-model and unmarked curves set the random effects to zero
(re.form = NA). These are predictions at the stated covariate values for
a group with zero deviation, not averages over sites, years, or the
random-effect distribution. To show a curve for each year, build your own
prediction grid conditioned on that year with the fitted factor coding.
Zero-effect curves need only the fixed design and offsets. They do not
evaluate unused learned random slopes or need new grouping variables.
Unmarked models
Panels use the variables of the selected component's formula, recovered
by column name. Factor contrasts such as Year2 are coefficient labels,
not data columns, so the factor itself gets one point per observed level.
Site keys that are not fixed predictors, and detection-only predictors,
get no state panels. Other factors are held at their first observed
level. Curves stay on the native response scale for both link settings,
and their limits are the native lower and upper confidence limits.
-
occu()andpcount(). State curves use the original site rows, and detection curves use the original observation rows. Detection is conditional on occupancy foroccu(). Forpcount()it is the probability of detecting each individual on one survey. Curves for Poisson, negative binomial, and ZIPpcount()fits use the same checked native target as point, snapshot, and raster predictions. ZIP state curves keep the overall expected abundance, including structural zeros. Each component prepares only its own training basis, and fixed scaling, polynomial, and spline calls and transformed offsets use the original raw covariates before site removal. -
gdistremoval(). Curves use the component's own site, primary-period, or removal-interval rows and its fitted design, with spline knots, polynomial recipes, nested scaling, and factor interactions fixed at training."lambda"is the native abundance or density parameter,"phi"is availability,"dist"is the native distance-detection parameter, and"rem"is the removal parameter. Inactive components have no curve. These are native component values, not survey averages or random-effect marginal means. GDR models with active formula offsets or TMB zero inflation are rejected, asaic_tab()explains. -
Other classes that would need a different basis or a derived state prediction stop rather than plot one.
Factor coding uses retained or unambiguously recoverable original
metadata. A logical pipe inside I(), such as I(a | b), is a fixed
operation, not a random-effect declaration, but the native unmarked
parser can reject it, or a column name containing a pipe, before fitting.
Then precompute the logical predictor as a named column, or rename the
column. For complete logical inputs, I(as.integer(a) + as.integer(b) > 0)
expresses the same OR without a pipe. With missing values, precompute
a | b to keep R's missing-value logic.
Supply raw reference rows
A fitted model frame can keep poly(temperature, 2), I(elevation^2), or
a compound offset without the raw columns behind them. A square cannot
recover the sign of its input, and an orthogonal polynomial needs its
fitted prediction metadata. If you kept the raw predictors, pass them as
reference_data, with row names that identify the fitted rows:
fit_rows <- row.names(fit$opt_mod$model) reference <- training_data[match(fit_rows, row.names(training_data)), ] row.names(reference) <- fit_rows plot_marginal_effects(fit, reference_data = reference)
The rows are matched by ID and checked against the evaluated training
features, the full native coefficient design or smooth basis, the factor
contrasts, and the formula offsets. Missing rows or inputs, nonfinite
values, new levels, and mismatches raise an error. Transformations and
contrasts are taken from the fit, not relearned from the supplied rows or
the plotting grid. Supported nested calls use a single standard learner's
original retained attributes, and the default refitter can also recover
supported Cox recipes while the original training rows are available.
Precompute a predictor whose recipe is ambiguous or missing. For native
conditional logistic fits with learned predictors, keep the model frame
with model = TRUE and fit complete choice sets with
na.action = stats::na.fail, because some survival versions drop training
attributes when they omit rows.
For native refits, the reference must also hold the final fitted spatial
columns in their fitted units, standardized by default. The analytic
backends instead rebuild the selected kernel values from their verified
preparation. Passing the check establishes that the supplied rows
reproduce the fitted features. It cannot prove a unique raw value behind a
square, polynomial, or other many-to-one transformation, and it does not
refit the model. The reference_data_contract attribute records this.
Offsets supplied outside the formula, unsupported native structures,
matrix-valued raw inputs, and nested learned transformations without
recoverable metadata are rejected. unmarked and Bayesian curves keep
their own data requirements.
GAMs with several linear predictors
Select component explicitly. Link curves use the selected predictor's
active variables. Response curves consider every component's inputs,
because one response column can depend on several predictors. Native
response meanings are kept. For example, mgcv::gaulss() returns the mean
and the reciprocal standard deviation, and multinomial response columns
are category probabilities. Limits use native standard errors on the
selected output scale and condition on the fitted smoothing parameters and
scales of effect. Native GAM curves keep the saved factor coding of
interaction-only factors when session contrast options change. The
returned prediction_contract identifies the native output column.
Cox and step-selection models
Cox panels, including native survival::clogit() fits and the conditional
logistic backend, default to the log relative risk. link = TRUE
exponentiates it to a relative risk or relative selection score. Neither
is a probability of occurrence or survival, or a probability within a
choice set. Strata and cluster-only inputs are held at their first
observed value, which keeps an actual fitted group.
Bayesian fits
Bayesian panels use the stored marginal response-coefficient draws and the
original pooled reference normalization. Each landscape covariate sweeps a
hypothetical grid of values while the others stay at their reference
values. The coefficient draws keep their posterior variation, but the
landscape is not reevaluated at each draw's kernel scales. Response random
effects are zero, and observation noise is excluded. Use
predict.multiScaleR_bayes() with matched spatial inputs for
location-specific posterior expectations. A credible band does not
establish convergence or calibration, so check the fit diagnostics. Their
stored status appears in the caption when add_label = TRUE.
See Also
multiScaleR-prediction, predict.multiScaleR(),
prediction_contract, multiScale_optim(), and
vignette("v02-user-guide", package = "multiScaleR").
Examples
## Running example: counts at 100 survey points and two landscape layers
data("landscape_counts")
data("surv_pts")
pts <- terra::vect(surv_pts)
land <- terra::rast(system.file("extdata", "landscape.tif",
package = "multiScaleR"))[[c("land1", "land2")]]
inputs <- kernel_prep(pts, land, max_D = 1700, kernel = "gaussian",
bin = TRUE, verbose = FALSE)
dat <- data.frame(landscape_counts, inputs$kernel_dat)
start <- glm(counts ~ site + land1 + land2, family = poisson(), data = dat)
fit <- multiScale_optim(start, inputs, backend = "profile_glm",
n_cores = 1, verbose = FALSE)
## Expected count across each covariate, others at their means. The bands
## are 95% limits that hold the scales of effect at their estimates.
curves <- plot_marginal_effects(fit, ylab = "Expected count")
names(curves)
## The values behind one panel. land1 is back on its original scale, the
## kernel-weighted proportion of habitat around a point.
head(curves$land1$data)
## A caption stating what the limits include, useful while exploring
plot_marginal_effects(fit, ylab = "Expected count", add_label = TRUE)
## Expected abundance from a stored N-mixture fit, with native 95%
## confidence limits
nmix <- readRDS(system.file("extdata", "cache-user-guide-nmix.rds",
package = "multiScaleR"))
plot_marginal_effects(nmix, type = "state", ylab = "Expected abundance")
Summarize Posterior Landscape Scales
Description
Report the scale of each landscape predictor in projected map units, for every distinct combination of scale-formula covariates and groups, with its posterior uncertainty and the posterior mass outside the range of the prepared inputs.
Usage
posterior_scales(
object,
level = 0.95,
draws = NULL,
scale = c("distance", "log"),
estimator = c("draws", "weighted")
)
Arguments
object |
A fitted |
level |
Probability of the central posterior interval; default 0.95. |
draws |
Optional positive integer number of stored draws to use, taken
at evenly spaced positions. The default |
scale |
|
estimator |
|
Value
A data frame with one row per landscape predictor and distinct combination of scale-formula covariates and groups.
-
covariate: the landscape predictor. -
group: a label for the combination, such as"year=2021", or"shared"for a predictor with a single scale. -
row: a representative observation row with that combination. -
mean,median,sd,lower,upper: the posterior mean, median, and SD, and the limits of the centrallevelcredible interval. Values are in map units, or in log map units whenscale = "log". For log summaries,exp()of the median and the limits gives distances, butexp()of the mean gives a geometric mean, not the arithmetic mean distance. -
p_below_min_D,p_above_max_D: the posterior probability that the scale lies belowmin_Dor abovemax_Dof the prepared inputs. These flag truncation and resolution limits. They are not evidence of a biological boundary.
mean and sd summarize a finite set of draws. A finite value does not
show that the corresponding posterior moment exists. With
estimator = "weighted", quantiles are empirical inverse-CDF quantiles of
the weighted candidates and sd is the SD of that finite weighted
population.
Read annual scales after partial pooling
For a scale formula such as ~1 + (1 | year), each row describes one
fitted year's scale after partial pooling. Its median is not a separately
estimated annual value. The shared log-scale intercept describes a
population median, which differs from the arithmetic mean of the annual
scales. Intervals are conditional on the likelihood, the priors, the maps,
and the binning. With scale = "log", sd measures uncertainty in one
year's log distance. It differs from the between-year SD reported in
summary(object)$group_sd.
Read means of long-tailed distances
A random scale effect is \tau z, with standard-normal z and a
half-normal tau whose prior scale is s (scale_group_sd). Its prior
exponential moment of order r exists only when r s < 1. The
default scale_group_sd = 0.5 therefore places the variance of annual
distances at the boundary where it becomes infinite, and
scale_group_sd >= 1 also allows an infinite arithmetic mean distance. The
binned likelihood can keep these tails, because very large distances
approach uniform weighting within the extracted neighborhood. Report medians
and interval limits for distances, and use scale = "log" when you need
means and SDs.
Summarize importance-corrected fits directly
For a fit made with correction = "importance", estimator = "weighted"
summarizes the retained candidate population with its normalized weights
instead of the resampled draws. Both target the same posterior. The weighted
version avoids multinomial resampling noise, but it neither raises the
importance effective sample size nor recovers a posterior region the
candidates missed. Candidates with zero weight are dropped. The cautions
about infinite distance moments still apply.
plot.multiScaleR_bayes() uses the weighted estimator by default for
corrected fits, while this function and summary() default to the draws.
Request estimator = "weighted" in both to keep a table and a plot
consistent.
Weighted summaries are only as precise as the candidate population.
importance_max in the control list of multiScale_bayes() is a cap, and
a population that passes its checks at a smaller size stops there. To
require more candidates for precise quantiles, raise importance_min as
well, as in control = list(correction = "importance", importance_min = 65536, importance_max = 131072). Larger populations cost
more and do not guarantee a chosen quantile error. Check the retained count
in fit$diagnostics$candidates, and compare independently seeded fits.
See Also
multiScale_bayes(), multiScaleR_bayes,
plot.multiScaleR_bayes(), predict_scales(),
diagnose_bayes_scales(), kernel_dist();
vignette("v13-bayesian-scales", package = "multiScaleR") and
vignette("v15-bayesian-computation", package = "multiScaleR").
Examples
example <- readRDS(system.file("extdata", "bayesian-annual-example.rds",
package = "multiScaleR"))
fit <- example$fits$pooled # compact draws from an annual-scale NUTS fit
annual <- posterior_scales(fit)
annual[c("group", "median", "lower", "upper", "p_below_min_D")]
# Sigma for each year in meters, with central 95% credible intervals.
# Part of each posterior lies below min_D (100 m, one raster cell).
posterior_scales(fit, scale = "log")[c("group", "mean", "sd")]
# The log-distance SD measures uncertainty in one year's scale, not the
# variation among years.
# Convert the median sigma to the radius holding 90% of the kernel weight
kernel_dist(sigma = annual$median[1], kernel = "gaussian")
Predict from a Distance-Removal Model with a Fixed-Range Abundance Field
Description
Predict density, the distance scale or the removal probability from a
model fitted by fit_gdr_response_field(). Abundance predictions include
the fitted field, at fitted blocks or at new projected locations, and their
standard errors include the field's uncertainty.
Usage
## S4 method for signature 'unmarkedFitGDRField'
predict(
object,
type = "lambda",
newdata = NULL,
backTransform = TRUE,
na.rm = TRUE,
appendData = FALSE,
level = 0.95,
re.form = NULL,
coords = NULL,
crs = NULL,
...
)
Arguments
object |
An unmarkedFitGDRField returned
by |
type |
Character. The model component to predict: |
newdata |
A data frame of covariate values, or an |
backTransform |
Logical, default |
na.rm |
Logical, default |
appendData |
Logical, default |
level |
Confidence level between 0 and 1, default 0.95. |
re.form |
|
coords |
Optional two-column matrix or data frame of projected
coordinates for
abundance predictions at new locations, one row per row of |
crs |
The CRS of |
... |
Not used. Unrecognized arguments stop the prediction. |
Value
A data frame with one row per prediction row:
-
Predicted: the prediction on the scale set bybackTransform. -
SE: its standard error on the same scale. Back-transformed SEs use the delta method. -
lower,upper: confidence limits atlevel, computed on the link scale and then back-transformed, so they are not symmetric aroundPredicted.
The attribute response_field_uncertainty explains the SE. Its element
fitted_joint_predictor_variance is the link-scale variance from the
fitted coefficients and field. new_field_residual_predictor_variance is
the extra link-scale variance at new locations (zero at fitted blocks).
SE_includes_new_field_residual is TRUE when any row has that extra
variance. omitted lists what the SE leaves out: observation noise and
uncertainty in the ecological scales and the range.
Choose where to predict
For abundance, each prediction needs a field value. A row whose grouping
factor names a fitted block uses that block's fitted deviation. A row with
a location in coords uses the field value predicted at that location
from the fitted block deviations. At a fitted block location this equals
the block's own deviation. Far from all blocks, compared with the range, it
shrinks toward zero. For raster maps, use response_field_geometry() with
predict.multiScaleR() instead of calling this method cell by cell.
For type = "dist" with an observer random intercept, rows must name
fitted observers unless re.form = NA.
What the standard errors include
The SE combines two link-scale variances. The first comes from the joint covariance of the fitted coefficients and field values, including their cross-covariances. The second applies only at new locations. It is the field variance left after conditioning on the fitted blocks, evaluated at the estimated field SD. It is zero at a fitted block and grows toward the full field variance far from all blocks. Neither variance is observation noise, so these are confidence intervals for the expected value, not prediction intervals for a new count.
A density prediction is exp() of the linear predictor at the fitted field
values. It is not the average density over possible field values. The
intervals treat the ecological scales of effect and the correlation range
as known.
See Also
fit_gdr_response_field(), make_gdr_refitter()
Examples
# The field needs unmarked 1.5.2 and TMB 1.9.25.
if (requireNamespace("TMB", quietly = TRUE) &&
utils::packageVersion("unmarked") == "1.5.2" &&
utils::packageVersion("TMB") == "1.9.25") {
# Eight survey blocks 1 km apart, six point counts in each
block <- factor(rep(paste0("b", 1:8), each = 6))
hab <- rep(seq(-1, 1, length.out = 6), 8)
shift <- c(-0.4, -0.3, -0.1, 0, 0.1, 0.2, 0.35, 0.4)[block]
sim <- sim_dat_gdr(density = exp(log(400) + 0.5 * hab + shift),
distance_scale = 40, removal = 0.2, dist_breaks = c(0, 25, 50, 75),
interval_lengths = c(2, 3, 5), interval_units = "minutes",
site_covs = data.frame(hab = hab, block = block), seed = 1)
template <- unmarked::gdistremoval(lambdaformula = ~ hab + (1 | block),
removalformula = ~ 1, distanceformula = ~ 1, data = sim$observed,
keyfun = "halfnorm", mixture = "P", output = "density",
unitsOut = "kmsq", K = 60, engine = "TMB",
starts = c(log(400), 0, log(40), qlogis(0.2), log(0.3)))
block_xy <- cbind(x = 500000 + 1000 * (as.integer(block) - 1),
y = 4400000)
rownames(block_xy) <- rownames(unmarked::siteCovs(sim$observed))
cold <- c("beta_lambda[1]" = log(300), "beta_lambda[2]" = 0,
"beta_dist[1]" = log(30), "beta_rem[1]" = qlogis(0.4),
"lsigma_lambda[1]" = log(0.5))
settings <- list(method = "BFGS", se = TRUE, threads = 1L,
control = list(maxit = 2500L, reltol = 1e-10))
field_fit <- fit_gdr_response_field(template, block_xy, crs = 32617,
range = 2000, cold_starts = list(cold = cold),
audit_dir = tempfile("gdr-field-"), tmb_settings = settings)
# Density (birds per square km) at average habitat: in block b3, at a
# point halfway between blocks b3 and b4, and with the field set to zero
in_block <- predict(field_fit, type = "lambda",
newdata = data.frame(hab = 0, block = factor("b3", levels(block))))
between <- predict(field_fit, type = "lambda",
newdata = data.frame(hab = 0), coords = cbind(502500, 4400000),
crs = 32617)
no_field <- predict(field_fit, type = "lambda",
newdata = data.frame(hab = 0), re.form = NA)
dens <- rbind(in_block, between, no_field)
rownames(dens) <- c("block b3", "between b3 and b4", "no field")
print(dens)
# The SE between blocks adds field variance left after conditioning on
# the fitted blocks (both variances on the log scale)
u <- attr(between, "response_field_uncertainty")
print(c(fitted = unname(u$fitted_joint_predictor_variance),
between_blocks = unname(u$new_field_residual_predictor_variance)))
# Removal probability per minute, one row per survey and interval
print(head(predict(field_fit, type = "rem"), 3))
}
Predict from a fitted multiscale model
Description
Predict the expected response, a linear predictor, or a native model
component from a multiScale_optim() fit, at the fitted rows, at new
points, or across a raster. Kernel-weighted covariates are recomputed at the
fitted scales of effect and standardized with the mean and standard
deviation of the fitted data. Fits from the analytic backends
("profile_glm" and "joint_nb2") can also carry joint uncertainty in the
kernel scales and the regression coefficients.
multiScaleR-prediction explains which quantity each route returns and
what its uncertainty includes. This page gives the arguments and the rules
for each backend. vignette("v09-estimates-and-intervals", package = "multiScaleR") compares conditional and joint intervals, and
vignette("v03-map-predictions", package = "multiScaleR") maps predictions.
Usage
## S3 method for class 'multiScaleR'
predict(
object,
newdata = NULL,
kernel_inputs = NULL,
type = c("response", "link"),
se.fit = FALSE,
uncertainty = c("joint", "conditional"),
interval = c("none", "confidence"),
level = 0.95,
...
)
Arguments
object |
A fitted |
newdata |
Where to predict. One of:
|
kernel_inputs |
A |
type |
Scale or component to predict. For the analytic and joint mixed
backends, |
se.fit |
Logical. If |
uncertainty |
Which parameters the standard errors and intervals let
vary. |
interval |
|
level |
Confidence level for |
... |
Further controls. Which ones apply depends on the backend:
|
Value
The class depends on the route.
-
Analytic backends, no standard errors or interval: a numeric vector of predictions on the scale of
type, named by row ID. -
Analytic backends with
se.fit = TRUEorinterval = "confidence": a list withfit(the predictions),se.fit(standard errors on the scale oftype),type, anduncertainty("joint"or"conditional"). Confidence intervals addlowerandupper, on the scale oftype, andlevel. -
"conditional_logit": a named numeric vector, or withse.fit = TRUEa list withfit,se.fit,type, anduncertainty = "conditional". -
"joint_mixed": the native glmmTMB prediction vector, or withse.fit = TRUEits list withfitandse.fit. -
Native refits: the provider's own output, with a prediction_contract attribute that records the quantity and its uncertainty. For an
unmarkedmodel this is the vector of nativePredictedvalues, or withse.fit = TRUEthe native data frame withPredicted(the component on its natural scale),SE, and the confidence limitslowerandupper. -
Raster input: a
SpatRasterof predictions, with a standard-error layer when requested and available, andprediction_contractandprojection_contractattributes that record the controls used.unmarkedoutput keeps the nativePredicted,SE,lower, anduppercolumns as layers.
No route adds observation noise, except the native lm prediction
interval and the spaMM response variances (see "Native refits").
Choose the rows to predict
-
Fitted rows. Omit
newdataandkernel_inputs. The analytic backends rebuild the fitted design. Native refits return the provider's prediction for its fitted rows. -
New points. Run
kernel_prep()at the new points with the fitted kernel,max_D, and covariate definitions, then supply the matchingnewdata. For the refit backend, supply both or neither. -
A map. Smooth and standardize the raster with
kernel_scale.raster(), then pass the result asnewdata.
New kernel-weighted values are standardized with the fitted data's mean and
sample standard deviation. They are never standardized within the
prediction sample. Every non-spatial variable named in the formula must be
supplied in newdata. Values are not borrowed from the formula
environment. For the analytic backends, new factor levels, missing values,
and unmatched point IDs are errors. Use literal constants in transform
arguments, such as poly(z, 2). Preparing distance bins again at new
points can shift their representative distances slightly, so a prediction
at a fitted location can differ slightly from the fitted value.
Match the fitted formula
Fixed transformations, factor contrasts, and offsets follow the fitted
terms. For ordinary lm, glm, MASS::glm.nb, and time-fixed,
unpenalized coxph and clogit refits, prediction uses the original
fitted terms. A dot shortcut such as ~ . keeps its fitted meaning, and
new data columns never enter the design. Variables removed with a minus
term need no prediction column, while active interactions and offsets keep
their inputs. The original coefficients, covariance, factor coding, and
learned transformations are retained. Other native subclasses use their
provider's own prediction path. unmarked::pcount() (version 1.5.2)
rejects dot formulas when fitting, so write unmarked component formulas
explicitly.
Standard scale(), poly(), splines::ns(), and splines::bs() calls,
including namespace-qualified calls, keep their training constants (center
and spread, polynomial coefficients, spline knots) for supported LM, GLM,
GAM, lme4, glmmTMB, time-fixed unpenalized Cox, and ordinary unmarked
occupancy and count predictions. New rows never relearn them, and a single
new value or a constant raster does not define a new standard deviation.
Nested expressions such as I(scale(z)^2) and transformed formula offsets
recover one standard learner per evaluated predictor from its retained
attributes, using an aligned evaluated training frame. Missing or ambiguous
attributes, several learners in one predictor, and unsupported
transformations need precomputed training predictors or complete saved
prediction calls. Scaling arguments keep their original order and standard
abbreviations. Custom functions keep their own semantics. Legacy analytic
fits can recover this metadata, but numerical snapshots from
prepare_prediction() must be prepared again.
Analytic GLM backends
For "profile_glm" and "joint_nb2", standard errors use the delta
method. With uncertainty = "joint", they include the derivative of each
prediction with respect to the kernel scales and shapes, including how the
training mean and standard deviation change with scale. Confidence limits
are computed on the link scale and then transformed, and response-scale
standard errors are abs(d mu / d eta) times the link-scale standard
error. Binomial response predictions are probabilities.
Joint uncertainty is refused for fits at a parameter bound or with weak
identifiability. fit$uncertainty$reasons says why, and point predictions
and conditional uncertainty remain available. At the exact Poisson
boundary of a "joint_nb2" fit, point predictions and explicitly
conditional intervals hold both the scales and the Poisson dispersion
boundary fixed. Use vcov.multiScaleR() for the covariance matrices.
The native model in fit$opt_mod is a conditional GLM. Its own prediction
methods expect kernel predictors that are already standardized and do not
include scale uncertainty.
Conditional logistic backend
For "conditional_logit", type = "response" returns probabilities
normalized within each supplied choice set. They are not occurrence
probabilities or a utilization distribution. type = "link" returns the
linear predictor, including formula offsets, and differences within a set
describe relative selection. type = "risk" returns exp(link), a
relative selection score. Link and risk predictions at new points need
matching spatial inputs and every fixed formula input, but no choice-set
IDs. Response predictions also need explicit choice-set IDs, at least two
alternatives per set, and complete choice sets that you define.
se.fit = TRUE requires uncertainty = "conditional". Risk standard
errors are risk x SE(link), and response standard errors use the delta
method through the within-set normalization. Intervals and joint
uncertainty are unavailable. Formula offsets and training standardization
are preserved. The native fit$opt_mod prediction methods use their own
survival conventions and require already standardized covariates.
Joint mixed backend
For "joint_mixed", prediction delegates to the final native glmmTMB
model at the selected scales, with type = "response" or "link".
Standard errors require uncertainty = "conditional" and exclude scale
uncertainty. This wrapper provides no confidence intervals. For new rows,
supply both newdata and matching kernel_inputs, including every
fixed-effect, offset, and grouping variable. Kernel means need binned
summaries, and weighted surface SQ needs matching source specifications,
raw cell buffers, and row IDs. Spatial columns are recomputed with the
training mean and standard deviation.
Additional arguments, such as re.form and allow.new.levels, follow
native glmmTMB behavior. The default includes the fitted random effects,
and re.form = NA sets them to zero without integrating over their
distribution. Use native predict(fit$opt_mod, ...) for other glmmTMB
prediction types, or bind one with prepare_prediction().
Native refits
The default "refit" backend returns the provider's own prediction for
the model in fit$opt_mod, with spatial means and metrics recomputed from
matching source definitions, prepared rows, physical distance units, and
the selected scales. Unused prepared variables are ignored. Supply both
newdata and kernel_inputs, or omit both for the fitted rows. Explicit
join_by keys let several prediction rows share one site.
Standard errors require uncertainty = "conditional" and a provider that
supplies them. An unsupported native standard-error request raises an
error rather than returning zero. The wrapper's own interval must stay
"none". Native covariance, variance, and interval controls also require
uncertainty = "conditional", even with se.fit = FALSE, and cannot add
uncertainty in the kernel parameters. Cross-row native covariance, such as
glmmTMB's cov.fit = TRUE, needs point predictions, which keep the native
covariance output.
-
Linear models. For an ordinary
lmrefit,native_args = list(interval = "confidence", level = 0.9)returns native confidence limits for the mean, andinterval = "prediction"within that list returns limits for a future observation, including the residual variance. Both keep the nativefit,lwr, anduprcolumns for points and maps. -
Random effects. Native random-effect controls keep their meaning. For glmmTMB and lme4,
re.form = NAsets the random effects to zero. For nlme, usenative_args = list(level = 0). Zero-effect predictions can omit random-only grouping and slope inputs, but every fixed predictor and offset remains required. For partial lme4re.formformulas, supply the fixed predictors and the grouping and slope variables of the selected effects. Native validation still checks that the selected effects belong to the fitted model. -
spaMM. spaMM refits use their retained native model frames to verify fixed features. Zero and selected
re.formpredictions need only the fixed inputs and the selected random-effect inputs. The genericse.fitinterface is unavailable when the native method does not return a standard-error list. Nativevariancesandintervalsattributes keep their own scales and targets and require point predictions.fixefVarandpredVarare on the linear-predictor scale.residVarandrespVarare on the response scale and include observation noise. -
Cox models. Predictions are linear predictors (
"lp", also selected bytype = "link") or relative risks ("risk"). Neither is a probability. Use the"conditional_logit"backend for choice-set probabilities.
Predict from unmarked models
Name the component with type, such as "state" or "det".
multiScaleR-prediction lists what each component means. Supply
newdata in the row layout that native unmarked prediction expects for
that component, with row names that match the prepared point IDs or with
explicit join_by keys. See prepare_unmarked_data() for the key and
fixed-radius rules. Without
se.fit, the result is the vector of native Predicted values. With
se.fit = TRUE and uncertainty = "conditional", it is the native table
with confidence limits at the native level.
Ordinary occupancy and pcount state and detection predictions freeze
supported fixed scaling, polynomial, and spline terms from the original raw
covariates before site removal, including nested calls and formula
offsets. Keep those original covariates and the fitted designs. The
reconstructed designs and offsets must match the native fit before new rows
are evaluated. This check preserves the fitted target, but it cannot
detect edits to raw data that leave the evaluated design unchanged. Factor
contrasts use retained metadata, or original columns for factor main
effects when those recover the coding exactly. Other missing coding needs
explicit saved training contrasts.
For explicit data-frame rows, only the requested component's training
metadata is prepared. Raster chunks and effect curves reuse that
component's checked basis. A native unmarkedFrame input, or an omitted
newdata, keeps both components, because native missing-row removal
depends on both designs. Derived ZIP means and limits still use the native
zero-inflation estimate and covariance, and the full model's parameter
count and diagnostics are unchanged. Native observation rows, missing-site
handling, and confidence levels stay native, and frame subsets keep their
original known-group columns.
Conditional predictions with learned random-effect terms need precomputed
original training predictors. Zero-effect requests do not evaluate those
unused terms or need new random-only grouping or slope inputs. unmarked
treats every non-NULL re.form as zero random effects. It does not
select partial effects or integrate over them. Other unmarked classes
keep their provider's prediction requirements.
Qualified gdistremoval() predictions keep the original "lambda",
active "phi", "dist", and "rem" component recipes, with their native
site, primary-period, and removal-interval rows. Native C and TMB designs
are checked before frozen scaling, polynomial, spline, or factor
interaction terms are used. Points, prepared outputs, effect curves, and
raster chunks share these terms. Rows for one component need only that
component's inputs, and native GDR frames keep their native layout and
missing-covariate checks. Native component covariance and conditioning are
unchanged, and zero effects do not integrate over unknown groups.
Recompute fixed-radius predictors
By default, declared fixed-radius predictors are inputs you supply in
newdata. For the analytic, conditional logistic, joint mixed, and refit
backends, include_fixed = TRUE recomputes them from matching spatial
inputs instead. Their original prepared values and training means and
sample standard deviations must first be verified against the retained
native model frame. Source, metric, radius, kernel, resolution, buffer
extent (max_D), and observation-to-site alignment must match. Fixed radii
add no scale parameters or uncertainty.
Predict across a raster
First call kernel_scale.raster() with the fitted object,
scale_center = TRUE, and match_buffer = TRUE. match_buffer = TRUE
needs square cells in a projected or local planar coordinate reference
system, at the prepared resolution.
Modeled fixed-radius metrics also require include_fixed = TRUE there.
Set categorical and other non-spatial scenario values with site_values,
and offset inputs with offset_values. A simple log() offset defaults to
a raw value of 1 and a direct offset to 0, and a compound offset such as
offset(log(effort * duration)) needs explicit values. Logical predictors
are coded 0 and 1 in the raster and regain their fitted type during
prediction. The descriptor attached to the raster checks scales, source and
metric definitions, normalization, and support against this fit. It does
not rebuild a lost descriptor or establish that the maps have the right
scientific provenance. Recompute the raster after editing cells or saving
it in a file format that drops R attributes.
Raster standard errors are conditional on the selected kernel parameters,
with interval = "none". Analytic GLM maps use the same coefficient
information as point predictions. Other maps use native prediction, and
native matrix components return one layer per column, with standard-error
layers in the same column order. Cox maps default to linear predictors.
Conditional logistic maps need type = "link" or "risk", because choice
probabilities need complete point choice sets. unmarked maps need an
explicit component. Native cross-row covariance (cov.fit = TRUE) and
spaMM variance or interval attributes are rejected, because raster chunks
cannot keep them. Supply native controls in native_args. A raster
prediction from one set of selected scales is not a Bayesian posterior map.
The raster_args list accepts filename, overwrite, wopt, const,
cores, na.rm, and field_geometry. cores defaults to one worker,
and clusters created internally are stopped on exit. field_geometry
takes a checked response_field_geometry() descriptor, as described in
"Spatial response fields". Rasterization, distance binning, and partial source
coverage remain separate approximation choices.
Spatial response fields
Native glmmTMB exponential, Gaussian, and Matern response fields keep their
provider predictions and mean-prediction standard errors at the selected
kernel scales. Conformance checks cover Gaussian, log-Poisson,
logit-binomial, log-NB2, and log-Gamma responses with one shared projected
field without a year effect. Supply the native coordinate factor and
grouping columns explicitly, including new glmmTMB::numFactor()
positions and allow.new.levels = TRUE when appropriate. A field's
covariance range is distinct from the ecological kernel scale.
re.form = NA sets the response random effects to zero without
integrating over their distribution. These checks do not qualify scale
recovery, interval coverage, or a spatial field in the "joint_mixed"
likelihood. A full raster needs matching field coordinates in each cell,
which a constant site scenario does not provide. Use explicit native point
rows or raster_args = list(field_geometry = ...) for coordinate-aware
maps. That route requires a matching projected coordinate reference
system, uses cell-center coordinates and one worker, limits native batch
expansion to an explicit working-memory budget, and needs
allow.new.levels = TRUE in native_args for new positions.
Identified native TMB gdistremoval() response-field models keep their
conditional component predictor and full joint covariance through the
unmarked adapter. New abundance coordinates require the fitted projected
coordinate reference system. Field maps need a checked geometry descriptor
and type = "lambda", and they run on one worker, including zero-effect
references. The residual field variance at new locations is distinct from
observation noise and from ecological-scale uncertainty.
GAM and BAM predictions
GAMs with several linear predictors keep each component's terms,
coefficient spans, and native output columns. Response columns keep the
fitted family's meaning. For example, the second mgcv::gaulss() response
column is a reciprocal standard deviation, and multinomial response columns
are category probabilities. For mgcv::ziplss() response predictions, the
native mean is unchanged, and its standard error propagates the full native
coefficient covariance through both predictors, keeping signed
cross-covariance. It omits count noise and ecological-scale uncertainty.
Custom family prediction hooks remain guarded.
Native term selection, exclusions, and smoothing-parameter covariance
requests (unconditional) keep their native behavior, and none adds
uncertainty in the selected scales. Package predictions keep the saved
factor coding of interaction-only terms when session contrast options
change. BAM predictions keep the native discrete and block algorithms,
restore fitted coding in serial and native worker calls, and pass explicit
term exclusions and controls such as iterms.type and unconditional to
those workers. Worker mgcv versions must match the parent. Optimized
discrete predictions for binomial and Poisson BAMs keep their native
values, warnings, and output geometry across point, snapshot, and raster
routes, including the native warning that resets iterms to terms. Set
discrete = FALSE for ordinary iterms. Native warnings, such as one for
selecting terms from a model without parametric coefficients, reach the
calling session with their native meaning.
See Also
multiScaleR-prediction for the quantity and uncertainty of each
route, vcov.multiScaleR() for the covariance matrices,
prepare_prediction() for repeated summaries of fixed rows,
prepare_unmarked_data() for keyed unmarked prediction rows,
kernel_scale.raster() for prediction rasters, plot_marginal_effects()
for effect curves, and multiScale_optim().
Examples
## Running example: counts at 100 survey points and two landscape layers
data("landscape_counts")
data("surv_pts")
pts <- terra::vect(surv_pts)
land <- terra::rast(system.file("extdata", "landscape.tif",
package = "multiScaleR"))[[c("land1", "land2")]]
## The simulated layers are in meters but carry no coordinate reference
## system. Declare a local planar one so raster prediction can check cells.
terra::crs(land) <- "local"
terra::crs(pts) <- "local"
## bin = TRUE stores the distance bins that the analytic backend needs
inputs <- kernel_prep(pts, land, max_D = 1700, kernel = "gaussian",
bin = TRUE, verbose = FALSE)
dat <- data.frame(landscape_counts, inputs$kernel_dat)
start <- glm(counts ~ site + land1 + land2, family = poisson(), data = dat)
fit <- multiScale_optim(start, inputs, backend = "profile_glm",
n_cores = 1, verbose = FALSE)
## Expected counts at the first three survey points
predict(fit)[1:3]
## 95% limits for the expected count. Joint limits let the scales vary,
## conditional limits hold them at their estimates.
joint <- predict(fit, interval = "confidence")
cond <- predict(fit, interval = "confidence", uncertainty = "conditional")
round(cbind(expected = joint$fit,
joint_lower = joint$lower, joint_upper = joint$upper,
cond_lower = cond$lower, cond_upper = cond$upper)[1:3, ], 2)
## Back-transform a link-scale prediction yourself: exponentiate the
## estimate and its limits, never the standard error. This reproduces the
## joint limits for the first point.
eta <- predict(fit, type = "link", se.fit = TRUE)
exp(eta$fit[1] + c(-1, 1) * qnorm(0.975) * eta$se.fit[1])
## New points: prepare their landscape with the fitted settings, then give
## site values whose row names ("1", "2", "3") match the prepared point IDs
new_inputs <- kernel_prep(pts[1:3], land, max_D = 1700, kernel = "gaussian",
bin = TRUE, verbose = FALSE)
new_sites <- data.frame(site = c(-1, 0, 1))
predict(fit, new_sites, new_inputs, se.fit = TRUE)
## Map the expected count and its conditional standard error. The site
## layer holds the mean of site, so the map describes an average site.
layers <- kernel_scale.raster(land, multiScaleR = fit, scale_center = TRUE,
match_buffer = TRUE, verbose = FALSE)
count_map <- predict(fit, layers, se.fit = TRUE, uncertainty = "conditional")
terra::plot(count_map)
Predict Means from a Bayesian Scale Model
Description
Predict expected responses, or linear predictors, at fitted or new observations. Each prediction carries the joint posterior uncertainty in the scales, the coefficients, and the random effects. A site or year that was not in the fitted data needs an explicit choice, either drawing its effect from the estimated spread among groups or setting it to zero.
Usage
## S3 method for class 'multiScaleR_bayes'
predict(
object,
newdata = NULL,
type = c("response", "link"),
re.form = NULL,
summary = TRUE,
level = 0.95,
draws = NULL,
kernel_inputs = NULL,
row_id = NULL,
scale_re.form = NULL,
new_scale_levels = c("error", "sample", "zero"),
new_response_levels = c("error", "sample", "zero"),
seed = NULL,
include_fixed = FALSE,
...
)
Arguments
object |
A fitted |
newdata |
|
type |
|
re.form |
|
summary |
Logical. |
level |
Probability of the central interval; default 0.95. |
draws |
Optional positive integer number of evenly spaced posterior
draws to use. The default |
kernel_inputs |
Prepared landscape inputs for |
row_id |
Name of the column in |
scale_re.form |
|
new_scale_levels, new_response_levels |
What to do with a group level
that was not in the fitted data, set separately for scale and response
random effects. |
seed |
Optional positive integer seed for sampled new effects. Your own random-number state is restored afterward, even when prediction fails. |
include_fixed |
Logical. With new data, |
... |
Not used. Supplying any further argument is an error. |
Value
With summary = TRUE, a data frame with one row per observation,
in the supplied order.
-
row: the position of the observation. -
point_id: its prepared landscape ID. -
mean,median,sd,lower,upper: summaries of the predicted quantity on the scale set bytype.lowerandupperbound the centrallevelcredible interval. -
new_scale_level,new_response_level(new data only): whether the row belongs to an unseen group of an included scale or response component.
With summary = FALSE, a numeric matrix with one row per posterior draw
and one column per observation.
Results for new data carry a new_groups attribute, a data frame with
component, covariate, group, level, and action that lists each
unseen level and whether it was sampled or set to zero. Summaries also
carry a prediction_contract attribute that describes the target, the
included effects, the uncertainty, and the stored parameter map (see
prediction_contract). Its diagnostic status repeats the fit's own
status. Prediction does not make a failed fit eligible.
What the intervals include
Intervals describe uncertainty in the expected response or the linear
predictor. They include uncertainty in the scales, the coefficients, and
the fitted group effects, and, when new effects are sampled, the variation
among new groups. They leave out the scatter of a single new observation
around its mean. Use simulate.multiScaleR_bayes() for that. Each interval
is marginal for one observation, not a simultaneous band. mean and sd
summarize a finite set of draws and do not show that the corresponding
moment exists, so prefer the median and the interval limits for
long-tailed predictions.
Match new rows to their landscapes
kernel_inputs supplies the prepared bins for the prediction locations and
maps. Each prepared location has one unique entry in binned$point_ids,
and row_id matches every row of newdata to one of them. Rows can come
in any order and can repeat, as for repeated visits to one location. Build
the inputs with kernel_prep() or kernel_prep_by_group(), as in
vignette("v06-year-specific-rasters", package = "multiScaleR"). Keep the
fitted kernel, predictor definitions, and projected map units. The
numerical distance normalizer unit_conv may differ and is converted
internally, but that does not convert coordinate systems or physical
units. Kernel means need bins. Weighted SQ needs matching source and
metric specifications and the raw cell buffers.
Prediction reuses the fitted reference center and spread, the contrasts,
and the formula bases. It never standardizes the new rows on their own,
never learns a new scale reference, and never refits the model or uses
responses in newdata. A new kernel uses only the neighborhood you
prepared, so a predicted scale larger than max_D cannot draw on cells
beyond it.
Choose how to treat new groups
vignette("v14-bayesian-prediction", package = "multiScaleR") compares
the choices in a table. A few rules matter for every call. An unseen level
of a fixed year factor, such as factor(year), is always an error, under
every policy. To predict response years you have not surveyed, use a
random intercept for year or a scientifically justified numeric trend.
Exchangeable annual effects impose no trend or autocorrelation.
predict_scales() can still predict a new year's scale when the response
formula has fixed year effects. Setting new effects to zero is not
integration over group variation, and with a nonlinear link or kernel the
two predictions generally differ. Grouping columns used only by a
component you leave out with re.form = NA or scale_re.form = NA may be
absent from newdata.
Predict jointly across rows
Put every row whose joint prediction matters into one call. Within a call,
all new rows in the same grouping term and level share one new effect for
each posterior draw. Distinct terms and groups follow the model's
conditional independence, and the joint posterior dependence among
parameters is kept. Separate calls draw separate new effects, so do not
combine independently generated batches to infer joint spatial or annual
uncertainty or a total. For a total of expected values, set
summary = FALSE and sum each row of the matrix with rowSums().
The full matrix of draws by observations is built even when
summary = TRUE, at 8 bytes per value. When you need only an interval for
each location of a large map, predict smaller batches and keep their
summaries, or lower draws at a cost in simulation precision.
Use formula transformations safely
scale(), poly(), splines::ns(), and splines::bs() keep their
training definitions inside ordinary expressions such as I(scale(temp))
and in transformed offsets, so single rows, batches, and effect curves use
the same constants. An expression such as I(x - mean(x)) instead takes
its mean from the new batch, by ordinary R formula rules. Compute such a
covariate with training constants before fitting when you need the
original centering. Transforms must come from base R or stats, or carry an
explicit package namespace. Custom functions defined only in the fitting
workspace are not saved with the model, so compute them as covariate
columns instead. New levels of a fixed factor are always rejected. For
fits saved without design metadata, the rebuilt formula must reproduce the
stored training matrix from the original data, or prediction stops. Give
a namespace prefix to any custom function that reuses a learner name such
as scale.
Know what prediction cannot fix
Prediction passes the fitted posterior forward. It does not repair failed
sampling, an inaccurate approximation, or a misspecified observation
model, and it does not check the fit's diagnostics, so inspect
summary(object)$diagnostics first. Every method uses its stored joint
draws. For an importance-corrected fit these are resampled candidates, so
prediction has the finite precision of those resamples rather than a fresh
weighted integration.
Prediction stops on unmatched IDs, new fixed-factor levels, unavailable formula transforms, incompatible kernel inputs, and nonfinite results. It never clips scales to the input limits or replaces a problematic draw.
To test predictions, hold out data at the level you intend to predict. A
held-out visit at a known site and year is easier to predict than a whole
new site or year, and repeated sites or years are not independent
validation replicates. cross_validate_bayes() refits the model without
the held-out rows and scores them.
See Also
multiScale_bayes(), multiScaleR_bayes,
posterior_scales(), prediction_contract, predict_scales(),
simulate.multiScaleR_bayes(), cross_validate_bayes(),
multiScaleR-prediction for prediction across the package;
vignette("v14-bayesian-prediction", package = "multiScaleR").
Examples
example <- readRDS(system.file("extdata", "bayesian-annual-example.rds",
package = "multiScaleR"))
fit <- example$fits$pooled
fitted_means <- predict(fit, draws = 100)
head(fitted_means[c("point_id", "median", "lower", "upper")])
# Expected counts at the fitted rows, including fitted site effects.
# The draw limit keeps this demonstration short. Use all draws for
# final summaries.
# New surveys at known site-years reuse their annual maps and group effects
new_surveys <- example$data[1:3, c("site", "year", "site_year")]
predict(fit, new_surveys, kernel_inputs = example$inputs,
row_id = "site_year", draws = 100)
# simulate() would add the scatter of individual counts.
# A fit with random year intercepts can predict new sites and years
forecast <- readRDS(system.file("extdata", "bayesian-prediction-example.rds",
package = "multiScaleR"))
future <- predict(forecast$fit, forecast$newdata,
kernel_inputs = forecast$kernel_inputs, row_id = "site_year",
new_scale_levels = "sample", new_response_levels = "sample",
draws = 200, seed = 802)
future[c("point_id", "median", "lower", "upper", "new_response_level")]
attr(future, "new_groups") # the unseen levels and what was done to them
Predict Landscape Scales for New Covariates and Groups
Description
Carry joint posterior uncertainty into the scale of each landscape predictor at new values of the scale-formula covariates, including years that were not surveyed when the scale formula has a random year effect. This predicts the scale itself, so no prepared landscape is needed.
Usage
predict_scales(
object,
newdata,
new_levels = c("error", "sample", "zero"),
re.form = NULL,
level = 0.95,
draws = NULL,
summary = TRUE,
scale = c("distance", "log"),
seed = NULL
)
Arguments
object |
A fitted |
newdata |
A nonempty data frame that holds the fixed scale-formula covariates and the grouping variables of any included scale random effects. Responses, response-only covariates, and prepared landscape bins are not needed. |
new_levels |
What to do with a scale group level that was not in the
fitted data. |
re.form |
|
level |
Probability of the central interval; default 0.95. |
draws |
Optional positive integer number of evenly spaced stored
posterior vectors to use. The default |
summary |
Logical. |
scale |
|
seed |
Optional positive integer seed for sampled new effects. Your own random-number state is restored afterward, even when prediction fails. |
Value
With summary = TRUE, a data frame with one row per landscape
predictor and distinct active combination of scale covariates and groups.
-
covariate: the landscape predictor. -
group: a label for the covariates and groups of the row, such as"year=2026". -
row: a representative row ofnewdata. -
new_level: whether the row contains an unseen scale group. -
distribution: which question the row answers. See "Read the distribution column". -
mean,median,sd,lower,upper: summaries of the draws on the requested scale, with the centrallevelinterval. Prefer the median and the limits for distances. Seeposterior_scales()for why the arithmetic mean and SD of a distance can be poorly defined. -
p_below_min_D,p_above_max_D: the probability that the scale lies belowmin_Dor abovemax_Dof the fitted inputs. See "Read the support columns".
With summary = FALSE, a named list with one numeric matrix per
landscape predictor. Each matrix has one row per posterior vector and one
column per row of newdata, in the supplied order. Rows in the same new
group share its effect.
Both forms carry a new_groups attribute with component, covariate,
group, level, and action, listing the unseen levels that were
sampled or set to zero. Summaries also carry a prediction_contract
attribute (see prediction_contract) that describes the target, the
included scale effects, and the uncertainty. It does not establish
diagnostic eligibility or calibration.
Read the distribution column
-
"conditional_posterior": a surveyed group, using its estimated deviation. -
"new_group_predictive": the range of scales a new group could have. Its interval carries uncertainty in the typical scale and in the between-group SD, plus the variation among groups. It is a marginal prediction interval, not a simultaneous band and not an estimate of a new year's scale after its responses are observed. -
"zero_deviation_reference": the new group placed exactly at the typical scale (withnew_levels = "zero"), or every group withre.form = NA. Its interval keeps uncertainty in the typical scale but leaves out variation among groups, so it is narrower without being a more precise forecast.
The zero-deviation reference is not the average scale over years. With
\log D_y = a + \tau z_y, even for fixed a and
tau the mean of D_y over years is
\exp(a + \tau^2/2), while the zero-deviation
scale is \exp(a). Averaging over the uncertainty in a and tau
also depends on their posterior dependence.
Read the support columns
p_below_min_D and p_above_max_D refer to the range of the fitted
inputs. They say nothing about the coverage of a future map you have not
supplied. The distance priors have no upper or lower bound, so these
probabilities matter when much of the posterior lies outside the distances
your maps resolve. A scale below min_D is finer than one raster cell.
To check a future map, compare the scale draws with that map's max_D.
The scale parameter is not the reach of the kernel. Under an ideal,
untruncated planar kernel, the radius that holds 95% of the weight is
kernel_dist(prob = 0.95, sigma = 1, kernel = fit$specification$kernel)
times the scale. The examples compute both probabilities. Neither measures
actual cell coverage near raster edges or gaps, which you should inspect
separately. A smaller future buffer renormalizes a more truncated kernel.
If larger neighborhoods are scientifically needed, rebuild comparable
fitting and prediction inputs and refit, rather than changing the
predictor's support only at prediction time.
Predict new groups jointly
A new year's sampled effect is shared by all of that year's rows within one posterior vector. Different new years are independent given the population parameters, whose posterior dependence is kept. Effects for separate model components follow their specified independence. Separate calls draw separate new effects, so put rows that belong together in one batch. Exchangeable annual effects impose no temporal autocorrelation. A fitted numeric trend extrapolates under that trend assumption, and an unseen level of a fixed year factor is an error.
Know the limits
The method uses the stored joint draws, which for an importance-corrected
fit are stored resamples. It adds no posterior information and does not
validate a failed fit. A nonfinite distance stops with an error, so use
scale = "log" for extreme scales. Fitted contrasts and prediction-aware
bases such as scale(), poly(), and the splines keep their training
constants, including inside nested expressions such as I(scale(temp)).
Fits saved by older versions need verified recovery from the original
training data. An expression such as I(x - mean(x)) takes its mean from
the new batch by ordinary R formula rules, so use a prediction-aware basis
or precomputed training constants when the original centering matters.
Formula transforms must come from base R or stats, or carry an explicit
package namespace.
See Also
posterior_scales(), prediction_contract,
predict.multiScaleR_bayes(), simulate.multiScaleR_bayes(),
kernel_dist(), multiScaleR_bayes;
vignette("v14-bayesian-prediction", package = "multiScaleR").
Examples
example <- readRDS(system.file("extdata", "bayesian-prediction-example.rds",
package = "multiScaleR"))
fit <- example$fit # habitat scale varies among years 2021 to 2025
years <- data.frame(year = c("2025", "2026")) # 2026 was not surveyed
# A surveyed year, then a new year drawn from the spread among years
predict_scales(fit, years, new_levels = "sample", draws = 500,
seed = 801)[c("group", "distribution", "median", "lower", "upper")]
# The reference: the new year placed at the typical scale
predict_scales(fit, years[2, , drop = FALSE], new_levels = "zero",
draws = 500)[c("group", "distribution", "median", "lower", "upper")]
# Can a future map of the same extent hold the new year's kernel?
log_D <- predict_scales(fit, years[2, , drop = FALSE], new_levels = "sample",
scale = "log", summary = FALSE, draws = 500, seed = 806)$habitat
max_D <- example$kernel_inputs$max_D # 1200 m for the future inputs
radius_per_D <- kernel_dist(prob = 0.95, sigma = 1,
kernel = fit$specification$kernel)
mean(log_D > log(max_D)) # scale itself beyond max_D
mean(log_D + log(radius_per_D) > log(max_D)) # 95% radius beyond max_D
# The second probability is larger, because the kernel reaches past its
# scale parameter.
Read prediction contracts
Description
A prediction contract is a list of metadata that travels with a prediction. It names the quantity that was predicted, its scale, how random effects were treated, and which uncertainty the standard errors or intervals include and leave out. Read it when you are unsure what a result describes. A contract describes a calculation. It does not certify that a fit is eligible for prediction or that an interval is calibrated. multiScaleR-prediction explains the quantities and uncertainties that the fields name.
Find the contract
| Result | Where the contract is |
Snapshot from prepare_prediction() | snapshot$prediction_contract, a named list with one contract per prepared output type, such as $response and $link |
Native refit prediction from predict.multiScaleR() | attr(result, "prediction_contract") |
Raster prediction from predict.multiScaleR() | attr(map, "prediction_contract"), beside the projection_contract attribute |
Effect curves from plot_marginal_effects() for unmarked, glmmTMB, lme4, multi-component GAM, and Bayesian fits | attr(curves, "prediction_contract") |
Bayesian summaries and simulations from predict.multiScaleR_bayes(), simulate.multiScaleR_bayes(), and predict_scales() | attr(result, "prediction_contract")
|
Point predictions from the analytic backends return plain vectors or lists without a contract. Prepare a snapshot to get one. Raw posterior draw matrices and lists keep their existing attributes, and native numerical outputs inside a snapshot keep their native attributes.
Read the fields
-
schema_version: version of the metadata structure. -
inference_target,method: the posterior, likelihood, conditional likelihood, or native target, and the label of the computation that produced it. -
quantity,output_scale: what the numbers are, on the stated scale. The quantity is an expected response, a linear predictor, a kernel scale, a contrast between kernel scales, a replicate response, a choice probability, or a named native component. Native component meanings remain model specific. -
target_population: the supplied prediction rows, or the specified location pairs for private spatial scale contrasts. -
effects: the policy for known and unseen groups. Zero deviations ("zero_deviation_reference") are reference values, not integration over the group distribution. Sampled new effects are shared by each group's rows within a complete joint vector. -
conditioning,integration: the quantities held fixed and the recorded treatment of uncertainty. Missing historical solver metadata is marked as unrecorded rather than inferred. -
uncertainty: the treatment of the population and kernel parameters, whether observation noise is included (observation_noise), what the intervals mean, what is omitted (omitted), andcalibration, which is always"not_established". Analytic snapshots also record whether joint covariance was available at preparation (joint_available). This does not bypass the covariance checks inpredict.multiScaleR(). -
original_coordinates,joint_parameter_map_complete: the parameter representation used by the adapter. For Bayesian predictions, completeness checks the stored block dimensions against the original prepared parameter map. This structural check does not validate a coordinate transformation, reconstruct integrated coefficients, or establish posterior accuracy. -
diagnostics_status: the existing fit status when available,"passed","failed", or"unavailable". Joint covariance availability is separate from this status. -
kernel_support: for native predictions, any recoverable table of optimization bounds and the existing extraction-window diagnostic. These flags qualify the selected kernel. They do not add kernel uncertainty, alter conditional coefficient standard errors, or establish prediction eligibility. -
metadata_establishes_eligibility: alwaysFALSE. Read the original fit diagnostics before you interpret predictions. -
fixed_inputs,component: whether the rows and controls are bound to a snapshot, and the named component when one applies.
Read the uncertainty record
Expected-response intervals exclude observation noise, and replicates include it. New-group predictions also carry the group variation you requested. Native confidence intervals and standard errors condition on the selected kernel parameters. Likelihood summaries conditional on one population parameter vector omit its estimation uncertainty.
Native point and raster contracts record
uncertainty$standard_errorsas"provided"or"not_requested", and separately keepse.fit_requested. Provider controls such as glmmTMB'scov.fitcan return standard errors even when the wrapper'sse.fitisFALSE. Returned native covariance is conditional on the selected kernel parameters.spaMM variance attributes keep their native meaning and are listed in
native_variances, with their numerical attributes unchanged.fixefVarandpredVarare on the linear-predictor scale.residVarandrespVarare on the response scale, and the response variance includes observation noise, which is distinct from uncertainty in the mean.Native interval attributes are listed in
native_intervalsand keep the provider's target. Nativelminterval columns record"native_mean_confidence"or"native_prediction_interval"and the boundinterval_level. Only the prediction interval includes future-observation noise. Both include native parameter uncertainty and hold the selected kernel fixed.Native
mgcv::ziplss()response means combine both linear predictors. Their standard errors propagate the full native coefficient covariance through that mean, keeping signed cross-covariance. The contract records this asresponse_standard_error_method, distinct from the provider's own response standard-error formula. Kernel uncertainty and count noise remain omitted, and native smoothing-covariance requests keep their meaning.Refit snapshot contracts describe their cached point output, and
conditional_se_availablerecords whether a cached standard-error request succeeded.unmarkedsnapshots describe the retained native confidence tables. Mixed native snapshots keep both point and standard error choices, and"selection_by_request"identifies that capability. None of these fields certifies finite standard errors, covariance eligibility, or calibration.
Random effects in unmarked contracts
unmarked treats any non-NULL re.form as zero random effects. The
contract records zero deviations and no integration for that request,
including formula controls that other providers use to select some
effects. Native argument abbreviations are resolved before this policy is
recorded. Zero-effect contexts do not evaluate unused random
transformations or add latent variation. Conditional requests still need
their original random-design metadata.
Choice sets and selection scores
Conditional logistic linear predictors and exponentiated relative selection scores need no prediction choice sets. Choice probabilities need complete sets. A snapshot can keep the reason probabilities are unavailable while its link and risk outputs remain available. Relative scores are not occurrence probabilities or utilization distributions.
Spatial response fields
Native glmmTMB response and link predictions with recognized exponential,
Gaussian, or Matern response covariance add response_spatial_field. It
records the provider and layout status, the conditional-response
component, and each field's native term, covariance, coordinate and
grouping variable names, number of locations, independent fields, and
covariance-parameter count. Conditioning records either the native
spatial prediction or all response random effects set to zero.
New-location controls keep their native meaning. Coordinate units are not
inferred from factor labels. The field range is distinct from the
ecological kernel scale, and kernel uncertainty is not included.
Identification checks the provider's registered covariance codes and the
fitted block layout. Coordinate-aware field maps also record geometry:
the projected coordinate reference system and units, native column names
and shared group, reference and context hashes, serial batch size, and
memory budget. Cell centers supply the coordinates, and the working-memory
estimate is not an operating-system memory cap.
Identified native gdistremoval() response fields record a fixed
correlation range, conditional physical abundance effects, and a distinct
residual variance at new locations. Their standard errors keep the full
fitted fixed and latent covariance. Density point predictions are
inverse-link conditional predictors, not lognormal field averages. These
native field calculations do not enable the private RTMB fitting route,
field simulation, spatial cross-validation, or ecological-scale
uncertainty.
Spatial-field cross-validation records a joint assessment-response component. It uses exact Gaussian conditioning for Gaussian responses and the Laplace marginal likelihood ratio for other responses. Both include observation noise and conditional field variation at the fitted training parameters. Log-link response moments use exponentially tilted Laplace ratios, and Bernoulli moments use a Gaussian approximation. The predictive standard deviation describes observation variation. For non-Gaussian responses, the contract identifies field variance on the linear-predictor scale and observation variance on the response scale.
Kernel-scale contrasts
Private spatial contrasts use quantity = "kernel_scale_contrast" and
output_scale = "log_ratio" or "ratio". Both locations use the same
complete joint vector. Their intervals summarize the contrasts rather
than differences between marginal interval endpoints. Observation noise
is omitted, and calibration remains unestablished.
Subsets keep the original contract
A contract describes the original prediction call. Ordinary data-frame subsetting can keep the attribute, but it does not recompute the contract for a smaller batch. Use the existing row-level new-group flags for individual rows. No contract establishes interval calibration or upgrades a rejected fit.
See Also
multiScaleR-prediction, prepare_prediction(),
predict.multiScaleR(), predict.multiScaleR_bayes(),
predict_scales(), simulate.multiScaleR_bayes(), and
vignette("v09-estimates-and-intervals", package = "multiScaleR").
Examples
## A stored N-mixture fit used in vignette("v02-user-guide")
nmix <- readRDS(system.file("extdata", "cache-user-guide-nmix.rds",
package = "multiScaleR"))
## A snapshot stores one contract per prepared component
snap <- prepare_prediction(nmix, component = "state")
contract <- snap$prediction_contract$state
contract$quantity # a named native component
contract$uncertainty$kernel_parameters # "fixed_at_estimate": sigma held fixed
contract$uncertainty$omitted # what the limits leave out
## A native refit prediction carries its contract as an attribute
abundance <- predict(nmix, type = "state", se.fit = TRUE,
uncertainty = "conditional")
head(abundance) # expected abundance with 95% limits
attr(abundance, "prediction_contract")$uncertainty$intervals
Convert Linked Bird Records into Paired Distance-Removal Counts
Description
Turn a matrix of bird records, one row per individual at a survey, into the distance and removal count tables of a distance-removal model. The function finds each bird's first detection across all distance bands, including bands beyond the survey radius, before it applies the radius. It keeps every source record, reports what happened to each bird, and never deletes or repairs a record.
Usage
prepare_gdr_histories(
histories,
history_keys,
event_keys,
event_id,
individual_id,
cell_map,
dist_breaks,
radius,
interval_lengths,
interval_units,
units_in,
surveyed,
expected_event_keys = NULL,
native_frame = NULL
)
## S3 method for class 'msr_gdr_histories'
print(x, ...)
Arguments
histories |
Numeric or logical matrix with one row per individual
bird at a survey and one named column per source cell (one distance band
in one time interval). Enter 1 where the bird was recorded and 0
elsewhere. Any other value, including |
history_keys |
Data frame with one row per row of |
event_keys |
Data frame with one row per survey event, in the order the count tables should have. Include completed surveys that recorded no birds. Event keys must be unique. |
event_id |
Character vector naming the column(s) that identify a
survey in both |
individual_id |
Character vector naming the column(s) of
|
cell_map |
Data frame with columns |
dist_breaks |
Increasing distance boundaries of the source bands,
starting at zero, in |
radius |
Survey radius, in |
interval_lengths |
Positive whole numbers giving the duration of each
time interval, in |
interval_units |
Character string naming the time unit, such as
|
units_in |
Distance units of |
surveyed |
Logical vector with one value per event, in event order,
with no |
expected_event_keys |
Optional data frame, built independently, with
the |
native_frame |
Optional single-visit |
x |
A prepared |
... |
Not used. |
Value
A list of class msr_gdr_histories:
-
histories,history_keys,event_keysandcell_map: the inputs, unchanged. -
first: one row per bird, with its row inhistories(.history_row), its event (.event), the first interval with a recorded mark (candidate_interval), the resolved first detection (first_interval,first_distance_bin;NAwhen unresolved), whether the bird is counted (primary_eligible), whether every cell holds a valid 0 or 1 with at most one band per interval (history_complete), whether both hold (complete_history_eligible) and itsstatus(see "Read the status of each bird"). -
events: one row per event, withsurveyed,response_complete(whether its counts are observed),known_first_records(birds counted) andunresolved_first_histories. -
findings: one row per problem, with the history row, the cell (.cell,.column,interval,distance_bin), acodeand the originalvalue. Findings about a whole history have missing cell fields. -
first_cells: counts of first detections by event (rows) and cell inside the radius (columns), ordered by distance band, then interval. -
native_cells: the rows ofcell_mapfor those columns, in the same order. -
yDistanceandyRemoval: the two count tables, events by distance band and events by interval, ready forunmarked::unmarkedFrameGDR(). -
protocol: the source and in-radius distance breaks, the radius, units, interval lengths and the column order offirst_cells. -
surveyed,survey_audit(the audit ofnative_frame, orNULL),fingerprint(a SHA-256 of the inputs) andsummary(counts of histories, events, counted birds, complete histories, invalid cells, unresolved events and birds first detected outside the radius). -
fit_eligibility_establishedanddensity_identification_established: alwaysFALSE. Preparing counts does not show that a model fitted to them is valid.
Printing reports the summary counts and returns the object invisibly.
Errors in the inputs stop with a condition of class
msr_gdr_history_error whose history_rows element lists the rows
involved, when they are known.
Find each bird's first detection
The first detection is found across all source bands before the radius is applied. A bird first recorded beyond the radius stays out of the counts, even if a later mark places it near the point. If a bird has marks in more than one distance band in the same interval, its distance in that interval is not unique. Such marks are kept for review and never collapsed into one band. They may call for a model of movement or of the recording process.
A bird is counted when its first detection is known and inside the radius,
even if a later mark is malformed. That bird is then left out of the
complete-history subset. When a malformed or multi-band mark falls at or
before a bird's first detection, the first detection is unresolved, as it
is for a history with a malformed mark and no detection. The whole event's
counts then become missing, so that an incomplete count
cannot pass as an observed zero. The known partial count stays in
events$known_first_records, and the source rows stay in histories.
Read the status of each bird
status | Meaning |
retained_first | Counted. The history is complete |
retained_first_incomplete_history | Counted, but a later mark is malformed or spans two bands |
first_outside_radius | Not counted. The bird was first detected beyond the radius |
unresolved_first | The first detection cannot be determined. The event's counts are missing |
no_record | No detections were recorded, and every cell is a valid 0 |
unsurveyed_history | The history belongs to an event that was not surveyed |
findings uses the codes invalid_mark (a cell that is not 0 or 1, with
its value), multiple_distance_bins (marks in more than one band in an
interval), and unresolved_first, first_outside_radius and
unsurveyed_history as in the table.
Read the count tables
Summing the columns of first_cells over intervals gives yDistance, and
summing over distance bands gives yRemoval, so the two tables always
have equal row totals. A completed survey with no counted birds has a row
of zeros. An unsurveyed event, or an event with an unresolved bird, has a
row of NA.
Keep the other responses separate
The paired first detections are one response. Complete linked histories of the counted birds, re-detections, and marks beyond the radius are others. Their likelihoods have different constants and conditioning, so they cannot be compared in one AIC table. The time intervals within one count are also not independent visits. Keep the source records for any separate analysis. Better records of the detected birds do not by themselves identify the birds that were never detected.
See the "Prepare your own records" section of
vignette("v12-distance-removal", package = "multiScaleR") for a worked
example.
See Also
validate_unmarked_data(), prepare_gdr_intervals(),
expand_gdr_intervals()
Examples
# Source cells: 2 time intervals by 3 distance bands (0-25 m, 25-75 m and
# beyond the 75 m radius)
map <- expand.grid(interval = 1:2, distance_bin = 1:3)
map$column <- paste0("cell", 1:6)
h <- matrix(0, 2, 6, dimnames = list(NULL, map$column))
h[1, c(5, 2)] <- 1 # Beyond 75 m first, then near: not counted
h[2, 1] <- 1 # Interval 1, 0-25 m: counted
h[2, 2] <- 2 # Malformed later mark: the valid first still counts
prepared <- prepare_gdr_histories(h,
history_keys = data.frame(survey = c("a", "a"), bird = c("one", "two")),
event_keys = data.frame(survey = c("a", "b", "c")), event_id = "survey",
individual_id = "bird", cell_map = map, dist_breaks = c(0, 25, 75, Inf),
radius = 75, interval_lengths = c(75, 75), interval_units = "seconds",
units_in = "m", surveyed = c(TRUE, TRUE, FALSE))
# What happened to each bird
prepared$first[, c("first_interval", "first_distance_bin", "status")]
# Survey b is an observed zero. Survey c was not surveyed, so it is NA
prepared$yDistance
prepared$yRemoval
# Both tables are totals of the same first-detection cells
prepared$first_cells
Add Interval-Level Covariates to a Distance-Removal Frame
Description
Add covariates that can change from one removal interval to the next,
such as who was listening in each interval, to a copy of an
unmarkedFrameGDR. Rows are matched by survey identifier and interval
number, so the input can be in any order, and the alignment is recorded.
Usage
prepare_gdr_intervals(
object,
event_keys,
event_id,
interval_data,
interval_units,
interval = "interval",
site_id = NULL,
effort = NULL,
expected_event_keys = NULL
)
## S3 method for class 'msr_gdr_intervals'
print(x, ...)
Arguments
object |
An |
event_keys |
A data frame with one row per survey event, in the
frame's order (all primary periods of the first frame row, then the
second, and so on). Use the original survey identifiers. The names
|
event_id |
Character vector naming the column(s) of |
interval_data |
A data frame with the |
interval_units |
Character string naming the time unit of the removal
intervals, such as |
interval |
Character string, default |
site_id |
Optional column(s) of |
effort |
Optional numeric vector of survey effort, one value per
event, passed to |
expected_event_keys |
Optional independent event list in frame
order, passed to |
x |
A prepared |
... |
Not used. |
Value
A list of class msr_gdr_intervals:
-
data: a copy ofobjectwith the new observation covariates. -
survey_audit: the result ofvalidate_unmarked_data()for the frame. -
alignment: one row per observation row in frame order, with the event (.event), frame row (.site_row), primary period (.primary), interval (.interval), the matching row ofinterval_data(.input_row,.input_row_name) and theevent_keyscolumns. -
protocol: the survey protocol from the audit (units, distance breaks, interval lengths), plus the frame dimensions, theinterval_column, theadded_columns, any added names that also occur among the site or yearly covariates (shared_site_or_annual_names), whether the input order changed (reordered) and theunmarkedversion. -
fit_eligibility_established: alwaysFALSE.
Printing reports the dimensions and whether the input order changed,
and returns the object invisibly. If the survey audit finds an error, or
the interval rows cannot be aligned, the function stops with a condition
of class msr_gdr_interval_error carrying survey_audit and the
offending input_rows. The input frame is never changed.
How rows are aligned
unmarked orders observation rows by frame row, primary period and then
removal interval, and its own setter for observation covariates does not
check that order. This function checks the keys first. It rejects unknown,
duplicate, missing or extra survey and interval combinations, and any
attempt to overwrite an existing observation column. The event identifier
columns are used only for matching. Every other column of
interval_data, including the interval number, is added.
The counts, existing covariates, distance bands, interval lengths, units,
column classes, factor levels and contrasts are unchanged. Missing values
are kept, and unmarked applies its own missing-data rules when fitting.
Nothing is aggregated or imputed. Added names that also occur among the
site or yearly covariates are recorded for review. Use distinct names for
fields with different meanings, because multiScale_optim() will not
estimate a scale for a site covariate whose name is shadowed this way.
Model the first interval
Use formulas such as ~ I(interval == 1) or ~ factor(interval) when the
observation process justifies them. With equal unit intervals, hazards pi
in the first interval and b thereafter reproduce the first-time law of a
simple encounter Markov process regardless of persistence after an
encounter. First times alone do not estimate that persistence or
establish a finite corrected density. Unequal durations keep their
per-unit probability interpretation. Keep linked complete histories when
assessing re-detections. This function only arranges data. It adds no
model terms, parameters or uncertainty methods.
For covariates that are constant within a survey, expand_gdr_intervals()
builds interval_data for you.
See Also
expand_gdr_intervals(), validate_unmarked_data(),
prepare_gdr_histories()
Examples
frame <- unmarked::unmarkedFrameGDR(
yDistance = matrix(c(1, 0, 0, 1), 2, byrow = TRUE),
yRemoval = matrix(c(1, 0, 0, 0, 1, 0), 2, byrow = TRUE),
siteCovs = data.frame(site = factor(c("A", "B"))),
dist.breaks = c(0, 25, 75), unitsIn = "m",
period.lengths = c(1, 2, 1))
keys <- data.frame(site = c("A", "B"), survey = c("s1", "s2"))
# One row per survey and interval, deliberately out of frame order
bands <- data.frame(survey = rep(c("s2", "s1"), each = 3),
interval = rep(c(3, 1, 2), 2),
observer = factor(c("Ann", "Ann", "Bob", "Bob", "Ann", "Ann")))
prepared <- prepare_gdr_intervals(frame, keys, "survey", bands,
interval_units = "minutes", site_id = "site")
# Observer and interval number, now in frame order
unmarked::obsCovs(prepared$data)
# Which input row filled each observation row
prepared$alignment[, c(".event", ".interval", ".input_row", "survey")]
Prepare a fixed set of predictions for repeated use
Description
Compute the predictions for one fixed set of rows once and keep them in a
compact snapshot. For the analytic and conditional logistic backends, the
snapshot holds the prepared spatial design, so predict() on it can switch
between scales and uncertainty choices without rebuilding the kernels. For
joint mixed, unmarked, and other native refit models, it holds the native
numerical outputs for the controls you bind. A snapshot does not add
uncertainty, update the fit, or predict new locations.
Usage
prepare_prediction(
object,
newdata = NULL,
kernel_inputs = NULL,
max_bytes = 64 * 1024^2,
component = NULL,
native_args = list(),
join_by = NULL,
include_fixed = FALSE
)
## S3 method for class 'multiScaleR_prediction'
predict(
object,
type = c("response", "link"),
se.fit = FALSE,
uncertainty = c("joint", "conditional"),
interval = c("none", "confidence"),
level = 0.95,
...
)
## S3 method for class 'multiScaleR_prediction'
print(x, ...)
Arguments
object |
A fitted |
newdata, kernel_inputs |
Prediction rows and matching spatial inputs
from |
max_bytes |
Positive number. The largest allowed size of the returned
snapshot, in bytes. The default, |
component |
Character scalar naming the native prediction type to keep.
|
native_args |
A named list of native prediction controls to bind to
the snapshot. Default
Native argument abbreviations are resolved to their full names before the list is checked and are recorded by those names. Selected lme4 and spaMM effects and GAM terms are recorded in the prediction contracts. |
join_by |
For native refit and |
include_fixed |
Logical. The default |
type, se.fit, uncertainty, interval, level |
Output and uncertainty
controls for |
... |
For |
x |
A |
Value
prepare_prediction() returns an object of class
multiScaleR_prediction, printed as a one-line summary of the backend,
the number of fixed predictions, and the stored size. Its elements are
internal, except prediction_contract, a named list with one
prediction_contract per prepared output type. Each records the
quantity, its scale and conditioning, the random-effect policy, and the
uncertainty restrictions. This metadata does not establish fit
eligibility or interval calibration.
predict() on a snapshot returns the same output as
predict.multiScaleR() would return for the original model and fixed
rows. unmarked snapshots return the native table with Predicted,
SE, lower, and upper columns. Joint mixed snapshots return native
glmmTMB vectors or standard-error lists for the bound type and controls.
Numerical outputs keep their usual structure, including native
attributes.
print() returns the snapshot invisibly.
What a snapshot keeps
A snapshot binds the coefficients, covariance, selected scales, training
standardization, row order, choice sets, and native controls of one call.
It keeps neither raw spatial buffers nor the fitted native model, so it
can be saved with saveRDS() and restored with readRDS(). Later changes
to the original model or data do not update it. Call
prepare_prediction() again after changing the model, locations, choice
sets, metric definitions, distance units, or native controls. New data
cannot be passed to predict() on a snapshot.
Supported native and analytic models keep their trained standard scaling,
polynomial, and spline calls, including those inside nested expressions
and formula offsets. Recovery needs one unambiguous learner's attributes
per evaluated predictor. Missing or ambiguous metadata raises an error
rather than learning a transformation from the prediction rows. Ordinary
native lm, glm, and time-fixed unpenalized Cox snapshots use the
original fitted terms for dot shortcuts and active variables, so removed
variables add no prediction inputs and new data columns never enter the
design.
Analytic and conditional logistic snapshots
These snapshots keep the spatial design, so predict() on them accepts
the same type, se.fit, uncertainty, interval, and level choices
as predict.multiScaleR(), with the same restrictions. Reuse avoids
rebuilding the spatial engine when you need several summaries of the same
rows. Conditional logistic snapshots without valid choice-set IDs still
give linear predictors and relative scores, but they reject response
probabilities and keep the reason in their response contract. Their
standard errors need uncertainty = "conditional", and no scale
uncertainty is added.
Native snapshots
Joint mixed, unmarked, and other refit snapshots cache the native
numerical outputs for the bound controls, rather than keeping a native
model or rebuilding its prediction machinery. Native warnings are recorded
and repeated each time the cached output is requested. A native error in
the point predictions stops preparation.
-
Joint mixed models. Point and standard-error outputs are both cached. Standard errors stay conditional on the selected scales. Zero random-effect controls use formula syntax independently of its environment, and grouping columns may be omitted when the provider permits zero-effect predictions. glmmTMB
re.form = NAsets random effects to zero and does not integrate over their distribution. -
General refits. If the provider cannot supply standard errors, the point predictions remain available and a later standard-error request repeats the recorded error. Native prediction intervals and response variances keep the provider's observation noise. Cached native intervals or variance attributes need
uncertainty = "conditional", even withse.fit = FALSE. Leave the wrapper'sinterval = "none"when you retrieve those native outputs. GAM rows keep every formula-input requirement, including inputs to excluded terms, and the uncheckednewdata.guaranteedshortcut is not supported. spaMM refits use their retained native frames to verify fixed features. An unsupported native standard-error request stays an explicit error, recorded separately from the point output. -
unmarkedmodels.predict()returns the cached native table. Its confidence level and back-transformation are fixed bynative_argsand cannot be changed at prediction time.
Unmarked snapshots
Without kernel_inputs, supply native prediction rows with spatial
covariates already on their fitted scale, including raw units when the
native refit used them. With kernel_inputs, supply explicit join_by
keys and native prediction rows. prepare_unmarked_data() then computes
the spatial columns and applies the training standardization without
changing native observation or year ordering or non-spatial factor and
offset inputs. Spatial snapshots keep the prediction row names and site
keys in their provenance.
Ordinary occupancy and pcount state and detection terms use the
original raw training transformations, fitted factor contrasts, and native
component covariance. Missing contrasts can be recovered from unambiguous
original main-factor columns. Other missing coding needs explicit training
contrasts. Preparation verifies the fixed designs and offsets against the
retained native fit. Explicit data-frame rows prepare only the requested
component, while native frame inputs or an omitted newdata keep both
components for native missing-row removal. ZIP outputs keep their native
zero-inflation estimate and uncertainty, and every output keeps the full
model's parameter count and diagnostics. Keep the original covariates and
fitted designs. Frame subsets keep the original known-group columns.
gdistremoval() snapshots likewise freeze the active "lambda",
"phi", "dist", or "rem" component's original training terms and
native covariance, with distinct site, primary-period, and
removal-interval recipes. Data-frame rows limit preparation to the
requested component, and native GDR frames keep every active design and
their original missing-input checks. No model or executable TMB tape is
saved in the snapshot. GDR models with active formula offsets or TMB zero
inflation are rejected before fitting, model selection, or prediction, as
aic_tab() explains.
Conditional learned random-effect terms need precomputed training
predictors. Zero-effect contexts need only their fixed design and
offsets, and they reject a later conditional-effect request. Any
non-NULL native re.form sets the effects to zero. It neither selects
some effects nor integrates over them. For dynamic occupancy, "psi"
describes initial occupancy, and "col" and "ext" describe transitions.
These component predictions are distinct from smoothed or projected
occupancy trajectories.
See Also
predict.multiScaleR(), prediction_contract,
multiScaleR-prediction, prepare_unmarked_data()
Examples
## Analytic fit from the running example: counts and two landscape layers
data("landscape_counts")
data("surv_pts")
pts <- terra::vect(surv_pts)
land <- terra::rast(system.file("extdata", "landscape.tif",
package = "multiScaleR"))[[c("land1", "land2")]]
inputs <- kernel_prep(pts, land, max_D = 1700, kernel = "gaussian",
bin = TRUE, verbose = FALSE)
dat <- data.frame(landscape_counts, inputs$kernel_dat)
start <- glm(counts ~ site + land1 + land2, family = poisson(), data = dat)
fit <- multiScale_optim(start, inputs, backend = "profile_glm",
n_cores = 1, verbose = FALSE)
## Prepare three new survey points once. Row names of new_sites match the
## prepared point IDs.
new_inputs <- kernel_prep(pts[1:3], land, max_D = 1700, kernel = "gaussian",
bin = TRUE, verbose = FALSE)
new_sites <- data.frame(site = c(-1, 0, 1))
prepared <- prepare_prediction(fit, new_sites, new_inputs)
prepared
## Several summaries of the same rows, without rebuilding the kernels
predict(prepared) # expected counts
predict(prepared, type = "link", se.fit = TRUE) # log scale, joint SEs
predict(prepared, interval = "confidence",
uncertainty = "conditional")$upper # upper 95% limits
## A native unmarked snapshot binds one component. This stored N-mixture
## fit is used in vignette("v02-user-guide").
nmix <- readRDS(system.file("extdata", "cache-user-guide-nmix.rds",
package = "multiScaleR"))
detection <- prepare_prediction(nmix, component = "det")
head(predict(detection)) # detection probability per survey, 95% limits
Prepare spatial covariates for native unmarked prediction
Description
Calculate the optimized spatial predictors at new sites and insert them
into an explicitly keyed data frame for native unmarked prediction. The
training means and standard deviations are reused, so the new sites are on
the fitted model's covariate scale. Pass the result to
unmarked::predict(), or give the same inputs to prepare_prediction()
for a reusable snapshot.
Usage
prepare_unmarked_data(
object,
newdata,
kernel_inputs,
join_by,
include_fixed = FALSE
)
Arguments
object |
A fitted |
newdata |
A nonempty data frame of prediction rows, in the layout
that native |
kernel_inputs |
A |
join_by |
A data frame with one unique key row per prepared site, in
|
include_fixed |
Logical. The default |
Value
A data frame with the same rows, row names, and non-spatial columns
as newdata. The calculated spatial columns hold the fitted kernel
transforms in standard-deviation units of the training sample, the scale
the native model was fitted on. They are model inputs, not predictions.
Do not standardize them again.
What the function does and does not do
This function prepares data only. Native prediction determines the
component's meaning, factor handling, offsets, missing-data behavior, and
confidence limits, and neither this function nor prepare_prediction()
adds uncertainty in the selected scales. multiScaleR-prediction lists
what each unmarked component predicts.
Spatial predictors are static site covariates, as the unmarked fitting
adapter requires. Supply the native row layout for detection and annual
components yourself. The function does not infer observation times,
expand sites into years, modify an unmarkedFrame, or borrow non-spatial
values from the fitting data.
Match the spatial inputs to the fit
Distances inside kernel_inputs are converted with its own unit_conv,
and the reported scales remain in map units. Metric definitions and the
choice of binned or exact kernel evaluation must match the fit. Preparing
bins at new sites can shift their representative distances slightly, as in
other binned prediction routes. Source names are checked, but raster
contents are not fingerprinted, so prepare the sites from the intended
source rasters and coordinate system. When the internal fitted parameters
are retained, they are reused directly, which avoids rounding from a
conversion to reported units and back. Stored parameters that disagree
with the reported scales or shapes raise an error.
The calculated columns use the training sample's mean and standard deviation. Prediction values are never clamped or standardized within the new sample. Missing spatial values stay missing for the native prediction method, while infinite values or invalid training standard deviations raise errors.
Recompute fixed-radius predictors
Fixed-radius predictors are recalculated only with include_fixed = TRUE.
Their normalization comes from the original preparation object, and their
fitted site values must match that object after explicit training-site
alignment. This rejects manually rescaled or stale fixed predictors, changed
radii, ambiguous training keys, and missing training buffers rather than
guessing their fitted scale. Keep the original inputs if you need this
verification.
Distance-removal models
For unmarked::gdistremoval() fits, only active component formulas
identify spatial predictors. Availability is inactive with one primary
period, and the distance formula is inactive for a uniform key. Optimized
static site names must not also occur in the native yearly or observation
covariate tables, so use distinct names for distinct inputs. Dot formulas use
the original component's available training-column names. GDR models with
active formula offsets or TMB zero inflation are rejected, as aic_tab()
explains.
See Also
prepare_prediction(), predict.multiScaleR(),
multiScaleR-prediction, kernel_prep(), kernel_scale.raster(), and
vignette("v02-user-guide", package = "multiScaleR") for fitting and
mapping unmarked models.
Examples
## A stored N-mixture fit used in vignette("v02-user-guide"). Abundance
## depends on the bin1 and cont2 layers of a simulated landscape.
nmix <- readRDS(system.file("extdata", "cache-user-guide-nmix.rds",
package = "multiScaleR"))
layers <- subset(sim_rast(user_seed = 999, dim = 250), c("bin1", "cont2"))
## Three new sites, prepared with the fitted kernel, max_D, covariate
## definitions, and binning
new_pts <- terra::vect(cbind(x = c(800, 1250, 1700),
y = c(900, 1250, 1600)))
new_inputs <- kernel_prep(new_pts, layers, max_D = nmix$max_D,
kernel = nmix$kernel_inputs$kernel,
scale_vars = nmix$kernel_inputs$scale_vars,
bin = !is.null(nmix$kernel_inputs$binned),
verbose = FALSE)
## Keys follow the prepared point order. Site B appears twice, for
## example in two survey years, and reuses the same spatial values.
keys <- data.frame(site = c("A", "B", "C"))
scenarios <- data.frame(site = c("A", "B", "B", "C"))
nd <- prepare_unmarked_data(nmix, scenarios, new_inputs, join_by = keys)
nd # bin1 and cont2 in training standard-deviation units
## Expected abundance at each row, with native 95% confidence limits
unmarked::predict(nmix$opt_mod, type = "state", newdata = nd)
## The same rows and component as a reusable snapshot
prepared <- prepare_prediction(nmix, scenarios, new_inputs,
component = "state", join_by = keys)
predict(prepared)
Print a multiScaleR fit
Description
Prints a fit from multiScale_optim(): the kernel, the
estimated scales with their standard errors, the scale distances, the
fitted model, any warnings, and the follow-up recommendation. Use
summary.multiScaleR() for intervals.
Usage
## S3 method for class 'multiScaleR'
print(x, dimension = c("2d", "1d"), prob = 0.9, ...)
Arguments
x |
A |
dimension |
Character. |
prob |
Numeric between 0 and 1 (exclusive). Proportion of cumulative
kernel weight used for the distances. Default: |
... |
Ignored. |
Value
Invisibly returns x.
See Also
multiScaleR, summary.multiScaleR().
Examples
data(pts)
data(count_data)
hab <- terra::rast(system.file("extdata", "hab.tif",
package = "multiScaleR"))
inputs <- kernel_prep(pts = pts, raster_stack = hab, max_D = 250,
kernel = "gaussian", verbose = FALSE)
fit <- multiScale_optim(glm(y ~ hab, family = poisson, data = count_data),
inputs, verbose = FALSE)
fit # same as print(fit)
print(fit, prob = 0.5) # distances holding half of each kernel's weight
Print prepared multiScaleR inputs
Description
Prints a short report of a kernel_prep() object: the number
of points and covariates, the kernel, the binning, and the distance
bounds.
Usage
## S3 method for class 'multiScaleR_data'
print(x, ...)
Arguments
x |
A |
... |
Ignored. |
Value
Invisibly returns x.
See Also
multiScaleR_data, kernel_prep().
Examples
data(pts)
hab <- terra::rast(system.file("extdata", "hab.tif",
package = "multiScaleR"))
inputs <- kernel_prep(pts = pts, raster_stack = hab, max_D = 250,
kernel = "gaussian", verbose = FALSE)
inputs
Print a summary of a multiScaleR fit
Description
Prints the object returned by summary.multiScaleR(): the
estimated scales with their intervals, the scale distances under both
definitions, the fitted model, any warnings, and the follow-up
recommendation.
Usage
## S3 method for class 'summary_multiScaleR'
print(x, dimension = NULL, ...)
Arguments
x |
A |
dimension |
Character, |
... |
Ignored. |
Value
Invisibly returns x.
See Also
summary.multiScaleR(), kernel_dist() for the two distance
definitions.
Examples
data(pts)
data(count_data)
hab <- terra::rast(system.file("extdata", "hab.tif",
package = "multiScaleR"))
inputs <- kernel_prep(pts = pts, raster_stack = hab, max_D = 250,
kernel = "gaussian", verbose = FALSE)
fit <- multiScale_optim(glm(y ~ hab, family = poisson, data = count_data),
inputs, verbose = FALSE)
s <- summary(fit)
print(s, dimension = "1d") # line-based distances first
Profile Model Fit Across Sigma
Description
Evaluates the log-likelihood and AICc of a fitted model at a grid of sigma
values (or hard radii) for each optimized covariate. The resulting curve
shows whether an estimate sits at a clear optimum or on a flat plateau,
which tells you how well the data identify the scale of effect. Plot the
result with plot.sigma_profile().
Usage
profile_sigma(
x,
n_pts = 10,
metric = c("AICc", "LL"),
verbose = TRUE,
n_cores = NULL,
spacing = c("log", "linear"),
sigma_values = NULL,
sigma_range = NULL
)
Arguments
x |
A fitted |
n_pts |
Positive integer, at least 3. Number of sigma values in the
generated grid for each covariate. More values give a smoother curve at
the cost of more model refits. Ignored when |
metric |
Character. Which quantity |
verbose |
Logical. Print a progress message for each covariate.
Default: |
n_cores |
Optional positive integer. Number of CPU cores used to
profile covariates in parallel, one covariate per worker (a PSOCK
cluster). Default: |
spacing |
Character. Spacing of the generated grid. |
sigma_values |
Optional positive numeric vector of sigma values, in
map units, to evaluate directly. Duplicates are removed and the values
are sorted, and at least 3 unique values are required. When supplied,
|
sigma_range |
Optional positive numeric vector of length 2 giving the
smallest and largest sigma, in map units, of the generated grid. Default:
the search range of the fit, |
Value
A list of class sigma_profile with these elements:
-
profiles: data frame with one row per covariate and grid value, and columnsvariable(covariate name),sigma(map units),LL(log-likelihood of the refit model), andAICc. AICc isNAwhen the number of observationsnis not larger thanK + 1, whereKis the parameter count. -
opt_sigma: named numeric vector with the estimated sigma of each covariate, in map units. -
metric: the metric chosen for plotting. -
spacing: the grid type,"log","linear", or"custom"(forsigma_values). -
sigma_grid: the sigma values evaluated, shared by all covariates.
How the profile is computed
For each covariate in turn, sigma is set to each grid value while every
other sigma (and any shape) stays at its estimate. The model is refit at
each value, so its coefficients adjust, and the log-likelihood is
recorded. Because the other scales are not re-optimized, a model with
several covariates gives a slice through the likelihood surface rather than
a full profile likelihood. AICc counts all free likelihood parameters
(including ancillary, unmarked detection, and variance parameters) plus
the estimated sigma and shape parameters, as in aic_tab(), and uses the
model's observation count.
How to read the profile. A sharp peak in log-likelihood (or trough in
AICc) at the estimate means the data identify the scale well. A flat curve
over a wide range means many scales fit about equally well, so treat the
estimate with caution. A curve still improving at max_D suggests the
scale may lie beyond the search range. In that case, increase max_D in
kernel_prep() and refit. For a profile-likelihood interval for sigma,
use summary(fit, profile = TRUE). See
vignette("v09-estimates-and-intervals", package = "multiScaleR").
If every refit fails and returns the optimizer's penalty value, profiling
stops with an error instead of returning an artificially flat profile.
Keep the model formula and data available to the stored model call, or
give multiScale_optim() a working refit_fn.
Profile a hard radius
Landscape metrics, unweighted surface metrics, and every covariate fitted
with kernel = "fixed" have a hard radius, so a cell either counts fully
or not at all. The covariate changes only when the radius passes a cell
center, so the likelihood changes in steps. The Hessian standard error is
therefore not a useful measure of uncertainty, and the default summary
shows NA for the standard error and Wald interval. Use this profile to
inspect the likelihood, and report the estimate as a radius in map units.
The plot joins grid values with straight lines, so it does not show the
steps between them, and an interval read from a profile cutoff does not by
itself establish coverage for a stepped likelihood. Candidate scales that
make a covariate undefined at a modeled observation are rejected during
fitting, so all likelihoods compare the same observations. Hard-radius
covariates can be profiled in exponential-power fits, and their unused
shape positions do not affect the profile or the parameter count. See
multiScaleR-kernels.
Analytic and conditional-logistic fits
Fits from backend = "profile_glm", "joint_nb2", and
"conditional_logit" profile serially, and every sigma value must lie
within the fitted bounds (min_D to max_D). For a "conditional_logit"
fit, each grid value is the log-likelihood of a native
survival::coxph() refit at that sigma, with the coefficients refit and
every other scale held at its estimate. That backend withholds scale
uncertainty, so summary(fit, profile = TRUE) returns no profile interval
for it. The grid describes the likelihood surface only.
See Also
plot.sigma_profile(), multiScale_optim(),
summary.multiScaleR(), multiScaleR-kernels.
Examples
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,
kernel = "gaussian",
verbose = FALSE)
mod <- glm(y ~ hab, family = poisson,
data = data.frame(count_data["y"], kernel_inputs$kernel_dat))
opt <- multiScale_optim(fitted_mod = mod,
kernel_inputs = kernel_inputs,
verbose = FALSE)
## Default: 10 log-spaced values from min_D to max_D
prof <- profile_sigma(opt, verbose = FALSE)
# Log-likelihood and AICc at each sigma (m)
prof$profiles
plot(prof) # AICc is lowest near the estimated sigma (dashed line)
## Linearly spaced values between explicit limits
prof <- profile_sigma(opt, n_pts = 8, spacing = "linear",
sigma_range = c(25, 250), verbose = FALSE)
## Your own sigma values, drawn as log-likelihood
prof <- profile_sigma(opt, sigma_values = c(25, 50, 75, 100, 150, 250),
metric = "LL", verbose = FALSE)
plot(prof) # log-likelihood peaks near the estimate
Survey points for the hab example
Description
Locations of the 75 survey points that go with count_data and the
hab.tif raster.
Usage
data(pts)
Format
An sf point object with 75 features, no coordinate reference
system, and coordinates in the map units of hab.tif (from 400 to 3600).
Its one attribute column, obs, repeats the counts in count_data$y.
Source
Simulated for this package.
See Also
count_data, hab, kernel_prep().
Examples
data(pts)
pts
hab <- terra::rast(system.file("extdata", "hab.tif",
package = "multiScaleR"))
terra::plot(hab)
terra::points(terra::vect(pts), pch = 19)
Bind Projected Coordinates to a Fitted Response Field
Description
Check 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.
Usage
response_field_geometry(
object,
coords,
crs,
batch_size = 128L,
max_memory_mb = 512
)
Arguments
object |
A
|
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 |
crs |
The projected CRS of |
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
|
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.
See Also
predict.multiScaleR(), kernel_scale.raster(),
fit_gdr_response_field(), prediction_contract(),
vignette("v11-spatial-fields", package = "multiScaleR")
Examples
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
}
Profile and Bootstrap Inference for an NB2 Scale
Description
Examine the full allowed scale range of an NB2 fit with one spatial predictor, retain separate likelihood regions, and optionally calibrate likelihood-ratio tests by parametric bootstrap. This diagnostic is experimental. The likelihood profile and the bootstrap decision retain their numerical audits, and bootstrap confidence-set calibration is not established. The diagnostic preserves the fitted object.
Usage
scale_inference(
object,
sigma_values = NULL,
level = 0.95,
grid_points = 41L,
bootstrap = 0L,
bootstrap_values = NULL,
seed = NULL,
n_starts = 12L
)
Arguments
object |
A |
sigma_values |
Optional positive scale values in map units to examine. The search bounds and the refined optimum are always included. |
level |
Confidence level between zero and one; default |
grid_points |
Number of log-spaced scale values when
|
bootstrap |
Number of parametric bootstrap samples per calibrated scale; zero (the default) skips calibration. Small values have substantial Monte Carlo uncertainty. At least 999 is advisable for final tail estimation, although this can be expensive. |
bootstrap_values |
Optional subset of scales to calibrate, in map units. They are added to the profile grid. Omitting this argument calibrates every grid point. A subset supplies pointwise tests, not a complete bootstrap confidence set. |
seed |
Nonnegative integer random seed, required when
|
n_starts |
Number of additional dispersed starts for inference refits;
default |
Details
Coefficients and NB2 theta are reestimated at every constrained scale.
Weighted SQ uses the same refit and audit machinery. Existing kernel-mean
coverage studies do not establish interval coverage for surface SQ or
interaction models. Native factor contrasts and product terms are retained
in every constrained, unrestricted, and bootstrap refit.
Exponential-power shape is also reestimated. A stronger unrestricted refit
and a full-range grid can reveal an optimum missed by the original fit;
the returned reference records this without modifying object.
If conditional NB2 GLM iterations fail for a full-rank design, the backend
refines coefficients using the likelihood score and observed information,
checks convergence, and rebuilds the conditional GLM result.
For joint_nb2 fits, these refits use the boundary-aware conditional
likelihood in rho = log(1 + 1/theta) coordinates, including exact
Poisson fits. Bootstrap samples use Poisson sampling when the constrained
dispersion estimate is on that boundary. This preserves the boundary in
inference without substituting a large finite theta. These refits currently
profile coefficients rather than using the joint fitting optimizer.
The profile cutoff is qchisq(level, 1) for twice the log-likelihood
difference. Each detected accepted component is retained. Finite grids can
still miss narrow regions. A bound-limited endpoint is not a resolved
confidence limit.
The zero-effect diagnostic removes all response columns involving the optimized kernel, including its products and factor interactions. If that model is inside the profile likelihood cutoff, every admissible scale has a feasible fit inside the cutoff. Scale is then reported as unresolved. This is a likelihood diagnostic, not a calibrated test for the presence of a kernel effect.
Bootstrap samples are generated at each constrained scale using its fitted
coefficients and theta, with the landscape, fixed design, and offsets held
fixed. Every sample is refitted both freely and at the generating scale.
The tail estimate is (1 + exceedances) / (bootstrap + 1). Monte Carlo
limits transform exact binomial limits by the same formula. A test accepts
when its tail estimate exceeds 1 - level; the ambiguity flag is
separate. Any failed bootstrap pair makes that scale's calibration missing.
Only unit observation weights are currently supported for bootstrap.
A simulation with 32 datasets per scenario and 99 bootstrap draws per test compared the bootstrap and chi-squared decisions at the known generating scale. In the interior NB2 scenario, both included the generating scale in 24 of 32 datasets and agreed on every decision. The exact 95 percent binomial interval for inclusion was 0.566 to 0.885. This measures pointwise inclusion in that simulation design. Coverage of the returned finite-grid sets is a separate target.
In a separate 48-dataset simulation, all full-grid sets were available.
Their coverage changed with the grid even when the bootstrap decisions
at shared nodes were held fixed. A singleton component contains only
its accepted scale. Its outside brackets record adjacent rejected
nodes. vignette("v09-estimates-and-intervals", package = "multiScaleR")
summarizes the simulation results.
These are plug-in parametric bootstrap tests for independent observations,
not exact tests with known nuisance parameters. Neither bootstrap nor
positive curvature guarantees calibrated coverage under weak identification
or at parameter boundaries. Full-range, disconnected, bound-limited, or
Monte Carlo-ambiguous results should not be reduced to a precise scale.
Defaults of multiScale_optim(), summary(), and predict()
are unchanged.
Value
A list of class msr_scale_inference with:
- estimate
Refined scale estimate in map units.
- reference
Refined log-parameter vector, negative log likelihood, start audit, original negative log likelihood, and improvement. The original fitted object remains unchanged.
- grid
Scale values, profile negative log likelihood, likelihood-ratio statistic, chi-squared acceptance, bootstrap p-value and 95 percent Monte Carlo limits, bootstrap acceptance, and whether the Monte Carlo limits cross the rejection threshold. Uncalibrated entries are missing.
- profile_set
Separate accepted scale regions. Columns
lowerandupperare root-refined endpoints in map units;lower_outsideandupper_outsideretain adjacent rejected grid points. The two*_bound_limitedcolumns mark endpoints limited by the optimization bounds.- bootstrap_set
Accepted grid components with the same columns, or
NULLunless every grid point was successfully calibrated. Endpoints are accepted grid values, not root-refined limits; outside brackets show their resolution.- diagnostics
Zero-effect likelihood deviance and compatibility with the profile cutoff; profile status (
localized,disconnected,bound_limited, orunresolved); original Wald availability; and bootstrap status, failure count, and Monte Carlo ambiguity count.- bootstrap_records
One row per attempted bootstrap refit pair: generating scale, replicate, success, likelihood-ratio statistic, fitted scale and theta, boundary indicator, both likelihoods, attempted/eligible start counts, errors, and warnings. No failed replicate is silently dropped.
- profile_audit
Start records at each observed profile grid point.
- level, bootstrap, seed, bounds, call
Requested confidence level, bootstrap count and seed, map-unit search bounds, and matched call.
See Also
multiScale_optim, profile_sigma,
diagnostics
Examples
if (requireNamespace("MASS", quietly = TRUE)) {
set.seed(42)
habitat <- terra::rast(nrows = 60, ncols = 60, xmin = 0, xmax = 600,
ymin = 0, ymax = 600, crs = "EPSG:32617")
cells <- seq_len(terra::ncell(habitat))
terra::values(habitat) <- sin(cells / 41) + cos(cells / 73)
names(habitat) <- "hab"
sites <- terra::vect(expand.grid(x = seq(150, 450, length.out = 6),
y = seq(150, 450, length.out = 6)),
geom = c("x", "y"), crs = terra::crs(habitat))
ki <- kernel_prep(sites, habitat, max_D = 120, bin = TRUE, verbose = FALSE)
dat <- data.frame(ki$kernel_dat)
dat$y <- rnbinom(nrow(dat), mu = exp(.5 + dat$hab), size = 2)
initial <- glm(y ~ hab, data = dat, family = MASS::negative.binomial(2))
fit <- multiScale_optim(initial, ki, backend = "profile_glm",
n_cores = 1, verbose = FALSE)
assessment <- scale_inference(fit, grid_points = 9, n_starts = 2)
assessment$profile_set # Separate regions, with explicit search bounds.
assessment$diagnostics # A broad region may leave scale unresolved.
}
Validate Training-Only Model Selection Within CV Folds
Description
Score a model-selection rule rather than a single model. In each fold the rule picks the candidate with the lowest training AIC, AICc, or BIC, and the result keeps the held-out predictions that candidate already made. No models are refitted.
Usage
select_cv(
mod_list,
criterion = c("AICc", "AIC", "BIC"),
ties = c("error", "first"),
keep_fits = FALSE
)
Arguments
mod_list |
Named list of complete cross-validation results, all scored
on the same folds and observations. Each must keep its training records
( |
criterion |
Training criterion, declared in advance: |
ties |
What to do when two candidates have exactly the same training
criterion. The default |
keep_fits |
Logical. The default |
Value
A cross-validation result of the same class as the candidates
that scores the selection procedure. Each fold's predictions, training
values, and diagnostics come from the candidate chosen in that fold, and
settings$backend is "training_selection". The result adds
selection, which holds chosen (the candidate picked in each fold,
NA where selection failed), tables (each fold's training table, with
every candidate's K, log-likelihood, and criterion), and the criterion,
ties, and candidates. Results from cross_validate(),
cross_validate_glm(), and cross_validate_clogit() also record the
metrics scored and metrics_dropped, and each candidate's
candidate_settings. See multiScaleR_cv for the other elements.
How the procedure is scored
Suppose your plan is to fit several candidate models and keep the one with
the lowest AICc. Scoring only the winner on held-out data would flatter it,
because it was chosen after seeing all of the data. select_cv() scores
the whole plan instead. In each fold it computes the training criterion of
every candidate from its fit to that fold's analysis rows, picks the
lowest, and keeps the held-out predictions that candidate made. Assessment
outcomes and CV scores never choose the winner. The pooled score therefore
evaluates the declared candidate set and rule. If you then tune the
candidate set or the rule using these results, evaluate the final choice
with an independent test set or an outer validation layer.
What the candidates must keep
Run every candidate with keep_selection = TRUE (compact records) or
keep_fits = TRUE (full fits). A record holds the native training
log-likelihood, the native and ecological parameter counts, the rows that
entered the likelihood, their responses, trials, and frequency weights,
the formula as text, the controls, and the original diagnostics. NB2 and
Gamma records also hold the estimated or fixed nuisance parameter. A
record holds no fitted model, design matrix, raster, or formula
environment, so it is much smaller than a fit, although its row metadata
still grows with the number of observations and folds. Keeping records
adds no fitting and does not change which folds pass their diagnostics.
Before selecting, the function checks each record or fit against the
fold's analysis rows and the recorded responses and weights. If a
candidate keeps both records and fits, they must agree exactly. A record
that could not be built makes selection fail in that fold, without
changing the candidate's own result. Results that kept fits work without
records. A result that kept neither must be run again with
keep_selection = TRUE.
Which candidates can be combined
The candidates must pass the same checks as in cv_tab(), with identical
folds and observations and comparable likelihoods. NB2 and Poisson
candidates can share a count target. Gamma and Gaussian candidates can
share a continuous target, scored with RMSE or MAE. An information
criterion cannot compare a count likelihood with a continuous density.
Conditional-choice candidates must also share their partial-likelihood
method.
For results from cross_validate(), cross_validate_glm(), and
cross_validate_clogit(), the procedure is scored on the metrics that
every candidate recorded. A default Poisson candidate records "deviance"
and a default NB2 candidate does not, so their selection keeps "rmse",
"mae", and "neg_log_score". selection$metrics lists the metrics kept
and selection$metrics_dropped those left out. Field and mixed-model
candidates must record the same metrics. Bayesian results have no
training likelihood and are rejected.
Penalties follow the native parameter counts, and scales and shapes
estimated by multiScale_optim() count toward K.
Conditional choice: the sample size in AICc and BIC is the number of choice sets (one event each), not the number of alternatives.
Spatial fields: the coefficients, field SD, estimated range, and any observation dispersion count toward K. The integrated field values add nothing. The held-out joint block score is that of the model chosen in the fold.
Mixed models: the sample size is the number of analysis observations. The covariance parameters count toward K, and the integrated group effects add nothing.
Read the result
Read complete and selection$chosen first. A fold fails, and the pooled
scores become NA, when a criterion cannot be computed, is not finite, or
ties under ties = "error". selection$tables shows the training table
behind each choice. For GLM and conditional-choice results, the shared
settings are copied from the first candidate, named in
settings$controls_from, and selection$candidate_settings holds every
candidate's controls. NB2 and Gamma selections also keep the settings
(settings$fold_settings) and distribution of the model chosen in each
fold, including when a Poisson or Gaussian reference wins. GLM,
conditional-choice, and mixed-model selections also keep every
candidate's warnings and diagnostics in selection, and grouped-map
labels (raster_groups) are kept for the chosen model. The score does not
integrate parameter or selection uncertainty, add intervals, or establish
calibration.
See Also
cv_tab(), cross_validate(), cross_validate_glm(),
multiScaleR_cv, aic_tab(), bic_tab(), and
vignette("v08-cross-validation", package = "multiScaleR").
Examples
data("landscape_counts")
data("surv_pts")
# Three spatial folds. The simulated coordinates are in meters.
folds <- spatial_cv_folds(crds(vect(surv_pts)), block_size = 1000, k = 3,
crs = 32617)
# keep_selection = TRUE stores the training likelihoods that select_cv() reads
candidates <- list(
null = cross_validate_glm(counts ~ 1, landscape_counts, folds,
family = "poisson", keep_selection = TRUE),
site = cross_validate_glm(counts ~ site, landscape_counts, folds,
family = "poisson", keep_selection = TRUE))
selected <- select_cv(candidates, criterion = "AICc")
selected$selection$chosen # model picked by training AICc in each fold
selected$selection$tables$fold1 # the training table behind the first pick
selected$summary # held-out scores of the whole procedure
Simulate Responses at Known Scales of Effect
Description
Simulates survey points and a response that depends on
kernel-weighted landscape covariates at scales of effect you choose. Fit
the simulated data with kernel_prep() and multiScale_optim() to check
whether the true scales and coefficients are recovered, or to explore how
sample size and kernel choice affect estimation.
Usage
sim_dat(
alpha = 1,
beta = NULL,
kernel = c("gaussian", "exp", "expow", "fixed"),
type = c("count", "count_nb", "occ", "gaussian"),
StDev = 0.5,
n_points = 50,
min_D = NULL,
raster_stack = NULL,
sigma = NULL,
shape = NULL,
max_D = NULL,
user_seed = NULL,
...
)
Arguments
alpha |
Numeric scalar. Intercept of the linear predictor, on the link
scale of |
beta |
Numeric vector of slopes, one per layer of |
kernel |
Character. Kernel used to weight raster values by distance
when computing the true covariates: |
type |
Character. Distribution of the simulated response:
|
StDev |
Positive numeric scalar. The |
n_points |
Either a positive integer number of points to simulate, or
a |
min_D |
Positive numeric scalar. Starting spacing, in map units, of
the point grid when |
raster_stack |
A |
sigma |
Positive numeric vector of true scale parameters, in map
units, one per layer of |
shape |
Positive numeric vector of true shape parameters, one per
layer. Required when |
max_D |
Positive numeric scalar. Radius, in map units, of the buffer
used to compute the true covariates with |
user_seed |
Optional integer seed. When supplied, |
... |
Not used. |
Details
Model. For each point, sim_dat() computes the kernel-weighted mean of
each layer at its true sigma (and shape) with kernel_prep(), and
standardizes it across points. The linear predictor is
eta = alpha + sum(beta * x), where x holds those standardized
covariates, and the response is drawn from the distribution set by type.
Point placement. With an integer n_points, points start as the cell
centers of a regular square grid over a window inset from the raster
edges, which reduces edge effects. The inset is 15% of the raster's
maximum x coordinate on each side, and the same limits are used for x and
y. This assumes a square raster whose extent starts at 0, as produced by
sim_rast(). Rasters with other extents can fail or place points poorly,
so supply your own points through n_points for them. The grid spacing
starts at 97% of min_D and shrinks by 3% at a time until the grid holds
at least n_points points, and then n_points of them are sampled at
random.
Recovering the scales. Prepare pts and the same raster_stack with
kernel_prep(), using a max_D comfortably above the largest true
scale. Fit a starting model to the standardized covariates, run
multiScale_optim(), and compare the estimated sigma values with sigma.
The example below shows these steps.
Value
A named list with three elements:
-
obs: numeric vector with the simulated response, one value per point. -
df: data frame with the response in columnyand one column per raster layer. The layer columns hold the true kernel-weighted means, standardized to mean 0 and standard deviation 1. A model fitted to this data frame estimates the coefficients at the true scales. -
pts: the survey points with anobscolumn holding the response. With an integern_points, ansfPOINT object with no coordinate reference system. Otherwise the supplied points. Pass it tokernel_prep()aspts.
See Also
sim_rast(), sim_dat_unmarked(), kernel_prep(),
multiScale_optim(). vignette("v02-user-guide", package = "multiScaleR") simulates zero-inflated counts with known scales.
Examples
## Four simulated layers. Keep one binary and one continuous layer
rs <- sim_rast(user_seed = 555)
rs <- terra::subset(rs, c("bin1", "cont1"))
## Counts with true scales of 75 m (bin1) and 150 m (cont1)
s_dat <- sim_dat(alpha = 0.5,
beta = c(0.75, -0.75), # log-scale effect per SD
kernel = "gaussian",
sigma = c(75, 150),
type = "count",
n_points = 75,
raster_stack = rs,
max_D = 400,
user_seed = 999)
# Response and the true standardized covariates
head(s_dat$df)
# Counts rise with bin1 and fall with cont1
plot(y ~ bin1, data = s_dat$df)
plot(y ~ cont1, data = s_dat$df)
## Check whether multiScale_optim() recovers the true scales
# max_D well above the largest true scale
kernel_inputs <- kernel_prep(pts = s_dat$pts, raster_stack = rs,
max_D = 750, verbose = FALSE)
mod <- glm(y ~ bin1 + cont1, family = poisson,
data = data.frame(y = s_dat$obs, kernel_inputs$kernel_dat))
fit <- multiScale_optim(fitted_mod = mod, kernel_inputs = kernel_inputs,
verbose = FALSE)
# Compare the sigma estimates with the true 75 and 150 m
summary(fit)
Simulate Paired Distance-Removal Surveys with Retained Truth
Description
Simulate single-visit point counts in which each bird is recorded by distance band and by the time interval of its first detection. Abundance is Poisson, detection by distance follows a half-normal curve, and detection over time follows a removal (first-detection) process. The two count tables describe the same birds. The observed data and the true values used to generate them are returned separately, so you can fit a model to the data and compare its estimates with the truth.
Usage
sim_dat_gdr(
density,
distance_scale,
removal,
dist_breaks,
interval_lengths,
interval_units,
units_in = c("m", "km"),
site_covs = NULL,
event_keys = NULL,
seed,
return_joint = FALSE,
provenance = list()
)
## S3 method for class 'msr_gdr_simulation'
print(x, ...)
Arguments
density |
Numeric vector of expected bird densities, in birds per
square kilometer, one value per survey point. Zero is allowed. This is
the response scale, not the log scale. Compute any ecological formula
or kernel-weighted covariate effect first, for example
|
distance_scale |
Positive number, or one per point. The standard
deviation (sigma) of the half-normal detection function, in |
removal |
Probability, between 0 and 1, that a bird present is first detected during one unit of interval time. Supply one number, one value per point, or a matrix with points in rows and removal intervals in columns for interval-specific probabilities. |
dist_breaks |
Increasing numeric distance boundaries starting at
zero, in |
interval_lengths |
Positive whole numbers giving the duration of each
removal interval, in |
interval_units |
Character string naming the time unit of
|
units_in |
Distance units, |
site_covs |
Optional data frame of site covariates, one row per point,
such as kernel-weighted landscape covariates from |
event_keys |
Optional data frame with one row per point holding the
original survey identifiers. It is returned unchanged, separate from the
covariates, for use with |
seed |
Nonnegative whole number used as the random seed. Your random number state is restored afterward, so the simulation does not change later random draws in your session. |
return_joint |
Logical, default |
provenance |
Optional named list of notes about how the inputs were
made, such as the generating formula, coefficients or the kernel scale
used for a covariate. It is stored in |
x |
An object returned by |
... |
Not used. |
Value
A list of class msr_gdr_simulation:
-
observed: theunmarkedFrameGDRto analyze, with the distance and removal tables,site_covs, distance breaks, units and interval lengths. It holds no true values. -
truth: a data frame with one row per point. See "Read the truth". -
probabilities: a list withdistance, a points by distance-band matrix of the probability that a bird in the circle is detected in each band, andremoval, a points by interval matrix of the probability that a bird is first detected in each interval. -
joint: the points by distance band by interval array of simulated counts whenreturn_joint = TRUE, otherwiseNULL. -
event_keys: as supplied. -
design: the settings used, includingdensity_units("birds/km2"),area_km2(the survey circle),distance_scaleandremovalper point, the breaks, interval lengths and units, theseedandRNGkind, the model assumptions (mixture = "P",keyfun = "halfnorm", one primary period, closed population), theunmarkedversion andprovenance.
Printing shows a short summary of the number of points, bands and intervals, the density range and the units, and returns the object invisibly. The full frame and truth stay in the object.
How the counts are generated
The survey area is pi * radius^2, in square kilometers, and expected
abundance is density times that area. Detection by distance and by time
are independent for each bird. The probability of a first detection in an
interval accounts for not being detected in earlier intervals, and an
interval of duration t has detection probability 1 - (1 - p)^t for
per-unit probability p. The function draws independent Poisson counts
for every combination of distance band and interval, plus one for birds
never detected. Their sum is the Poisson abundance in the circle, and both
count tables are totals of the same simulated counts, so their row totals
always match.
Read the truth
| Quantity | Where | How to read it |
| Expected density | truth$expected_density | Birds per square km, before imperfect detection |
| Expected abundance | truth$expected_abundance | Expected birds in the survey circle: density times design$area_km2 |
| Realized abundance | truth$realized_abundance | Birds simulated in the circle, a Poisson draw around the expectation |
| Distance detection | truth$distance_probability | Chance that a bird in the circle is detected by distance, averaged over the circle |
| Removal detection | truth$removal_probability | Chance that a bird is first detected at some point during the count |
| Overall detection | truth$observation_probability | The product of the two, the share of birds an observer records |
| Expected observations | truth$expected_observed | Expected count after both detection processes |
| Realized observations | truth$realized_observed | Birds recorded, equal to the row totals of both count tables |
| Distance scale | design$distance_scale | Half-normal sigma, in units_in |
| Your notes | design$provenance | Whatever you passed in provenance
|
The truth never enters the observed frame, so it cannot leak into fitted
covariates. truth$site_row gives the frame row of each point.
What the simulator covers
The simulator covers single-visit Poisson surveys with a half-normal
distance function and equal or unequal whole-number interval lengths. It
assumes a closed population inside the radius. It does not simulate
repeat visits with availability, negative binomial or zero-inflated
abundance, movement across the radius, or random variation in detection.
It fits no model and leaves sim_dat_unmarked() unchanged. See the
"Simulate a survey with a known scale of effect" section of
vignette("v12-distance-removal", package = "multiScaleR") for a full
example.
See Also
validate_unmarked_data(), prepare_gdr_histories(),
fit_gdr_response_field()
Examples
# Three points: two with birds and one with density zero
sim <- sim_dat_gdr(density = c(100, 200, 0), distance_scale = 40,
removal = 0.3, dist_breaks = c(0, 25, 75),
interval_lengths = c(1, 2, 1), interval_units = "minutes", seed = 24)
sim # compact summary
# Truth behind the counts: about 1.8 and 3.5 birds expected in the circle
sim$truth[, c("expected_density", "expected_abundance",
"realized_abundance", "realized_observed")]
# The same birds by distance band and by time interval
sim$observed@yDistance
sim$observed@yRemoval
Simulate data for optimizing scales of effect with unmarked
Description
Generates simulated replicated detection/non-detection or count
data formatted for use with the unmarked package, with known
kernel-weighted landscape covariates at a controlled scale of effect.
Usage
sim_dat_unmarked(
alpha = 1,
beta = NULL,
kernel = c("gaussian", "exp", "expow", "fixed"),
type = c("count", "count_nb", "occ"),
StDev = 0.5,
n_points = 50,
n_surv = 3,
det = 0.5,
min_D = NULL,
raster_stack = NULL,
sigma = NULL,
shape = NULL,
max_D = NULL,
user_seed = NULL,
...
)
Arguments
alpha |
Numeric scalar. Intercept for the abundance/occupancy linear
predictor. Default: |
beta |
Numeric vector of slope coefficients, one per raster layer in
|
kernel |
Character. Kernel function used to weight raster values by
distance. One of |
type |
Character. Response type to simulate. One of:
|
StDev |
Positive numeric. Dispersion (size) parameter for
|
n_points |
Positive integer. Number of spatial sample sites. Points are
placed on a hexagonal grid and randomly subsampled. Default: |
n_surv |
Positive integer. Number of repeated surveys per site, forming
the columns of the returned observation matrix. Default: |
det |
Numeric between 0 and 1. Per-survey detection probability applied
via binomial thinning of the true abundance/occupancy. Default: |
min_D |
Positive numeric. Minimum inter-point spacing on the hexagonal
grid. If |
raster_stack |
A |
sigma |
Positive numeric vector. True kernel scale parameters, one per raster layer. Must be in the same units as the raster projection. |
shape |
Positive numeric vector. Shape parameters for
|
max_D |
Positive numeric. Maximum buffer radius for
|
user_seed |
Optional integer seed for reproducibility. Default:
|
... |
Additional arguments. Not currently used. |
Details
Sites are distributed on a hexagonal grid across the interior of the raster
extent (85% of the x/y range) and then randomly subsampled. The true
abundance or occupancy at each site is a function of the kernel-weighted
landscape covariates at the specified scale. Repeated surveys introduce
imperfect detection controlled by det.
Use the returned y matrix and df (as siteCovs) to
construct an unmarkedFrame, fit a model, and then pass both the
fitted model and fresh kernel_prep output to
multiScale_optim.
Value
A named list with three elements:
yInteger matrix of dimensions
n_points x n_survcontaining the simulated replicated observations. Pass as theyargument when constructing anunmarkedFrame.dfData frame with
n_pointsrows. Theycolumn contains the simulated true abundance/occupancy (before detection thinning). Remaining columns are the true kernel-weighted covariate values, scaled to zero mean and unit variance.ptsAn
sfPOINT object withn_pointsrows. Anobscolumn is appended containing the true abundance/occupancy values. Pass tokernel_prepaspts.
Examples
rs <- sim_rast(dim = 50, user_seed = 123)
rs <- terra::subset(rs, c(1, 3))
s_dat <- sim_dat_unmarked(alpha = 1,
beta = c(0.75, -0.75),
kernel = 'gaussian',
sigma = c(40, 80),
n_points = 20,
n_surv = 3,
det = 0.5,
type = 'count',
raster_stack = rs,
max_D = 220,
user_seed = 123)
# True abundance rises with bin1 (beta = 0.75) and falls with cont1 (-0.75)
plot(s_dat$df$y ~ s_dat$df$bin1)
plot(s_dat$df$y ~ s_dat$df$cont1)
# Observed counts: one row per site, one column per repeated survey
head(s_dat$y)
## unmarked analysis
kernel_inputs <- kernel_prep(pts = s_dat$pts,
raster_stack = rs,
max_D = 220,
kernel = 'gaus',
verbose = FALSE)
umf <- unmarked::unmarkedFramePCount(y = s_dat$y,
siteCovs = kernel_inputs$kernel_dat)
## Base unmarked model
mod0 <- unmarked::pcount(~1 ~ bin1 + cont1,
data = umf,
K = 30)
## The unmarked optimization is slower than the simulation and base model
## fit, so it is skipped in automated example checks.
if (interactive()) {
opt1 <- multiScale_optim(fitted_mod = mod0,
kernel_inputs = kernel_inputs)
summary(opt1)
}
Simulate Spatially Autocorrelated Raster Surfaces
Description
Creates a SpatRaster with four simulated landscape layers, two binary
(0 or 1) and two continuous (0 to 1), for testing and teaching. Each pair
has one layer with a fine and one with a broad autocorrelation range. Use the layers with
sim_dat() or sim_dat_unmarked() to simulate responses at known scales
of effect, then check that multiScale_optim() recovers them.
Usage
sim_rast(
dim = 100,
resolution = 10,
autocorr_range1 = NULL,
autocorr_range2 = NULL,
sill = 10,
plot = FALSE,
user_seed = NULL,
...
)
Arguments
dim |
Positive integer. Number of cells along each side of the square
raster, so the output is a |
resolution |
Positive numeric. Cell size (edge length) in map units.
The raster spans 0 to |
autocorr_range1 |
Optional positive numeric. Autocorrelation range, in
cells, of the fields behind |
autocorr_range2 |
Optional positive numeric. Autocorrelation range, in
cells, of the fields behind |
sill |
Positive numeric. Variance (partial sill) of the exponential
covariance used for all four fields. Each field is rescaled to 0 to 1
afterward, so the sill does not change the returned values. Default:
|
plot |
Logical. If |
user_seed |
Optional integer seed for reproducibility. Each layer uses
a different multiple of the seed (1, 9, 99, and 55 times |
... |
Not used. |
Details
Each layer comes from a Gaussian random field with the exponential
covariance function sill * exp(-d / range), with d in cells. The field
is simulated with a fast Fourier transform (FFT) on a periodic grid twice
the size of the output (circulant embedding), and one dim x dim corner
is kept, so opposite edges of the output are not artificially correlated.
Each field is rescaled to run from 0 to 1 before it is thresholded (binary
layers) or returned (continuous layers). Version 0.7.48 corrected this
construction, so a given user_seed gives different layers than in
earlier versions.
Two ranges let you simulate covariates that act at different spatial
scales, as when one resource is patchy at fine scales and another varies
broadly across the study area. vignette("v02-user-guide", package = "multiScaleR") uses these layers to simulate zero-inflated, N-mixture,
and occupancy data.
Value
A SpatRaster with dim rows and columns, cell size resolution,
extent 0 to dim * resolution in x and y, no coordinate reference system,
and four layers:
-
bin1: binary, fine-scale (autocorr_range1). 1 where the field, rescaled to 0 to 1, is at least 0.55, and 0 elsewhere. -
bin2: binary, broad-scale (autocorr_range2). 1 where the rescaled field is below 0.4, and 0 elsewhere. -
cont1: continuous, rescaled to 0 to 1, with a range offloor(0.75 * autocorr_range1)cells, and at least 1. -
cont2: continuous, rescaled to 0 to 1, with a range offloor(1.25 * autocorr_range2)cells, and at least 1.
The thresholds are on the rescaled values, not percentiles, so the share
of cells equal to 1 in bin1 and bin2 varies from one simulation to the
next.
See Also
sim_dat(), sim_dat_unmarked(), kernel_prep()
Examples
## Four 50 x 50 layers with 20 m cells (1,000 m on a side)
r_sim <- sim_rast(dim = 50, resolution = 20, user_seed = 555)
r_sim
# Binary layers in the top row, continuous below. Layers ending in 1 are
# fine-scale and layers ending in 2 broad-scale
terra::plot(r_sim)
# Share of cells equal to 1 in each binary layer
terra::global(r_sim[[c("bin1", "bin2")]], "mean")
## Broader patterns: raise the fine-scale range from 2 to 10 cells
r_smooth <- sim_rast(dim = 50, resolution = 20, autocorr_range1 = 10,
user_seed = 555)
terra::plot(r_smooth[[c("bin1", "cont1")]])
Simulate Posterior Predictive Responses
Description
Generate replicate responses for fitted or new observations. Each replicate includes joint parameter uncertainty, any requested new-group effects, and the scatter of individual observations around their means, so replicates show the values you might record.
Usage
## S3 method for class 'multiScaleR_bayes'
simulate(
object,
nsim = 1L,
seed = NULL,
newdata = NULL,
kernel_inputs = NULL,
row_id = NULL,
re.form = NULL,
scale_re.form = NULL,
new_scale_levels = c("error", "sample", "zero"),
new_response_levels = c("error", "sample", "zero"),
trials = NULL,
include_fixed = FALSE,
...
)
Arguments
object |
A fitted |
nsim |
Positive integer number of replicate data sets; default 1. |
seed |
Optional positive integer simulation seed. Your own random-number state is restored after simulation, even when it fails. |
newdata |
|
kernel_inputs |
Prepared landscape inputs for |
row_id |
Name of the column in |
re.form |
|
scale_re.form |
|
new_scale_levels, new_response_levels |
What to do with a group level
that was not in the fitted data, set separately for scale and response
random effects. |
trials |
Positive integer binomial trial totals, one value or one per
observation row. The default |
include_fixed |
Logical. With new data, |
... |
Not used. Supplying any further argument is an error. |
Value
A data frame with one row per fitted or new observation and one
column per replicate data set, named sim_1, sim_2, and so on. Values
are counts for Poisson and NB2 models, success counts out of the fitted
or supplied trial totals for binomial models (not proportions), and
response units for Gaussian models. Each column uses
one complete posterior vector, drawn at random with replacement, together
with the requested random effects.
For new data, a point_ids attribute gives the prepared landscape ID of
each row, and a new_groups attribute lists the unseen levels that were
sampled or set to zero, as in predict(). A prediction_contract
attribute (see prediction_contract) marks the result as posterior
predictive replicates that include observation noise and records the
policies for included effects. It does not establish diagnostic
eligibility or calibration.
Check the model against the data
Compare summaries of the replicate data sets with the same summaries of
the observed response. An observed value far outside the replicated range
means the model cannot reproduce that feature. Good sampling diagnostics do
not show that the observation model fits the data, and agreement on one
statistic does not establish adequacy.
vignette("v13-bayesian-scales", package = "multiScaleR") works through
such a check. To use bayesplot, convert the replicates to a matrix with one
simulated data set per row, t(as.matrix(replicated)). For a count model,
ppc_stat() with stat = function(y) mean(y == 0) checks the fraction of
zeros.
Simulate new groups jointly
Within one call, new-group effects are drawn afresh for each replicate
data set and shared by all of its rows in that group. Different new groups
are independent given the population parameters, whose joint posterior
dependence is kept. Observation noise is then drawn separately for each
row. Separate calls do not share a realization across components or
batches, so put every row that enters a joint question into one call.
Reusing a seed across predict_scales(), predict(), and simulate()
does not promise matching latent effects, because the three functions use
their random numbers differently.
To get an interval for a total, sum each replicate column first with
colSums() and then take quantiles of the sums. Adding the limits of
individual intervals overstates the range of the total.
The three prediction functions return different orientations, which
matters for joint contrasts and totals. simulate() returns observations
by replicates. predict(summary = FALSE) returns posterior draws by
observations, and predict_scales(summary = FALSE) returns a named list of
draws-by-observations matrices, one per landscape predictor.
Supply trials for binomial data
For a binary fit, new observations default to one trial. For a fit to
cbind(successes, failures), supply the actual future totals, for example
trials = rep(10L, nrow(newdata)). simulate() then returns success
counts out of those totals, while predict() returns success
probabilities whatever the number of trials.
See Also
multiScale_bayes(), simulate_bayes_prior(),
predict.multiScaleR_bayes(), predict_scales(),
prediction_contract, multiScaleR_bayes;
vignette("v14-bayesian-prediction", package = "multiScaleR").
Examples
example <- readRDS(system.file("extdata", "bayesian-annual-example.rds",
package = "multiScaleR"))
replicated <- simulate(example$fits$pooled, nsim = 20, seed = 94)
dim(replicated) # one row per original observation, one column per replicate
# Posterior predictive check of the fraction of zero counts
range(vapply(replicated, function(y) mean(y == 0), numeric(1)))
mean(example$data$count == 0) # observed fraction of zero counts
# These replicate counts include observation noise. Fitted means do not.
# Counts at eight future surveys, and an interval for their total
forecast <- readRDS(system.file("extdata", "bayesian-prediction-example.rds",
package = "multiScaleR"))
future <- simulate(forecast$fit, nsim = 200, seed = 803,
newdata = forecast$newdata, kernel_inputs = forecast$kernel_inputs,
row_id = "site_year", new_scale_levels = "sample",
new_response_levels = "sample")
quantile(colSums(future), c(0.025, 0.5, 0.975)) # total of the eight surveys
Simulate Prior Predictive Responses and Landscape Scales
Description
Check what the complete set of priors implies before you fit. Each simulated data set draws every parameter from its prior and then generates responses for the prepared observations, including the scatter of individual observations around their means.
Usage
simulate_bayes_prior(object, nsim = 100L, seed = NULL)
Arguments
object |
A |
nsim |
Positive integer number of prior predictive data sets; default 100. More data sets explore the priors more thoroughly and use more memory. |
seed |
Optional positive integer simulation seed. Your own random-number state is restored afterward, even when simulation fails. |
Value
A list with these elements.
-
responses: a data frame with one row per prepared observation and one column per simulated data set, namedsim_1,sim_2, and so on. Values are counts for Poisson and NB2 models, success counts out of the prepared trial totals for binomial models, and response units for Gaussian models. -
means: a data frame of the matching expected responses. Binomial values are success probabilities, so multiply by the trial totals for expected counts. Other families use the response scale. Each mean is conditional on its own prior draw and excludes observation noise. It is not an expectation over the whole prior. -
log_scales: a named list with one matrix per landscape predictor. Rows are its distinct combinations of scale covariates and groups, labeled as inposterior_scales(), and columns match the simulated data sets. Entries are natural log distances in projected map units, so exponentiate medians and interval limits to read them as distances. -
observation_ids: the prepared landscape ID of each observation, in the row order ofresponsesandmeans. -
priors: the complete prior settings used, with defaults filled in.
Read the simulations
Compare the simulated magnitudes, fractions of zeros, and scale quantiles
with ranges that are scientifically plausible for your design. Extreme
simulations show that a prior is loose for your design and may call for a
tighter setting, such as a smaller beta_sd. They are not evidence of a
poor posterior fit, and they do not choose a prior for you.
vignette("v13-bayesian-scales", package = "multiScaleR") works through
this check.
Broad distance priors can have infinite arithmetic moments, so summarize scales with log-scale summaries and distance quantiles. Broad response group-SD priors with a log link can also give infinite prior predictive count moments. A finite simulation does not show that a mean over prior replicates exists.
How the simulation works
Each data set uses one complete, independent prior parameter vector. All observations in a group share that vector's group effect, which keeps the dependence that the scale and response formulas specify. Scale effects and response effects are drawn separately, as the model specifies.
Simulation conditions on the prepared maps, fixed covariates, offsets, group identities, binomial trial totals, and the frozen predictor standardization. It uses no observed responses and no posterior draws, and it creates no new sites or years. No optional Bayesian package is needed. A nonfinite value stops with an error that names the replicate. Values are never clipped and draws are never replaced.
See Also
multiScale_bayes(), simulate.multiScaleR_bayes(),
posterior_scales();
vignette("v13-bayesian-scales", package = "multiScaleR").
Examples
example <- readRDS(system.file("extdata", "bayesian-annual-example.rds",
package = "multiScaleR"))
prepared <- multiScale_bayes(count ~ habitat + factor(year) + (1 | site),
example$inputs, example$data, scales = list(habitat = ~1 + (1 | year)),
row_id = "site_year", priors = list(scale_median = 250), method = "prepare")
prior <- simulate_bayes_prior(prepared, nsim = 20, seed = 63)
# Fraction of zero counts in each prior data set, against the observed 0.04
range(vapply(prior$responses, function(y) mean(y == 0), numeric(1)))
# The default priors are loose and allow far more zeros than were observed.
# Prior range of sigma for each year, in meters
exp(apply(prior$log_scales$habitat, 1, stats::quantile, c(.025, .5, .975)))
# These are prior scale intervals, not posterior estimates or evidence of fit.
Create Spatially Blocked Cross-Validation Folds
Description
Lay a square grid over projected points and assign whole grid blocks to assessment folds, so that the model must predict parts of the landscape it was not fitted to. Optional sampling groups join the blocks they touch into indivisible units. A distance buffer can exclude nearby training units without dropping assessment rows.
Usage
spatial_cv_folds(
coords,
block_size,
k = 5,
ids = NULL,
group = NULL,
buffer = 0,
origin = c(0, 0),
crs = NULL
)
Arguments
coords |
Projected |
block_size |
Positive width of each grid cell, in the units of the coordinate CRS (usually meters). Larger blocks put more distance between held-out points and their nearest training points, which moves the task closer to predicting a new area. |
k |
Number of folds, at least two. The default is five. At least |
ids |
Unique character row IDs. Defaults to the row names of |
group |
Optional sampling-group labels aligned with |
buffer |
Nonnegative training-to-assessment separation, in coordinate CRS units. The default 0 adds no exclusions. With a positive buffer, an entire training unit is excluded from a fold if any of its points lies within, or exactly at, this distance from an assessment point of that fold. Assessment rows are never dropped. A buffer that leaves a fold with no training rows is an error. |
origin |
Numeric grid origin of length two, in coordinate CRS units.
Defaults to |
crs |
Projected CRS declaration for coordinate tables, in any form
accepted by |
Details
Units are assigned largest first to balance row counts, with stable tie-breaking and no random draws, so the same call always gives the same folds. Several disjoint blocks can share a fold, so a fold need not be one contiguous region. Buffers measure the separation between sampled points, not the distance to block edges. Because whole units are excluded, the gap can be larger than requested, and a large buffer can leave few training points. Distance calculations use nearest-point searches rather than a dense training-by-assessment distance matrix.
Choose the block size, groups, buffer, and prediction target from the
sampling design and the ecological question. A projected CRS and a
distance buffer alone do not establish independence or validate
calibration. vignette("v08-cross-validation", package = "multiScaleR")
maps a set of spatial folds and shows how a buffer changes the training
sets.
Value
A named list of class multiScaleR_folds, structured as described
in grouped_cv_folds(). Each fold holds analysis and assessment row
IDs. Every row is assessed exactly once, although a buffer can leave a
row out of some training sets. The attribute fold_info holds the
method ("spatial"), k, block_size, buffer, origin, the crs
(as WKT) and its distance units, an assignment data frame with each
row's row_id, coordinates x and y, grid block, joined unit,
assessment fold, and group when supplied, and excluded, the
training IDs removed by the buffer in each fold.
See Also
grouped_cv_folds(), cross_validate(), cv_tab()
Examples
# Six points in three 50 m blocks (crs = 32617 declares meter units)
xy <- cbind(x = rep(c(0, 100, 200), each = 2), y = rep(c(0, 10), 3))
spatial_cv_folds(xy, block_size = 50, k = 3, crs = 32617)
# The bundled survey points, in 1,000 m blocks. A 320 m buffer removes
# training blocks that have a point near any held-out point.
data("surv_pts")
pts <- crds(vect(surv_pts))
buffered <- spatial_cv_folds(pts, block_size = 1000, k = 3, buffer = 320,
crs = 32617)
buffered # 'excluded' counts rows used for neither fitting nor scoring
head(attr(buffered, "fold_info")$assignment) # block and fold of each row
Summarize a multiScaleR fit
Description
Summarizes a fit from multiScale_optim(): the estimated scales of effect
with standard errors and intervals, the distances that contain most of each
kernel's weight, and the fitted model at those scales.
Usage
## S3 method for class 'multiScaleR'
summary(object, profile = FALSE, dimension = c("2d", "1d"), ...)
Arguments
object |
An object of class |
profile |
Logical. If |
dimension |
Character. |
... |
Optional arguments. |
Value
An object of class summary_multiScaleR, a list that prints as a
report. Its elements:
-
opt_scale: data frame with one row per optimized covariate and columnsMean(estimated sigma, map units),SE,2.5%, and97.5%. Itsinterval_methodattribute records"wald"or"profile"for each row. -
opt_shape: the same table for the shape parameter underkernel = "expow", otherwiseNULL. -
opt_dist_1d: distances in map units, with columnsMean,2.5%, and97.5%, at which a kernel's cumulative weight along a line through the point reachesprob(about 1.65 sigma for a Gaussian kernel at 90%). -
opt_dist_2d: the radius, in map units and with the same columns, of the circle around the point that holdsprobof the weight of an ideal, untruncated kernel on a plane (about 2.15 sigma for a Gaussian kernel at 90%). -
opt_distandopt_distance: two names for the distance table selected bydimension(2D by default, rather than the 1D definition used through version 0.7.3). -
dimension: the selected definition,"2d"or"1d". -
prob: the cumulative weight proportion used for the distances. -
fitted_mod: the model refit at the estimated scales (opt_modof the fit). -
kernel: the kernel name. -
hard_radius: names of covariates whose scale is a hard radius. -
diagnostics,warn_message,next_run,call: copied from the fit; see multiScaleR. -
backend: the backend name, present for the analytic and conditional-logistic backends.
Read the summary
Sigma is the kernel's scale parameter, and it is not itself a distance you
can report. The distance tables translate it into the distance that holds
90 percent (by default) of the kernel's weight, which is usually the number
to report as the scale of effect. Hard-radius covariates report their
radius in both tables. See kernel_dist() and multiScaleR-kernels for
when to use each definition and for the formulas.
Kernel-scale limits default to Wald intervals from the Hessian. For
hard-radius landscape and unweighted surface metrics, and every radius
estimated under kernel = "fixed", Hessian standard errors and Wald limits
are shown as NA; use profile = TRUE for profile-likelihood limits. An
error during profiling is reported rather than returning invalid limits.
Set dimension = "1d" to keep the original opt_dist and opt_distance
values in existing scripts. For extraction that does not depend on the
setting, use opt_dist_1d or opt_dist_2d. Neither choice changes the
fitted sigma, coefficients, or likelihood. The 2D radius is for an ideal
continuous kernel; max_D, raster edges, missing cells, and cell geometry
can change the realized weight in the prepared data.
Profile-likelihood intervals
The default refit backend caches profile results during the current R
session; the analytic backends recompute them. Set
options(multiScaleR.profile_cache_max_bytes = 64 * 1024^2) to bound the
retained cache entries (64 MiB by default), or set it to zero to disable
caching and clear retained entries at the next profile request. Oversized
entries and custom refits are computed without the cache. A failure to
store a cache key warns and computes the same intervals directly, while
numerical profile failures still raise errors. The returned refit scale
table records cache availability in its profile_cache attribute. The
option bounds retained entries, not temporary key construction or the
memory used by the numerical profile.
Analytic backends
For backend = "profile_glm" or "joint_nb2", default scale limits use
joint information on the log scale and are omitted when the
identifiability checks fail (see multiScaleR-fitting-methods). A returned
Wald interval describes the local curvature around the selected optimum
and can extend beyond the searched scale range. Coverage can fall below the
nominal level even for an interior fit, so inspect the likelihood over the
admissible range when scale inference matters.
With profile = TRUE, the analytic summary follows the connected
likelihood region around the fitted scale, and an endpoint at a search
bound is labeled bound-limited. For a supported one-scale NB2 fit,
scale_inference() checks the full range and reports the regions it
detects. If a full-range profile suggests a competing optimum, compare
additional starts, including both bounds. The printed coefficient summary
still conditions on the estimated kernels; use vcov.multiScaleR() for the
joint covariance.
See Also
multiScale_optim(), print.summary_multiScaleR(),
profile_sigma(), kernel_dist(), and
vignette("v09-estimates-and-intervals", package = "multiScaleR").
Examples
data(pts)
data(count_data)
hab <- terra::rast(system.file("extdata", "hab.tif",
package = "multiScaleR"))
inputs <- kernel_prep(pts = pts, raster_stack = hab, max_D = 250,
kernel = "gaussian", verbose = FALSE)
fit <- multiScale_optim(glm(y ~ hab, family = poisson, data = count_data),
inputs, verbose = FALSE)
s <- summary(fit)
s$opt_scale # sigma with Wald limits, in map units
s$opt_dist_2d # radius holding 90 percent of the kernel weight
# Profile-likelihood limits instead of Wald limits
summary(fit, profile = TRUE)$opt_scale
Estimate Scales of Effect with Bayesian Inference
Description
Estimate landscape scales of effect and response coefficients together, as one posterior distribution that combines what the data say with the priors you state. Give each landscape predictor one shared scale, let the scale change with measured covariates, or let it vary among groups such as regions or years. This interface is experimental. A printed fit reports "Experimental Bayesian landscape-scale model".
Usage
## S3 method for class 'multiScaleR_bayes'
summary(object, ...)
## S3 method for class 'multiScaleR_bayes'
print(x, ...)
multiScale_bayes(
formula,
inputs,
data,
scales = NULL,
family = c("nbinom2", "poisson", "binomial", "gaussian"),
row_id = NULL,
priors = list(),
method = c("sample", "prepare", "laplace", "marginal", "slice"),
chains = 4L,
iter = 2000L,
warmup = floor(iter/2),
seed = NULL,
control = list(),
laplace_draws = 2000L,
cores = 1L
)
Arguments
object |
A |
... |
Not used. Supplying any further argument is an error. |
x |
A |
formula |
Two-sided response formula, such as
|
inputs |
Prepared landscape inputs from |
data |
Data frame with one row per observation, holding the response,
fixed covariates, and grouping variables. Landscape predictors whose
scales are estimated are rebuilt from |
scales |
Named list with one one-sided formula for each landscape
predictor in |
family |
Response family, one of |
row_id |
Optional name of a column in |
priors |
Named list of prior settings to change. Settings you leave
out take their defaults, and the default |
method |
Computation, one of |
chains |
Number of independent chains for |
iter |
Iterations per chain, including warmup; default 2000. Raise it when effective sample sizes fall short. |
warmup |
Iterations at the start of each chain that are discarded
while the sampler tunes itself; default |
seed |
Optional positive integer seed for sampling or approximation
draws; default |
control |
Named list of method-specific settings; default |
laplace_draws |
Number of draws taken from a |
cores |
Positive integer limit on parallel R worker processes. The default of 1 runs everything in the current session. Parallel fits need the optional package processx. See "Use parallel workers". |
Value
An object of class multiScaleR_bayes, a list that holds the
frozen model specification, the parameter layout in parameters, the
call, an inference label, and inference_metadata. Fitted objects
add posterior draws, diagnostics, and a record of the computation.
The class page multiScaleR_bayes describes every element, shows
where each parameter lives and on which scale, and explains how to
back-transform it. A prepared object (method = "prepare") has no draws.
summary() returns a list described in "Read the summary output".
print() shows the computation, family, number of observations, scale
formulas, and stored diagnostic status, and returns x invisibly.
Choose a computation method
method | What it computes | Optional packages |
"prepare" | Matches rows to landscapes and checks formulas, priors, and bins. Fits nothing | None |
"sample" (default) | The full posterior by NUTS, a gradient-based Markov chain Monte Carlo (MCMC) sampler, run through RTMB and tmbstan with the Laplace option off | RTMB, tmbstan, rstan, posterior |
"slice" | The same full posterior by a slice sampler written in R | None to fit. posterior (>= 1.6.0) for diagnostics |
"laplace" | A joint Gaussian approximation around the posterior mode, in the same unconstrained, noncentered coordinates the samplers use | RTMB |
"marginal" | Numerical integration over one scale-group SD, with conditional Laplace approximations for every other parameter | RTMB, plus posterior with importance correction |
check_bayes_setup() reports whether these packages are installed.
Joint Laplace and uncorrected marginal Laplace are exploratory. In matched
simulations they disagreed with full sampling about annual-scale
probabilities even when their own numerical checks passed. Confirm every
quantity you report with "sample" or "slice".
vignette("v15-bayesian-computation", package = "multiScaleR") compares
the methods on one model and shows what to do when a fit struggles.
Preparation, NUTS, slice sampling, and joint Laplace accept several landscape predictors and additive or crossed random intercepts. Marginal Laplace, with or without importance correction, needs exactly one scale-group SD across all landscape predictors. A second random scale term adds another SD even when it uses the same grouping variable. The function checks this before the numerical fit begins and never switches methods for you. A model that the syntax accepts can still fail to converge, leave a scale weakly identified, or give intervals of unknown calibration.
Choose a response family
-
"nbinom2": counts with a log link. The variance is\mu + \mu^2/\theta, where theta is the size (dispersion) parameter reported bysummary(). -
"poisson": counts with a log link. -
"binomial": a logit link. Supply 0 and 1 values,FALSEandTRUE, a two-level factor whose second level is a success, orcbind(successes, failures)for grouped trials. Response-scale predictions are success probabilities. -
"gaussian": a continuous response with an identity link and an estimated residual SD.
Write the response formula
The response formula accepts the following terms.
Fixed covariates, factors, and offsets.
Additive random intercepts such as
(1 | site). Each grouping variable can appear once in a formula and needs at least two levels. Use one for repeated observations at a site.Products, crossings, nesting, and factor interactions with a landscape predictor, such as
habitat * yearorhabitat:forest.habitat * yearestimates a separate habitat association in each year. It changes the response coefficients only and adds no year effect to the scale formula. An interaction between two landscape predictors still has one scale model per predictor. Every expanded coefficient keeps the normal prior on R's native factor and contrast coding.Transformations of fixed covariates.
scale(),poly(),splines::ns(), andsplines::bs()keep their training definitions, including inside nested expressions such asI(scale(temp))and in transformed offsets. Prediction reuses those constants for single rows, batches, and effect curves. Give a namespace prefix to any custom function that reuses one of these names, or compute its predictor before fitting.Arithmetic on landscape predictors and literal numbers, such as
I(habitat^2). The operators+,-,*,/, and^and the functionsexp(),log(),sqrt(),sin(),cos(), andtan()are allowed. These expressions act on the standardized kernel value after smoothing, not on raster cells, and keep the fixed reference standardization and coefficient priors.Cubic splines of a landscape predictor, from
splines::ns()orsplines::bs()with literal fixed knots. See "Use splines of a landscape predictor".
The following stop with an error: a fixed covariate inside an expression
with a landscape predictor (write the interaction habitat:forest rather
than I(habitat * forest)), any other function, including
nondifferentiable ones, a landscape predictor in an offset, and adaptive
spline recipes. An expression that is not finite is also an error. Values
are never clipped. Random slopes, spatial random fields, observation
weights, zero inflation, and imperfect detection are not supported.
method = "prepare" checks all of this before any optional package is
needed. vignette("v07-fitting-methods", package = "multiScaleR") lists
the covariate types each fitting route accepts.
Use splines of a landscape predictor
Supply literal knots and two increasing Boundary.knots, with every knot
distinct and strictly inside the boundaries, for example
splines::ns(habitat, knots = 0, Boundary.knots = c(-3, 3)). Knots are in
the units of the standardized predictor, after the fixed reference
transformation. To place knots at raw kernel-weighted values, prepare the
model once with the plain predictor, then subtract
prepared$specification$center and divide by
prepared$specification$spread for both the knots and the boundaries.
Write the resulting numbers into the formula. Never learn knots from
prediction data.
Basis values and their derivatives update at every candidate scale, while
the knots, the coefficient basis, and the priors stay fixed. All basis
columns share the scale of their source predictor, including in factor
interactions. Natural-spline tails are linear on the link scale. These are
unpenalized bases of fixed complexity, with no smoothing-variance
uncertainty and no monotonicity constraint. Adaptive df recipes,
repeated or boundary knots, and degrees other than 3 are not supported
here. The error message points to the refit backend of
multiScale_optim() for those.
Write the scale formulas
Each formula in scales models the natural log of one predictor's scale.
Scale formulas use columns of data. They cannot use landscape
predictors, offsets, or a rank-deficient design.
-
~1(the default): one shared scale for all observations. -
~ elevation: the log scale changes linearly with a numeric covariate.exp()of its coefficient is the multiplicative change in scale per unit of the covariate. -
~ year: fixed effects of a factor on the log scale, coded as contrasts with the first level. -
~0 + year: a separate log scale for each level, each with the same distance prior, and no pooling. An intercept-free formula must define disjoint factor levels like this. Every other formula needs an intercept. -
~1 + (1 | year): partial pooling. Years share a typical scale and an estimated between-year SD.
Random intercepts are noncentered, so each group's deviation is a
standard-normal latent value times the group SD. For ~1 + (1 | year) the
scale of year y is
\log D_y = \alpha + \tau z_y, with
z_y \sim N(0, 1). Here alpha is the log of the
typical scale and tau is the SD of log scale among years. exp(tau) is a
multiplier. A year one SD above typical has a scale exp(tau) times the
typical one. Years are exchangeable, and the model imposes no trend or
temporal autocorrelation.
The two formulas describe different parts of the model. A year effect in the response formula changes baseline abundance or occurrence. A year effect in the scale formula changes how far the landscape effect reaches.
Expand a dot in a scale formula
A dot expands every column of data, including the response and the
row-ID column. Remove the response, row keys, and unrelated columns
explicitly, as in ~ . - count - site_year. Only the active terms create
scale coefficients and priors. A removed column adds no coefficient and no
latent group coordinate. Prediction reuses the fitted active terms and
does not need the removed columns. A landscape predictor of the response
formula cannot also enter a scale formula.
Set the priors
| Setting | Default | What it controls |
scale_median | sqrt(inputs$min_D * inputs$max_D) | Prior median of each scale, in map units. One positive number, or a named vector with one value per landscape predictor. It is the center of the normal prior on each log-scale intercept, or on each coefficient of a ~0 + year formula |
scale_intercept_sd | 1 | SD of that normal prior, on the natural log scale |
scale_coef_sd | 0.5 | SD of the zero-centered normal prior on other scale coefficients (slopes and log-distance contrasts) |
scale_group_sd | 0.5 | Scale of the half-normal prior on each between-group SD of log scale |
beta_sd | 2.5 | SD of the zero-centered normal prior on each response coefficient, on the link scale |
response_group_sd | 1 | Scale of the half-normal prior on each response random-intercept SD, on the link scale |
dispersion_log_mean, dispersion_log_sd | 0, 1 | Mean and SD of the normal prior on the log of NB2 theta or of the Gaussian residual SD |
The scale priors act on log distances and set no hard limit at min_D or
max_D. A scale beyond max_D weights the extracted neighborhood ever
more evenly. It cannot draw on cells outside the prepared buffers.
posterior_scales() reports the posterior mass below min_D and above
max_D. Check what the priors imply with simulate_bayes_prior() before
you fit. vignette("v13-bayesian-scales", package = "multiScaleR")
converts these settings into distances and multipliers.
Understand the fixed standardization
Kernel means use the finite-cell numerator and denominator stored in the
bins. Missing raster cells are excluded and the remaining weights
renormalized. Each landscape predictor is then centered and scaled once,
across the fitting rows, at its prior median scale (scale_median). That
reference transformation is held fixed for every candidate scale, group,
and draw, including when a site has repeated observations or scales differ
among years. It is never estimated again from prediction rows. The
retained values are specification$center and specification$spread.
multiScale_optim() restandardizes at each fitted scale, so the two
functions give coefficients with different meanings. Here a response
coefficient is the change in the linear predictor for one reference SD of
the kernel-weighted predictor at scale_median, not at the fitted scale.
Its prior therefore has a fixed meaning, but its value changes when you
change scale_median. Report scale_median with any coefficient, and do
not compare these coefficients directly with those of multiScale_optim().
Weighted surface SQ is the square root of the kernel-weighted centered variance, divided by the sum of the weights, computed over each source's finite cells. It uses the same pooled reference transformation.
Plan memory for weighted SQ
Preparation records specification$surface$memory, which gives the number
of observation-cell evaluations (observation_cells), the retained buffer
bytes (retained_bytes), and a planning estimate of differentiation memory
(estimated_AD_bytes). Repeated observations count separately. Before a
differentiation tape is recorded for SQ, a conservative check against
installed RAM must pass, and the fit stops otherwise. The estimate is a
planning figure, not a quota or a guarantee, so leave headroom. Candidate
batches are evaluated in bounded pieces. Other optimized surface metrics
are not supported.
Read the summary output
summary() of a prepared object returns inference, family,
observations, and scale_formulas. For a fit with draws it returns a
list with these elements.
-
inference,family,observations: the computation label, the response family, and the number of observations. -
coefficients: a data frame with one row per responsecoefficientand columnsmean,median,sd,lower, andupper(a central 95% credible interval). Values are on the link scale, the log expected count for Poisson and NB2, the log odds for binomial, and response units for Gaussian models. For a count model,exp()of a landscape coefficient is the multiplicative change in the expected count per reference SD of the predictor. -
scales: theposterior_scales()table, with each scale in map units. -
scale_coefficients: a list with one data frame per landscape predictor. Intercepts and~0 + yearcoefficients are in log map units, soexp()gives a distance. Other coefficients are log-distance contrasts, soexp()gives a ratio of distances. -
group_sd: a list withlog_scale_group_sd, the between-group SD of log scale (tau) for each scale random term labeledpredictor:groupinterm, andresponse_group_sd, the random-intercept SDs on the link scale. Each isNULLwhen the model has no such term. These SDs measure variation among groups. They are not the standard error of any one group's scale. -
dispersion: NB2 theta or the Gaussian residual SD on its natural scale, orNULLfor Poisson and binomial models. -
diagnostics: the fit's stored checks, described on the class page multiScaleR_bayes.
Summary intervals are marginal central 95% intervals for individual
quantities, not a joint band. mean and sd are summaries of the draws.
For long-tailed distances, prefer median, lower, and upper. For an
importance-corrected fit, the scales table uses the resampled draws.
posterior_scales(fit, estimator = "weighted") summarizes the weighted
candidates directly, as plot() does by default.
The stored check covers the raw parameters and, for NUTS, sampler
behavior. It does not replace diagnose_bayes_scales() for the scales you
report, or a posterior predictive check with
simulate.multiScaleR_bayes().
Interpret weakly informed scales
A few years or regions say little about variation among them, so the group-SD prior can drive the answer. Compare plausible scale and group-SD priors, inspect posterior predictive behavior, and check the sampling diagnostics. A response coefficient near zero leaves its landscape scale weakly identified even when the chains mix well. The half-normal prior on a group SD has no point mass at zero, so a positive lower interval limit is not a test of equal scales. Compare a shared-scale model instead. Numerical accuracy depends on the response, the scale design, and the method. Interval calibration for general ecological data sets has not been established.
Use parallel workers
cores sets how many local R processes run at once. NUTS and slice
sampling spread chains across workers, so the useful limit is chains.
Joint and uncorrected marginal Laplace spread optimizer starts, so the
limit is the number of starts. Marginal integration still visits grid
nodes in order, so each node can start from the previous fits. With
importance correction, workers also evaluate batches of candidate
posterior densities, while proposal generation and diagnostics stay in
the main process. Preparation uses one process.
Each worker holds its own copy of the model data and, where needed, its
own differentiation tape, so memory use rises with cores. Temporary
worker files are removed after fitting. Worker start-up and data transfer
can make small fits slower. The effective limit is recorded in
sampling$cores, laplace$cores, or marginal$cores.
Set computation controls
| Setting | Method | Default | What it does |
adapt_delta | "sample" | 0.9 | Target acceptance rate during NUTS adaptation, strictly between 0 and 1. Raise it when transitions diverge |
max_treedepth | "sample" | 12 | Maximum NUTS tree depth. Raise it when the sampler hits the limit |
starts | "laplace", "marginal" | 6 for Laplace, 3 per grid node for marginal | Deterministic, dispersed optimizer starts. Every start adds run time |
iter.max | "laplace", "marginal" | 1000 | Optimizer iterations per start |
max_grid | "marginal" | 129 | Largest integration grid, 33, 65, 129, or 257 nodes. More nodes cost more time |
cdf_tol, quantile_tol, logz_tol | "marginal" | 0.005, 0.02, 0.01 | Largest change allowed between successive grids in the SD CDF, its 2.5%, 50%, and 97.5% quantiles (in prior SDs), and the log normalizing constant |
correction | "marginal" | "none" | "importance" reweights the approximation against the full posterior |
importance_min | importance | 16384 | Minimum number of production candidates retained |
importance_max | importance | 65536 | Cap on production candidates, 16384, 32768, 65536, or 131072 |
importance_df | importance | 7 | Degrees of freedom of the Student t proposal, 7 or 5 |
importance_refinements | importance | 1 | Further proposal adaptations allowed after a failed stage, 0, 1, or 2 |
nested_response | importance | TRUE, or FALSE with conditional_beta = TRUE | Integrate response random effects when locating conditional modes |
conditional_beta | importance | FALSE | Experimental. Propose response coefficients conditional on each candidate's scales and response random effects |
Grid refinement stops when all three changes fall within their tolerances. It measures numerical integration error, not Laplace error.
importance_max is a cap, not a target. A population that passes its
checks at a smaller size stops there. To require more candidates, as you
may for precise annual quantiles, also raise importance_min, which takes
the same values and cannot exceed importance_max. A separate training
pilot of 16384 candidates always runs first and is discarded. Larger
populations cost more, and they guarantee neither a chosen Monte Carlo
error nor recovery of a missed posterior region. importance_df = 5 gives
heavier proposal tails, which can help when importance ratios are
unstable, though it can need more candidates. With
importance_refinements = 1, a failed first production stage of 16384
candidates trains one further proposal. Its candidates are discarded and a
fresh final stage is drawn. These settings change sampling efficiency,
not the priors or the diagnostic thresholds.
nested_response = FALSE keeps the original joint conditional proposal,
which can miss response-SD uncertainty. An explicit
nested_response = TRUE requires importance correction.
conditional_beta = TRUE also requires importance correction and selects
nested_response = FALSE unless you supply it, so an explicit
nested_response = TRUE is then an error. Gaussian coefficient
conditionals are exact. Other families use a normalized Student t proposal
with 7 degrees of freedom, and a fixed 20% latent-prior component guards
regions the local geometry misses. Conditional optimization costs more per
candidate and does not guarantee precise interval endpoints.
vignette("v15-bayesian-computation", package = "multiScaleR") reports the
simulation evidence for the corrected proposals and its limits.
How each computation works
Slice sampling
Slice sampling updates blocks of parameters in turn from the full posterior. For Gaussian responses it draws the regression coefficients from their exact conditional distribution. It reuses kernel values when it updates response parameters and recomputes only the changed kernel during scale updates. Efficiency depends on the data set and on dependence among scales and response effects, so compare Rhat and effective sample size per second before choosing a sampler for a larger fit.
Joint Laplace approximation
The Laplace method inverts the positive-definite Hessian of the full
negative log posterior at a numerically stationary mode, including the
Jacobians of the log-SD coordinates. It approximates all parameters
jointly. It neither fixes the estimated pooling SDs nor integrates random
effects with a nested approximation. Non-positive curvature, or failure to
find a stationary mode, stops the fit with an error whose starts element
keeps every attempted solution. Catch it with tryCatch() to inspect them.
Distinct modes within two log-posterior units trigger a warning. Skewness,
weak scale identification, and dependence between group SDs and year
effects can make the pooling and the intervals inaccurate even when the
checks pass. Compare important results with method = "sample",
especially with few years or weak landscape effects. chains, iter, and
warmup are unused.
Marginal Laplace approximation
The marginal method needs exactly one scale-group SD, such as the
between-year SD in list(habitat = ~1 + (1 | year)). It integrates that
SD numerically on a grid in the coordinates of its half-normal prior CDF,
which leaves the prior unchanged and allows a skewed SD distribution. Every
other parameter, including any response random-intercept SD, gets a
conditional joint Gaussian approximation at each grid node, and the
conditional posterior volume corrects the SD marginal. This is not full
INLA. Linear interpolation between nodes and triangular mixture sampling
give continuous SD draws and carry conditional dependence into the other
parameters. The grid endpoints use SDs of 1e-8 and 8 times the prior
scale. These approximate the prior CDF endpoints and do not bound the
sampled SDs. The checks also fail when more than 0.001 of the posterior
mass lies above prior CDF 0.9999, or more than 0.01 of the node weight
carries competing conditional modes. A failed node stops the fit rather
than being dropped. Conditional skewness, remaining multimodality, and
response-SD uncertainty still call for comparison with full sampling.
Importance correction
control = list(correction = "importance") targets the same full
posterior as NUTS by reweighting candidates from a proposal built on the
marginal approximation. It does not rescale intervals by an empirical
coverage factor. A training pilot draws from an equal mixture of
multivariate and coordinatewise Student t distributions (7 degrees of
freedom, or 5 with importance_df = 5, inflated by a factor of 1.2) and
fits local proposal means and covariances. The pilot is then discarded.
Production candidates come 80% from the learned proposal and 20% from the
original one. Training weights are tempered and learned covariances are
shrunk toward the original, which stabilizes learning without changing the
target. Production weights are neither smoothed nor truncated, and every
mixture density, including the prior-CDF Jacobian, enters the importance
ratio. A 1% uniform component in prior-CDF coordinates keeps the proposal
positive in very small tails. A further 1% normal component for the log
SD, with mean log(2 * prior SD) and SD 0.6, covers SDs beyond the
numerical CDF endpoints. A refinement after a failed stage fits a new
component with 60% of the proposal weight and keeps 40% for the previous
mixture. Training stages never enter the final estimate, though history
and production_candidates keep their diagnostics and cost.
With nested response integration, outer curvature comes from central differences of RTMB's analytic gradient. With exactly one response random-intercept term, each candidate draws its site effects from independent Student t proposals with 20 degrees of freedom, centered on their conditional modes and scaled by their curvatures. This follows the dependence of site effects on the sampled response SD. Only the smaller outer covariance is stored at each SD node, which avoids dense site-by-site matrices. More response terms use an expanded joint proposal, and its reliability has not been established. Nonfinite site geometry falls back to the normalized prior proposal for that candidate and is counted. Candidates are never dropped. Unusable learned covariances keep their original nodes. The full-posterior ratios still correct these proposals, and the same checks apply.
The corrected checks require Pareto k at most 0.7, raw weight effective
sample size (ESS) at least 1000, tail-indicator ESS at least 400, maximum
weight at most 0.01, and split-half CDF differences at most 0.05.
Indicators are evaluated at the 2.5%, 50%, and 97.5% quantiles of the
unconstrained parameters, annual log scales, and group SDs. These are
importance diagnostics, not MCMC Rhat or ESS. The original proposal flag
stays in diagnostics$proposal_passed, but only the corrected checks
decide eligibility. A finite candidate set can still miss modes or tails.
A warning or a failed check calls for NUTS, and passing does not establish
interval calibration.
See Also
The class page multiScaleR_bayes for the returned object;
check_bayes_setup(), simulate_bayes_prior(), posterior_scales(),
plot.multiScaleR_bayes(), diagnose_bayes_scales(),
predict.multiScaleR_bayes(), predict_scales(),
simulate.multiScaleR_bayes(), cross_validate_bayes(),
kernel_prep_by_group(), multiScale_optim(), and
multiScaleR-glossary for terms;
vignette("v13-bayesian-scales", package = "multiScaleR") for fitting
and reading a model,
vignette("v14-bayesian-prediction", package = "multiScaleR") for
prediction, and
vignette("v15-bayesian-computation", package = "multiScaleR") for
choosing and checking a computation method.
Examples
# Annual survey example: 100 counts at 25 sites over five years, with one
# habitat map per year prepared by kernel_prep_by_group()
example <- readRDS(system.file("extdata", "bayesian-annual-example.rds",
package = "multiScaleR"))
# Check the model before fitting. Preparation matches each row to its
# landscape through row_id and needs no optional packages.
prepared <- multiScale_bayes(count ~ habitat + factor(year) + (1 | site),
example$inputs, example$data, scales = list(habitat = ~1 + (1 | year)),
row_id = "site_year", family = "nbinom2",
priors = list(scale_median = 250), method = "prepare")
prepared # family, observations, and scale formula
prepared$inference_metadata$uncertainty$intervals # "not_provided" yet
# The same model fitted with NUTS, stored as 2,000 thinned draws
fit <- example$fits$pooled
fit_summary <- summary(fit)
fit_summary$diagnostics$passed # TRUE: the sampler checks passed
# Response coefficients on the log expected-count scale
fit_summary$coefficients[c("coefficient", "median", "lower", "upper")]
# Sigma for each year, in meters, after partial pooling
fit_summary$scales[c("group", "median", "lower", "upper")]
# Tau, the SD of log sigma among years, and the multiplier exp(tau)
fit_summary$group_sd$log_scale_group_sd[c("term", "median", "lower", "upper")]
exp(fit_summary$group_sd$log_scale_group_sd$median)
# A slice-sampled fit with one shared sigma per layer. Its call shows the
# sampling arguments, and its scale intercepts are in log meters.
shared <- readRDS(system.file("extdata", "cache-bayesian-scales.rds",
package = "multiScaleR"))$fit
shared$call
shared_coef <- summary(shared)$scale_coefficients
exp(sapply(shared_coef, function(x) x$median)) # median sigma in meters
# See vignette("v13-bayesian-scales", package = "multiScaleR") for fitting
# and interpretation.
Survey points for the vignette example
Description
Locations of the 100 survey points that go with landscape_counts and the
landscape.tif raster.
Usage
data(surv_pts)
Format
An sf point object with 100 features, no coordinate reference
system, and coordinates in the map units of landscape.tif. Its one
attribute column, obs, is a numeric column carried over from the
simulation; the vignettes use landscape_counts$counts as the response.
Source
Simulated for this package.
See Also
landscape_counts, landscape,
vignette("v01-quickstart", package = "multiScaleR").
Examples
data(surv_pts)
land <- terra::rast(system.file("extdata", "landscape.tif",
package = "multiScaleR"))
terra::plot(land$land1)
terra::points(terra::vect(surv_pts), pch = 19)
Fitted Distance-Removal Model with a Fixed-Range Abundance Field
Description
The class of object returned by fit_gdr_response_field(). It extends the
unmarkedFitGDR class of unmarked with one slot, response_field, which
holds the field geometry, the covariance retained from the fit and its
diagnostics. Most unmarked methods work as usual. The methods listed
below are replaced or stopped because the inherited versions do not handle
the correlated field.
Usage
## S4 method for signature 'unmarkedFitGDRField'
confint(object, parm, level = 0.95, type, method = c("normal", "profile"))
## S4 method for signature 'unmarkedFitGDRField'
update(object, ...)
## S4 method for signature 'unmarkedFitGDRField'
simulate(object, nsim = 1, seed = NULL, ...)
## S4 method for signature 'unmarkedFitGDRField'
profile(fitted, ...)
## S4 method for signature 'unmarkedFitGDRField'
ranef(object, ...)
Arguments
object, fitted |
A fitted |
parm, type, level, method |
Arguments of |
... |
Not used. The stopped methods ignore extra arguments. |
nsim, seed |
Not used. |
Slots
response_fieldA named list. The elements you are most likely to read are:
-
definition: the field definition, withcovariance("exponential"), the suppliedrange,range_estimated(alwaysFALSE), the linearunitsof the CRS,state_count(the number of blocks) andsurvey_count. -
coords: the survey coordinates supplied tofit_gdr_response_field(), one row per survey.blockgives each survey's block number, andcrsholds the CRS as WKT text. -
point: the complete parameter vector at the optimum, named by TMB block. It holds the fixed coefficients (beta_*, link scale), the log SDs (lsigma_*) and the block deviations in their internal whitened form (b_lambda). -
joint_covariance: the covariance matrix ofpoint, the inverse of the joint precision returned byTMB::sdreport(). -
lower: the lower Cholesky factor of the block correlation matrix. Multiplying the whitened deviations bylowergives the physical field values reported bycoef(). -
diagnostics: the checks of the selected start, such aspdHess,maximum_absolute_gradient,conditional_latent_maximum_absolute_gradientandconditional_latent_Newton_decrement. -
settings: the evaluatedtmb_settings.audit_fileis the path of the final audit record, andmax_memory_mbis the planning budget used bypredict().
The remaining elements are frozen design recipes and SHA-256 fingerprints. Every method checks them before use and stops if any has changed, so do not edit this slot.
-
Methods for this class
| Method | Behavior |
coef(), logLik(), unmarked::sigma(), summary() | Inherited from unmarked. Field values reported by coef(fixedOnly = FALSE) are physical deviations on the log density scale |
predict() | Replaced. See predict,unmarkedFitGDRField-method |
vcov() | Replaced. See vcov,unmarkedFitGDRField-method |
confint() | Normal (Wald) intervals from the retained covariance. method = "profile" stops |
update() | Stops. Refit through make_gdr_refitter(), which keeps the field |
simulate(), profile(), ranef() | Stop. They are not available for this class |
See fit_gdr_response_field() for a table that locates each parameter and
its scale, and vignette("v12-distance-removal", package = "multiScaleR")
for a worked example.
See Also
fit_gdr_response_field(), make_gdr_refitter(),
response_field_geometry()
Examples
# The field needs unmarked 1.5.2 and TMB 1.9.25.
if (requireNamespace("TMB", quietly = TRUE) &&
utils::packageVersion("unmarked") == "1.5.2" &&
utils::packageVersion("TMB") == "1.9.25") {
# Eight survey blocks 1 km apart, six point counts in each
block <- factor(rep(paste0("b", 1:8), each = 6))
hab <- rep(seq(-1, 1, length.out = 6), 8)
shift <- c(-0.4, -0.3, -0.1, 0, 0.1, 0.2, 0.35, 0.4)[block]
sim <- sim_dat_gdr(density = exp(log(400) + 0.5 * hab + shift),
distance_scale = 40, removal = 0.2, dist_breaks = c(0, 25, 50, 75),
interval_lengths = c(2, 3, 5), interval_units = "minutes",
site_covs = data.frame(hab = hab, block = block), seed = 1)
template <- unmarked::gdistremoval(lambdaformula = ~ hab + (1 | block),
removalformula = ~ 1, distanceformula = ~ 1, data = sim$observed,
keyfun = "halfnorm", mixture = "P", output = "density",
unitsOut = "kmsq", K = 60, engine = "TMB",
starts = c(log(400), 0, log(40), qlogis(0.2), log(0.3)))
block_xy <- cbind(x = 500000 + 1000 * (as.integer(block) - 1),
y = 4400000)
rownames(block_xy) <- rownames(unmarked::siteCovs(sim$observed))
cold <- c("beta_lambda[1]" = log(300), "beta_lambda[2]" = 0,
"beta_dist[1]" = log(30), "beta_rem[1]" = qlogis(0.4),
"lsigma_lambda[1]" = log(0.5))
settings <- list(method = "BFGS", se = TRUE, threads = 1L,
control = list(maxit = 2500L, reltol = 1e-10))
field_fit <- fit_gdr_response_field(template, block_xy, crs = 32617,
range = 2000, cold_starts = list(cold = cold),
audit_dir = tempfile("gdr-field-"), tmb_settings = settings)
# TRUE: the methods of unmarked still apply
print(methods::is(field_fit, "unmarkedFitGDR"))
# The supplied range, its units, and the number of blocks and surveys
str(field_fit@response_field$definition[c("range", "units",
"state_count", "survey_count")])
# Wald limits for the abundance coefficients, on the log scale
print(confint(field_fit, type = "lambda"))
}
Audit Survey Identities and Paired Distance-Removal Counts
Description
Check an unmarkedFrameGDR against a table of original survey identifiers
before you fit a model. The audit looks for split or duplicated surveys,
covariates out of line with the surveys, distance and removal counts that
disagree, and counts that conflict with survey effort. It only reports. It
does not combine surveys, reorder rows, remove records or repair counts.
Usage
validate_unmarked_data(
object,
event_keys,
event_id,
site_id = NULL,
interval_units,
effort = NULL,
expected_event_keys = NULL
)
## S3 method for class 'msr_unmarked_audit'
print(x, ...)
Arguments
object |
An |
event_keys |
A data frame with one row per survey event, in the frame's order. An event is one primary period at one frame row, so with one visit per point there is one row per frame row. With several primary periods, list all periods of the first frame row, then all periods of the second, and so on. Use the original survey identifiers, such as a point name and date, rather than a row number. |
event_id |
Character vector naming the columns of |
site_id |
Optional character vector naming the columns of
|
interval_units |
Character string naming the time unit of
|
effort |
Optional numeric vector with one value per event, in event
order, such as minutes surveyed. A positive value marks a completed
survey, zero marks an event that was not surveyed (its counts must be
|
expected_event_keys |
Optional data frame, built independently of
|
x |
An object returned by |
... |
Further arguments passed to the data-frame print method. |
Value
A list of class msr_unmarked_audit:
-
valid:TRUEwhen no errors were found. Warnings can remain, so read them too. -
findings: a data frame with one row per finding. Columns areseverity("error"or"warning"),code(see "Finding codes"),message, the event's position in frame order (.event), its frame row (.site_row) and primary period (.primary), followed by theevent_keyscolumns for that event. Findings about the whole frame have missing positions. -
events:event_keysas supplied. -
summary: the number of frame rows (sites),primary_periods,events,errorsandwarnings, andmissing_histories, the number of events with both count tables fully missing. -
protocol:distance_units,interval_units,distance_breaksandinterval_lengthsfrom the frame. -
effort: the supplied effort vector.
Printing shows the error and warning counts and at most ten findings,
and returns the object invisibly. The full table stays in $findings.
Identify survey events and physical sites
A physical site can be visited more than once. Give each visit its own
event identifier, and keep the site in a separate column named by
site_id. A row number from a spreadsheet cannot show that a detection
record and a zero-detection record belong to the same survey, so resolve
survey identities when you build the frame from the original records, for
example with prepare_gdr_histories().
The distance and removal tables count the same birds, so their totals
must match for each event. Matching totals are necessary but cannot reveal
a survey split across two frame rows. Supplying the original event keys
lets the audit report such a split as duplicate_event. Key names that
look like row indices (such as index, row_id or X) give a warning.
When an event_id or site_id column also appears in the site, yearly or
observation covariates, its values are compared with event_keys row by
row. Without expected_event_keys or such shared columns, unique keys
alone cannot prove that the rows are aligned.
Record survey effort
A survey that took place and detected nothing is an observed zero. A
survey that never took place should have fully missing counts in both
tables. Supply effort so the audit can tell these apart. Counts that are
missing in only one table, or in only some columns, are reported because
their totals cannot be compared. Character and factor values, including the
literal string "None", are kept as values and not treated as missing.
Finding codes
| Code | Severity | Meaning |
frame_layout | error | The count tables do not have matching rows and complete primary-period blocks. Other checks are skipped |
survey_type | error | The frame is not a point survey |
event_layout | error | event_keys does not have one row per event. Other checks are skipped |
missing_event_key | error | An event identifier is missing or blank |
duplicate_event | error | One event key appears in more than one event, as when a survey is split |
index_like_event_key | warning | An event_id column name looks like a row index |
missing_site_key | error | A site identifier is missing or blank |
physical_site_alignment | error | Primary periods in one frame row have different site keys |
event_alignment | error | The key differs from expected_event_keys in that row |
duplicate_reference_event | error | expected_event_keys repeats an event |
covariate_layout | error | A covariate table has the wrong number of rows or repeated names |
covariate_key_alignment | error | A key column in a covariate table differs from event_keys |
response_slot_alignment | error | The frame's response and removal tables disagree |
distance_breaks | error | Distance breaks do not start at zero, increase, and match the distance columns |
distance_units | error | Distance units are not "m" or "km" |
interval_lengths | error | Interval lengths are not positive whole numbers, one per removal column |
invalid_counts | error | A count is negative, fractional, infinite or NaN |
partial_history | error | An event's counts are only partly missing |
unequal_totals | error | Distance and removal totals differ for the event |
effort_unspecified | warning | No effort was supplied |
invalid_effort | error | Effort is negative or infinite |
unsurveyed_counts | error | An event with zero effort has counts, including zeros |
surveyed_missing | error | An event with positive effort has fully missing counts |
unknown_effort | warning | Effort is NA for the event
|
The audit does not decide how to treat a bird first detected beyond the
survey radius and later inside it, or how to turn raw bird records into
counts. prepare_gdr_histories() handles that step. See the "Check that
the records line up with the surveys" section of
vignette("v12-distance-removal", package = "multiScaleR") for the audit
in a full workflow.
See Also
prepare_gdr_histories(), prepare_gdr_intervals(),
expand_gdr_intervals(), sim_dat_gdr()
Examples
# Two visits to site A, one frame row each, with matching totals
frame <- unmarked::unmarkedFrameGDR(
yDistance = matrix(c(1, 0, 0, 0), 2, byrow = TRUE),
yRemoval = matrix(c(0, 1, 0, 0), 2, byrow = TRUE),
dist.breaks = c(0, 25, 75), unitsIn = "m",
period.lengths = c(1, 2))
keys <- data.frame(site = c("A", "A"), visit = c("spring", "summer"))
audit <- validate_unmarked_data(frame, keys, c("site", "visit"),
site_id = "site", interval_units = "minutes", effort = c(3, 3))
audit$valid # TRUE: no errors and, with effort supplied, no warnings
audit
# Give both rows the same key, as if one survey had been split in two.
# Their totals still match, but the event mapping is now invalid.
split_keys <- keys
split_keys$visit[2] <- "spring"
split_audit <- validate_unmarked_data(frame, split_keys, c("site", "visit"),
site_id = "site", interval_units = "minutes", effort = c(3, 3))
split_audit$valid
split_audit$findings[, c("severity", "code", ".event", "visit")]
Covariance Matrix for a Distance-Removal Model with a Fixed-Range Field
Description
Return the covariance matrix of the coefficients of a model fitted by
fit_gdr_response_field(). The matrix is retained from the fit, so this
method does not rerun TMB. It matches coef() on the link scale and keeps
the covariances between components and between the fixed coefficients and
the field values.
Usage
## S4 method for signature 'unmarkedFitGDRField'
vcov(object, type, altNames = TRUE, method = "hessian", fixedOnly = TRUE, ...)
Arguments
object |
An unmarkedFitGDRField returned
by |
type |
Optional character naming one component: |
altNames |
Logical, default |
method |
Character. Only |
fixedOnly |
Logical, default |
... |
Not used. Unrecognized arguments stop the call. |
Details
The log SDs of the random effects are estimated parameters, but they are
not rows of this matrix. Use unmarked::sigma(object) to see the field SD
with its confidence limits.
The matrix treats the ecological scales of effect and the correlation
range as known, and it contains no observation noise. confint() uses it
for normal (Wald) intervals, and
predict() uses it for standard
errors.
Value
A square numeric matrix with row and column names matching
coef(object, type, altNames = altNames, fixedOnly = fixedOnly). Entries
are on the link scale of each coefficient: log for abundance and
distance, logit for removal. Block field values are physical deviations
on the log density scale, not TMB's internal whitened values. The square
roots of the diagonal are the standard errors.
See Also
fit_gdr_response_field(), unmarkedFitGDRField,
predict,unmarkedFitGDRField-method
Examples
# The field needs unmarked 1.5.2 and TMB 1.9.25.
if (requireNamespace("TMB", quietly = TRUE) &&
utils::packageVersion("unmarked") == "1.5.2" &&
utils::packageVersion("TMB") == "1.9.25") {
# Eight survey blocks 1 km apart, six point counts in each
block <- factor(rep(paste0("b", 1:8), each = 6))
hab <- rep(seq(-1, 1, length.out = 6), 8)
shift <- c(-0.4, -0.3, -0.1, 0, 0.1, 0.2, 0.35, 0.4)[block]
sim <- sim_dat_gdr(density = exp(log(400) + 0.5 * hab + shift),
distance_scale = 40, removal = 0.2, dist_breaks = c(0, 25, 50, 75),
interval_lengths = c(2, 3, 5), interval_units = "minutes",
site_covs = data.frame(hab = hab, block = block), seed = 1)
template <- unmarked::gdistremoval(lambdaformula = ~ hab + (1 | block),
removalformula = ~ 1, distanceformula = ~ 1, data = sim$observed,
keyfun = "halfnorm", mixture = "P", output = "density",
unitsOut = "kmsq", K = 60, engine = "TMB",
starts = c(log(400), 0, log(40), qlogis(0.2), log(0.3)))
block_xy <- cbind(x = 500000 + 1000 * (as.integer(block) - 1),
y = 4400000)
rownames(block_xy) <- rownames(unmarked::siteCovs(sim$observed))
cold <- c("beta_lambda[1]" = log(300), "beta_lambda[2]" = 0,
"beta_dist[1]" = log(30), "beta_rem[1]" = qlogis(0.4),
"lsigma_lambda[1]" = log(0.5))
settings <- list(method = "BFGS", se = TRUE, threads = 1L,
control = list(maxit = 2500L, reltol = 1e-10))
field_fit <- fit_gdr_response_field(template, block_xy, crs = 32617,
range = 2000, cold_starts = list(cold = cold),
audit_dir = tempfile("gdr-field-"), tmb_settings = settings)
# Abundance coefficients: covariance and standard errors (log scale)
V <- vcov(field_fit, type = "lambda")
print(V)
print(sqrt(diag(V)))
# All components together: abundance, distance, then removal
print(round(vcov(field_fit), 4))
# Adding the eight block field values gives a 10 x 10 matrix
print(dim(vcov(field_fit, type = "lambda", fixedOnly = FALSE)))
}
Covariance matrices for an analytic multiscale fit
Description
Return the covariance matrix of the estimated parameters from a
multiScale_optim() fit made with an analytic backend. The joint matrix
covers the kernel parameters and the regression coefficients together, and
it is what predict.multiScaleR() uses for joint uncertainty. The
conditional matrix covers the coefficients with the kernel parameters held
at their estimates. multiScaleR-prediction explains when each kind of
uncertainty applies.
Usage
## S3 method for class 'multiScaleR'
vcov(object, type = c("joint", "conditional"), ...)
Arguments
object |
A |
type |
|
... |
Passed to native |
Value
A numeric covariance matrix with named rows and columns, as
described in Details. For "joint_mixed" with type = "conditional",
the native glmmTMB covariance list, one matrix per model component,
conditional on the selected scales.
Read the joint matrix
Rows and columns are named by parameter:
-
log_scale:<covariate>:log(sigma / u), the natural log of that covariate's sigma after dividing it by the internal distance unitu = object$kernel_inputs$unit_conv. Dividing byushifts the log by a constant, so the variance equals the variance of log(sigma) in map units. -
log_shape:<covariate>: the log shape parameter, forkernel = "expow". -
beta:<term>: a regression coefficient on the link scale, named after its model-matrix column, for examplebeta:(Intercept). A standardized kernel-weighted covariate's coefficient describes one standard deviation of that covariate. A final dispersion row when the family has one:
log_thetafor a negative binomial model andlog_residual_sdfor a Gaussian model.
The square root of a diagonal element is a standard error on that
parameter's scale. For sigma, a 95% Wald interval in map units is
sigma x exp(-1.96 x SE) to sigma x exp(1.96 x SE), where SE is the
standard error of log_scale. These are the limits that summary(object)
reports, and object$scale_est$SE is sigma x SE. Off-diagonal elements
show how the estimates trade off, and stats::cov2cor() turns them into
correlations.
Joint covariance is unavailable for fits at a parameter bound or when the
identifiability checks fail. In that case type = "joint" raises an error
that lists object$uncertainty$reasons, rather than reporting a misleading
Wald result. The conditional matrix remains available.
Read the conditional matrix
The conditional matrix holds only the beta: rows. It answers how
uncertain the coefficients are if the scales of effect are exactly their
estimates, which is also what vcov(object$opt_mod) and
summary(object$opt_mod) describe.
See Also
predict.multiScaleR() for predictions that use these matrices,
multiScaleR-prediction, multiScale_optim(), and
vignette("v09-estimates-and-intervals", package = "multiScaleR").
Examples
## Running example: counts at 100 survey points, two landscape layers
data("landscape_counts")
data("surv_pts")
pts <- terra::vect(surv_pts)
land <- terra::rast(system.file("extdata", "landscape.tif",
package = "multiScaleR"))[[c("land1", "land2")]]
inputs <- kernel_prep(pts, land, max_D = 1700, kernel = "gaussian",
bin = TRUE, verbose = FALSE)
dat <- data.frame(landscape_counts, inputs$kernel_dat)
start <- glm(counts ~ site + land1 + land2, family = poisson(), data = dat)
fit <- multiScale_optim(start, inputs, backend = "profile_glm",
n_cores = 1, verbose = FALSE)
## Joint covariance of the two log scales and four coefficients
V <- vcov(fit)
round(V, 4)
## 95% Wald limits for sigma, in meters, from the log-scale standard errors.
## They match the limits in summary(fit).
se_log <- sqrt(diag(V))[c("log_scale:land1", "log_scale:land2")]
sigma <- stats::setNames(fit$scale_est$Mean, rownames(fit$scale_est))
round(cbind(sigma, lower = sigma * exp(-qnorm(0.975) * se_log),
upper = sigma * exp(qnorm(0.975) * se_log)))
## Correlations show how the scale and coefficient estimates trade off
round(cov2cor(V), 2)
## Coefficient standard errors with and without scale uncertainty
round(cbind(joint = sqrt(diag(V))[-(1:2)],
conditional = sqrt(diag(vcov(fit, type = "conditional")))), 3)