Skip to contents

Heatmap of taxa contributions across functions

Source: R/taxa_contribution_viz.R
taxa_contribution_heatmap.Rd

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.

Value

A ggplot2 or patchwork object.

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.

Examples

# \donttest{
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)
# }