README last updated: 2026-11-14
| CI | Development | CRAN | License |
|---|---|---|---|
Overview
The scale of effect is the distance over which a landscape variable influences an ecological response. multiScaleR estimates it directly. It weights the raster cells around each survey point with a distance kernel and chooses the kernel scale (sigma) that maximizes the likelihood of your regression model. You fit your model once at starting values, and multiScaleR searches over scales, reports each one with its uncertainty, and helps you compare, check, and map the result.
multiScaleR works with:
- linear, generalized linear, additive, and mixed models;
- occupancy and abundance models from
unmarked, including distance-removal models; - step-selection models fitted with
survival::clogit()oramt; - Bayesian models in which a scale of effect can vary among years or with a covariate.
It also computes kernel-weighted landscape and surface metrics, cross-validates models with spatial or grouped folds, maps predictions across a landscape, and simulates data with known scales of effect so you can test a design before collecting data.
Installation
Install the CRAN release with:
install.packages("multiScaleR")Install the latest build from R-universe with:
install.packages(
"multiScaleR",
repos = c("https://wpeterman.r-universe.dev", "https://cloud.r-project.org")
)R-universe rebuilds multiScaleR from the master branch on GitHub whenever that branch changes. This version can therefore be newer than the CRAN release. R-universe provides precompiled Windows and macOS binaries with the vignettes already built, so this route does not require Rtools.
If installing from GitHub on Windows, you may need Rtools to compile the package from source. Choose the Rtools release that matches your version of R and follow the installation instructions at https://cran.r-project.org/bin/windows/Rtools/.
Then execute the following commands in R:
# Install 'remotes' package, if needed
if (!requireNamespace("remotes", quietly = TRUE)) {
install.packages("remotes", repos = "https://cloud.r-project.org")
}
remotes::install_github("wpeterman/multiScaleR",
build_vignettes = TRUE) # Install & build vignette
library(multiScaleR) # Load the packageA first example
The package includes simulated counts at 75 points, generated with a habitat effect whose true scale of effect (sigma) is 75 map units.
library(multiScaleR)
data(pts) # survey points
data(count_data) # counts at each point
hab <- terra::rast(system.file("extdata", "hab.tif", package = "multiScaleR"))
# 1. Weight the habitat raster around each point with a Gaussian kernel
inputs <- kernel_prep(pts = pts, raster_stack = hab, max_D = 250,
kernel = "gaussian")
# 2. Fit your model once, at the starting scale
start_model <- glm(y ~ hab, family = poisson, data = count_data)
# 3. Estimate the scale of effect
fit <- multiScale_optim(start_model, inputs)
summary(fit) # sigma, its interval, and the distance holding 90% of the weight
plot(fit) # the fitted kernel weight curveThe estimated sigma is close to the simulated value of 75, and summary() converts it into the distance that contains 90% of the kernel’s weight, which is the number to report as the scale of effect.
Learn more
The vignettes work through simulated data and explain how to read each result. Start with the quick start and the user guide, then turn to the topics you need. Open one in R with vignette("v01-quickstart", package = "multiScaleR"), or read them all on the package website.
Reference topics in the help system give the details that the vignettes leave out:
| Help topic | What it covers |
|---|---|
?multiScaleR |
Package overview and the main functions, step by step |
?"multiScaleR-kernels" |
Kernel families, sigma, hard radii, and effective distance |
?"multiScaleR-fitting-methods" |
The fitting backends and the uncertainty each reports |
?"multiScaleR-prediction" |
What each prediction represents and how uncertain it is |
?"multiScaleR-glossary" |
Plain-language definitions of the terms used |
NEWS.md lists the changes in each version, including the switch to planar (2D) kernel distances in version 0.7.4.
Experimental tools
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() are experimental. Their arguments and results may change in a later release without a deprecation period.

