% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hsa_sample_constrained.R
\name{hsa_sample_constrained}
\alias{hsa_sample_constrained}
\title{Constrained HespDiv Sensitivity Analysis by Subsampling}
\usage{
hsa_sample_constrained(
  obj,
  n.runs = 100,
  subsample_factor = 0.7,
  RAM = NULL,
  load_prop = NULL,
  chunk_size = 8,
  workers = NULL
)
}
\arguments{
\item{obj}{A \code{hespdiv} object.}

\item{n.runs}{Integer. The number of subsampling runs to perform (default: 100).}

\item{subsample_factor}{Numeric proportion of data to subsample within each polygon (0 to 1].
For example, 0.7 means 70\% of the data in each polygon are retained.}

\item{RAM}{Integer. Approximate amount of RAM in GB to guide how many parallel
workers to use. The function uses up to 80\\% of your available CPU cores
but also caps the number of workers at \code{RAM}.}

\item{load_prop}{Numeric value (0,1]. Specifies the proportion of available
CPU cores or RAM to be used for setting up parallel workers. For example,
\code{load_prop = 0.8} uses 80\% of the available resources. If both
\code{load_prop} and \code{RAM} are provided, the number of workers will
be the minimum based on the constraints imposed by both. Defaults to
\code{0.8} if not provided.}

\item{chunk_size}{Integer. Number of runs submitted per batch. Parallelism is
controlled by \code{workers}; chunking mainly controls memory/queue size.}

\item{workers}{A number of parrallel workers. Determines the number of hespdiv runs to be processed in parallel.}
}
\value{
A \code{hsa_constrained} class object, a list with two elements:
\itemize{
\item \strong{Alternatives}
A named list corresponding to each polygon where each entry is another
list of \code{hespdiv} results for each subsample run.

\item \strong{Basis}
The original \code{hespdiv} object (\code{obj}).
}
}
\description{
Conduct a constrained sensitivity analysis on a \code{hespdiv} object by
repeatedly subsampling observations within each polygon. Each subsample
is used to call \code{hespdiv} with recursion disabled (i.e., single-split only).
}
\details{
For each polygon in the \code{hespdiv} object, this function draws \code{subsample_factor}
of the data (by default 70\%), creating multiple random subsamples (\code{n.runs}).
These are processed in chunks (as given by \code{chunk_size}) and runs in each chunk being
parallelized to manage memory usage.
}
\seealso{
\code{\link{hespdiv}} for details on the main function.
\CRANpkg{future.apply}

Other functions for hespdiv sensitivity analysis: 
\code{\link{change_base}()},
\code{\link{hsa}()},
\code{\link{hsa_detailed}()},
\code{\link{hsa_quant}()},
\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_detailed}()},
\code{\link{hsa_quant}()},
\code{\link{nulltest}()},
\code{\link{taxon_effect}()}
}
\concept{functions for hespdiv results post-processing}
\concept{functions for hespdiv sensitivity analysis}
