% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/loadMicrobiomeData.R
\name{loadMicrobiomeData}
\alias{loadMicrobiomeData}
\title{Load and Normalize Microbiome Taxa Table Data}
\usage{
loadMicrobiomeData(
  taxa_table,
  col_data = NULL,
  normalization = c("CLR", "TSS"),
  pseudocount = 0.5,
  min_prevalence = 0.1
)
}
\arguments{
\item{taxa_table}{A \code{matrix} of non-negative integer counts.
Expected orientation: taxa in \strong{rows}, samples in
\strong{columns} (Bioconductor convention). If samples appear to
be in rows (more rows than columns and row names suggest samples),
the matrix is transposed with a warning.}

\item{col_data}{An optional \code{data.frame} or \code{DataFrame}
of sample-level metadata. Row names must match the column names of
\code{taxa_table}. Default: \code{NULL}.}

\item{normalization}{A \code{character(1)}, either \code{"CLR"}
(centered log-ratio, default) or \code{"TSS"} (total sum scaling).}

\item{pseudocount}{A positive \code{numeric(1)} pseudocount added to
all counts before log-transformation (CLR only). Default: \code{0.5}.}

\item{min_prevalence}{A \code{numeric(1)} in \code{[0, 1]}. Taxa
present in fewer than this fraction of samples are removed.
Default: \code{0.1} (remove taxa in fewer than 10\% of samples).}
}
\value{
A \code{SummarizedExperiment} with two assays:
  \describe{
    \item{\code{"counts"}}{Raw integer count matrix (taxa x samples).}
    \item{\code{"CLR"} or \code{"TSS"}}{Normalized values.}
  }
}
\description{
Imports a microbiome taxa count table and applies either centered
log-ratio (CLR) or total sum scaling (TSS) normalization. The result
is a \code{SummarizedExperiment} with both raw counts and normalized
values stored as named assays.
}
\details{
Microbiome data is \strong{compositional}: only relative abundances
are observed, not absolute counts. Treating compositional data with
standard correlation or distance measures leads to spurious results
(the Aitchison problem). MultiOmicsBridge applies one of two
microbiome-appropriate normalizations:

\describe{
  \item{CLR (default)}{The centered log-ratio transformation:
    \deqn{clr(x_j) = \log(x_j + \delta) - \frac{1}{D}
      \sum_{k=1}^{D} \log(x_k + \delta)}
    where \eqn{\delta} is the pseudocount and the sum is over all
    \eqn{D} taxa. CLR maps compositional data to real space and removes
    the unit-sum constraint, enabling Euclidean geometry.}
  \item{TSS}{Total sum scaling divides each sample by its library
    size, producing relative abundances (proportions). Simpler but
    retains the compositional constraint.}
}

Zero counts are handled by adding a small pseudocount before
log-transformation; the default pseudocount of 0.5 is a conservative
choice appropriate for sparse 16S data.
}
\examples{
set.seed(42)
n_taxa    <- 80
n_samples <- 20
taxa_table <- matrix(rpois(n_taxa * n_samples, lambda = 30),
                     nrow = n_taxa, ncol = n_samples)
rownames(taxa_table) <- paste0("Taxon", seq_len(n_taxa))
colnames(taxa_table) <- paste0("Sample", seq_len(n_samples))

mb_se <- loadMicrobiomeData(taxa_table, normalization = "CLR")
mb_se
SummarizedExperiment::assayNames(mb_se)

}
\seealso{
\code{\link{loadHostData}}, \code{\link{matchSamples}},
  \code{\link{MultiOmicsBridgeAnalysis}}
}
