% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/add_rarefaction_metrics.R
\name{add_rarefaction_metrics}
\alias{add_rarefaction_metrics}
\title{Calculate and append pre-rarefaction statistics to microbiome data}
\usage{
add_rarefaction_metrics(data)
}
\arguments{
\item{data}{A \code{phyloseq} object or a \code{data.frame} with samples
as rows and taxa as columns.}
}
\value{
The same object (\code{phyloseq} or \code{data.frame}) with new
columns:
\itemize{
\item \code{read_num}
\item \code{singleton_num}
\item \code{goods_cov}
\item \code{outlier}
}
}
\description{
This function adds read count, singleton count, Good's coverage,
and marks outlier samples to a \code{phyloseq} object or \code{data.frame}
based on the OTU/ASV abundance table.
}
\details{
About Good's coverage. Initially developed by Alan
Turing and I.J. Good during their cryptographic analyses in
World War II, it was later adopted by ecologists, particularly
in microbial diversity studies, to assess the completeness of
a sample's representation of the overall community.
It's calculated as \code{1 - (F1/N)}, where \code{F1} is the number of
OTUs (Operational Taxonomic Units) represented by only one
individual (singletons) and \code{N} is the total number of
individuals in the sample. For example, a Good's coverage of
0.95, means that 5\% of the reads in that sample are from OTUs
that appear only once.
}
\examples{
library(phyloseq)
library(BRCore)

# Adding metrics to a "phyloseq" object
bcse_metrics <- add_rarefaction_metrics(data = bcse)
sample_data(bcse_metrics)|>
head(10)


# Adding metrics to a "data.frame" count table object
bcse_otutable <- as.data.frame(
  as.matrix(otu_table(bcse))
)

bcse_otutable_metrics <- add_rarefaction_metrics(
  data = bcse_otutable
)
bcse_otutable_metrics[
  head(seq_len(nrow(bcse_otutable_metrics)), 10),
  tail(seq_len(ncol(bcse_otutable_metrics)), 20)
]


}
\seealso{
\code{\link[=plot_rarefaction_metrics]{plot_rarefaction_metrics()}} for visualizing these metrics, and
\code{\link[=multi_rarefy]{multi_rarefy()}} for performing rarefaction on a \code{phyloseq} object.
}
