hsa: HespDiv Sensitivity Analysis

In hespdiv: Hierarchical Spatial Data Subdivision into Topologically Contiguous Units

HespDiv Sensitivity Analysis

Description

This function performs sensitivity analysis of the hespdiv method. Starting from a reference hespdiv object, it generates a specified number of alternative hespdiv calls by randomly sampling new values for selected arguments from user-provided sets.

Usage

hsa(
  obj,
  n.runs = 100,
  data.paired = TRUE,
  display = FALSE,
  images.path = NULL,
  pnts.col = 1,
  data = NULL,
  xy.dat = NULL,
  same.n.split = NULL,
  n.split.pts = NULL,
  N.crit = NULL,
  N.rel.crit = NULL,
  N.loc.crit = NULL,
  N.loc.rel.crit = NULL,
  S.crit = NULL,
  S.rel.crit = NULL,
  Q.crit = NULL,
  c.splits = NULL,
  c.Q.crit = NULL,
  c.crit.improv = NULL,
  c.X.knots = NULL,
  c.Y.knots = NULL,
  c.max.iter.no = NULL,
  c.fast.optim = NULL,
  c.corr.term = NULL,
  study.pol = NULL,
  use.chull = NULL,
  generalize.f = NULL,
  maximize = NULL,
  method = NULL,
  compare.f = NULL,
  .run.id = NULL,
  parallel = FALSE,
  RAM = NULL,
  load_prop = 0.8,
  chunk_size = workers * 2,
  workers = NULL,
  future_seed = TRUE
)

Arguments

obj	A hespdiv class object.
n.runs	Integer. The number of alternative hespdiv calls to evaluate.
data.paired	Logical. Controls whether alternative values of data are paired with corresponding elements of xy.dat.
display	Logical. Controls the value of the display argument in each hespdiv call.
images.path	Character or NULL. Path to an existing directory where PNG images of displayed results will be saved. If NULL (default), images are not saved.
pnts.col	Value passed to the pnts.col argument of each hespdiv call. Can be provided as atomic vector, vector or list of vectors.
data	A list of data objects (matrices, data frames, vectors, lists, or other supported data structures) used as alternative inputs for sensitivity analysis.
xy.dat, study.pol	Lists of data frames with two columns: x and y.
same.n.split, c.fast.optim, use.chull, c.splits	Logical vectors specifying alternative values for corresponding hespdiv arguments.
n.split.pts, c.max.iter.no, N.crit, N.loc.crit, c.X.knots, c.Y.knots	Integer vectors specifying alternative values for corresponding arguments.
N.rel.crit, N.loc.rel.crit, S.crit, S.rel.crit	Numeric vectors with values between 0 and 1.
Q.crit, c.Q.crit, c.crit.improv	Numeric vectors specifying alternative threshold or improvement criteria.
c.corr.term	Numeric vector with values between 0.01 and 0.2.
generalize.f, compare.f	Lists of functions defining custom similarity or generalization methods.
maximize	Logical vector of the same length as compare.f, indicating whether the corresponding similarity metric should be maximized.
method	Character vector specifying predefined similarity metrics.
.run.id	Integer. Runs with indices less than or equal to this value will be skipped. This can be used to resume an interrupted analysis.
parallel	Logical. If TRUE, runs are evaluated in parallel using future.apply. If FALSE (default), runs are evaluated sequentially.
RAM	Integer. Approximate amount of available RAM (in GB) used to limit the number of parallel workers when parallel = TRUE.
load_prop	Numeric in (0, 1]. Proportion of available CPU cores to use when determining the number of parallel workers automatically. Defaults to 0.8.
chunk_size	Integer. Number of runs submitted per batch (chunk) to the parallel backend when parallel = TRUE. Chunking does not change how many runs execute simultaneously (controlled by workers). Smaller values reduce the number of queued futures at once (often lowering RAM overhead). Defaults to workers*2.
workers	Integer. Number of parallel workers (CPU cores) to use when parallel = TRUE. At most this many hespdiv calls will be executed simultaneously. If NULL, the number of workers is determined automatically based on RAM and load_prop.
future_seed	Logical. Passed to future.apply::future_lapply(). If TRUE, RNG is managed by future to provide parallel-safe, reproducible random streams.

Details

Difference Between "hsa" and other sensitivity analysis functions

The hsa_detailed function evaluates all combinations of provided argument values, resulting in dense sampling of the parameter space at substantial computational cost. In contrast, hsa samples the parameter space stochastically and is generally more suitable for exploratory or large-scale sensitivity analyses.

In hsa_detailed, alternative argument values are provided as lists, whereas in hsa they are supplied as vectors or lists depending on the argument.

The hsa_sample_constrained function performs non-recursive hespdiv runs for each split-line produced based on different data subsamples. Thus, hsa is more general, as it allows to inspect sensitivity to other arguments.

Paired Arguments

When data.paired = TRUE, the same index is used to sample elements of data and xy.dat, allowing sensitivity analysis across datasets of differing size or composition. When FALSE, data and coordinates are sampled independently, enabling analyses based on noise addition or spatial shuffling.

Arguments defining custom methods (compare.f, generalize.f, maximize) are always treated as paired and must therefore have equal lengths.

Value

An object of class hsa, containing:

Alternatives

A list of alternative hespdiv results produced during the sensitivity analysis.

Basis

The reference hespdiv object whose arguments were perturbed.

Note

If a particular run produces a warning or an error, the corresponding list element will contain two components. In case of a warning, these are the resulting hespdiv object and the warning message. In case of an error, they are the arguments used for the call and the error message.

See Also

Other functions for hespdiv sensitivity analysis: change_base(), hsa_detailed(), hsa_quant(), hsa_sample_constrained(), plot_cs_hsa(), plot_hsa(), plot_hsa_q()

Other functions for hespdiv results post-processing: cross_comp(), hsa_detailed(), hsa_quant(), hsa_sample_constrained(), nulltest(), taxon_effect()

hespdiv documentation built on May 21, 2026, 5:09 p.m.