taxa_contribution_bar: Stacked bar plot of taxa contributions

In ggpicrust2: Make 'PICRUSt2' Output Analysis and Visualization Easier

Stacked bar plot of taxa contributions

Description

Creates a stacked bar plot showing taxa contributions to predicted functional abundances, faceted by function or sample group.

Usage

taxa_contribution_bar(
  contrib_agg,
  metadata,
  group,
  function_ids = NULL,
  n_functions = 6,
  facet_by = "function",
  show_percentage = TRUE,
  color_theme = "default",
  font_size = 12,
  legend_position = "right",
  custom_title = NULL
)

Arguments

contrib_agg	A data.frame from aggregate_taxa_contributions.
metadata	A data.frame containing sample metadata.
group	Character. Column name in metadata for grouping samples.
function_ids	Optional character vector of function IDs to plot. If NULL (default), the top n_functions by between-sample variance in total contribution are shown. Single-sample inputs are ranked by total contribution because variance is undefined. Facets preserve this ranking or the order of explicitly supplied IDs.
n_functions	Integer. Number of functions to show when function_ids is NULL. Default 6.
facet_by	Character. Facet by "function" (default) or "group".
show_percentage	Logical. Normalize bars to 100%? Default TRUE.
color_theme	Character. Color theme name, passed to get_color_theme. Default "default".
font_size	Numeric. Base font size. Default 12.
legend_position	Character. Legend position. Default "right".
custom_title	Optional character string for the plot title.

Details

The sample, function_id, and taxon_label columns must contain non-empty values without NA. These columns define plotting and aggregation groups, so missing identifiers would otherwise be dropped by R aggregation or shown as unlabeled categories. When show_percentage = TRUE, every plotted sample/function combination must have a positive total contribution. Relative percentages are undefined for zero-total combinations; use show_percentage = FALSE to display absolute zero contributions.

Value

A ggplot2 object.

Examples

# Synthetic example
agg <- expand.grid(
  sample = c("S1", "S2", "S3", "S4"),
  function_id = c("K00001", "K00002"),
  taxon_label = c("Genus_A", "Genus_B", "Other"),
  stringsAsFactors = FALSE
)
agg$contribution <- runif(nrow(agg))
metadata <- data.frame(
  sample = c("S1", "S2", "S3", "S4"),
  group = c("Control", "Control", "Treatment", "Treatment")
)
p <- taxa_contribution_bar(agg, metadata, group = "group")

ggpicrust2 documentation built on Oct. 7, 2026, 1:07 a.m.