% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/taxa_contribution.R
\name{aggregate_taxa_contributions}
\alias{aggregate_taxa_contributions}
\title{Aggregate taxa contributions for visualization}
\usage{
aggregate_taxa_contributions(
  contrib_data,
  taxonomy = NULL,
  tax_level = "Genus",
  top_n = 10,
  daa_results_df = NULL,
  pathway_ids = NULL,
  p_threshold = 0.05
)
}
\arguments{
\item{contrib_data}{A data.frame from \code{\link{read_contrib_file}} or
\code{\link{read_strat_file}}.}

\item{taxonomy}{Optional data.frame mapping taxon IDs to taxonomy. Supports
QIIME2 format (semicolon-delimited taxonomy strings) or DADA2 format
(separate columns for each rank).}

\item{tax_level}{Character. Taxonomic rank for aggregation. One of
\code{"Kingdom"}, \code{"Phylum"}, \code{"Class"}, \code{"Order"},
\code{"Family"}, \code{"Genus"}, \code{"Species"}. Default \code{"Genus"}.}

\item{top_n}{Integer. Number of top taxa to keep; remaining are lumped as
"Other". Default 10.}

\item{daa_results_df}{Optional data.frame from \code{\link{pathway_daa}},
used to filter contributions to significant pathways.}

\item{pathway_ids}{Optional character vector of pathway IDs to filter.
Alternative to \code{daa_results_df}.}

\item{p_threshold}{Numeric. Significance cutoff when using
\code{daa_results_df}. Default 0.05.}
}
\value{
A tidy data.frame with columns: \code{sample}, \code{function_id},
  \code{taxon_label}, \code{contribution}.
}
\description{
Core aggregation function that bridges PICRUSt2 contribution data with
differential abundance analysis results. Optionally maps ASV/OTU IDs to
taxonomic names and filters to significant pathways.
}
\details{
When \code{daa_results_df} is provided, the function:
\enumerate{
  \item Extracts significant pathway IDs from the DAA results
  \item Maps pathway IDs to their constituent KO IDs using the internal
    ko_to_kegg reference
  \item Filters contribution data to only matching KO IDs
}

Taxonomy can be provided in two formats:
\itemize{
  \item QIIME2: A column named \code{Taxon} or \code{taxonomy} containing
    semicolon-delimited strings (e.g., "k__Bacteria;p__Firmicutes;...")
  \item DADA2: Separate columns for each rank (\code{Kingdom}, \code{Phylum}, etc.)
}
}
\examples{
\donttest{
# Basic usage with synthetic data
contrib <- data.frame(
  sample = rep(c("S1", "S2"), each = 6),
  function_id = rep(c("K00001", "K00002", "K00003"), 4),
  taxon = rep(c("ASV1", "ASV2"), each = 3, times = 2),
  taxon_function_abun = runif(12),
  norm_taxon_function_contrib = runif(12)
)
agg <- aggregate_taxa_contributions(contrib, top_n = 2)
head(agg)
}

}
