Fits that check memory before automatic differentiation,
including some multiScale_bayes() fits, no longer stop with
“Cannot detect RAM” on Windows machines where PowerShell is slow or
blocked. multiScaleR now reads total RAM directly from the operating
system and runs outside commands only as a fallback.
CRAN’s package check no longer runs the code in vignettes 2 to 15
or the 77 slowest test files, so the check fits within CRAN’s time
limit. The built vignettes still show their full results, and GitHub
Actions and devtools::check() still run every vignette and
test.
multiScaleR 1.0.0 is the first release since 0.7.4. It adds Bayesian scale estimation, new fitting backends, cross-validation that re-estimates scales, and prediction tools, and it reorganizes the documentation.
Some new tools are experimental, so their arguments and results may
change in a later release without a deprecation period:
multiScale_bayes(), scale_inference(), the
profile_glm backend and the radius_grid
argument of multiScale_optim(), predictions from the
joint_mixed backend, cross_validate_bayes(),
cross_validate_mixed(), the count, binary, and positive
families of cross_validate_field(), and
diagnose_bayes_laplace(). Their help pages say so.
multiScale_bayes() estimates scales of effect in a
Bayesian model, with shared, covariate-dependent, and partially pooled
scales. Slice sampling needs no Stan toolchain.
posterior_scales(), predict_scales(),
predict(), and simulate() summarize and
predict from a fit, and check_bayes_setup(),
simulate_bayes_prior(),
diagnose_bayes_scales(), and
diagnose_bayes_probabilities() check the setup, priors, and
chains. diagnose_bayes_laplace() checks a scale probability
from a fast approximation.multiScale_optim() gains opt-in fitting backends:
profile_glm and joint_nb2 for GLM and negative
binomial models, joint_mixed for glmmTMB random-intercept
models, and conditional_logit for step-selection models
fitted with survival::clogit() or amt. The
default refit backend is unchanged.cross_validate(), cross_validate_glm(),
cross_validate_clogit(),
cross_validate_mixed(),
cross_validate_field(), and
cross_validate_bayes(), with spatial and grouped folds from
spatial_cv_folds() and grouped_cv_folds(), and
comparisons with cv_tab() and
select_cv().multiScale_optim(radius_grid = ) compares listed radii
for landscape and surface metrics with a hard radius.predict() works on fitted objects at survey points, new
points, and rasters, and prepare_prediction() stores
prediction snapshots. Prediction and effect plots cover more model
classes, including GAM and BAM, Cox and clogit, spaMM,
lme4, glmmTMB, and unmarked models with factors and
repeated site-year rows.response_field_geometry().unmarked gain data
checks and preparation (validate_unmarked_data(),
prepare_unmarked_data(),
prepare_gdr_histories(),
prepare_gdr_intervals(),
expand_gdr_intervals()), simulation
(sim_dat_gdr()), and a spatial abundance field
(fit_gdr_response_field(),
make_gdr_refitter(), gdr_start_values()).scale_inference() examines the scale likelihood of
single-kernel NB2 models, with optional bootstrap calibration.covariate_transform = "raw" keeps optimized covariates in
their own units with the default backend.multiScale_optim() warns when the default refit search
returns its starting values, names the remedy, and records
start_stall in diagnostics().plot_marginal_effects() captions are off by default.
Set add_label = TRUE to restore them.pct_mx clamping moves each limit by a share of the
observed range, so projected values change when pct_mx is
not 0.kernel_dist() and plot_kernel() take
shape in place of beta. beta
still works in this release, with a deprecation warning.library(multiScaleR) no longer attaches
sf.summary(fit, profile = TRUE)
for an interval.multiScale_optim() screens starting values by default
for kernel = "fixed", so fixed-kernel estimates can change.
Set start_strategy = "single" to restore the old single
start.sim_rast() gives different layers for the same
user_seed, because its fields are now simulated
correctly.kernel_scale.raster() averages over the mapped cells
near raster edges with the default fft = TRUE, as
kernel_prep() does at survey points. In 0.7.4, a raster
with no missing cells was smoothed as if the area beyond its edge held
zeros, which pulled values toward zero. Smoothed layers and projected
maps change within the kernel’s reach of the edge.kernel_scale.raster() with fft = FALSE
keeps missing source cells missing instead of filling them. With
na.rm = FALSE, windows that extend beyond the raster edge
return NA.predict() under the analytic backends stops on
arguments it cannot use.multiScale_optim() withholds Wald standard errors, and
warns, when a refit failed at one of the points used to compute the
Hessian. The failure penalty had produced standard errors near zero with
no warning.sim_dat() counts the points of an sf
object correctly, sets max_D for the "expow"
kernel from each layer’s sigma and shape, places points inside rasters
whose extent does not start at the origin, and gives generated points
the raster’s coordinate reference system.multiScale_optim() runs stop their workers
when worker setup fails or the run is interrupted, instead of leaving
them running until R closes their connections.kernel_dist(), kernel plots,
and the selected summary distance now default to the 2D radius
containing the requested share of ideal untruncated planar kernel
weight. Set dimension = "1d" to restore the original
line-based definition. Fitted sigma values are unchanged.opt_dist and opt_distance follow
the selected dimension; use opt_dist_1d or
opt_dist_2d for explicitly defined tables. Print methods
show the selected definition first and retain the other for
comparison.join_by now preserves unmarked response and
site-covariate row alignment, validates site keys, and rejects
mismatched rows instead of recycling values.pcountOpen() and colext()
workflows with static site covariates.kernel_prep_by_group() prepares pooled model inputs
from aligned annual or other group-specific rasters, with shared
distance bins and pooled scaling.offset_values. Model
selection includes ancillary likelihood parameters such as
negative-binomial dispersion in its count.plot_marginal_effects() holds offset-only variables at
their sample mean for prediction without drawing misleading effect
panels for them.x, which is reserved for internal coordinates.kernel_prep() extracts raster cells in batches of 25
points to reduce temporary extraction memory while preserving point
order and results.kernel_dist() gains dimension = "2d", the
radius of a circle holding prob of an ideal, untruncated
planar kernel’s weight. For a Gaussian kernel at 90%, it is about 2.15
sigma, versus 1.65 sigma along a line. summary() and
print() report both distances, and summary()
returns the planar table as opt_dist_2d;
opt_dist and the kernel_dist() default are
unchanged.data-raw/generate_vignette_cache.R.profile_sigma() is faster when profiling models with
multiple expensive covariates. Along the profile grid only the profiled
covariate’s sigma changes, so the kernel-weighted columns of the other
covariates are now computed once and reused, and only the profiled
covariate is re-evaluated at each grid point. The reproducible benchmark
in
tools/benchmarks/profile_sigma_covariate_reuse_benchmark.R
checks that the profile values match the legacy full-recompute loop
before timing. On the local benchmark, the current path was 2.61x faster
for four landscape metrics and 2.40x faster for four weighted surface
metrics.kernel_scale_fn() is factored into
.msr_kernel_cov_w() (which can compute a single covariate
column), and the objective accepts a precomputed covariate matrix via a
new cov_w argument. Behavior of the optimizer and the
profile-likelihood intervals is unchanged.kernel_prep() and scale profiling now provide
metric-specific guidance when fragile landscape metrics cannot be scaled
because the derived covariate is all NA or has zero
variance. The messages call out the common failure modes for
iji, siei, and msiei, and the
landscape-metric documentation now recommends prescreening these metrics
before optimizing their scales.landscape_var() gains nine categorical metrics, all
reproducing the values returned by the landscapemetrics
package (FRAGSTATS conventions) for both the fixed-buffer path and the
FFT raster projection."iji" (interspersion and juxtaposition),
the evenness of the adjacencies among different classes. Like contagion,
it is built from the per-window class-pair co-occurrence matrix that
already powers "contag", so it adds no extra
convolutions."ent" (marginal entropy), "condent"
(conditional entropy), "joinent" (joint entropy),
"mutinf" (mutual information), and "relmutinf"
(relative mutual information). These separate composition from
configuration, which the diversity and contagion metrics confound. The
base argument now sets the logarithm base for these
entropies as well as the diversity metrics; set base = 2
for bits, matching landscapemetrics. The ratio metrics
("relmutinf", "iji") are unaffected by
base.class
argument naming the focal class: "clumpy" (clumpiness
index, -1 to 1), "pland" (percentage of landscape), and
"ca" (class area in hectares). class is
required for these three metrics and is not accepted for any other
metric."ent") with
configuration ("mutinf", "clumpy").surface_var() gains the "sdr" metric
(surface area ratio): the percentage by which the true 3D surface area
of the neighborhood exceeds its flat projected area. It behaves as a
continuous edge-density analog and uses the same quad triangulation as
geodiv::surface_area(). Unlike geodiv::sdr(),
which rescales the surface to a unit range and is dimensionless,
multiScaleR computes "sdr" in physical units (real
elevation values and the real cell size), so a tilted plane of slope
s returns (sqrt(1 + s^2) - 1) * 100. The
physical definition is the interpretable one for terrain and, unlike the
rescaled version, is FFT-projectable."sdr" joins "sdq" as a neighbor-based
surface metric (it caches raster cell IDs and its projection matches
point extraction to a small boundary tolerance). Kernel weighting is not
offered for the slope/area family.surface_var() gains a weighted argument.
With weighted = TRUE, the distribution metrics
("sa", "sq", "ssk",
"sku") are computed as kernel-weighted moments: each cell
is weighted by the model’s distance kernel (gaussian, exp, or expow) and
the optimized parameter is the kernel scale (sigma) rather than a hard
neighborhood radius. Because the weights vary smoothly with sigma, the
likelihood is smooth in the scale parameter, so
multiScale_optim() estimates the scale of effect of
heterogeneity with a standard error, exactly as it does for a
kernel-weighted mean. The default (weighted = FALSE) is
unchanged."expow", since they use the kernel (and its shape).
Weighting is not available for the slope metric "sdq", and
the scale is always optimized (no fixed radius)."sq", "ssk", and
"sku" uses kernel-weighted FFT power sums; weighted
"sa" uses the compiled focal pass, now generalized to
accept per-cell weights (a 0/1 mask reproduces the unweighted result
exactly).surface_var() gains three metrics: "ssk"
(skewness) and "sku" (excess kurtosis), which describe the
shape of the neighborhood value distribution, and "sdq"
(root mean square slope), which describes local gradient steepness or
ruggedness. With "sa" and "sq" this completes
the dispersion, distribution-shape, and slope families of gradient
surface metrics. "ssk" and "sku" match
geodiv’s adjusted-skewness and excess-kurtosis defaults;
"sdq" matches geodiv::sdq() after accounting
for cell resolution (multiScaleR reports a true slope, dividing the
gradient by the cell size)."ssk", "sku", and
"sdq" uses FFT convolution. The moment projections center
on the global raster mean first to avoid floating-point cancellation in
the third and fourth power sums. Like the landscape edge metrics,
"sdq" caches raster cell IDs and its projection agrees with
point extraction to within a small boundary tolerance.surface_metric_covariates vignette section
demonstrating the shape and slope surfaces.surface_var(), a new covariate specification for
continuous surface texture metrics, alongside the existing
kernel_var() and landscape_var(). Two metrics
are supported in this release: "sa" (average roughness, the
mean absolute deviation from the neighborhood mean) and
"sq" (root mean square roughness, the sample standard
deviation of the neighborhood values). Both definitions match the
geodiv package. These metrics summarize within-neighborhood
heterogeneity of a continuous raster (elevation, NDVI, canopy height,
temperature, and similar surfaces) rather than its mean, so they
complement kernel_var(). The buffer radius can be fixed or
optimized, and the covariates flow through kernel_prep(),
multiScale_optim(), and kernel_scale.raster()
exactly like landscape metrics.surface_var() projections in
kernel_scale.raster() compute "sq" with fast
Fourier transform (FFT) convolution and "sa" with an exact
masked focal pass. Average roughness has no closed-form FFT
decomposition, so "sa" is projected with a compiled focal
routine (surface_sa_focal_cpp) rather than an R closure;
this is exact and roughly twice as fast as the equivalent
terra::focal() call in benchmarks. Surface metrics require
a continuous raster with square cells.geodiv to Suggests; the
surface-metric tests use it as a validation oracle and are skipped when
it is not installed.surface_metric_covariates vignette, which
walks through defining, fitting, optimizing, and projecting surface
texture covariates and how to interpret roughness at different
scales.multiScale_optim() no longer queries system RAM on
every call. The next_run recommendation previously invoked
estimate_multiscale_ram() at the end of each fit, which
shelled out to an external process (PowerShell on Windows) and rebuilt
the optimization context; under load this could make
multiScale_optim() appear to hang after the optimization
had finished. The parallel worker-count suggestion is now obtained only
on demand by calling estimate_multiscale_ram() directly.
next_run$n_cores is now NULL.
estimate_multiscale_ram()’s own RAM query is also bounded
by a 5-second timeout so it degrades to NA instead of
blocking.kernel_prep() now precomputes distance-binned summaries
of kernel-weighted covariates (bin = TRUE,
nbins = 256 by default). multiScale_optim(),
profile_sigma(), and the screened-start path evaluate
kernel covariates from these summaries in O(nbins) per point instead of
iterating every buffer cell on each optimizer evaluation. The
per-evaluation cost becomes independent of max_D, making
optimization roughly 10-80x faster in benchmarks (the speedup grows with
the number of points and the buffer size), while recovering sigma to
within ~1e-5 (relative) of the exact per-cell result. Set
bin = FALSE to force the exact path.kernel_prep(store_cell_data = FALSE)) that drops the
per-cell d_list/raw_cov data when every
covariate is kernel-type, retaining only the binned summaries. This
reduces the multiScaleR_data memory footprint by roughly
30-40x in benchmarks and is sufficient to optimize, profile, and refit.
Cell-level data are retained automatically when landscape-metric
covariates are present.estimate_multiscale_ram() and
print.multiScaleR_data() now report binned summary sizes
and handle lean inputs.kernel_prep() now stores each point’s extracted cell
values as a dense or sparse matrix, whichever is smaller (continuous and
categorical layers store dense; low-prevalence binary layers stay
sparse), so raw_cov memory is never worse than before and
is ~1.5x smaller for continuous rasters. scale_type()
evaluates dense values in vectorized R, matching the compiled sparse
path to machine precision while avoiding per-cell sparse random access;
this speeds up the exact (bin = FALSE) per-cell weighting
and removes the repeated sparse-to-dense conversion in the
landscape-metric path. (One-time kernel_prep() and
landscape optimization wall-clock change little, as those are dominated
by raster extraction and the C++ metric computation respectively.)kernel_prep() instead of being re-scanned (with a per-call
unique() class detection) on every optimizer evaluation.
Optimized radii are unchanged. Direct calls to the landscape metric
helpers still validate by default.multiScale_optim() no longer spawns a
PowerShell process to query RAM on every call when populating its
parallel-worker recommendation.estimate_multiscale_ram() to report
kernel_prep() memory use, conservative parallel RAM
budgets, and recommended worker counts based on available RAM and
physical CPU cores while reserving two coresmultiScale_optim() when
requested parallel workers exceed the RAM-based budget estimated for the
current kernel_prep() payloadai) as a supported
landscape_var() metric, including fixed-buffer,
optimized-radius, and FFT raster projection paths with accuracy checks
against landscapemetricssummary.multiScaleR() argument handling so
optional arguments such as prob and profile
are validated consistentlyn_cores and
Windows PSOCK behavior, and added real-worker regression coveragemultiScale_optim() using the same n_cores
allocation as the main optimization when
start_strategy = "screen"profile_sigma() via n_cores and documented
practical core-selection guidance in vignettesmultiScale_optim() documentation and testsnext_run recommendations to
multiScale_optim() output with follow-up starting values
and a diagnostic-informed max_D suggestionaic_tab() roxygen registration so package
checks generate the proper help alias and no longer warn about missing
documentation entriesaic_tab(),
bic_tab(), sim_rast(), sim_dat(),
and sim_dat_unmarked()multiScale_optim() that scouts sigma values with log-spaced
prescreening and short serial screening runs before a single full
optimizationplot_marginal_effects() for wrapped/nested
fitted models such as amt::fit_clogit()-style objectsclogit analysis modelssigma/shape
term in aic_tab(), bic_tab(), and
profile_sigma() AICc calculations.libPaths() and R_LIBS*
settings to PSOCK workers for more reliable project-local parallel
optimization on Windowsopt_distance summary alias alongside the
existing opt_distkernel_scale.raster()
when stored scale_vars include unused source layersmsr_vars() specifications with 100 spatial sample
pointsmsr_vars(), kernel_var(), and
landscape_var() specifications for explicit derived raster
covariatesclogit wrappers in
serial and PSOCK optimizationglm.nb() after library(MASS)kernel_prep()
outputs used during optimizationprofile_sigma()diagnostics() accessormultiScale_optim()
export handlingsummarykernel_scale.rasterkernel_scale.raster to create ‘dummy’ layers
for site effect variablesverbose argument to functions to optionally
supress console printingkernel_scale.raster documentation and clamping
defaultsplot_marginal_effectsrhub.yamlaic_tab and bic_tab to properly
check model types.kernel_scale.rasterplot_marginal_effectkernel_scale.rastersim_rast for efficiency. Uses custom fftkernel_scale.rasterscale_opt is now deprecated in
kernel_scale.raster; replaced with multiScaleR
argument.pct_wt from 0.95 to 0.975 when
smoothing raster layersmultiScale_optimmethod and opt_parallel
variables. Method is always ’L-BFGS-B` and if cores > 1 is specified,
parallelization is implicit.multiScaleR with
unmarked.unmarked models
with stacked data formatsmultiScaleR_optim to reduce size of final
optimized object.insight package.multiScale_optim