compare_metagenome_results: Compare Metagenome Results

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

Compare Metagenome Results

Description

Compare Metagenome Results

Usage

compare_metagenome_results(
  metagenomes,
  names,
  daa_method = "ALDEx2",
  p_adjust_method = "BH",
  reference = NULL,
  p.adjust = NULL,
  correlation_permutations = 999,
  correlation_seed = 123,
  correlation_p_adjust_method = "BH"
)

Arguments

metagenomes	A list of metagenome matrices with rows as KOs and columns as samples. Each matrix must have unique, non-empty feature row names and sample column names, and finite non-negative numeric abundance values. Each matrix in the list should correspond to a different metagenome.
names	A unique, non-empty character vector of names for the metagenomes in the same order as in the 'metagenomes' list.
daa_method	Character. Paired differential abundance method. Choices are "ALDEx2" (paired ALDEx2 t and Wilcoxon tests) or "paired Wilcoxon" (paired Wilcoxon signed-rank tests on sample-wise relative abundances). Methods that model the metagenomes as independent groups are not supported because all matrices represent the same aligned biological samples.
p_adjust_method	A character specifying the method for p-value adjustment. Possible choices are: "BH" (Benjamini-Hochberg), "holm", "bonferroni", "hochberg", "fdr", and "none". The default is "BH".
reference	Optional metagenome name used as the first group in pairwise DAA comparisons. Other metagenome pairs are still compared.
p.adjust	Deprecated alias for p_adjust_method. Do not supply both parameters with different values.
correlation_permutations	Non-negative integer. Number of joint sample-label permutations used to test the median per-feature Spearman correlation. Use 0 to skip correlation p-values. Default 999.
correlation_seed	Non-negative integer used to generate correlation permutations reproducibly. The caller's random-number state is restored.
correlation_p_adjust_method	P-value adjustment method for the unique off-diagonal metagenome correlation tests. Default "BH".

Details

Metagenome matrices are aligned to the same sample identifiers. Each DAA comparison uses the feature intersection for that pair, so an unrelated third metagenome cannot remove testable features from the pair. Correlations use the feature intersection across all metagenomes so every matrix entry is based on the same feature universe. Because each matrix measures the same biological samples, DAA must retain this pairing. Independent-group DAA methods would treat repeated measurements as independent replicates and are therefore rejected.

Correlation inference permutes the sample columns of one metagenome jointly across all features. This preserves within-metagenome feature dependence while breaking only the cross-metagenome sample correspondence. Monte Carlo p-values use the plus-one correction (b + 1) / (B + 1).

Value

A list containing three elements:

• "daa": paired differential abundance results for every metagenome pair.

• "correlation": a list containing cor_matrix, p_matrix, p_adjust_matrix, and n_features_matrix. Correlations are medians of finite per-feature Spearman correlations. P-values use joint sample-label permutation and are adjusted across unique off-diagonal metagenome pairs. Diagonal p-values are NA.

• "heatmap": a ComplexHeatmap object visualizing the correlation matrix. Use print() or draw() to display it.

References

Fernandes AD, Macklaim JM, Linn TG, Reid G, Gloor GB. Unifying the analysis of high-throughput sequencing datasets: characterizing RNA-seq, 16S rRNA gene sequencing and selective growth experiments by compositional data analysis. Microbiome. 2014;2:15.

Phipson B, Smyth GK. Permutation P-values Should Never Be Zero: Calculating Exact P-values When Permutations Are Randomly Drawn. Statistical Applications in Genetics and Molecular Biology. 2010;9(1).

Examples

library(dplyr)
library(ComplexHeatmap)
# Generate example data
set.seed(123)
# First metagenome
metagenome1 <- abs(matrix(rnorm(1000), nrow = 100, ncol = 10))
rownames(metagenome1) <- paste0("KO", 1:100)
colnames(metagenome1) <- paste0("sample", 1:10)
# Second metagenome
metagenome2 <- abs(matrix(rnorm(1000), nrow = 100, ncol = 10))
rownames(metagenome2) <- paste0("KO", 1:100)
colnames(metagenome2) <- paste0("sample", 1:10)
# Put the metagenomes into a list
metagenomes <- list(metagenome1, metagenome2)
# Define names
names <- c("metagenome1", "metagenome2")
# Call the function
results <- compare_metagenome_results(
  metagenomes,
  names,
  daa_method = "paired Wilcoxon",
  correlation_permutations = 99
)
# Print the correlation matrix
print(results$correlation$cor_matrix)
# Display the heatmap
print(results$heatmap)

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