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
multiScaleRfit frombackend = "profile_glm"orbackend = "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_valuesis omitted; default41. 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.
Value
A list of class msr_scale_inference with:
- estimate
Refined scale estimate in map units.
- reference
Refined log-parameter vector, negative log likelihood, start audit, original negative log likelihood, and improvement. The original fitted object remains unchanged.
- grid
Scale values, profile negative log likelihood, likelihood-ratio statistic, chi-squared acceptance, bootstrap p-value and 95 percent Monte Carlo limits, bootstrap acceptance, and whether the Monte Carlo limits cross the rejection threshold. Uncalibrated entries are missing.
- profile_set
Separate accepted scale regions. Columns
lowerandupperare root-refined endpoints in map units;lower_outsideandupper_outsideretain adjacent rejected grid points. The two*_bound_limitedcolumns mark endpoints limited by the optimization bounds.- bootstrap_set
Accepted grid components with the same columns, or
NULLunless every grid point was successfully calibrated. Endpoints are accepted grid values, not root-refined limits; outside brackets show their resolution.- diagnostics
Zero-effect likelihood deviance and compatibility with the profile cutoff; profile status (
localized,disconnected,bound_limited, orunresolved); original Wald availability; and bootstrap status, failure count, and Monte Carlo ambiguity count.- bootstrap_records
One row per attempted bootstrap refit pair: generating scale, replicate, success, likelihood-ratio statistic, fitted scale and theta, boundary indicator, both likelihoods, attempted/eligible start counts, errors, and warnings. No failed replicate is silently dropped.
- profile_audit
Start records at each observed profile grid point.
- level, bootstrap, seed, bounds, call
Requested confidence level, bootstrap count and seed, map-unit search bounds, and matched call.
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.
Examples
# \donttest{
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.
}
#> Warning: Joint Wald uncertainty unavailable: Poisson limit within the diagnostic likelihood threshold. Inspect diagnostics and likelihood profiles.
#> $zero_effect_deviance
#> [1] 20.88188
#>
#> $zero_effect_compatible
#> [1] FALSE
#>
#> $profile_status
#> [1] "localized"
#>
#> $original_wald_available
#> [1] FALSE
#>
#> $bootstrap_status
#> [1] "not_requested"
#>
#> $bootstrap_failures
#> [1] 0
#>
#> $monte_carlo_ambiguous
#> [1] 0
#>
# }
