taxa_contribution_heatmap: Heatmap of taxa contributions across functions

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

Heatmap of taxa contributions across functions

Description

Creates a heatmap showing mean taxa contributions across pathways/functions, with optional clustering and pathway annotations.

Usage

taxa_contribution_heatmap(
  contrib_agg,
  annotation_data = NULL,
  n_functions = 20,
  cluster_rows = TRUE,
  cluster_cols = TRUE,
  clustering_method = "complete",
  clustering_distance = "euclidean",
  low_color = "#f7f7f7",
  high_color = "#ca0020",
  font_size = 12,
  dendro_line_size = 0.5,
  custom_title = NULL
)

Arguments

contrib_agg	A data.frame from aggregate_taxa_contributions.
annotation_data	Optional data.frame from pathway_annotation for replacing function IDs with readable descriptions. It must contain either feature/description or pathway/pathway_name columns.
n_functions	Integer. Number of functions to include. Default 20.
cluster_rows	Logical. Cluster rows (taxa)? Default TRUE.
cluster_cols	Logical. Cluster columns (functions)? Default TRUE.
clustering_method	Character. Method for hclust. Default "complete". Ward methods require clustering_distance = "euclidean".
clustering_distance	Character. Distance metric. Default "euclidean". Supported values are "euclidean", "maximum", "manhattan", "canberra", "binary", and "minkowski".
low_color	Character. Color for low values. Default "#f7f7f7".
high_color	Character. Color for high values. Default "#ca0020".
font_size	Numeric. Base font size. Default 12.
dendro_line_size	Numeric. Dendrogram line width. Default 0.5.
custom_title	Optional 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. PICRUSt2 contribution outputs are sparse; combinations absent from contrib_agg are treated as zero when computing mean contribution across samples. If annotation_data contains multiple non-empty labels for the same plotted function ID, the function errors instead of silently choosing one label. Repeated rows with the same ID and same label are allowed, and label whitespace is normalized before comparison and display.

Value

A ggplot2 or patchwork object.

Examples

agg <- data.frame(
  sample = rep(c("S1", "S2"), each = 6),
  function_id = rep(rep(c("K00001", "K00002", "K00003"), each = 2), 2),
  taxon_label = rep(c("Genus_A", "Genus_B"), 6),
  contribution = runif(12)
)
p <- taxa_contribution_heatmap(agg)

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