% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rarefy.r
\name{suggest_rarefy_depth}
\alias{suggest_rarefy_depth}
\title{Suggest Rarefaction Depth}
\usage{
suggest_rarefy_depth(biom)
}
\arguments{
\item{biom}{An \link[=rbiom_objects]{rbiom object}, or any value accepted by \code{\link[=as_rbiom]{as_rbiom()}}.}
}
\value{
A single integer representing the suggested rarefaction depth.
}
\description{
Calculates a rarefaction depth that balances retaining samples against
retaining total observations.
}
\section{Heuristic}{

This function selects a depth by analyzing the trade-off between dropping
samples (to increase depth) and lowering depth (to keep samples).
\enumerate{
\item \strong{Calculate Yields:} For every distinct sample depth in the dataset,
calculate the total number of observations that would remain if the
dataset were rarefied to that level.
\deqn{Yield_d = d \times N_{\ge d}}
Where \eqn{d} is the depth and \eqn{N_{\ge d}} is the number of samples
with at least that many reads.
\item \strong{Define Threshold:} Calculate 10\% of the total observations in the
original un-rarefied dataset.
\item \strong{Select Depth:} Find the \strong{lowest} depth \eqn{d} where the \eqn{Yield_d}
exceeds this 10\% threshold.
}

This approach prioritizes keeping as many samples as possible, provided that
doing so doesn't discard more than 90\% of the dataset's total information.
}

\examples{
    library(rbiom)
    
    suggest_rarefy_depth(hmp50)

}
\seealso{
\code{\link[=rarefy]{rarefy()}} which uses this heuristic when \code{depth = NULL}.
}
