% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rarefy.r
\name{rarefy}
\alias{rarefy}
\title{Rarefy Counts to a Constant Depth}
\usage{
rarefy(
  biom,
  depth = NULL,
  seed = 0L,
  inflate = FALSE,
  clone = TRUE,
  cpus = n_cpus()
)
}
\arguments{
\item{biom}{An \link[=rbiom_objects]{rbiom object}, or any value accepted by \code{\link[=as_rbiom]{as_rbiom()}}.}

\item{depth}{The number of observations to keep per sample. Must be an
integer greater than 0.
\itemize{
\item If \code{NULL} (the default), a depth is automatically selected
that retains at least 10\% of the dataset's total abundance
while maximizing the number of samples kept. See
\code{\link[=suggest_rarefy_depth]{suggest_rarefy_depth()}} for the specific heuristic used.
\item Samples with total counts less than \code{depth} will be
dropped from the result.
}}

\item{seed}{Random seed for permutations. Must be a non-negative integer.
Default: \code{0}}

\item{inflate}{Logical. Handling for non-integer data (e.g. relative abundances).
\itemize{
\item \code{FALSE} (Default): The function will error if non-integers are detected.
Rarefaction requires discrete counts (integers).
\item \code{TRUE}: The function will automatically rescale (inflate)
non-integers to integers using \code{\link[=biom_inflate]{biom_inflate()}} before rarefying.
This is useful for 'shoehorning' metagenomic relative abundance
data into diversity functions that strictly require integers.
}}

\item{clone}{Create a copy of \code{biom} before modifying. If \code{FALSE}, \code{biom}
is modified in place as a side-effect. See \link[=speed]{speed ups} for
use cases. Default: \code{TRUE}}

\item{cpus}{The number of CPUs to use. Set to \code{NULL} to use all available,
or to \code{1} to disable parallel processing. Default: \code{NULL}}
}
\value{
An \link[=rbiom_objects]{rbiom object}.
}
\description{
This function reduces the number of observations (reads) in each sample to
a fixed integer value (\code{depth}). Samples with fewer observations than the
specified depth are discarded.

Rarefaction is a common technique in microbiome analysis used to account for
uneven sequencing effort across samples. By standardizing the library size,
it allows for fair comparisons of alpha and beta diversity metrics.
}
\details{
Normalizes the library sizes of a dataset by randomly sub-sampling
observations from each sample to a specific depth.
}
\examples{
    library(rbiom)
    
    biom <- hmp50[1:5]
    sample_sums(biom)
    
    # Rarefy to the lowest sample depth 
    # (All samples are kept, but counts are reduced)
    biom_rare <- rarefy(biom, depth = min(sample_sums(biom)))
    sample_sums(biom_rare)
    
    # Auto-select depth (may drop samples with low coverage)
    biom_auto <- rarefy(biom)
    sample_sums(biom_auto)

}
\seealso{
\code{\link[=suggest_rarefy_depth]{suggest_rarefy_depth()}} for details on the default depth selection.

Other transformations: 
\code{\link{biom_inflate}()},
\code{\link{biom_relativize}()},
\code{\link{biom_rescale}()},
\code{\link{modify_metadata}},
\code{\link{slice_metadata}},
\code{\link{subset}()},
\code{\link{with}()}
}
\concept{transformations}
