Skip to contents

multiScale_optim() returns an object of class "multiScaleR", a list that holds the estimated scales of effect, your model refit at those scales, and the record of the search. This page describes every element and the functions that read the object.

Elements

Every fit has these elements:

  • scale_est: data frame with one row per optimized covariate (row names are covariate names) and two columns. Mean is the estimated sigma in map units, and SE is its Hessian-based standard error. SE is NA for hard-radius landscape and unweighted surface metrics and for every radius estimated under kernel = "fixed", because their likelihood changes in steps.

  • shape_est: data frame with the same layout for the shape parameter when kernel = "expow", otherwise NULL. Hard-radius covariates have NA shape and shape SE because a shape does not apply to them; their unused shape positions are left out of the likelihood parameter count.

  • optim_results: the raw list returned by stats::optim() or optimParallel::optimParallel(), including par, value (the negative log-likelihood), hessian, and convergence codes. It also holds par_unscale (sigma values in map units) and hessian_unscale. For a radius grid, this list describes the selected combination: its Hessian covers only the smooth parameters at those fixed radii, with NA for hard-radius rows and columns and any inactive shape. See diagnostics(fit)$radius_profile for every candidate.

  • opt_mod: your model refit at the estimated scales. Use it for coefficients, inference, prediction, and plot_marginal_effects(). Its coefficients are on the model's link scale (for example log for a Poisson model), and by default each optimized covariate is standardized, so a coefficient describes the change in the linear predictor for one standard deviation of the covariate.

  • fitted_mod_original: the fitted_mod you supplied, kept for reference.

  • min_D, max_D: the lower and upper bounds for sigma during the search, in map units.

  • kernel_inputs: the kernel_inputs list (see multiScaleR_data), without min_D and max_D, which are stored separately.

  • scl_params: named list with mean and sd vectors, the centering and scaling values of each optimized covariate at the estimated scales. kernel_scale.raster() uses them when scale_center = TRUE so that maps match the model's covariates. With covariate_transform = "raw", the centers are zero and the scales one; prediction never relearns these values from new data.

  • join_by: the join_by data frame, or NULL.

  • opt_context: internal record of the model-class-specific refit logic, kept for profile_sigma(). With covariate_transform = "raw" it also records that setting. NULL for the analytic backends.

  • profile_scale_est: data frame of profile-likelihood intervals, or NULL until profile_sigma() has been run.

  • diagnostics: list of diagnostic records; read it with diagnostics().

  • next_run: list of suggested settings for a follow-up fit: max_D for the next kernel_prep() call (raised when an estimate approaches the current max_D), the estimated start_sigma values in map units, start_shape for kernel = "expow", and start_par, the starts on the internal scale that multiScale_optim() expects, scaled to that max_D. n_cores is NULL; ask estimate_multiscale_ram() for a parallel worker count. NULL for some analytic backends.

  • warn_message: integer vector of warning codes. It starts with 0 and adds 1 when an estimate approaches max_D, 2 when a sigma standard error is at least half its estimate, and 3 when a shape standard error is at least half its estimate. See "Read the warnings" in multiScale_optim().

  • call: the matched call.

Elements added by the analytic backends

  • profile_fit, uncertainty, dispersion_est: present for "profile_glm" and "joint_nb2". They keep the transformed parameter estimates, the starts and their convergence scores, the profile and joint information matrices, identifiability diagnostics, and NB2 theta. uncertainty$available says whether joint uncertainty passed its checks, and uncertainty$reasons says why not. opt_mod and its coefficient summary condition on the estimated kernel parameters. Use vcov.multiScaleR() and predict.multiScaleR() for joint uncertainty.

  • profile_fit and uncertainty for "conditional_logit", which keep the starts, every start outcome, and the selected start. Scale uncertainty is not available.

  • mixed_fit for "joint_mixed": the kernel engine, log-scale estimates and bounds in internal distance units, the independent starts, every start outcome and warning, the selected start, and the variables prediction needs. uncertainty$available is FALSE, and next_run and opt_context are NULL.

multiScaleR-fitting-methods explains what each backend records and why uncertainty may be withheld.

Where each quantity lives

QuantityWhere to find itScale
Scale of effect (sigma)fit$scale_est$Mean, summary(fit)Map units
Kernel shapefit$shape_est$MeanShape units of the exponential power kernel
Effective distancesummary(fit), kernel_dist()Map units
Regression coefficientscoef(fit$opt_mod), summary(fit)Link scale, per standard deviation of each covariate by default
NB2 dispersionfit$dispersion_est$theta (analytic backends)Natural scale
Profile-likelihood intervalsfit$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

FunctionWhat 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

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)
#>  [1] "scale_est"           "shape_est"           "optim_results"      
#>  [4] "opt_mod"             "fitted_mod_original" "min_D"              
#>  [7] "max_D"               "kernel_inputs"       "scl_params"         
#> [10] "join_by"             "opt_context"         "profile_scale_est"  
#> [13] "diagnostics"         "next_run"            "warn_message"       
#> [16] "call"               
fit$scale_est            # sigma (Mean) and its SE, in map units
#>         Mean       SE
#> hab 76.16637 9.567451
coef(fit$opt_mod)        # coefficients on the log (link) scale
#> (Intercept)         hab 
#>   0.4806770   0.8691288 
fit$warn_message         # 0 plus a code for each warning raised
#> [1] 0 1
fit$next_run$max_D       # max_D suggested for a follow-up fit
#> [1] 250.56