
README last updated: 2026-11-18
| CI | Development | CRAN | License |
|---|---|---|---|
Documentation: the package website, https://wpeterman.github.io/multiScaleR/, has every vignette, the function reference, and the changelog.
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:
unmarked, including
distance-removal models;survival::clogit() or
amt;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.
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 packageThe 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.
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.
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.
Run citation("multiScaleR") to cite the paper that
describes the method and the package version you used.