pathway_errorbar_table: Generate Abundance Statistics Table for Pathway Analysis

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

Generate Abundance Statistics Table for Pathway Analysis

Description

This function generates a table containing mean relative abundance, standard deviation, and log2 fold change statistics for pathways, similar to the data used in pathway_errorbar plots but returned as a data frame instead of a plot.

Usage

pathway_errorbar_table(
  abundance,
  daa_results_df,
  Group,
  ko_to_kegg = FALSE,
  p_values_threshold = 0.05,
  select = NULL,
  max_features = 30,
  metadata = NULL,
  sample_col = NULL
)

Arguments

abundance	A data frame or matrix containing predicted functional pathway abundance, with pathways/features as rows and samples as columns. Data frames may also provide a leading non-numeric feature ID column (for example #NAME, feature, or pathway); it is converted to row names before sample alignment or Group length validation. The column names should match the sample names in metadata.
daa_results_df	A data frame containing differential abundance analysis results from pathway_daa function. Must contain columns: feature, group1, group2, p_adjust. Within the selected method and group pair, feature identifiers must be unique.
Group	A vector containing group assignments for each sample in the same order as the columns in abundance matrix. Alternatively, if metadata is provided, this should match the order of samples in metadata. Values must be non-missing and non-empty after alignment, and must include the selected DAA result's group1 and group2 labels. Without metadata, a vector named with sample IDs is aligned to abundance columns. Prefer this to an unchecked unnamed vector.
ko_to_kegg	Logical value indicating whether to use KO to KEGG conversion. Default is FALSE.
p_values_threshold	Numeric value for p-value threshold to filter significant features. Default is 0.05. Must be in the range (0, 1].
select	Character vector of specific features to include. If NULL, all significant features are included.
max_features	Maximum number of features to include in the table. Default is 30.
metadata	Optional data frame containing sample metadata. If provided, the Group vector will be reordered to match the abundance column order.
sample_col	Character string specifying the column name in metadata that contains sample identifiers. Default is NULL, which triggers auto-detection via the same logic used by pathway_daa() (common names like "sample", "Sample", "sample_id", "sample_name", or metadata rownames).

Details

Relative abundances use all supplied feature rows as each sample's denominator. Filtering the input matrix first changes the summaries. The table's log2 fold change is a descriptive group-mean ratio with a pseudocount, not a covariate-adjusted DAA model coefficient.

Value

A data frame containing the following columns:

• feature: Feature/pathway identifier

• group1: Reference group name

• group2: Comparison group name

• mean_rel_abundance_group1: Mean relative abundance for group1

• sd_rel_abundance_group1: Standard deviation of relative abundance for group1

• mean_rel_abundance_group2: Mean relative abundance for group2

• sd_rel_abundance_group2: Standard deviation of relative abundance for group2

• log2_fold_change: Log2 fold change (group2/group1)

• p_adjust: Adjusted p-value from differential analysis

• Additional annotation columns (e.g., description, pathway_name, pathway_class) if present in the input daa_results_df

Examples

## Not run: 
# Load example data
data("ko_abundance")
data("metadata")

# Convert KO abundance to KEGG pathways
kegg_abundance <- ko2kegg_abundance(data = ko_abundance)

# Perform differential abundance analysis
daa_results_df <- pathway_daa(
  abundance = kegg_abundance,
  metadata = metadata,
  group = "Environment",
  daa_method = "LinDA"
)

# Annotate results
daa_annotated_results_df <- pathway_annotation(
  pathway = "KO",
  daa_results_df = daa_results_df,
  ko_to_kegg = TRUE
)

# Generate abundance statistics table
abundance_stats_table <- pathway_errorbar_table(
  abundance = kegg_abundance,
  daa_results_df = daa_annotated_results_df,
  Group = setNames(metadata$Environment, metadata$sample_name),
  ko_to_kegg = TRUE,
  p_values_threshold = 0.05
)

# View the results
head(abundance_stats_table)

## End(Not run)

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