Generate Abundance Statistics Table for Pathway Analysis — pathway_errorbar

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).

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

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.

Examples

if (FALSE) { # \dontrun{
# 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)
} # }