% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/detailed_hsa.R
\name{hsa_detailed}
\alias{hsa_detailed}
\title{Detailed HespDiv Sensitivity Analysis}
\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{
\item{obj}{An object of hespdiv class. The base object whose call will be
modified to produce alternative hespdiv objects.}

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

\item{pick.n.args}{A numeric vector that controls how many arguments would
you like to change at once in hespdiv runs. Multiple values allowed.}

\item{comb.type}{A character determining how combinations of argument values
are selected. Possible values: "all", "random", or "handpicked".}

\item{n.combs}{An integer controlling how many argument value combinations
should be randomly selected from all possible combinations when comb.type
is "random".}

\item{display}{A Boolean value. The value of the "display" argument in each
hespdiv call.}

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

\item{paired}{Logical. Are the provided \code{data} and \code{xy.dat}
arguments paired?}

\item{pnts.col}{The value of the "pnts.col" argument in each hespdiv call.}

\item{data}{A list containing matrices, time-series, lists, data frames,
vectors, or other data structures.}

\item{xy.dat, study.pol}{Lists of coordinate data frames. Each data frame
must contain two columns named \code{x} and \code{y}.}

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

\item{n.split.pts, c.max.iter.no, N.crit, N.loc.crit, c.X.knots, c.Y.knots}{Lists with integer values.}

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

\item{Q.crit, c.Q.crit, c.crit.improv}{Lists of numeric values.}

\item{c.corr.term}{A list of numeric values between 0.01 and 0.2.}

\item{generalize.f, compare.f}{Lists of functions.}

\item{maximize}{A list of logical values with the same length as the
\code{compare.f} list.}

\item{method}{A list of character values.}
}
\value{
An object of class \code{hsa}. The object is a list with two elements:
\describe{
\item{\code{Alternatives}}{A list containing the alternative
\code{hespdiv} objects produced by the sensitivity analysis.}
\item{\code{Basis}}{The original \code{hespdiv} object whose call was
modified to produce the alternative subdivisions.}
}
}
\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 \code{plot.hsa} and
\code{hsa_quant} functions.
}
\details{
\subsection{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).
}
\subsection{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.
}
\subsection{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.
}
}
\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.
}
\seealso{
Other functions for hespdiv sensitivity analysis: 
\code{\link{change_base}()},
\code{\link{hsa}()},
\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}()},
\code{\link{hsa_quant}()},
\code{\link{hsa_sample_constrained}()},
\code{\link{nulltest}()},
\code{\link{taxon_effect}()}
}
\author{
Liudas Daumantas
}
\concept{functions for hespdiv results post-processing}
\concept{functions for hespdiv sensitivity analysis}
