% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rarefy.r
\name{biom_inflate}
\alias{biom_inflate}
\title{Inflate Relative Abundances to Integer Counts}
\usage{
biom_inflate(biom, depth = NULL, clone = TRUE)
}
\arguments{
\item{biom}{An \link[=rbiom_objects]{rbiom object}, or any value accepted by \code{\link[=as_rbiom]{as_rbiom()}}.}

\item{depth}{The target library size (sum) for each sample. Must be an
integer greater than 0. If \code{NULL} (the default), the depth is
estimated per-sample using the "Singleton Peak Heuristic". See
\code{\link[=suggest_inflate_depths]{suggest_inflate_depths()}} for algorithm details.}

\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}}
}
\value{
An \link[=rbiom_objects]{rbiom object}.
}
\description{
Scaling a matrix of proportions (or counts) to a new target depth,
rounding to integers while preserving the original total abundance sum
exactly.
}
\section{Rounding (Largest Remainder Method)}{


To ensure the sum of the resulting counts equals the target \code{depth} exactly
(avoiding drift caused by simple rounding), this function uses the Largest
Remainder Method (also known as the Hare-Niemeyer method).

It assigns the integer part of the scaled value to each feature, and then
distributes the remaining counts to the features with the largest fractional
parts.
}

\examples{
    library(rbiom)
    
    biom <- hmp50[1:5]
    sample_sums(biom)
    
    biom <- biom_relativize(biom)
    sample_sums(biom)
    
    biom <- biom_inflate(biom)
    sample_sums(biom)

}
\seealso{
\code{\link[=suggest_inflate_depths]{suggest_inflate_depths()}} for details on how target depths are
estimated when \code{depth = NULL}.

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