Package {multiScaleR}


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 ORCID iD [aut, cre]
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

Package logo

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

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:

See Also

Useful links:

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: multiScaleR objects from multiScale_optim(), plain fitted models (for example glm or lm), or both. Every model must be fitted to the same observations with a comparable likelihood (see "Check that models are comparable"). Bayesian fits, cross-validation results, and private spatial prototypes are rejected.

AICc

Logical. If TRUE (the default), rank by the second-order corrected AIC (AICc). Set FALSE for standard AIC. AICc is recommended when the number of observations is small relative to the number of parameters (n / K < 40 is a common rule of thumb). AICc requires n > K + 1 for every model and raises an error otherwise. Use AICc = FALSE in that case.

mod_names

Optional character vector of model names, one per model in mod_list. By default, multiScaleR objects are labeled ⁠[kernel=...; family=...]⁠ followed by the right-hand side of the model formula. unmarked labels name the model class and, where present, the mixture, so Poisson, negative binomial, and ZIP alternatives get distinct labels.

verbose

Logical. If TRUE, the table is also printed to the console. Default FALSE.

...

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:

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.

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.

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

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

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: multiScaleR objects from multiScale_optim(), plain fitted models, or both. Every model must be fitted to the same observations with a comparable likelihood, including matching responses, weights, and likelihood measure. Bayesian fits, cross-validation results, and private spatial prototypes are rejected.

mod_names

Optional character vector of model names, one per model in mod_list. By default, multiScaleR objects are labeled ⁠[kernel=...; family=...]⁠ followed by the right-hand side of the model formula.

verbose

Logical. If TRUE, the table is also printed to the console. Default FALSE.

...

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:

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 multiScale_bayes(). "sample" (default, NUTS) needs RTMB, tmbstan, rstan, and posterior. "laplace" and "marginal" need RTMB. "slice" and "prepare" need no optional packages to run in one process. Slice chain diagnostics need posterior (version 1.6.0 or later).

correction

"none" (default) or "importance". Importance correction applies only to method = "marginal" and also needs posterior.

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 "prepare", which always uses one process.

x

A multiScaleR_bayes_setup object from check_bayes_setup().

...

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.

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

multiScale_bayes()

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:

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

pts, hab, multiScale_optim().

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 stats::glm(). The response must be a column of data, optionally wrapped in I(), or cbind(successes, failures) for grouped binomial data. Create any other transformed response as a column before the call. Predictors can include factors, interactions, offsets, and the data-dependent terms described in "Formula terms that learn from the data". Every variable must be a column of data or a covariate prepared in kernel_inputs, and at least one predictor must be a covariate whose scale is optimized.

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$kernel_dat. The folds refer to rows by these IDs. Spatial covariate columns are rebuilt inside every fold, so any values data holds for them are ignored. Rows with missing values are never dropped silently, so a fold that contains one fails.

kernel_inputs

A multiScaleR_data object from kernel_prep() or kernel_prep_by_group() for the same observations. It must keep the cell-level distances and values (store_cell_data = TRUE, the default), because every fold rebuilds its covariates from the raw cells. Lean objects are rejected. Choose max_D, the starting scales, and any metric definitions without looking at the assessment outcomes.

folds

Named list of explicit splits, for example from grouped_cv_folds() or spatial_cv_folds(). Each split is a list of two character vectors of row IDs, analysis and assessment, which must not overlap. A row can be left out of a split entirely (for example, by a spatial buffer) and can be assessed in more than one split. Keep rows that share a site, animal, or other sampling unit on the same side of every split.

family

Character response family. Choose "gaussian" (identity link, the default), "poisson" (log), "binomial" (logit), "nbinom2" (negative binomial, log), or "Gamma" (log). Lowercase "gamma" is accepted. For "nbinom2" the variance is mu + mu^2 / theta, where mu is the expected count and theta the size parameter, so a small theta means strong extra variation. For "Gamma" the variance is dispersion x mu^2. Other links and quasi-likelihood families are not supported.

backend

Fitting route for the scales, passed to multiScale_optim(). The default "profile_glm" is the fast analytic route. "refit" refits the GLM at every trial scale and accepts formula terms the default rejects, such as a spline of an optimized covariate without fixed knots. "joint_nb2" estimates the scales, coefficients, and theta together, and applies only to family = "nbinom2" with theta estimated. If you leave backend unset, "Gamma" and an NB2 model with a fixed theta use "refit", the only route they support. Naming another backend for them is an error. The usual starting-value, convergence, and kernel or metric checks of multiScale_optim() apply in every fold. See multiScaleR-fitting-methods.

weights

Optional case frequencies, one nonnegative whole number per row of data in the same order. If the vector has names, they must equal the row names. A weight of 3 counts the row three times. A weight of 0 keeps the row in the records but out of the fit and the scores. The default NULL gives every row a weight of one. Gaussian models accept only weights of one. For binomial data, put the trial counts in a cbind(successes, failures) response, not in weights. Weighted proportions are rejected. Some scale-fitting backends add their own weight requirements.

optim_args

Named list of extra multiScale_optim() arguments used in every fold, such as par or profile_control. Supply radius_grid with backend = "refit" to profile hard radii, together with any smooth scales, in each training split. Supply covariate_transform = "raw" with backend = "refit" to keep optimized covariates in their own units (see "Keep optimized covariates in their own units"). Arguments that supply data, the starting model, a custom refit function, parallel workers, backend, or verbose are reserved. Every fold runs on one worker. The default list() keeps the backend's own defaults. Choose starting values without using the assessment outcomes.

glm_control

Named list of stats::glm.control() settings for the initial GLM fitted to the analysis rows of each fold. The default keeps the settings of glm().

metrics

Optional character vector of scores to record. The defaults depend on family. They are c("rmse", "mae") for Gaussian, c("rmse", "mae", "neg_log_score", "deviance") for Poisson, c("neg_log_score", "brier") for binomial, and c("rmse", "mae", "neg_log_score") for NB2 and Gamma. You can request a subset of the defaults, but not other scores. NB2 and Gamma leave out the deviance because its value depends on theta or the dispersion, which makes it unsuitable for comparing models. Lower is better for every score, and the multiScaleR_cv page defines each one.

keep_fits

Logical. The default FALSE keeps the predictions, scores, fold estimates, and compact diagnostics. TRUE also keeps the full fitted model of every fold in fits, which can use much more memory. You need full fits only to inspect the fold models or to have select_cv() return the selected fits.

keep_selection

Logical. TRUE keeps a compact record of each fold's training likelihood and parameter count in selection_records, which is what select_cv() needs when keep_fits = FALSE. The records come from the fits already run, so they add no fitting time. The default is FALSE.

theta

Optional NB2 size parameter fixed in advance, one positive number. The default NULL estimates theta separately from the analysis rows of each fold. A fixed theta adds no parameter to K (the parameter count used by AIC) and requires the "refit" backend. Fix it only from information independent of the assessment outcomes. Other families reject it.

dispersion

Optional Gamma dispersion fixed in advance, one positive number. The default NULL estimates it in each fold as the training deviance divided by the sum of the frequency weights, the value native Gamma AIC uses. A fixed dispersion adds no parameter to K and is built into the Gamma density before fitting. Fix it only from information independent of the assessment outcomes. Other families reject it.

x

A multiScaleR_cv result, for print().

...

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.

  1. 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.

  2. Fit the initial GLM to the analysis rows.

  3. Estimate the scales and coefficients with multiScale_optim(). No fit to the full data is used as a starting point.

  4. 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.

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 multiScale_bayes() syntax. Use a data column as the response, or cbind(successes, failures) for grouped binomial data. An I() wrapper is also accepted.

data

Data frame of raw observations and formula variables. Its unique row names identify observations in folds, even when several observations share one prepared point.

kernel_inputs

Prepared landscape inputs from kernel_prep() or kernel_prep_by_group(). For the default training-only rebinning, prepare kernel means with bin = TRUE and store_cell_data = TRUE (both defaults of kernel_prep()). Weighted SQ and fixed-radius metrics also use the raw cells.

folds

Uniquely named list of splits. Each split holds nonempty, disjoint character vectors analysis and assessment of row names of data, as returned by grouped_cv_folds() or spatial_cv_folds(). Every analysis set needs at least two observations.

scales

Named list of scale formulas, as in multiScale_bayes(). The default NULL estimates one shared scale per landscape predictor.

family

Response family, one of "nbinom2" (default) or "poisson" for counts, "binomial" for successes and trials, or "gaussian" for continuous outcomes.

row_id

Optional name of the column of data that holds prepared point IDs. The default NULL uses the row names of data as point IDs. Point IDs may repeat. They do not replace the unique row names that identify observations.

priors

Named list of prior settings passed to multiScale_bayes(). Set them before you look at any assessment outcome. The default list() uses the documented defaults.

method

Computation for every fold. The default "slice" needs no optional sampling packages. "sample" runs NUTS. "laplace" and "marginal" use the approximations, and an importance-corrected marginal fit is scored directly with its candidate weights.

fit_args

Named list of further fitting arguments for multiScale_bayes(), chosen from chains, iter, warmup, control, laplace_draws, and cores. Settings you leave out take the defaults of multiScale_bayes(). Folds always run one after another.

assessment_group

Optional name of a column of data that defines joint scoring blocks within each assessment split. The default NULL scores each whole assessment split as one block. Choose the blocks to match your prediction question before you see any assessment outcome.

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 "sample" averages over new-group variation by simulation. "error" refuses an unseen level, and "zero" predicts at a zero deviation. Groups present in the analysis split keep their fitted effects.

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

"training" (default) computes the representative bin distances from the unique analysis points of each fold and freezes them for its assessment points. Use "fixed" only when the supplied bins were fixed independently of all analysis and assessment data.

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 FALSE stores compact fold records only. TRUE also keeps every fold's complete fit in fits, for investigation, at a cost in memory.

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.

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 strata(choice_id) term naming the column that identifies each choice set. Factors, interactions, offsets, and the data-dependent terms scale(), poly(), splines::ns(), and splines::bs() are allowed. A dot (.) expands to the columns of data, so remove the set ID from it, for example case_ ~ . - step + strata(step).

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 and, when supplied, by kernel_inputs. They must be unique.

folds

Named list of explicit splits of row IDs, as in cross_validate(). Every choice set must lie wholly in the analysis rows, wholly in the assessment rows, or wholly outside the split. grouped_cv_folds() applied to the set IDs, or to animal IDs, does this. See "Build folds that keep choice sets whole".

kernel_inputs

Optional multiScaleR_data object from kernel_prep() or kernel_prep_by_group() with the cell-level data kept, one prepared row per alternative. The default NULL fits an ordinary conditional logistic reference model without scales. When it is supplied, each fold also estimates the scales, and learns the standardization and distance bins, from its analysis rows only.

backend

Scale-fitting route used with kernel_inputs, either "conditional_logit" (default) or "refit". Supply optim_args = list(radius_grid = ...) with "refit" to profile hard radii, together with any smooth scales, in each training split. The usual kernel, metric, and numerical checks of multiScale_optim() apply. Ignored when kernel_inputs is NULL.

method

Partial-likelihood method passed to survival::clogit(), one of "exact" (default), "efron", or "breslow". These are rules for tied event times. With one used alternative per set they give the same likelihood, but the method is recorded, and cv_tab() and select_cv() compare only candidates that declare the same method.

cox_control

Named list of survival::coxph.control() settings for the native training fit. The default keeps the settings of coxph.control().

optim_args

Named list of extra multiScale_optim() arguments used in every fold, such as par or profile_control. Supply radius_grid with backend = "refit" to profile hard radii, together with any smooth scales, in each training split. Supply covariate_transform = "raw" with backend = "refit" to keep optimized covariates in their own units (see "Keep optimized covariates in their own units"). Arguments that supply data, the starting model, a custom refit function, parallel workers, backend, or verbose are reserved. Every fold runs on one worker. The default list() keeps the backend's own defaults. Choose starting values without using the assessment outcomes.

keep_fits

Logical. The default FALSE keeps the predictions, scores, fold estimates, and compact diagnostics. TRUE also keeps the full fitted model of every fold in fits, which can use much more memory. You need full fits only to inspect the fold models or to have select_cv() return the selected fits.

keep_selection

Logical. TRUE keeps a compact record of each fold's training likelihood and parameter count in selection_records, which is what select_cv() needs when keep_fits = FALSE. The records come from the fits already run, so they add no fitting time. The default is FALSE.

x

A multiScaleR_choice_cv result, for print().

...

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. Products, interactions, factors, offsets, and the data-dependent terms scale(), poly(), splines::ns(), and splines::bs() keep their usual meanings, with their constants learned from the analysis rows. Do not add random effects or penalized smooths, because the function adds the one shared field itself.

data

Data frame of raw responses and predictors, with unique row names that match the fold IDs, in the same row order as coords. Supply raw predictors, not transformations learned from all rows. Every row has a case weight of one.

coords

Locations of the observations, one per row of data, as projected sf points, a terra::SpatVector of points, or a numeric two-column table. Rows with identical coordinates share one field value, so repeated surveys of a location are linked.

folds

Named list of explicit splits, usually from spatial_cv_folds(). A location cannot appear in both the analysis and the assessment rows of one split, so keep repeated surveys of a location together. Rows excluded from a split, for example by a buffer, enter neither its fit nor its score.

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 sf::st_crs(). It is required when coords is a coordinate table. The default NULL uses the CRS of spatial coords, which must be projected, and a supplied crs must match it. Coordinates are never transformed, so the correlation range is reported in the CRS units.

covariance

Correlation function of the field, either "exponential" (default), with correlation exp(-d / range) at distance d, or "gaussian", with correlation exp(-(d / range)^2). The range and the field SD are estimated in every fold, as is the observation dispersion for Gaussian, NB2, and Gamma models.

kernel_inputs

Optional multiScaleR_data object from kernel_prep() with the cell-level data kept and row names matching data. The default NULL fits a field model without estimating scales. When it is supplied, each fold also estimates the scales of the optimized covariates that appear in formula (list them with msr_vars()) by refitting the field model.

optim_args

Named list of extra multiScale_optim() arguments for the scale fit, used only with kernel_inputs. The default is an empty list. This function fixes the backend ("refit"), the data, the refit function, and the single worker, so those cannot be replaced.

control

Named list of native nlminb() optimizer settings for each field fit. Accepted names are iter.max, eval.max, rel.tol, x.tol, and abs.tol, each a positive number. The defaults are iter.max = 1000, eval.max = 1500, rel.tol = 1e-10, and x.tol = 1e-8. The settings are stored with each fit, and the convergence and curvature checks apply whatever they are.

metrics

Scores to record, any of "rmse", "mae", and "neg_log_score" (all three by default). The negative log score uses one joint density, or one joint probability for counts and 0/1 data, per assessment block. The pooled score sums the block losses and divides by the number of assessment observations.

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. TRUE keeps the complete training model of each fold in fits. The default FALSE saves memory. The compact training records that select_cv() reads are kept either way.

family

Response family and link. Use "gaussian" (identity, the default) for continuous observations, "poisson" or "nbinom2" (log) for counts, "binomial" (logit) for numeric 0/1 observations, or "Gamma" (log) for strictly positive continuous observations. All families other than "gaussian" are experimental.

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 stats::glm(). The response must be a column of data, optionally wrapped in I(), or cbind(successes, failures) for grouped binomial data. Predictors can include factors, interactions, offsets, and the data-dependent terms scale(), poly(), splines::ns(), and splines::bs(). Use y ~ 1 for a null model. Every variable must be a column of data.

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 grouped_cv_folds() or spatial_cv_folds(). Each split is a list of two character vectors of row IDs, analysis and assessment, which must not overlap. A row can be left out of a split entirely (for example, by a spatial buffer) and can be assessed in more than one split. Keep rows that share a site, animal, or other sampling unit on the same side of every split.

family

Character response family. Choose "gaussian" (identity link, the default), "poisson" (log), "binomial" (logit), "nbinom2" (negative binomial, log), or "Gamma" (log). Lowercase "gamma" is accepted. For "nbinom2" the variance is mu + mu^2 / theta, where mu is the expected count and theta the size parameter, so a small theta means strong extra variation. For "Gamma" the variance is dispersion x mu^2. Other links and quasi-likelihood families are not supported.

weights

Optional case frequencies, one nonnegative whole number per row of data in the same order. If the vector has names, they must equal the row names. A weight of 3 counts the row three times. A weight of 0 keeps the row in the records but out of the fit and the scores. The default NULL gives every row a weight of one. Gaussian models accept only weights of one. For binomial data, put the trial counts in a cbind(successes, failures) response, not in weights. Weighted proportions are rejected. Some scale-fitting backends add their own weight requirements.

glm_control

Named list of stats::glm.control() settings for the GLM fitted in each fold. The default keeps the settings of glm().

metrics

Optional character vector of scores to record. The defaults depend on family. They are c("rmse", "mae") for Gaussian, c("rmse", "mae", "neg_log_score", "deviance") for Poisson, c("neg_log_score", "brier") for binomial, and c("rmse", "mae", "neg_log_score") for NB2 and Gamma. You can request a subset of the defaults, but not other scores. NB2 and Gamma leave out the deviance because its value depends on theta or the dispersion, which makes it unsuitable for comparing models. Lower is better for every score, and the multiScaleR_cv page defines each one.

keep_fits

Logical. The default FALSE keeps the predictions, scores, fold estimates, and compact diagnostics. TRUE also keeps the full fitted model of every fold in fits, which can use much more memory. You need full fits only to inspect the fold models or to have select_cv() return the selected fits.

keep_selection

Logical. TRUE keeps a compact record of each fold's training likelihood and parameter count in selection_records, which is what select_cv() needs when keep_fits = FALSE. The records come from the fits already run, so they add no fitting time. The default is FALSE.

theta

Optional NB2 size parameter fixed in advance, one positive number. The default NULL estimates theta in each fold with MASS::glm.nb(). A fixed theta is fitted with glm(family = MASS::negative.binomial(theta)) and adds no parameter to K. Fix it only from information independent of the assessment outcomes. Other families reject it.

dispersion

Optional Gamma dispersion fixed in advance, one positive number. The default NULL estimates it in each fold as the training deviance divided by the sum of the frequency weights, the value native Gamma AIC uses. A fixed dispersion adds no parameter to K and is built into the Gamma density before fitting. Fix it only from information independent of the assessment outcomes. Other families reject it.

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.

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 count ~ habitat + (1 | site). Gaussian models also support one block of numeric random slopes such as (1 + habitat | site). Other families allow one random intercept. Use explicit predictors (no .) and formula offsets. The response is a data column, or cbind(successes, failures) for grouped binomial data with positive trial counts.

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 grouped_cv_folds() or spatial_cv_folds() to hold out entire groups. Use explicit splits within groups, such as later visits, for existing-group prediction.

family

Character response family. Choose "gaussian" (identity, default), "poisson" (log), "binomial" (logit), "nbinom2" (log), or "Gamma" (log).

prediction

Character prediction target. "new_group" (default) predicts groups absent from training, so each assessment group must have no analysis rows in that split, and its prediction averages over the fitted distribution of group effects. "existing_group" predicts new observations of groups seen in training, so every assessment group must have analysis rows in that split, and its prediction conditions on them.

kernel_inputs

Optional raw-cell multiScaleR_data object for estimating the scales of effect from the analysis rows by native refits. The default NULL fits the supplied formula without scale optimization.

optim_args

Named list of extra serial multiScale_optim() controls. Use only with kernel_inputs. profile_control and the arguments this function sets itself are reserved.

metrics

Character vector of "neg_log_score", "rmse", "mae", or "brier" (binomial only). By default, report the joint group log score and RMSE, or the joint group log score and Brier score for binomial responses. The log score is summed across assessment groups and divided by the number of assessment rows. Binomial RMSE and MAE compare the expected success probability with the observed fraction of successes. The Brier score averages the squared probability error over trials.

control

A glmmTMB::glmmTMBControl() list for the native analysis fits. The default NULL uses glmmTMBControl().

integration_tol

Relative tolerance for the one-dimensional adaptive integration over the group effect in non-Gaussian models. The default is 1e-8.

keep_fits

Logical. Retain the fitted model of each successfully scored fold. Defaults to FALSE.

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 list(landscape = cv, null = null_cv). The names label the rows of the table and must be unique. Every candidate must use identical folds, responses, trials, and frequency weights, and the candidates must be of compatible kinds (see "What can be compared").

metric

One score name, chosen explicitly: "rmse", "mae", "neg_log_score", "deviance", or "brier". Every candidate must have recorded it. There is no default, because the scores answer different questions.

by_fold

Logical. The default FALSE ranks the pooled scores. TRUE ranks the candidates separately within each fold, which shows whether a ranking is consistent across folds.

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:

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 multiScale_bayes() object from method = "laplace", or from method = "marginal" without importance correction, with its approximation draws and geometry intact. The check needs the RTMB and posterior (version 1.6.0 or later) packages.

thresholds

Named list of scale thresholds, as in diagnose_bayes_probabilities(). Each name selects a fitted landscape predictor, and each vector holds distinct finite thresholds, such as list(habitat = c(150, 350)). Every threshold is checked for every distinct fitted combination of scale covariates and groups, such as each year.

scale

Units of thresholds. "distance" (default) uses map units and needs positive values. "log" uses natural log map units. The event is a fitted kernel scale less than or equal to the threshold.

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.

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 multiScale_bayes() object that keeps its original, unpermuted post-warmup chains from NUTS (sampler) or slice sampling (chains). Compact, thinned, and approximate fits return an unavailable report, because permuted draws cannot recover chain order.

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, list(habitat = c(100, 250)) checks two scales in projected map units.

scale

"distance" (default) means thresholds are positive kernel scales in map units. "log" means they are natural logs of those scales. Thresholds refer to the scale parameters summarized by posterior_scales(), not to transformed kernel-weight radii such as those from kernel_dist().

mcse_target

Optional target for the Monte Carlo standard error (MCSE) on the probability axis, strictly between 0 and 1. For example, 0.005 asks for an MCSE no larger than half a percentage point. The default NULL reports precision without judging it against a target.

Value

A list with these elements.

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 multiScale_bayes() object. New diagnostics need the original unpermuted post-warmup chains from NUTS (sampler) or slice sampling (chains). Prepared, approximate, and compact fits return an unavailable report.

probs

Numeric vector of distinct probabilities strictly between 0 and 1. The default c(0.025, 0.5, 0.975) gives the median and the limits of a central 95% interval. Changing it changes which quantiles have their simulation error reported, not any diagnostic threshold.

Value

A list with these elements.

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 multiScaleR.

...

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_distance

A 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; see kernel_dist), max_D (the limit used), ratio (max_D / effective_distance), and suggested_max_D (a recommended minimum max_D value). Triggered when max_D / effective_distance < 2.

sigma_precision

A list describing whether sigma estimates are imprecise. Fields include: triggered (logical), variables (names of affected covariates), estimate (sigma means), se (standard errors), and se_to_mean (ratio of SE to mean). Triggered when SE / Mean >= 0.5 for any covariate. NULL when no precision concern was flagged.

shape_precision

Identical structure to sigma_precision but for the shape parameter of the exponential power kernel. NULL unless kernel = "expow" was used and a precision concern arose.

sample_size

A list with fitted_n, the number of observations in the final model, and prepared_n, the number of observations in the preparation object, or model rows for repeated-site unmarked data. For unmarked fits, prepared_sites is the number of distinct spatial sites in the preparation object. triggered is TRUE when the fitted model uses fewer observations. Candidate scales that change the initial model's sample are rejected during optimization.

start_stall

For 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 from start_strategy = "screen"), start (starting sigma values in map units), function_evaluations, and message, which names the remedy. reason is "hard_radius" when every optimized scale is a hard radius, as under kernel = "fixed". Its likelihood changes in steps, so the gradient is zero almost everywhere. reason is "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. reason is "no_progress" otherwise. A warning gives the same message when the fit is made, and print() and summary() repeat it.

refit_hessian

For 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-5 log 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_profile

For a declared radius grid, one row per combination. radius, or one radius:<predictor> column per hard radius, uses map units. Any sigma:<predictor> and shape:<predictor> columns hold the reoptimized smooth bandwidths in map units and unitless shapes, respectively. The table also reports native log_likelihood, status (scored or failed), any failure message, and a logical selected flag. With smooth predictors, smooth_starts holds 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_glm

Present for both opt-in analytic GLM backends. Includes uncertainty_available, explanatory reasons, weak_identifiability, boundary, condition_number, log-kernel standard errors, competing-mode flags, and attempted/eligible start counts. poisson_limit marks negligible fitted NB2 extra variance; poisson_compatible and poisson_deviance compare the NB2 fit with a Poisson fit at the selected kernel scales. See multiScale_optim for thresholds and limitations.

See Also

multiScale_optim, kernel_prep

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 multiScaleR_data object created by kernel_prep() or kernel_prep_by_group().

fitted_mod

Optional fitted starting model, as you would pass to multiScale_optim(). When supplied, the estimate also includes the optimization context sent to each worker. Without it, the estimate can understate the real payload. Default: NULL.

join_by

Optional data frame passed through to multiScale_optim() for unmarked workflows. Default: NULL.

refit_fn

Optional custom refit function passed through to multiScale_optim(). Default: NULL.

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: TRUE on Windows and FALSE on Unix-like systems. The estimate is the same either way, because forked workers are also budgeted as though each holds its own copy.

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: 1.5.

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: 0.75.

leave_free

Non-negative integer. Number of physical CPU cores to leave unused when computing the CPU limit. Default: 2.

x

A multiScaleR_ram object returned by estimate_multiscale_ram().

...

Not used.

Value

estimate_multiscale_ram() returns a list of class multiScaleR_ram with these elements:

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.

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 unmarkedFrameGDR with its original counts and its site, yearly and observation covariates.

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 event_keys that identify a survey.

interval_units

Character string naming the time unit of the removal intervals, such as "minutes". Interval lengths are kept, not converted.

site_covariates

Character vector naming the site covariates (siteCovs) to repeat. The default is none. Name an element to give the copy a new name, for example c(rem_forest = "forest", rem_observer = "Observer"). Unnamed elements keep the source name. Nothing is inferred from model formulas, so list every covariate you need.

yearly_covariates

Character vector naming covariates in the frame's yearly table (yearlySiteCovs, one row per primary period) to repeat, with the same naming convention. The default is none. Despite the name, these rows are primary periods (visits), not necessarily years.

interval

Character string, default "interval". The name of the new column holding the interval number (1, 2, ...). It must differ from the event keys and from the other new columns.

site_id

Optional column(s) of event_keys that identify the physical site, passed to prepare_gdr_intervals() and validate_unmarked_data().

effort

Optional numeric vector of survey effort, one value per event, passed to validate_unmarked_data(). Positive values mark completed surveys, zero marks unsurveyed events and NA marks unknown effort.

expected_event_keys

Optional independent event list in frame order, passed to validate_unmarked_data().

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 unmarkedFitGDR fitted by unmarked::gdistremoval() with engine = "TMB". It serves as the template. Its data, formulas, cutoff K and estimates are reused, and its independent abundance intercepts become the field. See "Check that your model qualifies" for the supported model forms.

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 rownames(unmarked::siteCovs(model@data)) when the frame has site covariates. All surveys in one block (one level of the abundance grouping factor) must carry exactly the same coordinates, usually the block center, and different blocks must have different coordinates.

crs

The projected coordinate reference system of coords, as an EPSG code (for example 32617) or any other input accepted by sf::st_crs(). It must have two horizontal axes and declared linear units. Coordinates are never transformed, so range and coords must use these units.

range

Positive number. The fixed correlation range of the exponential field, in the linear units of crs. Two blocks range apart have correlation exp(-1), about 0.37, and blocks three ranges apart have correlation about 0.05. This is a distance over which density deviations are shared. It is not a kernel scale of effect, and it is not counted as a parameter.

cold_starts

Named list of one or more extra starting vectors (for example list(cold = cold)). Each vector holds one value for every fixed coefficient and log standard deviation, on the link scales listed by gdr_start_values(). Supply it either unnamed, in the order of gdr_start_values(model)$starts, or named by parameter block and position, such as "beta_lambda[1]" (log density intercept), "beta_dist[1]" (log distance scale), "beta_rem[1]" (logit removal probability) and "lsigma_lambda[1]" (log SD of the abundance intercepts). Each vector must differ from the template's estimates and from the other vectors. The names "original" and "final" are reserved.

audit_dir

Character string naming a directory for audit records. It is created if needed. Every fit writes small .rds records there: the request, the validated inputs, each attempt (including failures), the optimizer result saved before covariance work, and the final outcome. Records hold numbers, settings and identities, not fitted models. Keep the directory to inspect a failed fit.

tmb_settings

Named list of optimizer settings with elements method, se, threads and control. This function requires method = "BFGS", se = TRUE, threads = 1 and a positive integer control$maxit, for example list(method = "BFGS", se = TRUE, threads = 1L, control = list(maxit = 2500L, reltol = 1e-10)). The optional elements random.start, inner.control and record_memory are described in make_gdr_refitter(). Pass the identical list to make_gdr_refitter() when you later estimate scales of effect with the field.

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 predict() calls on the fitted object. It is an estimate, not an operating-system memory cap.

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:

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 unmarkedFitGDR fitted by unmarked::gdistremoval() with unmarked 1.5.2, using the C or TMB engine. Its stored estimates and optimizer values must be complete and agree with each other. Models with offset() terms and zero-inflated TMB models are not supported. Finite values do not show that the model converged.

Value

A plain list:

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 group. Use the row names of the modeling data. The default uses the names of group, or the row numbers as character strings when group is unnamed. Named groups must align exactly with supplied IDs.

x

A multiScaleR_folds object, for print().

...

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

pts, count_data.

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 multiScaleR object from multiScale_optim(). When supplied, distances and 95% confidence limits are returned for every optimized covariate, and any sigma, kernel, or shape passed through ... is ignored with a warning. When omitted, supply sigma and kernel (and shape for "expow") through ....

prob

Numeric between 0 and 1 (exclusive). Proportion of the kernel weight that the reported distance must hold. Default: 0.9. Larger values give longer distances. Under dimension = "1d" the proportion is of the weight along a line through the point. Under "2d" it is of the weight on a plane.

dimension

Character. How the distance is measured. "2d" (default) returns the radius of the circle around the point that holds prob of the ideal kernel weight on an unbounded plane. "1d" returns the original line-based distance, which encloses prob of the area under the kernel curve along a transect through the point. For distance-weighted kernels the "2d" radius is longer than the "1d" distance. Hard-radius covariates in a fitted model report the same radius under both. See Details.

...

Kernel parameters used when model is not supplied:

  • sigma: positive numeric scalar. The kernel scale parameter, in the map units of the points and rasters passed to kernel_prep(). For the Gaussian kernel it is the standard deviation, for the negative exponential kernel the decay length, and for the fixed kernel the buffer radius.

  • kernel: character. One of "gaussian", "exp" (negative exponential), "expow" (exponential power), or "fixed" (fixed-radius buffer). Required.

  • shape: positive numeric scalar. Shape of the exponential power kernel. Required when kernel = "expow" and ignored otherwise.

  • beta: deprecated former name of shape. It is still accepted, with a warning, and will be removed in a future release. Supplying both shape and beta with different values is an error.

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:

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:

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 SpatVector (terra) or sf object, in a projected coordinate system whose units match max_D. Row names are kept as point IDs.

raster_stack

A SpatRaster (terra) with one or more layers, on the same projection as pts. Without scale_vars, each layer becomes a covariate with the layer's name, so the names must match the model formula. Layer names cannot be "x", which is reserved for internal coordinate data. The raster must cover a buffer of max_D around every point.

max_D

Positive numeric scalar. Radius, in map units, of the circle around each point within which raster cells are extracted. It is also the upper bound of the sigma search, and kernels are cut off at this distance. Set it above the largest plausible scale of effect, at least about 3.3 times the largest plausible sigma for a Gaussian kernel. If an estimate comes back near max_D, increase it and run kernel_prep() again. See the section on choosing max_D in multiScaleR-kernels.

kernel

Character. Distance-weighting function used for every covariate: "gaussian" (default), "exp" (negative exponential), "expow" (exponential power, which also estimates a shape), or "fixed" (equal weight within a radius). The weight functions are given in multiScaleR-kernels. To compare kernels, run kernel_prep() once per kernel.

scale_vars

Optional covariate specifications created with msr_vars(). Omit it to make each raster layer one kernel-weighted mean. Supply it to define derived covariates, such as a kernel mean and a landscape or surface metric from the same layer.

sigma

Optional numeric vector of starting sigma values, in map units, one per covariate whose scale is estimated (one per raster layer when scale_vars is omitted). Default: NULL, which starts every sigma at max_D / 2. The default is recommended. These values set the covariates in kernel_dat and are not the starting values of multiScale_optim(), which chooses its own.

shape

Optional numeric vector of starting shape values for kernel = "expow", with the same length as sigma. Default: NULL, which starts every shape at 2 (the Gaussian form). Ignored for other kernels.

projected

Logical. Whether pts and raster_stack use projected (planar) coordinates. Only projected coordinates are supported, so FALSE is an error. Default: TRUE.

progress

Logical. Show progress bars during extraction and weighting. Default: FALSE.

verbose

Logical. Print status messages. Default: TRUE.

bin

Logical. If TRUE (default), summarize each kernel mean's cell values into distance bins. multiScale_optim() then evaluates kernel means from the bins instead of every cell, which is much faster and no longer depends on max_D, at the cost of a negligible approximation. The analytic backends and multiScale_bayes() require it for kernel means. Landscape and surface metrics are never binned. FALSE forces exact cell-by-cell evaluation.

nbins

Integer, at least 2. Number of equal-width distance bins when bin = TRUE. More bins increase accuracy and memory. The default (256) reproduces exact optimization results to several significant figures. Ignored when bin = FALSE.

store_cell_data

Logical. If TRUE (default), the per-cell distances (d_list) and values (raw_cov) are kept. If FALSE, they are dropped after binning, often shrinking the object by one to two orders of magnitude. This lean mode needs bin = TRUE and only kernel means. With landscape or surface metrics, or bin = FALSE, the cell data are kept and a message says so. The bins suffice for optimization, profile_sigma(), and the final refit.

Value

An object of class multiScaleR_data, a list. Its full structure is described in multiScaleR_data. The parts you use directly:

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 sf or SpatVector object. Point order matches group and the returned covariate rows.

raster_stacks

Named list of SpatRaster maps. Each map has the same extent, grid, CRS, layer names, and class coding. Its name identifies a year or other observation group.

group

Character or factor vector, one value per point, identifying the corresponding name in raster_stacks. Every point uses only its assigned map, including cells affected by changes outside the point's immediate location.

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 max_D in multiScaleR-kernels.

kernel

Kernel weighting function: "gaussian" (default), "exp", "expow", or "fixed". See kernel_prep() and multiScaleR-kernels.

scale_vars

Optional msr_vars specification. By default, each raster layer becomes a kernel-weighted mean covariate.

sigma

Optional starting scales in map units. Defaults to max_D / 2 for each optimized covariate.

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: TRUE. All observations use one set of bin definitions.

nbins

Number of distance bins when bin = TRUE; default 256.

store_cell_data

Logical. Retain per-cell values and distances. Default: TRUE. Set FALSE for a lean kernel-only binned object; metrics requiring cell detail retain it regardless.

progress

Logical. Display extraction progress. Default FALSE.

verbose

Logical. Print preparation messages. Default TRUE.

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_dat

Initial 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_cov

Named per-point distance vectors (divided by unit_conv) and raster-value matrices. Both are NULL in lean mode.

binned

Pooled distance-bin summaries for kernel covariates, or NULL when bin = FALSE. Each covariate has finite-value sums and counts by point and distance bin.

cell_size

Fixed 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_group

Named character vector recording the map assigned to each point, in input order.

scl_params

Pooled means and standard deviations used to create kernel_dat; the fitted model replaces these with scaling parameters at the optimized scales.

kernel, sigma, shape

Kernel name, initial scales divided by unit_conv, and optional initial shape values.

min_D, max_D, unit_conv

Lower scale bound, maximum extraction radius, and internal distance scaling factor. These are in map units except the internally scaled sigma.

n_covs, scale_vars

Number of optimized covariates and the validated covariate definitions.

resolution, n_cols

Raster cell size and column count, used to calculate landscape configuration metrics.

cell_data_stored

Whether 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 SpatRaster with the source layer(s). Layer names must match the covariate names used in fitting, or the source names in scale_vars. Use the same map units and cell size as in fitting.

sigma

Numeric vector of kernel scale parameters (or hard radii), in map units. Supply one value per optimized covariate in declaration order when scale_vars is used, or one per raster layer otherwise. Without scale_vars, a length that does not match the number of layers gives a warning and the first value is used for every layer. Ignored when multiScaleR is supplied.

multiScaleR

A fitted multiScaleR object from multiScale_optim(), or a prepared multiScaleR_data object from kernel_prep(). When supplied, sigma, shape, kernel, and scale_vars are taken from it. A fitted object supplies the estimated scales. A prepared object supplies the starting scales of kernel_prep(). Default: NULL.

shape

Numeric vector of shape parameters for the exponential power kernel (kernel = "expow"), one per optimized covariate. A hard-radius covariate ignores its shape position. Ignored when multiScaleR is supplied. Default: NULL.

kernel

Character. Kernel used for smoothing: "gaussian" (default), "exp", "expow", or "fixed". See multiScaleR-kernels. Ignored when multiScaleR is supplied.

scale_vars

Optional covariate specifications from msr_vars(). Use it to project landscape or surface metrics, or derived covariates, without a fitted object. When multiScaleR is supplied, its specifications are used, and for a fitted model only the covariates in the model formula are projected.

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 pct_wt of the kernel weight, rounded up to whole cells. Larger values (for example 0.99) include more of the kernel tail and take longer. It is not the share of planar weight within the window. Ignored when match_buffer = TRUE and by hard-radius metrics. Default: 0.975.

fft

Logical. If TRUE (default), smoothing uses fast Fourier transform (FFT) convolution, which is much faster for large rasters and wide kernels. Set FALSE for direct moving-window (focal) calculations. Both engines support kernel means and the declared surface and landscape metrics, with the same support and missing-value rules.

scale_center

Logical. If TRUE, each smoothed layer is centered and scaled with the mean and standard deviation stored in multiScaleR$scl_params, so its values match the standardized covariates used in fitting. Required for prediction from a model fitted on standardized covariates, which is the default. Needs multiScaleR. Default: FALSE.

clamp

Logical. If TRUE, standardized values are limited to the range observed at the survey points (moved by pct_mx), which prevents extrapolation beyond the fitted range. Active only when scale_center = TRUE. Default: FALSE.

pct_mx

Numeric greater than -0.5 and no larger than 0.99. When clamp = TRUE, each clamping limit moves outward by pct_mx times the range of that covariate observed at the survey points: lower = min - pct_mx * (max - min) and upper = max + pct_mx * (max - min), on the standardized scale. For example, a covariate observed from -1 to 3 is clamped to -1.4 and 3.4 with pct_mx = 0.1, and to -0.6 and 2.6 with pct_mx = -0.1. Negative values move the limits inward. Default: 0 (the exact training range).

na.rm

Logical. If TRUE (default), missing cells are left out and the weights of the remaining cells renormalize. If FALSE, any window with a missing cell, including cells beyond the raster edge, returns NA.

verbose

Logical. Print a progress message for each layer. Default: TRUE.

offset_values

Named numeric vector of raw input values for variables inside model offsets, such as c(n_weeks = 4) for offset(log(n_weeks)). When omitted, a log offset uses 1 (zero on the log scale) and a direct offset uses 0. Set it for a meaningful projection scenario. See Details.

include_fixed

Logical. Set TRUE, with scale_center = TRUE and a fitted native model, to standardize modeled fixed-radius metrics with their verified original training preparation. The default FALSE uses only the scaling parameters stored on the supplied object. See Details.

match_buffer

Logical. With the default FALSE, kernel means use the pct_wt window. Set TRUE to use the same circular footprint as kernel_prep(): every cell intersecting a circle of radius max_D. Requires a fitted or prepared multiScaleR object, a projected CRS with square cells at the prepared resolution, and na.rm = TRUE. Works with either value of fft. See Details.

site_values

Optional named list of scalar values for nonspatial predictors, in their native units, for example list(season = "spring", effort = 2, surveyed = TRUE). Requires a fitted object. Factor and character values must be fitted levels. Omitted numeric predictors default to zero, and categorical predictors need an explicit value. Unknown names and attempts to overwrite a spatial layer are errors. Use offset_values for variables that occur only inside offsets.

...

Reserved for deprecated arguments. Only scale_opt, a deprecated alias for multiScaleR, is handled (with a warning).

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:

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

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:

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:

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:

Source

Simulated for this package.

See Also

surv_pts, landscape_counts.

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:

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 K, mixture, distance function, output units and optimizer settings, and it never switches engine. The model needs unmarked 1.5.2, plus TMB 1.9.25 for the TMB engine. Formulas with offset() terms and zero-inflated TMB models (mixture = "ZIP" with engine = "TMB") are not supported.

cold_starts

Named list of one or more extra starting vectors on the link scales of the model, for example list(cold = cold). For a C-engine model, name each vector exactly like unmarked::coef(model), such as "lambda(Int)" and "dist(Int)". For a TMB-engine or field model, supply one value for every fixed coefficient and log SD, either unnamed in the order of gdr_start_values(model)$starts, or named by parameter block and position, such as "beta_lambda[1]" or "lsigma_lambda[1]". Random effects are not included. Each vector must differ from the model's estimates and from the other vectors, and the names "original" and "final" are reserved. These values are model coefficients, not kernel scales of effect and not the cutoff K.

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 NULL (the default) for a C-engine model, whose settings are read from the fitted model. Required elements:

  • method: one of "BFGS", "Nelder-Mead", "CG" or "L-BFGS-B".

  • se: logical. Whether the final refit of each call computes standard errors.

  • threads: must be 1.

  • control: named list of finite numeric optim() controls with a positive integer maxit, such as list(maxit = 2000L, reltol = 1e-10).

Optional elements:

  • lower, upper: parameter bounds for method = "L-BFGS-B", either one number or one value per coordinate in the fitted optimizer order (names(gdr_start_values(model)$fitted_values)), which can differ from the start order.

  • random.start: how TMB starts each search for the random-effect values. "cached_best" (the TMB default) starts from the best values found so far. "zero" starts from zero.

  • inner.control: a list with positive maxit, tol, grad.tol and step.tol for that inner search.

  • record_memory: TRUE records the memory used by the R process at each phase of a fit. It requires the ps package. The default is FALSE.

For a field model, pass the identical list used in fit_gdr_response_field().

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:

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 msr_vars(), one or more named specifications created with kernel_var(), landscape_var(), or surface_var(). Each name becomes the covariate's column name in the model data. Names must be unique, and "x" is reserved for internal coordinate data. At least one specification is required. For print(), further arguments passed to base::print.data.frame().

source

Character scalar. Name of the source layer in the raster_stack given to kernel_prep(). It must match a layer name exactly. Several covariates can share one source.

metric

Character scalar. Code of the metric to compute within the buffer, matched case-insensitively. landscape_var() accepts the 25 landscape metrics and surface_var() the six surface metrics defined in Details.

radius

Optional positive numeric scalar. Buffer radius in map units. With the default NULL, the radius is estimated with the model. It is a hard radius, so it has no Hessian standard error (see multiScaleR-kernels). When supplied, the metric is computed once at this radius and enters the model as an ordinary covariate, with no scale to estimate. Keep it within the max_D of kernel_prep(), because cells beyond max_D are never extracted.

base

Positive numeric scalar, not equal to 1. Base of the logarithm used by Shannon diversity ("shdi") and the information-theory metrics ("ent", "condent", "joinent", "mutinf"). Default: exp(1), so entropies are in nats. Use 2 for bits, which reproduces FRAGSTATS and the landscapemetrics package for the information-theory metrics, or 10 for Hartleys. The base cancels in the ratio metrics ("shei", "contag", "iji", "relmutinf"). The modified Simpson metrics ("msidi", "msiei") always use the natural log, as FRAGSTATS and landscapemetrics define them. For these and for metrics that take no logarithm, landscape_var() warns and ignores a non-default base.

classes_max

Positive numeric scalar. Number of classes that could occur in the landscape. Required for relative patch richness ("rpr"), where it is the denominator, and unused by every other metric. The observed class count is never substituted, so landscape_var() stops if "rpr" is requested without it.

class

Optional integer-like scalar. The focal class code for the class-level metrics ("clumpy", "pland", "ca"), which describe one class rather than the whole buffer. It must match one of the class codes in the source raster. It is required for those three metrics and an error for every other metric.

weighted

Logical, for surface_var() only. With FALSE (default), the metric summarizes every cell within a hard-edged circle, and the estimated scale is that radius. With TRUE, each cell is weighted by the model's distance kernel (the kernel given to kernel_prep()) and the estimated scale is the kernel's sigma, as for a kernel-weighted mean. Gaussian, negative exponential, and exponential power weights change smoothly with sigma, so sigma gets a standard error. With kernel = "fixed" the weights are 1 or 0, so the covariate is again a hard radius without a standard error. Weighting applies only to the distribution metrics ("sa", "sq", "ssk", "sku"), not to "sdq" or "sdr", and requires radius = NULL.

x

A multiScaleR_vars object returned by msr_vars().

Value

msr_vars() returns a data frame of class c("multiScaleR_vars", "data.frame") with one row per covariate and these columns:

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:

Elements added by the analytic backends

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:

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:

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

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:

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:

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:

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.

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


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:

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:

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.

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:

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

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

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.

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.

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.

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

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

Other elements

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

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.

Spatial field results (multiScaleR_field_cv)

cross_validate_field() scores each held-out block jointly, so that correlation among neighboring held-out observations counts.

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.

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

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. Supported classes include lm, glm, gls (nlme), and unmarkedFit (unmarked). Many other model classes also work through stats::update() or a custom refit_fn. A predictor cannot be named "x", which is reserved for internal coordinate data.

kernel_inputs

A list of class "multiScaleR_data" created by kernel_prep(). It must contain the elements raw_cov, d_list, min_D, max_D, unit_conv, and kernel. See multiScaleR_data.

join_by

Default: NULL. For unmarked models whose rows repeat sites (for example one row per site and year), a data frame with one unique key row per spatial site in kernel_inputs, in the same order as those sites. Its named key columns must also occur in the fitted model's siteCovs. See "Fit unmarked models with repeated sites" below.

par

Optional numeric vector of starting values. Default: NULL, which chooses starts automatically (see start_strategy). For the refit backend, divide each starting sigma by max_D to match the internal scaled parameter space. For the analytic backends, give scales in internal distance units (map distance divided by unit_conv), as for the rows of profile_control$starts. The length must equal the number of optimized covariates, or twice that for kernel = "expow", where the shape values follow the sigma values. The "expow" layout keeps one shape position per optimized covariate, including hard radii, which ignore it; give a finite positive placeholder there.

start_strategy

Character. How to choose starting values when par = NULL. "single" uses one shared default start. "screen" runs a cheap prescreen of sigma values and a few short searches before the one full search (see "Choose starting values" below). The default, NULL, uses "screen" when kernel_inputs was prepared with kernel = "fixed" and the backend is "refit" without a radius_grid, and "single" otherwise. Under a fixed kernel every optimized scale is a hard radius, and a gradient search cannot leave a single start on that stepped likelihood. A refit search that returns its starting values gives a warning and records start_stall in diagnostics().

screen_n_sigma

Positive integer. Number of log-spaced sigma values evaluated per covariate during the prescreen when start_strategy = "screen". Default: 5.

screen_n_jitter

Non-negative integer. Number of jittered candidate starts tried with short searches after the prescreen. Default: 6. Set to 0 to skip the short jittered runs.

screen_maxit

Positive integer. Maximum iterations for each short screening search. Default: 8.

screen_jitter_sd

Non-negative numeric scalar. Standard deviation of the multiplicative sigma jitter, on the log scale, used during screening. Default: 0.5.

n_cores

Positive integer. Number of cores for a parallel search through optimParallel. Default: NULL (serial). With start_strategy = "screen", the short screening searches also use these cores. Parallel searches help most with many covariates or slow model fits. When n_cores > 1, multiScale_optim() checks estimate_multiscale_ram() and stops before screening or creating workers if the requested workers exceed its conservative RAM-based limit. Use n_cores = 1 for a serial search, or rebuild the inputs with kernel_prep(..., bin = TRUE, store_cell_data = FALSE) (lean mode) when every covariate is kernel-weighted. Landscape and surface metrics cannot use lean mode. An unavailable RAM estimate does not block the run, a passing estimate does not guarantee enough memory, and the worker count is never reduced automatically.

PSOCK

Logical. On Windows, a PSOCK cluster is always used. On Unix, a FORK cluster is used by default because it is faster. Set TRUE to force a PSOCK cluster on Unix. Default: FALSE.

verbose

Logical. Print the search status and diagnostic messages to the console. Default: TRUE.

refit_fn

Optional function for refitting fitted_mod during the search. When NULL (default), stats::update() (or the unmarked equivalent) is used. Supply one only when the default refit is not enough; see "Supply a custom refit function" below.

backend

Character. The fitting method. "refit" (default) refits fitted_mod at each candidate scale and works with any model class that can be refit. "profile_glm" (Gaussian, Poisson, binomial, and NB2 GLMs), "joint_nb2" (NB2 models, including the exact Poisson boundary), "joint_mixed" (Poisson and NB2 glmmTMB models with one random intercept), and "conditional_logit" (step-selection models) estimate the scales and the model parameters in one likelihood. Fit a Gaussian model with glm(family = gaussian()) for the analytic backends, because lm() fits are rejected. multiScaleR-fitting-methods gives each backend's requirements and the uncertainty it reports.

profile_control

Named list of settings for the analytic backends, such as the number of starts (n_starts, default 6), a matrix of explicit starts, iteration limits, NB2 theta bounds, and a PSOCK worker_pool for "joint_nb2". Default: list(), which uses every default. The refit backend accepts no entries. The "Control settings" section of multiScaleR-fitting-methods lists every entry, the backends that accept it, and its default.

covariate_transform

Character. How optimized covariates enter the model. "candidate" (default) centers and scales the kernel or metric values at each candidate scale, so a coefficient describes a change of one standard deviation. "raw" keeps the values in their own units (for a binary layer, the kernel-weighted proportion) and records centers of zero and scales of one for prediction. Fit the starting model in those raw units, including any fixed spline knots. "raw" requires backend = "refit". See multiScaleR-fitting-methods.

radius_grid

Experimental, so its behavior may change in a later release without a deprecation period. With backend = "refit", an optional named list of candidate radius vectors, one for each optimized hard-radius predictor. For a single hard radius, supply the vector directly or name it in a list. Each vector needs at least two distinct radii in map units, between kernel_inputs$min_D and kernel_inputs$max_D. The fit evaluates every combination and reoptimizes any smooth kernel bandwidths and shapes at each one. The default NULL uses the backend's usual search. See "Profile hard radii over a grid" in multiScaleR-fitting-methods.

Value

An object of class "multiScaleR", a list. The elements you will use most are:

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:

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 multiScaleR object returned by multiScale_optim.

dimension

Character. "2d" (default) marks the radius containing the requested proportion of ideal planar kernel weight. "1d" restores the original distance along a line through the point.

...

Optional named arguments to customize the plot:

prob

Numeric between 0 and 1 (exclusive). Cumulative kernel weight enclosed by the marked distance under the selected dimension. Default: 0.9.

scale_dist

Logical. If TRUE (default), a vertical dashed line is drawn at the effective distance, and a shaded rectangle spans the 95% confidence interval.

add_label

Logical. If TRUE (default), a caption below the plot reports sigma, the dimensional definition, the effective distance, and 95% CI bounds (in map units).

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

plot_kernel

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 multiScale_bayes() object with posterior draws.

type

"scales" (default) plots one interval for each distinct combination of scale covariates and groups, such as each year. "group_sd" plots the between-group SDs, with scale and response effects in separate panels.

covariate

Optional character vector of landscape predictors to plot with type = "scales". The default NULL plots every predictor.

level

Probability of the central credible interval; default 0.95.

scale

"distance" (default) plots scales in projected map units. "log" uses natural log map units, which helps when the upper limits are very large. Used only with type = "scales". These are kernel scale parameters, not effective radii.

estimator

"auto" (default) uses the weighted production candidates of an importance-corrected fit and the stored draws otherwise. "draws" always uses the stored draws, and "weighted" requires retained importance candidates. Weighted plotting avoids resampling noise but does not raise the effective sample size or recover a missed mode.

...

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 sigma_profile object from profile_sigma().

...

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

profile_sigma()

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 dimension. Default: 0.9.

sigma

Positive numeric scalar. The kernel scale parameter, in the map units of the projection used with kernel_prep() (for example, meters). Larger values spread the weight over greater distances. For kernel = "fixed" it is the buffer radius. Required.

shape

Positive numeric scalar. Shape of the exponential power kernel (kernel = "expow"), required for that kernel and ignored for the others. shape = 1 gives the negative exponential curve, shape = 2 the Gaussian form (with standard deviation sigma / sqrt(2)), and larger values a flat top with a steep edge that approaches a fixed buffer. The default refit search of multiScale_optim() keeps the shape between 0.75 and 50. Default: NULL.

kernel

Character. The kernel to draw: "gaussian", "exp" (negative exponential), "expow" (exponential power), or "fixed" (fixed-radius buffer). Required. The weight functions are tabulated in multiScaleR-kernels.

scale_dist

Logical. If TRUE (default), a dashed red vertical line marks the distance that holds prob of the kernel weight under the selected dimension.

add_label

Logical. If TRUE (default), a caption below the plot reports the percentage of weight, the dimensional definition, sigma, and the marked distance. Shown only when scale_dist = TRUE.

dimension

Character. "2d" (default) marks the radius of the circle that holds prob of the ideal kernel weight on a plane. "1d" marks the original line-based distance, which holds that share along a transect through the point. See kernel_dist().

...

Not used.

beta

Deprecated former name of shape. It is still accepted, with a warning, and will be removed in a future release. Supplying both shape and beta with different values is an error.

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 multiScaleR object from multiScale_optim(). It must hold opt_mod (the model refit at the selected scales) and scl_params (the mean and standard deviation of each optimized covariate, used to put the x-axis back in original units). Also accepts a multiScaleR_bayes fit from multiScale_bayes(), as described in "Bayesian fits".

ylab

Character scalar. Y-axis label for every panel. Default "Estimated response". When you leave it unset, Cox fits use "Log relative risk" (or "Relative risk" with link = TRUE), and GAMs with several linear predictors name the native output column.

length.out

Positive integer. Number of equally spaced values at which each numeric curve is evaluated. Default 100. Larger values give smoother curves at a small cost in time.

type

Character. Component to plot for unmarked models, ignored for other models. Default "state".

  • occu() and pcount() fits: "state" (occupancy probability or expected abundance), "det" (detection probability), or "lambda", an alias for "state".

  • gdistremoval() fits: an active "lambda", "phi", "dist", or "rem" component, with "state" as an alias for "lambda".

  • Other unmarked classes: "state" or "lambda", as the native model names its state component.

link

Logical. If TRUE, predictions are passed through the model's inverse link, so the curve is on the response scale. Default FALSE. The setting matters only for some models:

  • glm fits, which include the model in opt_mod from the analytic backends, and single-predictor GAMs and BAMs always plot the response scale. spaMM HLfit curves are always transformed too.

  • Cox fits plot the log relative risk with FALSE and the relative risk with TRUE.

  • GAMs with several linear predictors plot the native link-scale output with FALSE and the native response-scale output with TRUE. component chooses the column.

  • unmarked, glmmTMB, lme4, and Bayesian curves use their native response scale for both settings.

  • For other models, set TRUE if the curve appears to be on the link scale.

draws

For Bayesian fits, either a positive number of stored draws to select evenly across the retained sample, or explicit draw indices. The default NULL uses at most 1000 evenly spaced draws. Ignored for other fits.

reference_data

Optional data frame of raw predictor values for the rows used to fit the model. Default NULL, which recovers the data from the fitted model. Supply it when the fitted model frame keeps only transformed columns, such as poly(temperature, 2). It needs unique row names that match the native training frame (rows may be reordered), and its values must reproduce the fitted features, design, factor coding, and offsets. Available for native LM, GLM, GAM, and Cox fits. See "Supply raw reference rows".

component

Optional positive integer selecting a native output column of a GAM with several linear predictors. Required for those fits and otherwise must be NULL. With link = FALSE it selects a linear predictor. With link = TRUE it selects a native response column, whose meaning and number depend on the family. For mgcv::ziplss() response curves, select component = 1, the overall expected count, which combines both linear predictors.

add_label

Logical. If TRUE, a caption under each panel states what the plotted limits include, such as conditioning on the selected scales or the treatment of random effects. Bayesian captions also report the number of draws and the stored status of the fit checks. Default FALSE, which draws the panels without a caption, as suits a figure for publication.

Value

Invisibly, a named list of ggplot2 objects, one per plotted covariate and named after it. Each plot is also printed. A panel shows:

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

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.

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 multiScale_bayes() object with posterior draws, from sampling or either approximation. A prepared object has no draws and gives an error.

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 NULL uses every stored draw. Fewer draws run faster and add simulation noise.

scale

"distance" (default) reports scales in projected map units. "log" reports natural log distances in those units. Log summaries avoid exponentiating very large distances, and their means and SDs stay finite under the default group-SD prior (see "Read means of long-tailed distances").

estimator

"draws" (default) summarizes the stored draws, for every method. "weighted" summarizes all retained production candidates of an importance-corrected fit with their normalized importance weights, which avoids the extra noise of resampling. It requires draws = NULL and a fit made with control = list(correction = "importance").

Value

A data frame with one row per landscape predictor and distinct combination of scale-formula covariates and groups.

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 fit_gdr_response_field().

type

Character. The model component to predict: "lambda" (density, the default), "dist" (distance scale) or "rem" (removal probability). "state" is accepted as another name for "lambda".

newdata

A data frame of covariate values, or an unmarkedFrameGDR with the fitted survey protocol (one visit, the same distance bands and the same interval lengths). The default NULL predicts for the rows used in fitting. Transformations, factor levels and spline bases keep their definitions from fitting. With the default, removal predictions have one row per survey and removal interval.

backTransform

Logical, default TRUE. TRUE returns density per square kilometer, the distance scale in meters or the removal probability per unit of interval time. FALSE returns the link scale (log, log or logit).

na.rm

Logical, default TRUE. Kept for compatibility with unmarked. Rows with missing predictor values are not dropped. They stop the prediction, so remove them first.

appendData

Logical, default FALSE. If TRUE, the prediction columns are added to the right of the prediction rows.

level

Confidence level between 0 and 1, default 0.95. NULL skips the limits, which are then returned as NA.

re.form

NULL (default) includes the fitted field, and any observer intercepts in the distance component. NA sets all of them to zero. A zero-field prediction describes a block with no deviation. It is not an average over blocks.

coords

Optional two-column matrix or data frame of projected coordinates for abundance predictions at new locations, one row per row of newdata. The default NULL locates each row by its level of the grouping factor (for example block = "b3"), which must be a fitted level.

crs

The CRS of coords, as an EPSG code or other input accepted by sf::st_crs(). Required with coords. It must equal the CRS used in fitting, because coordinates are never transformed.

...

Not used. Unrecognized arguments stop the prediction.

Value

A data frame with one row per prediction row:

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 multiScaleR object from multiScale_optim(), from any backend: "profile_glm", "joint_nb2", "conditional_logit", the experimental "joint_mixed", or the default "refit".

newdata

Where to predict. One of:

  • NULL (the default), with kernel_inputs = NULL, to predict the rows used to fit the model.

  • A data frame of new rows, supplied together with kernel_inputs. It must hold every non-spatial variable in the model formula: fixed covariates, offset inputs, and grouping variables. Row names must match the point IDs in kernel_inputs, unless you supply join_by keys (refit backend). Kernel-weighted columns are computed for you and replace any columns of the same name.

  • A SpatRaster from kernel_scale.raster(), to predict every cell. Leave kernel_inputs as NULL. See "Predict across a raster".

kernel_inputs

A multiScaleR_data object from kernel_prep() for the new points. Prepare it with the fitted kernel, the same covariates and source or metric definitions, and the same binned or exact evaluation as the fit. Kernel means in the analytic, conditional logistic, and joint mixed backends need binned inputs (bin = TRUE). Its own distance unit conversion is applied, and the reported scales stay in map units. Default NULL. For the analytic backends, a model with no non-spatial covariates can omit newdata, and a frame is built from the prepared point IDs. Conditional logistic fits with an optimized weighted surface SQ metric also need matching raw cell buffers and source or metric specifications here.

type

Scale or component to predict. For the analytic and joint mixed backends, "response" (the default, the model's expected response) or "link" (the linear predictor). For "conditional_logit", "response" (the default, a probability within each choice set), "link", or "risk". For native refits, any type the provider accepts. When type is not supplied, a refit predicts the response for most models, "state" for unmarked occupancy and count models, and the linear predictor ("lp") for Cox models, which have no response probability here. Raster prediction from an unmarked model needs an explicit type.

se.fit

Logical. If TRUE, also return standard errors of the predicted mean, on the scale of type. Default FALSE.

uncertainty

Which parameters the standard errors and intervals let vary. "joint" (the default) includes the estimated kernel scales and shapes and their covariance with the coefficients. It is available only for the analytic backends at points. "conditional" holds the kernel parameters at their estimates. Both include an estimated dispersion in the coefficient information when the family has one. Every other route needs uncertainty = "conditional" whenever it returns a standard error and stops otherwise.

interval

"none" (the default) or "confidence". Confidence limits describe the expected response, not a future observation. They are available only for the analytic backends at points.

level

Confidence level for interval = "confidence", strictly between zero and one. Default 0.95.

...

Further controls. Which ones apply depends on the backend:

  • include_fixed: logical, default FALSE. Set TRUE to recompute declared fixed-radius predictors at new points. See "Recompute fixed-radius predictors". This is the only control that the analytic and conditional logistic backends use.

  • join_by: refit backend only. A data frame of site keys, one row per prepared point in kernel_inputs order, that lets several newdata rows share one site, for example one row per site and year. See prepare_unmarked_data() for the key rules.

  • Native prediction controls for "joint_mixed" and refit models, such as re.form or allow.new.levels. Put a control whose name matches a wrapper argument in a named native_args list, for example native_args = list(level = 0) for nlme population predictions. Native argument abbreviations are resolved with the provider's exact-first matching before any other check. They cannot replace the wrapper's verified inputs or bypass its checks.

  • raster_args: a named list of raster controls. See "Predict across a raster".

Value

The class depends on the route.

No route adds observation noise, except the native lm prediction interval and the spaMM response variances (see "Native refits").

Choose the rows to predict

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.

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 multiScale_bayes() object with posterior draws, from sampling or either approximation.

newdata

NULL (default) uses the fitted observations. Otherwise a nonempty data frame of new observations that holds the fixed covariates, the offset variables, and the grouping variables of every component you include. Response values are neither needed nor used.

type

"response" (default) returns expected responses, which are expected counts for Poisson and NB2 models, success probabilities for binomial models (also for grouped binomial data), and means for Gaussian models. "link" returns the linear predictor.

re.form

NULL (default) includes the response random effects. NA sets them all to zero while keeping group-specific scales. This is a reference prediction, not an average over the random effects.

summary

Logical. TRUE (default) returns posterior summaries. FALSE returns the matrix of draws by observations.

level

Probability of the central interval; default 0.95.

draws

Optional positive integer number of evenly spaced posterior draws to use. The default NULL uses every draw. Fewer draws save time and memory at a cost in simulation precision.

kernel_inputs

Prepared landscape inputs for newdata, from kernel_prep() or kernel_prep_by_group(). Required with new data and NULL otherwise. Use the fitted kernel, predictor definitions, and physical map units. See "Match new rows to their landscapes" in predict.multiScaleR_bayes().

row_id

Name of the column in newdata that matches each row to an entry of kernel_inputs$binned$point_ids, or to a row name of kernel_inputs$kernel_dat for surface-only inputs. IDs may repeat. The default NULL uses the fitted row-ID column when the fit kept it, and the row names of newdata otherwise. Supply it for fits saved by older versions of the package. Used only with new data.

scale_re.form

NULL (default) includes the fitted scale random effects and any sampled new ones. NA sets every scale deviation to zero. It is separate from re.form, which controls response effects.

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. "error" (default) stops, "sample" draws a new effect, and "zero" sets the new effect to zero. A sampled effect is one standard-normal value per new group and posterior draw, multiplied by that draw's group SD, and shared by every row in the group. Zeroing gives a typical-group reference, not a population average. Known groups keep their fitted effects. Neither choice creates a coefficient for a new level of a fixed factor.

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, TRUE recomputes declared fixed-radius landscape predictors from kernel_inputs, using their original preparation means and SDs. The default FALSE requires those columns in newdata. Source, metric, radius, kernel, and resolution must match the fitted preparation, including its max_D buffer extent. This adds no scale parameters or uncertainty.

...

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.

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 multiScale_bayes() object with stored joint posterior draws, from sampling or either approximation.

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. "error" (default) stops and asks for a decision. "sample" draws a new standardized group effect for each joint posterior vector. "zero" sets the new deviation to zero. Known levels keep their fitted effects. Neither choice creates a coefficient for an unseen level of a fixed factor.

re.form

NULL (default) includes the scale random effects. NA sets every scale deviation to zero, a reference value rather than an average over group variation. Response effects are never used here.

level

Probability of the central interval; default 0.95.

draws

Optional positive integer number of evenly spaced stored posterior vectors to use. The default NULL uses every vector.

summary

Logical. TRUE (default) returns interval summaries and computes each repeated scale combination once, which avoids a large matrix when many rows share one year's scale. FALSE returns one matrix of draws by new observations for each landscape predictor.

scale

"distance" (default) returns projected map units. "log" returns natural log distances in those units.

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.

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

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

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.

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 NA, is kept as it is and reported in findings; it is never treated as 0.

history_keys

Data frame with one row per row of histories, in the same order, holding the original survey and individual identifiers and any other notes you want to keep.

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 event_keys and history_keys.

individual_id

Character vector naming the column(s) of history_keys that identify a bird within a survey. Each survey and individual combination must be unique.

cell_map

Data frame with columns column (a column name of histories), interval and distance_bin (positive whole numbers). It must map every column of histories to exactly one combination of interval and distance band, and every combination must appear once. Columns of histories can be in any order.

dist_breaks

Increasing distance boundaries of the source bands, starting at zero, in units_in. Include bands beyond the survey radius when the records have them. Only the last boundary may be Inf.

radius

Survey radius, in units_in. It must equal one of dist_breaks, because a band cannot be split without finer distances.

interval_lengths

Positive whole numbers giving the duration of each time interval, in interval_units. Intervals may differ in length.

interval_units

Character string naming the time unit, such as "seconds". It is recorded, not converted.

units_in

Distance units of dist_breaks and radius, "m" or "km".

surveyed

Logical vector with one value per event, in event order, with no NA: TRUE for a completed survey and FALSE for an event that was not surveyed. A recorded bird at an unsurveyed event is an error.

expected_event_keys

Optional data frame, built independently, with the event_id columns in the intended event order. The function stops if event_keys differs from it.

native_frame

Optional single-visit unmarkedFrameGDR built earlier from these records. It is audited with validate_unmarked_data(), and the function stops unless its two count tables, its distance boundaries up to the radius and its interval lengths match the prepared results exactly. Distances in meters and kilometers are compared in meters, without changing either input.

x

A prepared msr_gdr_histories object.

...

Not used.

Value

A list of class msr_gdr_histories:

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 unmarkedFrameGDR with its original counts and its site, yearly and observation covariates.

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 .input_row, .input_row_name and .interval are reserved.

event_id

Character vector naming the column(s) of event_keys that identify each survey.

interval_data

A data frame with the event_id columns, the interval number column and the new covariates. It needs exactly one row for every survey and removal interval. Rows can be in any order, and alignment records how they were matched.

interval_units

Character string naming the time unit of the removal intervals, such as "minutes". No time conversion is performed.

interval

Character string, default "interval". The name of the interval number column in interval_data. Its values must be whole numbers from 1 to the number of removal intervals per primary period. The column is also added to the observation covariates, so formulas can use it.

site_id

Optional column(s) of event_keys that identify the physical site, passed to validate_unmarked_data(). Frame rows need not be physical sites.

effort

Optional numeric vector of survey effort, one value per event, passed to validate_unmarked_data(). Positive values mark completed surveys, zero marks unsurveyed events and NA marks unknown effort.

expected_event_keys

Optional independent event list in frame order, passed to validate_unmarked_data().

x

A prepared msr_gdr_intervals object to print.

...

Not used.

Value

A list of class msr_gdr_intervals:

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 multiScaleR object from multiScale_optim(), using backend = "profile_glm", "joint_nb2", "conditional_logit", or "joint_mixed", or the default refit backend with a supported native model in object$opt_mod. For predict(), a snapshot returned by prepare_prediction().

newdata, kernel_inputs

Prediction rows and matching spatial inputs from kernel_prep(), with the same requirements as in predict.multiScaleR(). The default NULL for both uses the rows retained from fitting.

max_bytes

Positive number. The largest allowed size of the returned snapshot, in bytes. The default, 64 * 1024^2, is 64 MiB. A larger snapshot raises an error, so use fewer rows or raise the limit. It limits the stored size, not the temporary memory used while preparing.

component

Character scalar naming the native prediction type to keep.

  • unmarked models: required. Name one component, such as "state", "det", "psi", "col", or "ext", as the fitted model supports.

  • "joint_mixed": optional. Name one native glmmTMB type, such as "zprob". The default NULL prepares both "response" and "link".

  • Other refits: the default NULL prepares "response" and "link" for lm, glm, glmmTMB, lme4, gls, and lme models, and "lp" and "risk" for Cox models. Other native providers need an explicit component.

  • Analytic and conditional logistic backends: leave NULL. Their snapshots keep every type ("response", "link", and, for conditional logistic fits, "risk").

native_args

A named list of native prediction controls to bind to the snapshot. Default list(), which keeps the native defaults. Changing any control later needs a new snapshot. Supported controls:

  • "joint_mixed": re.form, allow.new.levels, and na.action.

  • unmarked: backTransform, na.rm, appendData, level, and re.form.

  • Other refits: re.form, allow.new.levels, na.action, reference, and level (such as nlme level = 0), when the native method accepts them. Ordinary lm refits also accept interval ("confidence" for mean limits, "prediction" for future-observation limits). spaMM refits accept variances and intervals, but cross-row covariance needs point predictions instead of a snapshot. mgcv GAMs accept exclude, terms, unconditional, iterms.type, and block.size, and BAMs also accept discrete. unconditional = TRUE requests the native smoothing-parameter covariance, which adds no kernel-scale uncertainty.

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 unmarked spatial predictions, a data frame of site keys with one row per prepared site, in kernel_inputs order. It needs both newdata and kernel_inputs. unmarked spatial snapshots require it (see prepare_unmarked_data()). The default NULL aligns general refit rows by row name, and unmarked data without spatial inputs pass unchanged. Not used by the analytic, conditional logistic, and joint mixed backends.

include_fixed

Logical. The default FALSE keeps fixed-radius predictors as explicit inputs in newdata. Set TRUE to recompute them from the spatial inputs after verifying their training preparation, as described in prepare_unmarked_data() and predict.multiScaleR(). It needs spatial inputs and verified row alignment, with explicit site keys for repeated sites and for unmarked models.

type, se.fit, uncertainty, interval, level

Output and uncertainty controls for predict() on a snapshot, with the defaults and checks of predict.multiScaleR(). For analytic and conditional logistic snapshots they choose the scale and the uncertainty summary of the fixed design. For joint mixed and refit snapshots, type selects one prepared component (the first one prepared by default), se.fit selects the cached point or standard-error output, and uncertainty must be "conditional" when standard errors or native interval attributes are returned. unmarked snapshots accept only type.

...

For predict(), any additional argument, including new prediction data, raises an error. Prepare a new snapshot for new rows. Ignored by print().

x

A multiScaleR_prediction snapshot from prepare_prediction().

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.

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 multiScaleR object whose opt_mod is an unmarkedFit, with its fitted scales, training standardization, and retained kernel_inputs.

newdata

A nonempty data frame of prediction rows, in the layout that native unmarked prediction needs for your chosen component. Include the site key columns and every non-spatial variable, including factors and offset inputs. Existing optimized spatial columns are replaced. Supply fixed-radius predictors on their fitted scale unless include_fixed = TRUE. Other columns and the row order are left unchanged.

kernel_inputs

A multiScaleR_data object from kernel_prep() for the new sites. Use the fitted kernel, source and metric definitions, buffer extent (max_D), raster resolution, and the same binned or exact evaluation as the fit. Landscape and surface metrics need cell-level inputs, while lean binned inputs are enough for kernel means.

join_by

A data frame with one unique key row per prepared site, in kernel_inputs point order. Its column names must occur in newdata, and every newdata row must match a key. Repeated keys in newdata repeat that site's spatial values, which lets you write site-by-year or site-by-survey scenarios without changing their order. Required.

include_fixed

Logical. The default FALSE leaves fixed-radius predictors as native inputs that you supply. Set TRUE to calculate modeled fixed-radius metrics at the new sites too, after verifying that their retained preparation values and standardization match the fitted static site covariates. Missing or inconsistent training information raises an error.

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 multiScaleR object.

dimension

Character. "2d" (default) prints the ideal planar radius first; "1d" prints the original line-based distance first.

prob

Numeric between 0 and 1 (exclusive). Proportion of cumulative kernel weight used for the distances. Default: 0.9.

...

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 multiScaleR_data object.

...

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 summary_multiScaleR object from summary.multiScaleR().

dimension

Character, "2d" or "1d". Selects which distance table is printed first. The default, NULL, uses the definition stored in x; summaries saved before this choice existed print the 1D table first.

...

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 multiScaleR object returned by multiScale_optim(). Fits from backend = "joint_mixed" are not supported.

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 sigma_values is supplied. Default: 10.

metric

Character. Which quantity plot.sigma_profile() draws: "AICc" (default) or "LL" (log-likelihood). Both are always computed. The log-likelihood is highest, and AICc lowest, at the best-supported sigma.

verbose

Logical. Print a progress message for each covariate. Default: TRUE.

n_cores

Optional positive integer. Number of CPU cores used to profile covariates in parallel, one covariate per worker (a PSOCK cluster). Default: NULL (serial). The analytic and conditional-logistic backends always profile serially.

spacing

Character. Spacing of the generated grid. "log" (default) places more values at small sigma, where the likelihood usually changes fastest. "linear" spaces them evenly. Ignored when sigma_values is supplied.

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, spacing, sigma_range, and n_pts are ignored.

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, min_D to max_D. Ignored when sigma_values is supplied.

Value

A list of class sigma_profile with these elements:

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 multiScaleR result from multiScale_optim() with the default backend = "refit", whose fitted model is one of:

  • a glmmTMB model with one shared exponential, Gaussian or Matern field, such as exp(pos + 0 | grp), and no other random effects. The family must be Gaussian, Poisson, NB2 or Gamma with a log link, or binomial with a logit link.

  • a distance-removal model with a fixed-range abundance field from fit_gdr_response_field().

coords

Numeric matrix or data frame with two finite projected coordinate columns (x, y), one row per fitting row in the original row order. Repeated locations repeat their coordinates. For glmmTMB, use the coordinates passed to glmmTMB::numFactor(), in the same units. For a distance-removal field, use exactly the coords passed to fit_gdr_response_field(). Those are block locations, which can be coarser than the survey points used for the kernel covariates.

crs

The projected CRS of coords, as an EPSG code (for example 32617) or any input accepted by sf::st_crs(). It must have two horizontal axes and linear units that match coords. Geographic, geocentric, vertical and compound CRSs are rejected. Prediction rasters must use an equivalent CRS. Nothing is transformed or rescaled, so choose the projected CRS before fitting.

batch_size

Positive integer, default 128. The largest number of raster cells passed to each native prediction call. Smaller batches use less memory but repeat the native setup more often.

max_memory_mb

Positive number, default 512. A conservative budget, in MiB, for the dense arrays of each prediction batch. A batch whose estimate exceeds the budget stops before native prediction. Lower batch_size if that happens. This is a planning estimate, not an operating-system memory cap. For a distance-removal field, the budget set in fit_gdr_response_field() also applies.

Value

A multiScaleR_field_geometry object, a small list that stores no model, coordinates or predictions. It contains:

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 multiScaleR fit from backend = "profile_glm" or backend = "joint_nb2", with NB2 errors and exactly one optimized kernel mean or weighted surface SQ covariate. Weighted SQ requires retained raw buffers and a Gaussian or exponential kernel.

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 0.95.

grid_points

Number of log-spaced scale values when sigma_values is omitted; default 41. Increase this to check whether narrow or disconnected regions were missed.

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 bootstrap > 0. The caller's random-number state is restored.

n_starts

Number of additional dispersed starts for inference refits; default 12. Original starts, the selected fit, and both scale bounds are also included. Failed starts cannot win.

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 lower and upper are root-refined endpoints in map units; lower_outside and upper_outside retain adjacent rejected grid points. The two *_bound_limited columns mark endpoints limited by the optimization bounds.

bootstrap_set

Accepted grid components with the same columns, or NULL unless 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, or unresolved); 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 (keep_selection = TRUE) or full fits (keep_fits = TRUE). Results from cross_validate_field() and cross_validate_mixed() always keep their records.

criterion

Training criterion, declared in advance: "AICc" (default), "AIC", or "BIC". It is computed from each candidate's training log-likelihood and parameter count K with the same rules as aic_tab() and bic_tab(). AICc needs more training observations than K + 1.

ties

What to do when two candidates have exactly the same training criterion. The default "error" marks the fold as failed. "first" picks the tied candidate listed first in mod_list. No tolerance is applied, so only exact ties count.

keep_fits

Logical. The default FALSE returns compact output. TRUE also returns the selected training fit of each fold in fits. This requires every candidate to have been run with keep_fits = TRUE, because records cannot rebuild a fit.

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.

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 type (log for counts, logit for occurrence, identity for "gaussian"). Default: 1.

beta

Numeric vector of slopes, one per layer of raster_stack and in the same order, on the link scale. Each slope is the effect of a one standard deviation change in that standardized covariate. Required.

kernel

Character. Kernel used to weight raster values by distance when computing the true covariates: "gaussian" (default), "exp" (negative exponential), "expow" (exponential power), or "fixed" (fixed-radius buffer). See multiScaleR-kernels.

type

Character. Distribution of the simulated response:

  • "count" (default): Poisson counts with mean exp(eta).

  • "count_nb": negative binomial counts with mean exp(eta) and size (dispersion) StDev.

  • "occ": binary (0 or 1) occurrence with probability plogis(eta).

  • "gaussian": normal values with mean eta and standard deviation StDev.

StDev

Positive numeric scalar. The size (dispersion) of the negative binomial for "count_nb", where smaller values give more overdispersion, or the residual standard deviation for "gaussian". Unused for "count" and "occ". Default: 0.5.

n_points

Either a positive integer number of points to simulate, or a SpatVector of points to use directly. An integer places points on a regular square grid over the interior of the raster and samples n_points of them at random (see Details). Default: 50.

min_D

Positive numeric scalar. Starting spacing, in map units, of the point grid when n_points is an integer. Default NULL uses 1.55 * max(sigma). The spacing shrinks until the grid holds at least n_points points.

raster_stack

A SpatRaster whose layers are the landscape variables, such as the output of sim_rast(). Layer names become the covariate names. Required.

sigma

Positive numeric vector of true scale parameters, in map units, one per layer of raster_stack. These are the values that multiScale_optim() should recover. Required.

shape

Positive numeric vector of true shape parameters, one per layer. Required when kernel = "expow" and ignored otherwise.

max_D

Positive numeric scalar. Radius, in map units, of the buffer used to compute the true covariates with kernel_prep(). Default NULL uses 1.1 times the line-based (1D) distance holding 99% of the kernel weight at max(sigma). That is shorter than the planar radius holding 99%, so supply a larger value if you need less truncation. Supply it when kernel = "expow", because the default cannot be computed for that kernel.

user_seed

Optional integer seed. When supplied, set.seed() is called with it, which makes the simulation reproducible and also resets the global random number stream. Default: NULL.

...

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:

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 exp(log(400) + 0.5 * habitat).

distance_scale

Positive number, or one per point. The standard deviation (sigma) of the half-normal detection function, in units_in. Detection falls to about 61% of its maximum at this distance. It is unrelated to the kernel scale of effect.

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 units_in. The last boundary is the survey radius.

interval_lengths

Positive whole numbers giving the duration of each removal interval, in interval_units. Intervals may differ in length.

interval_units

Character string naming the time unit of interval_lengths, for example "minutes". It is recorded, not converted.

units_in

Distance units, "m" (default) or "km".

site_covs

Optional data frame of site covariates, one row per point, such as kernel-weighted landscape covariates from kernel_prep(). Columns are copied into the observed frame unchanged. As in unmarked, character columns are converted to factors with a warning.

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 validate_unmarked_data().

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 FALSE. If TRUE, also return the simulated counts by point, distance band and interval as joint.

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 design$provenance without being evaluated.

x

An object returned by sim_dat_gdr().

...

Not used.

Value

A list of class msr_gdr_simulation:

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: 1.

beta

Numeric vector of slope coefficients, one per raster layer in raster_stack. Length must equal nlyr(raster_stack).

kernel

Character. Kernel function used to weight raster values by distance. One of "gaussian" (default), "exp" (negative exponential), "expow" (exponential power), or "fixed" (fixed-radius buffer).

type

Character. Response type to simulate. One of:

"count"

(Default) Poisson-distributed abundance with binomial thinning to simulate detection probability det.

"count_nb"

Negative binomial abundance with dispersion StDev, then binomial thinning.

"occ"

Bernoulli occupancy data; occupancy is generated from a logistic model and detections follow Bernoulli(occ * det).

StDev

Positive numeric. Dispersion (size) parameter for "count_nb". Default: 0.5.

n_points

Positive integer. Number of spatial sample sites. Points are placed on a hexagonal grid and randomly subsampled. Default: 50.

n_surv

Positive integer. Number of repeated surveys per site, forming the columns of the returned observation matrix. Default: 3.

det

Numeric between 0 and 1. Per-survey detection probability applied via binomial thinning of the true abundance/occupancy. Default: 0.5.

min_D

Positive numeric. Minimum inter-point spacing on the hexagonal grid. If NULL (default), set automatically to 1.55 * max(sigma).

raster_stack

A SpatRaster object. Layer names become covariate names in the returned data frame.

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 kernel = "expow", one per raster layer. Required when using the exponential power kernel.

max_D

Positive numeric. Maximum buffer radius for kernel_prep during simulation. If NULL (default), set automatically to 110% of the one-dimensional distance enclosing 99% of kernel weight along a line at max(sigma). Supply a larger max_D if the radius enclosing 99% of weight on a plane is needed.

user_seed

Optional integer seed for reproducibility. Default: NULL.

...

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:

y

Integer matrix of dimensions n_points x n_surv containing the simulated replicated observations. Pass as the y argument when constructing an unmarkedFrame.

df

Data frame with n_points rows. The y column 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.

pts

An sf POINT object with n_points rows. An obs column is appended containing the true abundance/occupancy values. Pass to kernel_prep as pts.

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 dim x dim grid. Default: 100.

resolution

Positive numeric. Cell size (edge length) in map units. The raster spans 0 to dim * resolution in each direction. Default: 10.

autocorr_range1

Optional positive numeric. Autocorrelation range, in cells, of the fields behind bin1 and cont1. Larger values give smoother, more broadly correlated patterns. Default NULL uses floor(0.05 * dim), and at least 1 (fine-scale autocorrelation).

autocorr_range2

Optional positive numeric. Autocorrelation range, in cells, of the fields behind bin2 and cont2. Default NULL uses floor(0.25 * dim), and at least 1 (broad-scale autocorrelation).

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: 10.

plot

Logical. If TRUE, plot the four layers with terra::plot(). Default: FALSE.

user_seed

Optional integer seed for reproducibility. Each layer uses a different multiple of the seed (1, 9, 99, and 55 times user_seed), so the layers differ but are fully reproducible. The seed also sets the global random number stream. Default: NULL (not reproducible).

...

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:

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 multiScale_bayes() object with posterior draws, from sampling or either approximation.

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

NULL (default) uses the fitted observations. Otherwise a nonempty data frame of new observations that holds the fixed covariates, the offset variables, and the grouping variables of every component you include. Response values are neither needed nor used.

kernel_inputs

Prepared landscape inputs for newdata, from kernel_prep() or kernel_prep_by_group(). Required with new data and NULL otherwise. Use the fitted kernel, predictor definitions, and physical map units. See "Match new rows to their landscapes" in predict.multiScaleR_bayes().

row_id

Name of the column in newdata that matches each row to an entry of kernel_inputs$binned$point_ids, or to a row name of kernel_inputs$kernel_dat for surface-only inputs. IDs may repeat. The default NULL uses the fitted row-ID column when the fit kept it, and the row names of newdata otherwise. Supply it for fits saved by older versions of the package. Used only with new data.

re.form

NULL (default) includes the response random effects. NA sets them all to zero while keeping group-specific scales. This is a reference prediction, not an average over the random effects.

scale_re.form

NULL (default) includes the fitted scale random effects and any sampled new ones. NA sets every scale deviation to zero. It is separate from re.form, which controls response effects.

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. "error" (default) stops, "sample" draws a new effect, and "zero" sets the new effect to zero. A sampled effect is one standard-normal value per new group and posterior draw, multiplied by that draw's group SD, and shared by every row in the group. Zeroing gives a typical-group reference, not a population average. Known groups keep their fitted effects. Neither choice creates a coefficient for a new level of a fixed factor.

trials

Positive integer binomial trial totals, one value or one per observation row. The default NULL keeps the fitted totals when you simulate the fitted rows. For new observations it uses one trial for a binary fit, and it is an error for a grouped binomial fit, which needs explicit totals. Use only with binomial models. Response columns in newdata never supply the totals.

include_fixed

Logical. With new data, TRUE recomputes declared fixed-radius landscape predictors from kernel_inputs, using their original preparation means and SDs. The default FALSE requires those columns in newdata. Source, metric, radius, kernel, and resolution must match the fitted preparation, including its max_D buffer extent. This adds no scale parameters or uncertainty.

...

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 multiScale_bayes() object. An object from method = "prepare" is enough. For a fitted object, the posterior draws are ignored and its specification supplies the same prior model.

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.

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 sf POINTs, a terra::SpatVector of points, or a numeric two-column coordinate matrix or data frame. Row order must match the data. Meaningful row names must match ids.

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 k indivisible spatial units must remain after joining groups.

ids

Unique character row IDs. Defaults to the row names of coords, or to the row numbers as character strings. Use the same IDs as the modeling data.

group

Optional sampling-group labels aligned with ids, such as site or animal IDs. Blocks joined by any shared group are kept together, including through chains of shared groups. This can reduce the number of available units.

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 c(0, 0). Cells are half-open intervals of width block_size, indexed by floor((coordinate - origin) / block_size).

crs

Projected CRS declaration for coordinate tables, in any form accepted by sf::st_crs(). For spatial objects, an optional declaration must match their existing CRS. Coordinates are never transformed or relabeled here, and longitude and latitude are rejected.

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 multiScaleR from multiScale_optim().

profile

Logical. If TRUE, report profile-likelihood confidence limits for sigma where feasible instead of Wald limits. Default: FALSE, which keeps summaries fast. See "Profile-likelihood intervals" below.

dimension

Character. "2d" (default) reports, as the selected distance, the radius that holds prob of the weight of an ideal kernel on a plane. "1d" restores the original distance along a line. Both definitions remain in the returned object and the printed output.

...

Optional arguments. prob, a number strictly between 0 and 1, sets the proportion of cumulative kernel weight used for the distances. Default: 0.9.

Value

An object of class summary_multiScaleR, a list that prints as a report. Its elements:

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 multiScaleR_bayes object from multiScale_bayes(), prepared or fitted.

...

Not used. Supplying any further argument is an error.

x

A multiScaleR_bayes object to print, prepared or fitted.

formula

Two-sided response formula, such as count ~ habitat + factor(year) + (1 | site). Name each landscape predictor as it is named in inputs. Its kernel-weighted value is computed at every candidate scale, so you never supply that column. The formula accepts fixed covariates, interactions with landscape predictors, offsets, and additive random intercepts. See "Write the response formula".

inputs

Prepared landscape inputs from kernel_prep() or kernel_prep_by_group(), built with a Gaussian or exponential kernel. Kernel means need the binned summaries (bin = TRUE, the default). Optimized weighted surface SQ needs the retained raw cell buffers and source specifications. Means and SQ can be combined. Distances, priors, and reported scales all use the projected map units of these inputs. Declared fixed-radius surface and landscape metrics enter as ordinary numeric covariates with their original preparation normalization, so keep their prepared columns in data. No scale is estimated for them, and a constant or undefined metric is an error.

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 inputs and need not appear here. A missing response or covariate value is an error. Rows are never dropped.

scales

Named list with one one-sided formula for each landscape predictor in formula, such as list(habitat = ~1 + (1 | year)). Each formula models the natural log of that predictor's scale. The default NULL gives every predictor one shared scale, the same as ~1. See "Write the scale formulas".

family

Response family, one of "nbinom2" (default, negative binomial with a log link), "poisson" (log link), "binomial" (logit link), or "gaussian" (identity link). See "Choose a response family".

row_id

Optional name of a column in data that matches each row to its prepared landscape, an entry of inputs$binned$point_ids (or a row name of inputs$kernel_dat for surface-only inputs). The default NULL matches the row names of data. IDs may repeat, so repeated visits can share one static landscape. With one map per year, use site-year IDs so each row reads the map for its own year. The name is kept with the fit and reused by predict() and simulate().

priors

Named list of prior settings to change. Settings you leave out take their defaults, and the default list() uses them all. See "Set the priors" for every setting and its default.

method

Computation, one of "sample" (default, NUTS sampling), "prepare", "slice", "laplace", or "marginal". The method changes how the posterior is computed, not the model, likelihood, or priors. "prepare" checks the data, formulas, priors, and bins without fitting. See "Choose a computation method".

chains

Number of independent chains for "sample" and "slice"; default 4. Chain diagnostics need at least two.

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 floor(iter / 2).

seed

Optional positive integer seed for sampling or approximation draws; default NULL. Slice, Laplace, and marginal fits restore your own random-number state after using a supplied seed. Slice sampling draws its chain seeds before any work is sent to workers, so a seed gives the same chains at every cores setting.

control

Named list of method-specific settings; default list() uses each method's defaults. NUTS accepts adapt_delta and max_treedepth. Slice sampling accepts no settings, so leave the list empty. See "Set computation controls" for every setting, including those for "laplace" and "marginal".

laplace_draws

Number of draws taken from a "laplace" or "marginal" approximation for summaries; default 2000, minimum 2. Without importance correction these are independent Gaussian or mixture draws. With it they are resampled from the weighted candidates. More draws reduce resampling noise in summaries. They do not improve the approximation or raise the importance effective sample size.

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

Write the response formula

The response formula accepts the following terms.

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.

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.

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 unmarkedFitGDRField object.

parm, type, level, method

Arguments of confint(). type names the component ("lambda", "dist" or "rem"), parm optionally selects coefficients within it, and level is the confidence level (default 0.95). method = "normal" (the default) gives Wald intervals from the retained covariance. method = "profile" stops for this class.

...

Not used. The stopped methods ignore extra arguments.

nsim, seed

Not used. simulate() stops for this class.

Slots

response_field

A named list. The elements you are most likely to read are:

  • definition: the field definition, with covariance ("exponential"), the supplied range, range_estimated (always FALSE), the linear units of the CRS, state_count (the number of blocks) and survey_count.

  • coords: the survey coordinates supplied to fit_gdr_response_field(), one row per survey. block gives each survey's block number, and crs holds 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 of point, the inverse of the joint precision returned by TMB::sdreport().

  • lower: the lower Cholesky factor of the block correlation matrix. Multiplying the whitened deviations by lower gives the physical field values reported by coef().

  • diagnostics: the checks of the selected start, such as pdHess, maximum_absolute_gradient, conditional_latent_maximum_absolute_gradient and conditional_latent_Newton_decrement.

  • settings: the evaluated tmb_settings. audit_file is the path of the final audit record, and max_memory_mb is the planning budget used by predict().

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 unmarkedFrameGDR holding paired distance and removal counts for point surveys. Other frame classes are not supported.

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 event_keys that together identify one survey event. Their combinations should be unique; repeated combinations are reported.

site_id

Optional character vector naming the columns of event_keys that identify the physical site. A site may appear in several events (repeat visits). The default NULL skips the site checks.

interval_units

Character string naming the time unit of object@period.lengths, for example "minutes". Removal probabilities are per unit of this time. The label is recorded, not converted.

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 NA), and NA marks unknown effort. With the default NULL, the audit adds a warning, because counts alone cannot separate a completed survey with no detections from one that never happened.

expected_event_keys

Optional data frame, built independently of event_keys (for example from the field schedule), with the event_id columns in the order the frame should have. Rows whose keys differ are reported. A key table cannot show by itself that it is in the right order.

x

An object returned by validate_unmarked_data().

...

Further arguments passed to the data-frame print method.

Value

A list of class msr_unmarked_audit:

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 fit_gdr_response_field().

type

Optional character naming one component: "lambda" (abundance), "dist" (distance) or "rem" (removal). If omitted, all components are returned together, in the order of coef(object).

altNames

Logical, default TRUE. TRUE labels rows and columns with component prefixes, such as lambda(Int), as coef() does.

method

Character. Only "hessian", the default, is available. It returns the covariance computed from the curvature of the likelihood during fitting. Bootstrap covariance is not available for this model.

fixedOnly

Logical, default TRUE. TRUE returns the fixed regression coefficients only. FALSE adds the field value of every block (labeled lambda(b_lambda)) and any observer intercepts in the distance component.

...

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 multiScaleR fit from backend = "profile_glm" or backend = "joint_nb2". A backend = "joint_mixed" fit returns only native conditional covariance. Other backends raise an error. Use vcov(object$opt_mod) for their coefficient covariance conditional on the selected scales.

type

"joint" (the default) or "conditional".

  • "joint" returns the observed-information covariance of the log kernel parameters, the regression coefficients, and the log dispersion when the family has one.

  • "conditional" returns the coefficient covariance with the kernel parameters held fixed and the dispersion estimated. At the exact Poisson boundary of a "joint_nb2" fit it also holds the dispersion at that boundary, and joint covariance is unavailable there.

...

Passed to native vcov() for "joint_mixed". Otherwise unused.

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:

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)