multiScale_optim() returns an object of class "multiScaleR", a list
that holds the estimated scales of effect, your model refit at those
scales, and the record of the search. This page describes every element
and the functions that read the object.
Elements
Every fit has these elements:
scale_est: data frame with one row per optimized covariate (row names are covariate names) and two columns.Meanis the estimated sigma in map units, andSEis its Hessian-based standard error.SEisNAfor hard-radius landscape and unweighted surface metrics and for every radius estimated underkernel = "fixed", because their likelihood changes in steps.shape_est: data frame with the same layout for the shape parameter whenkernel = "expow", otherwiseNULL. Hard-radius covariates haveNAshape and shape SE because a shape does not apply to them; their unused shape positions are left out of the likelihood parameter count.optim_results: the raw list returned bystats::optim()oroptimParallel::optimParallel(), includingpar,value(the negative log-likelihood),hessian, and convergence codes. It also holdspar_unscale(sigma values in map units) andhessian_unscale. For a radius grid, this list describes the selected combination: its Hessian covers only the smooth parameters at those fixed radii, withNAfor hard-radius rows and columns and any inactive shape. Seediagnostics(fit)$radius_profilefor every candidate.opt_mod: your model refit at the estimated scales. Use it for coefficients, inference, prediction, andplot_marginal_effects(). Its coefficients are on the model's link scale (for example log for a Poisson model), and by default each optimized covariate is standardized, so a coefficient describes the change in the linear predictor for one standard deviation of the covariate.fitted_mod_original: thefitted_modyou supplied, kept for reference.min_D,max_D: the lower and upper bounds for sigma during the search, in map units.kernel_inputs: thekernel_inputslist (see multiScaleR_data), withoutmin_Dandmax_D, which are stored separately.scl_params: named list withmeanandsdvectors, the centering and scaling values of each optimized covariate at the estimated scales.kernel_scale.raster()uses them whenscale_center = TRUEso that maps match the model's covariates. Withcovariate_transform = "raw", the centers are zero and the scales one; prediction never relearns these values from new data.join_by: thejoin_bydata frame, orNULL.opt_context: internal record of the model-class-specific refit logic, kept forprofile_sigma(). Withcovariate_transform = "raw"it also records that setting.NULLfor the analytic backends.profile_scale_est: data frame of profile-likelihood intervals, orNULLuntilprofile_sigma()has been run.diagnostics: list of diagnostic records; read it withdiagnostics().next_run: list of suggested settings for a follow-up fit:max_Dfor the nextkernel_prep()call (raised when an estimate approaches the currentmax_D), the estimatedstart_sigmavalues in map units,start_shapeforkernel = "expow", andstart_par, the starts on the internal scale thatmultiScale_optim()expects, scaled to thatmax_D.n_coresisNULL; askestimate_multiscale_ram()for a parallel worker count.NULLfor some analytic backends.warn_message: integer vector of warning codes. It starts with0and adds1when an estimate approachesmax_D,2when a sigma standard error is at least half its estimate, and3when a shape standard error is at least half its estimate. See "Read the warnings" inmultiScale_optim().call: the matched call.
Elements added by the analytic backends
profile_fit,uncertainty,dispersion_est: present for"profile_glm"and"joint_nb2". They keep the transformed parameter estimates, the starts and their convergence scores, the profile and joint information matrices, identifiability diagnostics, and NB2 theta.uncertainty$availablesays whether joint uncertainty passed its checks, anduncertainty$reasonssays why not.opt_modand its coefficient summary condition on the estimated kernel parameters. Usevcov.multiScaleR()andpredict.multiScaleR()for joint uncertainty.profile_fitanduncertaintyfor"conditional_logit", which keep the starts, every start outcome, and the selected start. Scale uncertainty is not available.mixed_fitfor"joint_mixed": the kernel engine, log-scale estimates and bounds in internal distance units, the independent starts, every start outcome and warning, the selected start, and the variables prediction needs.uncertainty$availableisFALSE, andnext_runandopt_contextareNULL.
multiScaleR-fitting-methods explains what each backend records and why uncertainty may be withheld.
Where each quantity lives
| Quantity | Where to find it | Scale |
| Scale of effect (sigma) | fit$scale_est$Mean, summary(fit) | Map units |
| Kernel shape | fit$shape_est$Mean | Shape units of the exponential power kernel |
| Effective distance | summary(fit), kernel_dist() | Map units |
| Regression coefficients | coef(fit$opt_mod), summary(fit) | Link scale, per standard deviation of each covariate by default |
| NB2 dispersion | fit$dispersion_est$theta (analytic backends) | Natural scale |
| Profile-likelihood intervals | fit$profile_scale_est, summary(fit, profile = TRUE) | Map units |
The effective distance converts sigma into the distance that contains a set proportion (by default 90 percent) of the kernel's total weight, which is usually the easiest number to report. See multiScaleR-kernels.
Functions that read the object
| Function | What it gives you |
print(), summary.multiScaleR() | Scales, effective distances, intervals, and coefficients |
plot.multiScaleR() | The fitted kernel weight curve for each covariate |
diagnostics() | Search, sample-size, and uncertainty diagnostics |
profile_sigma() | Profile-likelihood intervals for sigma |
predict.multiScaleR(), vcov.multiScaleR() | Predictions and covariance, with joint uncertainty where available |
kernel_scale.raster() | Maps of the covariates at the estimated scales |
plot_marginal_effects() | Effect curves for each covariate |
aic_tab(), bic_tab() | Model comparison by AIC or BIC |
cross_validate() | Out-of-sample prediction scores |
scale_inference() | Likelihood-range and bootstrap assessment of single-kernel NB2 scales |
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
