01. Quick start

Bill Peterman

1 What multiScaleR does

multiScaleR estimates the scale of effect, or the distance over which a landscape variable influences an ecological response measured at survey locations. You do not test a fixed set of buffer radii. Instead, the package weights the landscape around each survey point with a distance-decay kernel and estimates the kernel width, sigma, as a parameter of your regression model. You get a scale estimate with a standard error and confidence interval, alongside the familiar regression coefficients.

This guide takes about ten minutes. It fits one count model to data bundled with the package and shows how to read every result. It assumes you can fit a generalized linear model with glm() and have used terra to read a raster. When you finish, the table in Where to go next points to the vignette for your next question.

2 Install the package

install.packages("multiScaleR")

3 The workflow in four steps

Every multiScaleR analysis follows the same four steps.

  1. Prepare the inputs with kernel_prep(). This extracts the raster values around each survey point and stores what the optimizer needs.
  2. Fit a starting model with an ordinary regression function such as glm(). The model formula and family carry through to the next step.
  3. Estimate the scales of effect with multiScale_optim(). This finds the sigma for each landscape covariate and the regression coefficients that together maximize the model likelihood.
  4. Read and map the results with summary(), plot(), plot_marginal_effects(), profile_sigma(), and kernel_scale.raster().

4 Work through an example

4.1 Load the data

The package includes a simulated data set of counts at 100 survey locations and a raster with three landscape layers.

data("landscape_counts")   # data frame: counts and one site-level covariate
dat <- landscape_counts

data("surv_pts")           # survey locations (an sf object from the package)
pts <- vect(surv_pts)      # convert to a terra SpatVector

# Three landscape layers on one grid, in meters
land_rast <- rast(system.file("extdata", "landscape.tif",
                              package = "multiScaleR"))

The counts were simulated from known values, which lets you check each estimate against the truth later in this guide.

Quantity True value
Scale of effect (sigma) for land1, a binary habitat layer 250 m
Scale of effect (sigma) for land2, a continuous layer 500 m
Effect of land1 on log expected count -0.5
Effect of land2 on log expected count 0.7
Effect of site, a covariate measured at the survey point 0.3
land3, a continuous layer No effect
plot(land_rast)
The three landscape layers, and the survey points over land1.
The three landscape layers, and the survey points over land1.
plot(land_rast$land1, main = "land1 with survey points")
points(pts, pch = 19, cex = 0.6, col = "red")
The three landscape layers, and the survey points over land1.
The three landscape layers, and the survey points over land1.

4.2 Prepare the kernel inputs

kernel_prep() extracts the raster values within max_D map units of each survey point and computes a first set of distance-weighted covariate values. The map units here are meters.

kernel_inputs <- kernel_prep(
  pts          = pts,          # survey locations
  raster_stack = land_rast,    # landscape layers to summarize
  max_D        = 1700,         # largest distance (m) considered around a point
  kernel       = "gaussian",   # shape of the distance-decay function
  verbose      = FALSE
)

Choosing max_D: Set max_D to a distance you are confident exceeds the true scale of effect. If you are unsure, err toward a larger value, because the optimizer can only search within that distance. The cost is computation, since a larger max_D means more raster cells to process. If multiScale_optim() later warns that a sigma estimate is close to max_D, increase max_D and run kernel_prep() again.

The kernel-weighted covariates are in kernel_inputs$kernel_dat, one row per survey point. They are centered and scaled, so each has a mean of zero and a standard deviation of one. Combine them with the response data.

df <- data.frame(dat, kernel_inputs$kernel_dat)
head(df, 3)
#>   counts      site      land1      land2     land3
#> 1      0 0.9919247  0.9588974 -0.1501063 0.6937213
#> 2      2 1.9921151  0.5647553  0.7262473 0.9235087
#> 3      7 0.2997527 -0.1320171  0.5132579 0.4549547

4.3 Fit a starting model

Fit the regression model you intend to optimize. multiScale_optim() inherits the formula and family from this model, so settle the model structure here. The coefficients at this stage are only starting values, because the landscape covariates were weighted with a first guess at sigma.

mod <- glm(counts ~ site + land1 + land2,
           family = poisson(),
           data   = df)

4.4 Estimate the scales of effect

multiScale_optim() searches over sigma for each landscape covariate, refits the regression at each candidate, and keeps the combination with the highest likelihood.

opt <- multiScale_optim(fitted_mod    = mod,
                        kernel_inputs = kernel_inputs)

Larger problems can run in parallel with n_cores, which needs more memory. estimate_multiscale_ram() reports how much. If a model has several landscape covariates and the result seems sensitive to its starting values, see the screened-start option in vignette("v02-user-guide", package = "multiScaleR").

4.5 Read the summary

summary(opt)
#> 
#> Call:
#> multiScale_optim(fitted_mod = mod, kernel_inputs = kernel_inputs)
#> 
#> 
#> Kernel used:
#> gaussian
#> 
#> ***** Optimized Scale of Effect *****
#> 
#>           Mean       SE     2.5%    97.5%
#> land1 238.4880 33.12452 172.7364 304.2397
#> land2 499.5767 47.47055 405.3484 593.8050
#> 
#> 
#>   ==================================== 
#> 
#> ***** 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%
#> land1  511.79 370.69  652.89
#> land2 1072.07 869.86 1274.29
#> 
#> 1D, along a line through the point (comparison):
#>         Mean   2.5%  97.5%
#> land1 392.28 284.13 500.43
#> land2 821.73 666.74 976.72
#> 
#> 
#>   ==================================== 
#> 
#>  *****     Fitted Model Summary     *****
#> 
#> 
#> Call:
#> glm(formula = counts ~ site + land1 + land2, family = poisson(), 
#>     data = data)
#> 
#> Coefficients:
#>             Estimate Std. Error z value Pr(>|z|)    
#> (Intercept)  0.39291    0.09098   4.319 1.57e-05 ***
#> site         0.17482    0.08246   2.120    0.034 *  
#> land1       -0.48628    0.07923  -6.138 8.38e-10 ***
#> land2        0.62571    0.07245   8.636  < 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: 224.24  on 99  degrees of freedom
#> Residual deviance: 109.57  on 96  degrees of freedom
#> AIC: 314.25
#> 
#> Number of Fisher Scoring iterations: 5
#> 
#> 
#> 
#> ***** Follow-up recommendation *****
#> Recommended `max_D`: 1700
#> Recommended starting `sigma` values:
#>    land1    land2 
#> 238.4880 499.5767 
#> 
#> Action:
#> Use the optimized parameters as efficient starting values if refitting.

How to read the summary() output: The output has four parts.

The lines below pull those quantities out of the fitted object.

est     <- summary(opt)$opt_scale          # sigma, SE, and 95% interval (m)
dist90  <- kernel_dist(opt)                # radius holding 90% of kernel weight (m)
effects <- exp(coef(opt$opt_mod))          # multiplicative change in expected count

round(dist90)
#>       Mean 2.5% 97.5%
#> land1  512  371   653
#> land2 1072  870  1274
round(effects, 2)
#> (Intercept)        site       land1       land2 
#>        1.48        1.19        0.61        1.87

Three statements follow from these numbers.

Because the data are simulated, you can compare each estimate with its true value.

ci_beta <- confint.default(opt$opt_mod)    # Wald 95% intervals, log scale
check <- data.frame(
  Parameter = c("sigma, land1 (m)", "sigma, land2 (m)",
                "effect of land1", "effect of land2", "effect of site"),
  Truth     = c(250, 500, -0.5, 0.7, 0.3),
  Estimate  = c(est[, "Mean"], coef(opt$opt_mod)[c("land1", "land2", "site")]),
  Lower     = c(est[, "2.5%"], ci_beta[c("land1", "land2", "site"), 1]),
  Upper     = c(est[, "97.5%"], ci_beta[c("land1", "land2", "site"), 2])
)
# Does each 95% interval contain the value used to simulate the data?
check$Covered <- check$Truth >= check$Lower & check$Truth <= check$Upper
knitr::kable(check, digits = 2, row.names = FALSE)
Parameter Truth Estimate Lower Upper Covered
sigma, land1 (m) 250.0 238.49 172.74 304.24 TRUE
sigma, land2 (m) 500.0 499.58 405.35 593.80 TRUE
effect of land1 -0.5 -0.49 -0.64 -0.33 TRUE
effect of land2 0.7 0.63 0.48 0.77 TRUE
effect of site 0.3 0.17 0.01 0.34 TRUE

How to read the table: Covered is TRUE when the 95% interval contains the true value. One simulated data set cannot show that the intervals are reliable in general, but it does show what recovery looks like when the model matches the process that generated the data.

What this means for your study. Report the effective distance, not sigma alone, and say which weight it refers to (90% by default). The coefficient standard errors in the regression table treat the estimated sigma values as known. vignette("v09-estimates-and-intervals", package = "multiScaleR") explains what that leaves out and when it matters.

By default, the sigma intervals come from the optimizer’s standard errors (the delta method). When the sample is small or an estimate sits near max_D, request profile-likelihood intervals with summary(opt, profile = TRUE). They take longer to compute and do not assume a symmetric likelihood.

4.6 Plot the kernels and the covariate effects

plot(opt)
Kernel weight against distance for each landscape covariate.
Kernel weight against distance for each landscape covariate.
Kernel weight against distance for each landscape covariate.
Kernel weight against distance for each landscape covariate.

How to read these plots: Each curve shows how the weight given to a raster cell declines with its distance from the survey point. The dashed line marks the effective distance from summary(), the radius that holds 90% of the kernel weight, and the gray band is its 95% confidence interval. The three lines of text under each panel repeat sigma, that radius, and its interval. A curve that falls quickly means the response depends on nearby landscape. A curve that falls slowly means distant landscape still counts.

The text under each panel is useful while you explore a fit, but a figure for a manuscript or a slide usually reads better without it. Set add_label = FALSE to draw the same panels with no text beneath them. The dashed line and the gray band stay.

plot(opt, add_label = FALSE)
The same kernel plots without the text under each panel.
The same kernel plots without the text under each panel.
The same kernel plots without the text under each panel.
The same kernel plots without the text under each panel.

Versions through 0.7.3 reported a line-based distance, which is shorter (about 1.65 sigma at 90% for a Gaussian kernel, against about 2.15 sigma for the circle). Set dimension = "1d" in summary(), plot(), or kernel_dist() to reproduce those earlier values. The fitted model is the same either way.

plot_marginal_effects(opt)
Estimated effect of each covariate on the expected count.
Estimated effect of each covariate on the expected count.
Estimated effect of each covariate on the expected count.
Estimated effect of each covariate on the expected count.
Estimated effect of each covariate on the expected count.
Estimated effect of each covariate on the expected count.

How to read these plots: Each panel shows the expected count across the observed range of one covariate, with the other covariates held at their means. The horizontal axis is in the covariate’s own units. For land1, a binary habitat layer, that is the kernel-weighted proportion of habitat around a survey point. The shaded band is a 95% confidence band for the expected count. The band treats the estimated scales as known, so it does not include uncertainty in sigma. Set add_label = TRUE if you want that reminder printed under each panel.

4.7 Check that each scale is well identified

profile_sigma() refits the model across a range of sigma values for one covariate at a time, holding the other scales at their estimates.

prof <- profile_sigma(opt, n_pts = 15)   # 15 sigma values per covariate
plot(prof)
AICc across candidate sigma values. The dashed line marks the estimate.
AICc across candidate sigma values. The dashed line marks the estimate.
AICc across candidate sigma values. The dashed line marks the estimate.
AICc across candidate sigma values. The dashed line marks the estimate.

How to read these plots: Lower AICc means better support. A clear trough near the dashed line means the data identify that scale well. A flat profile, or one that keeps falling toward the edge of the search range, means the data say little about that scale, and its interval should be read with caution.

4.8 Map the fitted model

kernel_scale.raster() applies each fitted kernel to the whole raster. With scale_center = TRUE it also standardizes the result with the mean and standard deviation used in fitting, so the layers can go straight into terra::predict().

r_scaled <- kernel_scale.raster(raster_stack = land_rast,
                                multiScaleR  = opt,     # the fitted object
                                scale_center = TRUE,    # same scaling as the model
                                clamp        = TRUE)    # stay within the fitted range

# Expected count in every raster cell
pred <- terra::predict(r_scaled, opt$opt_mod, type = "response")
Landscape layers smoothed at their estimated scales, in standard deviation units.
Landscape layers smoothed at their estimated scales, in standard deviation units.
Expected count across the landscape, with survey points.
Expected count across the landscape, with survey points.

How to read these plots: The first figure shows each landscape layer after kernel weighting. Its values are in standard deviation units of the data used to fit the model, so zero is the average survey point. The second figure is the expected count per cell from the fitted model. With clamp = TRUE, cells whose covariate values fall outside the range seen at the survey points are held at the nearest observed value, which keeps the model from extrapolating.

The largest expected counts lie along the western and southern borders, beyond the outermost survey points. The smoothed covariates there fall outside the range seen at the survey points, so clamping holds each one at its surveyed limit. The result is a combination that no survey point had, so read the border with caution. vignette("v03-map-predictions", package = "multiScaleR") covers projection beyond the sampled conditions in detail.

5 Quick reference

The full workflow in one block.

library(multiScaleR)
library(terra)

# 1. Load the data
data("landscape_counts"); data("surv_pts")
pts       <- vect(surv_pts)
land_rast <- rast(system.file("extdata", "landscape.tif",
                              package = "multiScaleR"))

# 2. Prepare the kernel inputs
kernel_inputs <- kernel_prep(pts = pts, raster_stack = land_rast,
                             max_D = 1700, kernel = "gaussian")

# 3. Fit a starting model
df  <- data.frame(landscape_counts, kernel_inputs$kernel_dat)
mod <- glm(counts ~ site + land1 + land2, family = poisson(), data = df)

# 4. Estimate the scales of effect
opt <- multiScale_optim(fitted_mod = mod, kernel_inputs = kernel_inputs)

# 5. Read the results
summary(opt)                   # sigma, effective distance, regression table
summary(opt, profile = TRUE)   # profile-likelihood intervals for sigma (slower)
kernel_dist(opt)               # radius holding 90% of the kernel weight
exp(coef(opt$opt_mod))         # multiplicative change in expected count
plot(opt)                      # kernel weight against distance
plot(opt, add_label = FALSE)   # the same plot without the text beneath it
plot_marginal_effects(opt)     # expected count across each covariate
plot(profile_sigma(opt))       # AICc across sigma: is each scale identified?

# 6. Map the fitted model
r_scaled <- kernel_scale.raster(land_rast, multiScaleR = opt,
                                scale_center = TRUE, clamp = TRUE)
pred <- terra::predict(r_scaled, opt$opt_mod, type = "response")

5.1 Summary of key functions

Function Purpose
kernel_prep() Extract raster values around each survey point and prepare the optimizer inputs
multiScale_optim() Estimate sigma for each landscape covariate together with the regression coefficients
summary() Report sigma, the effective distance, and the regression table
kernel_dist() Convert sigma to the distance that holds a chosen share of the kernel weight
plot() Draw kernel weight against distance
plot_marginal_effects() Draw the expected response across each covariate
profile_sigma() Check how well the data identify each scale
kernel_scale.raster() Apply the fitted kernels to a raster for mapping and prediction

6 Where to go next

If you want to Read
Understand kernels, intervals, and model selection in depth, or fit unmarked models vignette("v02-user-guide", package = "multiScaleR")
Map predictions beyond the conditions you sampled vignette("v03-map-predictions", package = "multiScaleR")
Use land-cover composition or configuration, such as edge density or Shannon diversity vignette("v04-landscape-metrics", package = "multiScaleR")
Use the roughness or texture of a continuous surface vignette("v05-surface-metrics", package = "multiScaleR")
Analyze surveys from several years, each with its own map vignette("v06-year-specific-rasters", package = "multiScaleR")
Combine covariate types and choose a fitting method vignette("v07-fitting-methods", package = "multiScaleR")
Compare models by how well they predict held-out data vignette("v08-cross-validation", package = "multiScaleR")
Know what an interval includes and what it leaves out vignette("v09-estimates-and-intervals", package = "multiScaleR")
Fit step-selection models to animal movement data vignette("v10-step-selection", package = "multiScaleR")
Account for spatial autocorrelation with a spatial field vignette("v11-spatial-fields", package = "multiScaleR")
Fit distance-removal models to point-count data vignette("v12-distance-removal", package = "multiScaleR")
Let the scale of effect vary among years in a Bayesian model vignette("v13-bayesian-scales", package = "multiScaleR")
Predict new sites or years from a Bayesian fit vignette("v14-bayesian-prediction", package = "multiScaleR")
Choose and check a faster Bayesian approximation vignette("v15-bayesian-computation", package = "multiScaleR")
Look up a term used in these vignettes ?"multiScaleR-glossary"