
multiScaleR: estimate scales of effect for spatial covariates
Source:R/multiScaleR-package.R
multiScaleR-package.RdThe 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.
Start here
Work through vignette("v01-quickstart", package = "multiScaleR"), then
vignette("v02-user-guide", package = "multiScaleR"). Run
browseVignettes("multiScaleR") to see all 15 vignettes, which cover
mapping, landscape and surface metrics, year-specific rasters, fitting
methods, cross-validation, intervals, step selection, spatial fields,
distance-removal models, and Bayesian models. multiScaleR-glossary
defines the terms they use.
The basic workflow
| Step | Functions |
| 1. Describe the covariates | kernel_var(), landscape_var(), surface_var(), msr_vars() |
| 2. Prepare the points and rasters | kernel_prep(), kernel_prep_by_group(), estimate_multiscale_ram() |
| 3. Fit your model at starting values | Your usual function, such as glm() or unmarked::pcount() |
| 4. Estimate the scales | multiScale_optim() or multiScale_bayes() |
| 5. Read and check the fit | summary(), plot(), diagnostics(), profile_sigma(), kernel_dist(), plot_kernel() |
| 6. Compare models | aic_tab(), bic_tab(), cross_validate(), cv_tab(), select_cv() |
| 7. Predict and map | predict(), kernel_scale.raster(), plot_marginal_effects(), prepare_prediction() |
Specialized models and tools
Choosing a fitting method: multiScaleR-fitting-methods describes each backend of
multiScale_optim().Cross-validation for other model types:
cross_validate_glm(),cross_validate_clogit(),cross_validate_field(),cross_validate_mixed(),cross_validate_bayes(), with fold buildersspatial_cv_folds()andgrouped_cv_folds().Occupancy and abundance models from
unmarked:prepare_unmarked_data(),validate_unmarked_data().Distance-removal models:
prepare_gdr_histories(),prepare_gdr_intervals(),expand_gdr_intervals(),gdr_start_values(),make_gdr_refitter(),fit_gdr_response_field(),response_field_geometry().Bayesian models, in which a scale may vary among years or with a covariate:
multiScale_bayes(),check_bayes_setup(),simulate_bayes_prior(),posterior_scales(),predict_scales(),diagnose_bayes_scales(),diagnose_bayes_probabilities(),diagnose_bayes_laplace().Assessing NB2 scales over the full likelihood range:
scale_inference().Simulating data with known scales of effect:
sim_rast(),sim_dat(),sim_dat_unmarked(),sim_dat_gdr().
Reference topics
| Topic | What it covers |
| multiScaleR-kernels | Kernel families, sigma and shape, hard radii, effective distance |
| multiScaleR-fitting-methods | Backends, their requirements, and the uncertainty each reports |
| multiScaleR-prediction | Prediction quantities and the uncertainty each route carries |
| multiScaleR-glossary | Definitions of the terms used in the documentation |
| multiScaleR | The fitted object from multiScale_optim() |
| multiScaleR_data | The prepared inputs from kernel_prep() |
| multiScaleR_bayes | The fitted object from multiScale_bayes() |
| multiScaleR_cv | Cross-validation results |
Experimental tools
These tools are experimental. Their arguments and results may change in a
later release without a deprecation period: cross_validate_bayes(),
cross_validate_mixed(), the count, binary, and positive families of
cross_validate_field(), diagnose_bayes_laplace(), and the
radius_grid argument of multiScale_optim().
Author
Maintainer: Bill Peterman Peterman.73@osu.edu (ORCID)
Authors:
Bill Peterman Peterman.73@osu.edu (ORCID)
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
#>
#> Call:
#> multiScale_optim(fitted_mod = start_model, kernel_inputs = inputs,
#> verbose = FALSE)
#>
#>
#> Kernel used:
#> gaussian
#>
#> ***** Optimized Scale of Effect *****
#>
#> Mean SE 2.5% 97.5%
#> hab 76.16637 9.567451 57.09847 95.23428
#>
#>
#> ====================================
#>
#> ***** Optimized Scale of Effect -- Distance *****
#> Scale distances (map units) at 90%, two definitions.
#>
#> 2D, radius of the circle for the ideal untruncated kernel (selected):
#> Mean 2.5% 97.5%
#> hab 163.45 122.53 204.37
#>
#> 1D, along a line through the point (comparison):
#> Mean 2.5% 97.5%
#> hab 125.28 93.92 156.65
#>
#>
#> ====================================
#>
#> ***** Fitted Model Summary *****
#>
#>
#> Call:
#> glm(formula = y ~ hab, family = poisson, data = data)
#>
#> Coefficients:
#> Estimate Std. Error z value Pr(>|z|)
#> (Intercept) 0.4807 0.1021 4.707 2.51e-06 ***
#> hab 0.8691 0.0855 10.166 < 2e-16 ***
#> ---
#> Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
#>
#> (Dispersion parameter for poisson family taken to be 1)
#>
#> Null deviance: 186.585 on 74 degrees of freedom
#> Residual deviance: 70.185 on 73 degrees of freedom
#> AIC: 232.29
#>
#> Number of Fisher Scoring iterations: 5
#>
#>
#> WARNING!!!
#> The estimated scale of effect approaches or exceeds the current search extent.
#> Consider increasing max_D in `kernel_prep` to >= 250.56 to ensure accurate estimation of scale.
#>
#>
#>
#> ***** Follow-up recommendation *****
#> Recommended `max_D`: 250.56
#> Recommended starting `sigma` values:
#> hab
#> 76.16637
#>
#> Action:
#> Refit from the optimized parameters and address the flagged diagnostics.
