Skip to contents

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

StepFunctions
1. Describe the covariateskernel_var(), landscape_var(), surface_var(), msr_vars()
2. Prepare the points and rasterskernel_prep(), kernel_prep_by_group(), estimate_multiscale_ram()
3. Fit your model at starting valuesYour usual function, such as glm() or unmarked::pcount()
4. Estimate the scalesmultiScale_optim() or multiScale_bayes()
5. Read and check the fitsummary(), plot(), diagnostics(), profile_sigma(), kernel_dist(), plot_kernel()
6. Compare modelsaic_tab(), bic_tab(), cross_validate(), cv_tab(), select_cv()
7. Predict and mappredict(), kernel_scale.raster(), plot_marginal_effects(), prepare_prediction()

Specialized models and tools

Reference topics

TopicWhat it covers
multiScaleR-kernelsKernel families, sigma and shape, hard radii, effective distance
multiScaleR-fitting-methodsBackends, their requirements, and the uncertainty each reports
multiScaleR-predictionPrediction quantities and the uncertainty each route carries
multiScaleR-glossaryDefinitions of the terms used in the documentation
multiScaleRThe fitted object from multiScale_optim()
multiScaleR_dataThe prepared inputs from kernel_prep()
multiScaleR_bayesThe fitted object from multiScale_bayes()
multiScaleR_cvCross-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

Maintainer: Bill Peterman Peterman.73@osu.edu (ORCID)

Authors:

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.