multiScaleR multiScaleR package logo

README last updated: 2026-11-18

CI Development CRAN License
R-CMD-check Lifecycle: stable CRAN status License: GPL v3
codecov Project Status: Active CRAN downloads DOI
r-universe checks r-universe version

Documentation: the package website, https://wpeterman.github.io/multiScaleR/, has every vignette, the function reference, and the changelog.

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:

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 package

A 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 curve

The 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.

Vignette Name in vignette()
01. Quick start v01-quickstart
02. User guide v02-user-guide
03. Mapping predictions and limiting extrapolation v03-map-predictions
04. Landscape metrics as covariates v04-landscape-metrics
05. Surface texture metrics as covariates v05-surface-metrics
06. Using year-specific rasters in one model v06-year-specific-rasters
07. Choose a fitting method for your model v07-fitting-methods
08. Cross-validate scale-of-effect models v08-cross-validation
09. What your estimates and intervals mean v09-estimates-and-intervals
10. Estimate scales of effect in step-selection models v10-step-selection
11. Account for spatial autocorrelation with a spatial field v11-spatial-fields
12. Fit distance-removal models with scales of effect v12-distance-removal
13. Estimate scales of effect with a Bayesian model v13-bayesian-scales
14. Predict new sites and years from a Bayesian model v14-bayesian-prediction
15. Choose and check a Bayesian computation method v15-bayesian-computation

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.

Citation

Run citation("multiScaleR") to cite the paper that describes the method and the package version you used.

multiScaleR package logo