% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hsa.R
\name{hsa}
\alias{hsa}
\title{HespDiv Sensitivity Analysis}
\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{
\item{obj}{A \code{hespdiv} class object.}

\item{n.runs}{Integer. The number of alternative \code{hespdiv} calls to evaluate.}

\item{data.paired}{Logical. Controls whether alternative values of \code{data}
are paired with corresponding elements of \code{xy.dat}.}

\item{display}{Logical. Controls the value of the \code{display} argument
in each \code{hespdiv} call.}

\item{images.path}{Character or \code{NULL}. Path to an existing directory
where PNG images of displayed results will be saved. If \code{NULL}
(default), images are not saved.}

\item{pnts.col}{Value passed to the \code{pnts.col} argument of each
\code{hespdiv} call. Can be provided as atomic vector,  vector or list of
vectors.}

\item{data}{A list of data objects (matrices, data frames, vectors, lists,
or other supported data structures) used as alternative inputs for
sensitivity analysis.}

\item{xy.dat, study.pol}{Lists of data frames with two columns: \code{x} and \code{y}.}

\item{same.n.split, c.fast.optim, use.chull, c.splits}{Logical vectors specifying
alternative values for corresponding \code{hespdiv} arguments.}

\item{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.}

\item{N.rel.crit, N.loc.rel.crit, S.crit, S.rel.crit}{Numeric vectors with values
between 0 and 1.}

\item{Q.crit, c.Q.crit, c.crit.improv}{Numeric vectors specifying alternative
threshold or improvement criteria.}

\item{c.corr.term}{Numeric vector with values between 0.01 and 0.2.}

\item{generalize.f, compare.f}{Lists of functions defining custom similarity
or generalization methods.}

\item{maximize}{Logical vector of the same length as \code{compare.f},
indicating whether the corresponding similarity metric should be maximized.}

\item{method}{Character vector specifying predefined similarity metrics.}

\item{.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.}

\item{parallel}{Logical. If \code{TRUE}, runs are evaluated in parallel using
\pkg{future.apply}. If \code{FALSE} (default), runs are evaluated sequentially.}

\item{RAM}{Integer. Approximate amount of available RAM (in GB) used to limit
the number of parallel workers when \code{parallel = TRUE}.}

\item{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.}

\item{chunk_size}{Integer. Number of runs submitted per batch (chunk) to the
parallel backend when \code{parallel = TRUE}. Chunking does not change how
many runs execute simultaneously (controlled by \code{workers}). Smaller
values reduce the number of queued futures at once (often lowering RAM
overhead). Defaults to \code{workers*2}.}

\item{workers}{Integer. Number of parallel workers (CPU cores) to use when
\code{parallel = TRUE}. At most this many \code{hespdiv} calls will be executed
simultaneously. If \code{NULL}, the number of workers is determined
automatically based on \code{RAM} and \code{load_prop}.}

\item{future_seed}{Logical. Passed to \code{future.apply::future_lapply()}.
If \code{TRUE}, RNG is managed by \pkg{future} to provide parallel-safe,
reproducible random streams.}
}
\value{
An object of class \code{hsa}, containing:
\describe{
\item{\bold{Alternatives}}{A list of alternative \code{hespdiv} results
produced during the sensitivity analysis.}
\item{\bold{Basis}}{The reference \code{hespdiv} object whose arguments
were perturbed.}
}
}
\description{
This function performs sensitivity analysis of the \code{hespdiv} method.
Starting from a reference \code{hespdiv} object, it generates a specified
number of alternative \code{hespdiv} calls by randomly sampling new values
for selected arguments from user-provided sets.
}
\details{
\subsection{Difference Between \code{"hsa"} and other sensitivity analysis functions}{
The \code{hsa_detailed} function evaluates all combinations of provided
argument values, resulting in dense sampling of the parameter space at
substantial computational cost. In contrast, \code{hsa} samples the parameter
space stochastically and is generally more suitable for exploratory or
large-scale sensitivity analyses.

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

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

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

Arguments defining custom methods (\code{compare.f}, \code{generalize.f},
\code{maximize}) are always treated as paired and must therefore have
equal lengths.
}
}
\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 \code{hespdiv} object and the warning message. In case of an error,
they are the arguments used for the call and the error message.
}
\seealso{
Other functions for hespdiv sensitivity analysis: 
\code{\link{change_base}()},
\code{\link{hsa_detailed}()},
\code{\link{hsa_quant}()},
\code{\link{hsa_sample_constrained}()},
\code{\link{plot_cs_hsa}()},
\code{\link{plot_hsa}()},
\code{\link{plot_hsa_q}()}

Other functions for hespdiv results post-processing: 
\code{\link{cross_comp}()},
\code{\link{hsa_detailed}()},
\code{\link{hsa_quant}()},
\code{\link{hsa_sample_constrained}()},
\code{\link{nulltest}()},
\code{\link{taxon_effect}()}
}
\concept{functions for hespdiv results post-processing}
\concept{functions for hespdiv sensitivity analysis}
