hsa_detailed: Detailed HespDiv Sensitivity Analysis

In hespdiv: Hierarchical Spatial Data Subdivision into Topologically Contiguous Units

Detailed HespDiv Sensitivity Analysis

Description

This function is one of the two that perform HespDiv sensitivity analysis. It creates and evaluates alternative hespdiv calls, according to the desired changes in method, data and other subdivision criteria arguments. As a result, it returns alternative hespdiv objects that can be directly compared with the original hespdiv object and with each other using plot.hsa and hsa_quant functions.

Usage

hsa_detailed(
  obj,
  comb.args = TRUE,
  pick.n.args = NULL,
  comb.type = NULL,
  n.combs = NULL,
  display = TRUE,
  images.path = NULL,
  paired = 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
)

Arguments

obj	An object of hespdiv class. The base object whose call will be modified to produce alternative hespdiv objects.
comb.args	A Boolean value. Do you want to combine the provided argument values to make alternative hespdiv calls? If not, then at once only one argument will be modified, trying all provided values for it one by one.
pick.n.args	A numeric vector that controls how many arguments would you like to change at once in hespdiv runs. Multiple values allowed.
comb.type	A character determining how combinations of argument values are selected. Possible values: "all", "random", or "handpicked".
n.combs	An integer controlling how many argument value combinations should be randomly selected from all possible combinations when comb.type is "random".
display	A Boolean value. The value of the "display" argument in each hespdiv call.
images.path	A path to an existing directory where PNG images of the displayed results will be saved. If NULL (default), images won't be saved.
paired	Logical. Are the provided data and xy.dat arguments paired?
pnts.col	The value of the "pnts.col" argument in each hespdiv call.
data	A list containing matrices, time-series, lists, data frames, vectors, or other data structures.
xy.dat, study.pol	Lists of coordinate data frames. Each data frame must contain two columns named x and y.
same.n.split, c.fast.optim, use.chull, c.splits	Lists with a Boolean value (if used, should be different from the one in the basal hespdiv call).
n.split.pts, c.max.iter.no, N.crit, N.loc.crit, c.X.knots, c.Y.knots	Lists with integer values.
N.rel.crit, N.loc.rel.crit, S.crit, S.rel.crit	Lists with values between 0 and 1.
Q.crit, c.Q.crit, c.crit.improv	Lists of numeric values.
c.corr.term	A list of numeric values between 0.01 and 0.2.
generalize.f, compare.f	Lists of functions.
maximize	A list of logical values with the same length as the compare.f list.
method	A list of character values.

Details

Difference Between "hsa" And "hsa_detailed"

The major difference between "hsa_detailed" and "hsa" is that the former produces all possible hespdiv calls from combinations of the provided hespdiv arguments. Therefore, it samples a much smaller segment of the parameter space but more densely, requiring much more computation time. Although such behavior may be desired in some cases, the "hsa" function is generally more suitable for performing hespdiv sensitivity analysis.

Additionally, alternative values for hespdiv arguments in the "hsa_detailed" function are provided in lists, whereas in the "hsa" function, they are provided in vectors or lists (depending on the argument).

Internally Set Default Argument Values

When comb.args is TRUE, the default value of comb.type is "all".

When comb.args is TRUE and pick.n.args is NULL (default), the value of pick.n.args will be changed to a vector 1:N, where N is the maximum possible value of pick.n.args. The maximum possible value for pick.n.args depends on the hespdiv arguments provided. Each hespdiv argument that influences the results is counted as one, except for "data" and "xy.dat" when paired is TRUE, and all four arguments ("method", "compare.f", "generalize.f", and "maximize") that define the subdivision method, as the pair/group of them is counted as one. Therefore, N can vary from 1 (single argument provided) to 22 (all arguments provided and paired is FALSE). If comb.args is FALSE, then pick.n.args should be NULL. Using pick.n.args = 1 is the same as setting comb.type to FALSE.

Paired Arguments

If paired is TRUE, the "data" and "xy.dat" elements with the same index are treated as one value of the same argument. Therefore, the provided lists of "data" and "xy.dat" should be of the same length. Pairing of "data" and "xy.dat" can be useful, for example, when you want to re-run hespdiv after adding or removing some observations (these changes should be made in both "xy.dat" and "data") to test how hespdiv results are influenced by some extra observations or the number of observations in general. When paired is FALSE, the number of observations in "data" and "xy.dat" must be the same as it was in the call of the base hespdiv object. This option allows you to re-run hespdiv after adding some noise to the object features (via changes in "data") or coordinates (via changes in "xy.dat") to test how hespdiv results are influenced by the data itself or localization.

By default, arguments determining the custom method ("compare.f", "generalize.f", "maximize") are paired, similar to how "data" and "xy.dat" are paired when paired is TRUE. Thus, the lists of "compare.f", "generalize.f", and "maximize" should be of the same length.

Value

An object of class hsa. The object is a list with two elements:

Alternatives

A list containing the alternative hespdiv objects produced by the sensitivity analysis.

Basis

The original hespdiv object whose call was modified to produce the alternative subdivisions.

Note

Use "pnts.col" of length >1 only when the number of observations does not change.

If a particular call produced a warning or error, then a list of length 2 will be returned for that call. If a warning was produced, then the first element of the list will hold the created hespdiv object, and the second element will contain the warning message. In the case of an error, the first element will be a list of arguments used to produce the call, and the second element will contain the error message.

Author(s)

Liudas Daumantas

See Also

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

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

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